//DOCS Chorus

Chorus

Chorus is Punk's governed intelligence route for harder research, coding, analysis, policy, creative, operational, and technical work.

Call it with one public model id:

{ "model": "punk/chorus" }

Punk keeps the caller's normal wire format and privately coordinates routing, source evidence, verification, policy, cost controls, and receipts behind the gateway.

When To Use It

Use Chorus when a request needs more than a single straightforward model call:

• source-backed research or due diligence;
• long-context answer generation;
• coding, review, or debugging work that benefits from verification;
• policy, security, legal, finance, or operations analysis;
• high-value decisions where receipts and audit matter;
• evaluation or shadow traffic before adopting an optimized route.

Use a normal provider model when the work is simple, low-risk, latency-sensitive, or already handled by cache/artifact routes.

Quick Start

Use either supported gateway wire.

Example:

{
  "model": "punk/chorus",
  "messages": [
    { "role": "user", "content": "Compare these options and cite the evidence behind the recommendation." }
  ],
  "budget_limit_usd": 0.25,
  "latency_mode": "balanced",
  "quality_mode": "maximum_quality",
  "receipt_mode": "full",
  "circuit_mode": "learn",
  "chorus": {
    "requestId": "req_123",
    "workflowId": "wf_support",
    "labels": ["receipt-required"]
  }
}

The response includes the normal Punk headers:

Request Controls

Chorus has one model id. Different operating modes are selected with request fields:

Typical presets:

Evidence And Receipts

Every served Chorus run records a structured evidence trail in the Punk trace:

Retrieve receipt material through:

Receipts expose the audit objects customers need. They do not expose private scoring weights, routing formulas, internal prompts, or solver heuristics.

Agent-Step Mode

When model: "punk/chorus" is called on the Anthropic wire with declared tools, Punk runs a single delegated agent step instead of returning a normal text answer. The delegate receives the same normalized request with stream: false; if it returns tool calls, Punk serializes them back as Anthropic tool_use blocks and records the tool plan in the run trace.

Delegate selection order:

1. Request field or header such as chorus_agent_model, punk_chorus_agent_model, or x-punk-chorus-agent-model.
2. Tenant setting chorus_agent_model.
3. Environment variable PUNK_CHORUS_AGENT_MODEL.
4. Punk's fallback delegate model, currently claude-sonnet-4-6.

This lets tool-declaring Anthropic-compatible agents keep their native tool loop while Punk still owns routing, policy, trace, and receipt behavior.

Research Mode

Research mode is separate from quality mode because not every hard request needs web evidence.

When research_mode is som or deep, Chorus can gather source evidence, turn pages into compact source cards, check coverage gaps, and feed accepted evidence into the final answer and receipts.

Use live_synthesis_required: true for strict production gates where a mock/local fallback would be misleading.

How It Differs From Fusion

Fusion-style panels usually send the whole prompt to several models, compare full answers, and produce a final response.

Chorus is designed to be a governed superset of that pattern. Maximum-quality Chorus can run a live candidate panel and final-answer route, but the panel is only one lane inside a larger execution job:

1. Compile the request into a reasoning contract.
2. Build claim-level work units.
3. Gather source, tool, cache, or tenant evidence when needed.
4. Route unresolved work to qualified models, tools, artifacts, or verifiers.
5. Verify evidence coverage before answering.
6. Save useful routes as reusable circuits and failed routes as negative knowledge.

The product goal is to beat Fusion-style whole-answer ensembling on the combined mix of answer quality, speed, cost, reliability, evidence quality, governance, and auditability. The economic goal is to buy only the next useful unit of intelligence instead of paying every candidate model to solve the whole problem.

Configured provider families are documented in Configuration. The SDK helper is documented in SDK.

Safety And Governance

Chorus inherits Punk's enterprise controls:

• tenant isolation for runs, traces, receipts, and ledgers;
• redaction before stored traces and exports;
• policy checks before model/tool selection;
• configurable budget and latency ceilings;
• no side effects from evidence-review work;
• caveat, fallback, approval, or block for unsupported high-risk claims;
• opt-in, shape-level learning only across tenants.