Brain (brain)

Category: intelligence | Form: | Symbol: Bn

An LLM model within an Intelligence Lab

A Brain is a specific AI model (e.g. Claude Sonnet 4.6, GPT-4o, Mistral Large) inside an Intelligence Lab. Platform labs come with pre-configured brains that are tested and ready to use. You can add custom brains to any lab — your own or a platform lab. Agents select a brain by ID; the runtime finds the lab that contains it and handles the connection.

Guide

A specific LLM model (Claude Opus, GPT-4o, Mistral Large) that agents reference for chat completions

What It Does

A Brain represents a single LLM model within a Lab (provider). It defines the model’s identity, capabilities, context window, pricing, and optional parameter overrides. When an agent needs to make an LLM call, it references a brain — either by slug, alias, or model ID — and the platform resolves that reference to a fully-configured connection through the brain’s parent lab.

Brains are atoms: they have no children. They always live inside a Lab element, which provides the API endpoint and credentials.

Element Definition

Property	Value
Type	brain
Category	intelligence
Form	atom
Symbol	Br / #A855F7

Properties

Field	Type	Default	Description
model_id	string	—	Required. Model identifier sent to the provider API (e.g., claude-sonnet-4-6, gpt-4o)
aliases	array	[]	Alternative names that resolve to this brain (e.g., ["claude-sonnet"])
context_length	integer	—	Maximum input context window in tokens
max_output_tokens	integer	—	Maximum output tokens per response
pricing.input_per_mtok	number	—	Cost per million input tokens (USD)
pricing.output_per_mtok	number	—	Cost per million output tokens (USD)
tools	boolean	true	Supports tool/function calling
vision	boolean	false	Supports image inputs
streaming	boolean	true	Supports streaming responses
extended_thinking	boolean	false	Supports extended thinking / chain-of-thought
parameter_overrides	object	{}	Brain-specific overrides for temperature, top_p, top_k, etc.

Topology

• Lives in: a lab element (must be a direct child)
• Referenced by: agents via brain in their spec
• Accepts modifiers: rate-limit, audit

Brain Resolution

Agents reference brains via brain — a string that can be a slug, alias, or model_id. The platform resolves it in this order:

1. Slug match in the caller’s circle (via ElementResolver)
2. Alias or model_id match in the caller’s circle
3. Slug match in the platform circle (fallback)
4. Alias or model_id match in the platform circle

This means user-created brains in their own circle take priority over platform defaults. The platform circle provides pre-configured brains for all major providers so every agent has working LLM access out of the box.

What Resolution Returns

The resolver produces a complete connection tuple: model_id + protocol + base_url + api_key — everything needed to make an API call. The agent never sees credentials directly; they’re decrypted at resolution time and injected into the LLM request.

Quick Start

Creating via API

POST /api/{circle}/{lab-element}/
Content-Type: application/json

{
  "element_type": "brain",
  "slug": "claude-sonnet",
  "name": "Claude Sonnet 4.6",
  "spec": {
    "model_id": "claude-sonnet-4-6",
    "aliases": ["claude-sonnet", "sonnet"],
    "context_length": 200000,
    "max_output_tokens": 64000,
    "pricing": {
      "input_per_mtok": 3.0,
      "output_per_mtok": 15.0
    },
    "tools": true,
    "vision": true,
    "streaming": true,
    "extended_thinking": true
  }
}

Referencing from an Agent

In the agent’s spec, set brain to any of the brain’s identifiers:

# Any of these work — resolution tries slug → alias → model_id
brain: "claude-sonnet"         # slug
brain: "sonnet"                # alias
brain: "claude-sonnet-4-6"     # model_id

Operations

Operation	Method	Auth	Description
info	GET	viewer	Get brain metadata: model_id, context_length, capabilities, pricing
test	POST	operator	Send a test prompt to verify the brain works through its parent lab

Test Operation

POST /api/{circle}/{lab}/{brain}/ops/test

{
  "prompt": "Say hello in one word."
}

Returns the model’s response plus latency and token usage, useful for verifying credentials and connectivity before assigning the brain to an agent.

