Training and serving an ExoBrain

An ExoBrain is a small neural model trained on one organization’s knowledge graph. It is what makes POST /v1/retrieve return a cognition block instead of a ranked list. Without one, retrieval still works and says so honestly. With one, you get focal nodes, gate confidence and a fast-versus-slow reasoning tier.

Before you start

An admin key

POST /v1/brain/train requires the admin scope. Reads do not.

A graph with content

A brain trains on the graph. Too few nodes and the train is refused.

Patience for the job

Training runs on GPU hardware as a queued job, not inline.

Check what you have now

Start here, because the answer is often “nothing yet, and that is fine”.

curl https://api.get-exo.com/v1/brain/info \
  -H "X-Exo-API-Key: $EXO_KEY"

import httpx

info = httpx.get(
    "https://api.get-exo.com/v1/brain/info",
    headers={"X-Exo-API-Key": EXO_KEY},
).json()
print(info["training"]["status"])

const info = await (
  await fetch("https://api.get-exo.com/v1/brain/info", {
    headers: { "X-Exo-API-Key": process.env.EXO_KEY! },
  })
).json();
console.log(info.training.status);

GET /v1/brain/info reports which artifact is loaded for your organization, how big it is in model parameters and in graph nodes and edges, which backend is serving it, and a training block describing the most recent or in-flight train. When the organization has never trained, it degrades to a training status of none rather than failing, so this call is always safe to make.

The response shape for this route is not pinned in the OpenAPI contract, so treat the field names above as the documented contents rather than a fixed schema, and read defensively. Everything else on this page is schema-pinned.

Training

Enqueue the train

curl -X POST https://api.get-exo.com/v1/brain/train \
  -H "X-Exo-API-Key: $EXO_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "nightly refresh", "epochsScale": 1.0}'

r = httpx.post(
    "https://api.get-exo.com/v1/brain/train",
    headers={"X-Exo-API-Key": EXO_ADMIN_KEY},
    json={"reason": "nightly refresh", "epochsScale": 1.0},
)
job = r.json()

const r = await fetch("https://api.get-exo.com/v1/brain/train", {
  method: "POST",
  headers: {
    "X-Exo-API-Key": process.env.EXO_ADMIN_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ reason: "nightly refresh", epochsScale: 1.0 }),
});
const job = await r.json();

202 Accepted

{
  "jobId": "7c04b1e8-3a55-4f19-90d2-b1e6a2c73f40",
  "orgId": "0d5b7c92-3a41-4e88-9b02-6f7c1d4a5e30",
  "status": "pending"
}

Both body fields are optional. reason defaults to "manual" and is there so your audit log says why. epochsScale defaults to 1.0; raise it for a longer train, lower it for a cheaper one.

Watch it

Poll GET /v1/brain/info and read the training block. Only one train may be in flight per organization, so a second request while one is queued or running returns 409. That is a guard, not a failure: read it as “already training”.

import time

while True:
    t = httpx.get(
        "https://api.get-exo.com/v1/brain/info",
        headers={"X-Exo-API-Key": EXO_KEY},
    ).json()["training"]
    if t["status"] not in ("pending", "running"):
        break
    time.sleep(30)

You can also subscribe to brain.trained, an organization-scoped event that reaches every listener. See Reacting to change.

Confirm it is serving

A successful train does not silently change your reads. Confirm by looking at path on a retrieval:

curl -s -X POST https://api.get-exo.com/v1/retrieve \
  -H "X-Exo-API-Key: $EXO_KEY" -H "Content-Type: application/json" \
  -d '{"query": "pricing"}' | jq '{path, degraded, degradationReason}'

{ "path": "brain", "degraded": false, "degradationReason": null }

Before the train this reads {"path": "hybrid", "degraded": true, "degradationReason": "no_brain"}. The flip is the proof.

A failed train leaves the previous brain serving. The new artifact is published only after it passes a numerical parity gate, so a bad train degrades nothing. There is no window where your organization is running on a half-trained model.

Querying the brain directly

POST /v1/brain/query runs the model and hands back its internals rather than an answer. This is what you build a “what did it attend to” view on.

curl -X POST https://api.get-exo.com/v1/brain/query \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Where did we land on pricing?", "seed_k": 200, "focal_display": 5}'

r = httpx.post(
    "https://api.get-exo.com/v1/brain/query",
    headers={"X-Exo-API-Key": EXO_KEY},
    json={"question": "Where did we land on pricing?", "seed_k": 200, "focal_display": 5},
)
out = r.json()
for node in out["focal"]:
    print(node["node_id"], node["cosine_in_seed"], node["snippet"][:80])

const out = await (
  await fetch("https://api.get-exo.com/v1/brain/query", {
    method: "POST",
    headers: {
      "X-Exo-API-Key": process.env.EXO_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      question: "Where did we land on pricing?",
      seed_k: 200,
      focal_display: 5,
    }),
  })
).json();
out.focal.forEach((n: any) => console.log(n.node_id, n.cosine_in_seed));

200 OK

{
  "question": "Where did we land on pricing?",
  "tenant_id": "0d5b7c92-3a41-4e88-9b02-6f7c1d4a5e30",
  "alias": "base",
  "focal": [
    {
      "node_id": "ingest:4a1e88f0-9c2d-4f31-b7a0-5e6c1d820b93:7d3c9b1e04a2",
      "snippet": "Seat plus usage won on predictability.",
      "cosine_in_seed": true
    }
  ],
  "cosine_top": [],
  "confidence": 0.83,
  "tier": "growing",
  "use_system2": false,
  "drift_rate": 0.02,
  "contradictions": [],
  "negative_edges_in_subgraph": 4,
  "system_used": "system1",
  "latency_ms": 118.4,
  "subgraph": { "nodes": 1284, "edges": 5106 }
}

