Synapse

Synapse is the layer every Subsidia call passes through, whether it arrives on the Gateway, through an agent, or from one of the product modules. It makes four decisions on your behalf, and a fifth thing, the certificate, records them:

1. Is there personal data in this request, and may it leave? (the PII shield)
2. Which provider and model should answer? (routing by task and sensitivity)
3. What does this cost the workspace? (metering in questions)
4. Which machine runs it? (multi-node scheduling, for installations with several)

As an API consumer you mostly never see these decisions, which is the point. This page explains how they work so that you can predict them, steer them with the model address, and read the few places where they are exposed.

Routing turns two inputs, a task and a sensitivity, into a provider and a model. You do not pick the model by name: whatever you put in model is recorded but not obeyed (apart from the address prefixes and flags, which change the task and the sensitivity).

How the task is decided

The task is resolved in this order. The first rule that applies wins.

1. A sensitive call (see below) goes to the local lane.
2. An agent task goes to the full-quality model. A call is agentic when it uses pulse-agent or +agent, when the request defines tools, when the system prompt is longer than 8 000 characters (agent harnesses ship very long operating instructions), or when tool calls and tool results already appear in the conversation. Small models derail tool loops, so these never go to a small one.
3. A simple or extraction task goes to the fast tier.
4. A complex or code task goes to the full tier.
5. Otherwise Synapse auto-classifies: JSON mode (response_format: json_object) counts as complex, an estimated prompt of 500 tokens or more counts as complex, anything shorter is simple. The estimate is the character count divided by four, the same heuristic POST /v1/messages/count_tokens returns.

The call classifier is deliberately cheap and deterministic. There is no extra model call on the Gateway path, so routing adds no latency and no cost.

Providers and administrator policy

An installation can be configured with several providers (for example a European hosted provider, a US provider and a local model). Two rules bound what Synapse may choose:

• Workspace allow-list. An administrator can restrict which providers the workspace may use. Synapse never picks outside it, and never silently replaces a refused choice with an external provider: a request whose preference cannot be honoured is refused.
• The local lane is never restricted. A model that runs on the installation's own machines cannot leak anything, so it is always available.

Until an administrator writes an allow-list, routing stays on the installation's active provider. The x-pulse-provider header and the certificate tell you which one answered.

A call is treated as sensitive in two ways:

• Explicitly, with pulse-sensitive or the +sensitive flag. This always wins.
• Automatically, when the shield finds personal data in the request. This auto-escalation is skipped for agentic traffic (tool loops and harness prompts are full of incidental identifiers such as emails in code, and would otherwise land on a small local model every turn).

What "sensitive" does depends on the installation:

The certificate records the outcome: egress.provider is ollama when the call stayed local, and routing.taskType is sensitive.

The shield finds personal values in the system prompt and every message, replaces each with a token before the text is sent, and swaps the originals back into the answer before you see it. The model reasons over [EMAIL_k3j2h], you read jean.dupont@example.com.

It only masks what leaves

Masking exists to protect data from third parties, so Synapse applies it only when the request can reach an external provider. A request that can only land on a local model is sent as is: full fidelity, no tokens, no restoration step. That is why local answers are often better on names and figures.

• The shield is a no-op for local providers and when the mode is off.
• When a call routes to a local model after the scan, the original text is sent, even if PII was found.
• The count of masked values is reported as pii_masked, and is 0 for a local call.

Modes

The mode is a server setting chosen by the installation administrator (it can be changed from the admin interface, with a deployment-level default). It is not a per-request parameter.

Tokens are deterministic per entity. The suffix is a hash of the normalised value (accents, case and leading titles removed), so:

• The same entity gets the same token everywhere: in every turn of a conversation, across separate requests, and across documents. "Dr Jean Dupuis" and "jean dupuis" become the same alias.
• Distinct entities stay distinct. Two different people never collapse to one token, which would let a model confuse them.
• Restoration works inside a single call from a vault kept for that call only.

This is why a model can follow "the second email from [EMAIL_k3j2h]" across a long conversation without ever seeing the address.

The exact token suffixes depend on the value; do not parse them. The categories that were masked, never the values, are written to the certificate's egress.pii.categories.

Routing decisions are exposed in three places, from lightest to most complete. Everything below is also true of the Anthropic dialect except where noted.

Customers buy questions, and Synapse is where usage becomes questions. For an API consumer this comes down to four facts:

• Preflight check. Before any model is called, the workspace allowance is checked. An exhausted allowance is refused up front (402 insufficient_quota on the OpenAI dialect, 429 rate_limit_error on the Anthropic dialect), so a refused call consumes nothing.
• Charged on the model that answered. pulse-auto may route one call to a small model and the next to a large one. A larger model counts for more questions per answer, so routing a simple ask to the fast tier is also the cheapest outcome for you. Local models are the lightest class.
• Charged after the fact. The deduction happens once the completion has been served; an accounting failure is logged on the server and never fails your call.
• Local installations are not metered against a question allowance. They keep a usage ledger for the dashboard.

A key can also carry its own monthly ceiling (API_KEY_BUDGET_EXCEEDED, a 402). See Rate limits and quotas.

The usage object in every response (prompt_tokens, completion_tokens, total_tokens) is the real token count reported by the model, useful for your own cost tracking. It is not a bill.

Behind the scenes Synapse also estimates a dollar cost per call from the model's public price (local models cost zero) and compares it with what the configured full model would have cost. Those figures feed the operator dashboard of the installation (cost, saved cost, latency, time to first token); they are not returned by the Gateway.

On an installation with more than one machine running local models, Synapse spreads calls across them. It is entirely transparent to API clients: there is nothing to configure on your side and no field to set.

• One whole request per machine. A single request is never split across machines; sharding one model over a local network is slower than running it on one box.
• Least in-flight first. A new request goes to the healthy machine with the fewest requests already running.
• Failover. An unhealthy machine is skipped, and a request that fails on one machine is retried on another.
• Discovery is automatic, admission is a decision. A new machine on the network appears as a candidate and joins routing once an administrator admits it (or a shared cluster key is configured).

The visible effect is capacity and resilience: more concurrent calls without queueing, and no outage when one box is down. The egress.provider in the certificate is still ollama.