Parameter Overrides

A brain can override any parameter constraint set by its parent lab. The constraint system is constrain-only — it never force-sets defaults, only:

• Strips parameters the provider doesn’t support
• Clamps values to valid ranges
• Enforces provider quirks (e.g., Anthropic’s mutual exclusion of temperature and top_p)

{
  "parameter_overrides": {
    "temperature": { "default": 0.7, "min": 0.0, "max": 1.0 },
    "top_p": { "min": 0.0, "max": 1.0 }
  }
}

Model Catalogs

Platform brains are seeded from YAML catalogs in chemistry/elements/intelligence/brains/{provider}/.triform/catalog.yaml. These define the full brain inventory for each lab (Anthropic, OpenAI, Mistral, Gemini, Groq, Bedrock, Replicate, and more). You typically don’t need to create brains manually — the platform seeds them at startup.

Common Mistakes

Missing parent lab. A brain must be a child of a lab element. Creating a brain at the project level won’t work — there’s no provider connection to resolve.

Wrong model_id format. Use the exact model identifier the provider expects (e.g., claude-sonnet-4-6, not Claude Sonnet). Check the provider’s API docs or the model catalog.

Confusing brain with brain ID. Agents use brain (a human-readable slug, alias, or model_id). The platform resolves this to the internal brain element UUID — you never set brain to a UUID.

Expecting parameter defaults to be applied. The constraint system strips and clamps but never injects defaults. If an agent doesn’t send temperature, the provider uses its own default — the brain’s parameter_overrides.temperature.default is only used by UI model selectors.

Relationships

• Attaches to: rate-limit

Capabilities

• chat-completion: Can perform chat completions
• tool-use: Supports tool/function calling (when brain.tools = true)
• vision: Supports image inputs (when brain.vision = true)
• streaming: Supports streaming responses (when brain.streaming = true)
• image-generation: Supports text-to-image generation (when brain.image_generation = true)

Properties

Property	Type	Default	Description
model_id	string	—	Model identifier sent to the provider API (e.g. claude-sonnet-4-6, gpt-4o)
aliases	array	—	Alternative identifiers that resolve to this brain (e.g. claude-sonnet)
context_length	integer	128000	Maximum input context window in tokens
max_output_tokens	integer	8192	Maximum output tokens per response
pricing	object	—	Cost per million tokens (USD)
embedding_dimensions	integer	—	Output embedding vector dimensions. Declares the halfvec column size for vector storage. Required for embedding models.
tools	boolean	true	Supports tool/function calling
vision	boolean	false	Supports image inputs
streaming	boolean	true	Supports streaming responses
extended_thinking	boolean	false	Supports extended thinking / chain-of-thought mode
image_generation	boolean	false	Supports text-to-image generation
tts	boolean	false	Supports text-to-speech synthesis
video_generation	boolean	false	Supports text-to-video generation
music_generation	boolean	false	Supports text-to-music generation
max_tokens	integer	8192	Default max tokens per response. Agents using this brain inherit this value.
temperature	number	—	Default sampling temperature. 0 = deterministic, 2 = maximum creativity. Leave unset to use the model’s recommended default.
top_p	number	—	Default nucleus sampling threshold. Leave unset to use provider default.
parameter_overrides	object	—	Brain-specific parameter constraints that override lab defaults

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

info

Get /ops/info | Auth: Read

Get brain metadata, capabilities, and pricing

Returns this brain’s model ID, context length, capabilities, and pricing. Used by the model selector UI and for agent configuration.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

test

Post /ops/test | Auth: Execute

Send a test prompt to verify this brain works

Sends a minimal chat completion to verify the brain responds correctly through its parent lab’s connection. Returns response and latency.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
BRAIN_UNAVAILABLE	internal	yes	Brain’s parent lab is unreachable or in error state
BRAIN_CONTEXT_EXCEEDED	validation	no	Request exceeds this brain’s context window
BRAIN_UNSUPPORTED_FEATURE	validation	no	Requested feature (vision, tools) not supported by this brain