tier and system_used are two different measurements and are easy to confuse. tier describes how much graph the brain has to work with, and its values are seed, sprout, growing, mature and deep, assigned by node count. system_used describes how it thought about this one query, and its values are system1 and system2. A tier of "system1" is not a value the API produces.

The brain routes use snake_case, unlike the rest of the API, which is camelCase. seed_k, focal_display, drift_rate, use_system2, latency_ms, model_params and cosine_in_seed are all correct as written. Do not camelCase them.

The field worth understanding is cosine_in_seed. It tells you whether a focal node was also in the plain cosine top-K head. A focal node with cosine_in_seed: false is one the brain reached by propagating through the graph, not by similarity. That gap is the difference between search and reasoning, and it is the interesting thing to visualize. seed_k controls the cosine seed set size, from 10 to 2000, and drives the reasoning tier. focal_display caps how many focal nodes come back, from 1 to 20.

POST /v1/brain/query and POST /v1/brain/answer read the API key owner’s own content. The X-Exo-Subject selector is not accepted on either route. To reason over a subject’s data, use POST /v1/retrieve with the header instead.

Generating a conditioned answer

POST /v1/brain/answer produces text. question and arm are both required; k defaults to 8 retrieval chunks. With arm set to "brain" the forward pass runs first, and tercile_boundaries decides what happens next:

`tercile_boundaries`	What you get
Omitted	Raw signals, generation skipped, `answer` is an empty string
Supplied	Signals rendered into the prompt, then the answer generated

That two-step design exists so you can collect signals across a batch of questions, compute your own cut points from the distribution, then generate with boundaries that mean something for your data rather than arbitrary thresholds.

# Pass 1: collect signals, no generation.
curl -X POST https://api.get-exo.com/v1/brain/answer \
  -H "X-Exo-API-Key: $EXO_KEY" -H "Content-Type: application/json" \
  -d '{"question": "Where did we land on pricing?", "arm": "brain", "k": 8}'

# Pass 2: generate, with boundaries derived from pass 1.
curl -X POST https://api.get-exo.com/v1/brain/answer \
  -H "X-Exo-API-Key: $EXO_KEY" -H "Content-Type: application/json" \
  -d '{
        "question": "Where did we land on pricing?",
        "arm": "brain",
        "k": 8,
        "tercile_boundaries": {
          "confidence": [0.42, 0.71],
          "drift_rate": [0.03, 0.11]
        }
      }'

confidence and drift_rate each take two cut points, [lowMax, midMax], splitting the range into low, middle and high bands. The response carries answer, prompt_used, retrieval_chunk_ids and a brain_signals block with confidence, drift_rate, use_system2, tier, contradictions and appendix_lines.

Keeping a brain fresh

A brain trains on a snapshot. As the graph grows, the snapshot ages, and retrieval tells you:

{ "path": "brain", "degraded": true, "degradationReason": "brain_stale" }

brain_stale means the brain is still answering, and answering well, but the graph has moved on. It is a signal to schedule a retrain, not an incident. Two other reasons appear on the hybrid path: no_brain when none has been trained, and cold_start when there is not yet enough content to do better. Retrain when:

degradationReason has been brain_stale for a while.
You imported a large corpus.
You erased a subject. DELETE /v1/subjects/{id} marks the brain stale rather than deleting it, because it was trained on every subject. Retraining is what removes that person’s influence from the model. See Forgetting and portability.

When it goes wrong

What you see	Why	What to do
`403 permission_denied` on train	The key lacks `admin`	Mint an admin key. Reads need no special scope. See permission_denied
`409` on train	A train is already queued or running for this organization	Wait for it. One in flight per organization is the rule
`404` on `/v1/brain/query`	No brain artifact exists yet	Train first, or use `POST /v1/retrieve`, which falls back gracefully
`409` on `/v1/brain/query` right after a train	A newly published artifact is still being picked up	Retry shortly. The serve path reloads when it notices the new artifact
Train succeeded, `path` is still `hybrid`	The serve path has not reloaded yet	Give it a moment and re-check. If it persists, read the `training` block on `GET /v1/brain/info` for the real status
Train fails repeatedly	Too few nodes, or the artifact failed its parity gate	The previous brain keeps serving. Ingest more content before retrying
`503 service_degraded`	A dependency is briefly unavailable	Retry with backoff. See service_degraded

ExoBrain

What the per-organization model is, when it serves, and when it is stale.

Brain path and hybrid path

What path, degraded and each degradationReason actually mean.

Start

Building with Exo

Platform

Training and serving an ExoBrain

Before you start

An admin key

A graph with content

Patience for the job

Check what you have now

Training

Querying the brain directly

Generating a conditioned answer

Keeping a brain fresh

When it goes wrong

Next

ExoBrain

Brain path and hybrid path

​Before you start

An admin key

A graph with content

Patience for the job

​Check what you have now

​Training

​Querying the brain directly

​Generating a conditioned answer

​Keeping a brain fresh

​When it goes wrong

​Next

ExoBrain

Brain path and hybrid path

Before you start

Check what you have now

Training

Querying the brain directly

Generating a conditioned answer

Keeping a brain fresh

When it goes wrong

Next