Cendor for AI coding assistants

You probably arrived here because you told an assistant — Copilot, Claude Code, Cursor, Windsurf — “add cost budgeting to my OpenAI calls” and it reached for Cendor. Cendor is new, so a model that hasn’t seen much of it will guess the call-shape, and a few of our shapes are non-obvious (budget(cfg)(fn) is curried in TypeScript; prices.estimate is positional in Python; the SQLite session store is spelled differently in each language). This page is the canonical call-shape reference — a trap table your assistant (or you) can read once, then get every call right.

You don’t have to read this to use Cendor correctly, though. Every public symbol ships an inline @example and a one-line correct-shape in its type signature, so your editor’s language server (Pylance / tsserver) — and any agent-mode assistant that reads diagnostics — is handed the right shape at the moment you type the call. The wrong shape is a compile error whose message states the right one. This page just makes that knowledge copy-pasteable.

How to point your assistant here. Paste this page’s URL (or the trap table below) into your assistant’s context, or drop the trap table into your repo’s AGENTS.md / .github/copilot-instructions.md / .cursor/rules. The types teach the rest on install.

Or run one command. npx @cendor/init (Node) / uvx cendor-init (Python) writes the rules files into your repo for you — idempotently, never clobbering your own content — and can add the MCP config and a working starter. Offline, no key. It ships a doctor too: npx @cendor/init doctor static-checks your wiring (namespace, provider deps, instrument() once, money-as-Decimal, versions) and exits non-zero on hard problems, so it fits CI.

The trap table

Every row is verified against the current source in both languages. snake_case (Python) ↔ camelCase (TypeScript) is the default rename; the traps below are where the shapes genuinely differ or where a plausible guess is wrong.

A few cross-cutting rules that don’t fit a row:

• Provider SDKs are optional. In Python they’re extras (pip install "cendor-sdk[anthropic]"); in TypeScript they’re peer deps (npm i @anthropic-ai/sdk). Install only the ones you call — Cendor never pulls a provider SDK for you.
• Everything is offline by default. Token counting, pricing, guardrails, and cassette replay need no network and no API key. Nothing phones home.
• Python is a PEP 420 namespace. Import from the flat cendor.* path (from cendor.tokenguard import budget). There is no top-level cendor module object to import — install the package that owns the symbol (or the cendor-libs umbrella).

Canonical examples

These are the exact snippets from the two Getting Started pages — the libraries’ Getting Started and the SDK’s Getting Started — reproduced here so an assistant has both happy paths in one place. They are typechecked in CI, so they can’t drift.

Instrument once

from cendor.core import instrument
client = instrument(OpenAI())   # OpenAI · Anthropic · Hugging Face · Gemini · Bedrock · Ollama

import { instrument } from '@cendor/core';
const client = instrument(new OpenAI());   // OpenAI · Anthropic · Hugging Face · Gemini · Bedrock · Ollama

instrument() is idempotent (re-wrapping is a no-op), additive (coexists with other instrumentation), and supports sync, async, and streaming clients.

Count tokens and estimate cost, offline

from cendor.core import tokens, prices

n = tokens.count([{"role": "user", "content": "Summarize this in 3 bullets."}], model="claude-opus-4-8")
cost = prices.estimate("claude-opus-4-8", input_tokens=n, output_tokens=200)
print(n, cost)            # e.g. 13  0.005065 USD

import { tokens, prices } from '@cendor/core';

const n = tokens.count([{ role: 'user', content: 'Summarize this in 3 bullets.' }], 'claude-opus-4-8');
const cost = prices.estimate('claude-opus-4-8', n, { outputTokens: 200 });
console.log(n, cost.toString());   // e.g. 13  0.005065 USD

Refresh prices, and show where a rate came from

from cendor.core import prices

prices.refresh()                        # the cendor-prices feed (dated, per-row provenance)
# or a provider's own catalog:  prices.refresh(source="azure", region="eastus2")
# or, when stale rates are worse than none:  prices.refresh(required=True)

e = prices.explain("gpt-4o")
print(e.summary())     # gpt-4o: … — exact, from azure as of 2026-07-01
print(e.registered)    # True if one of YOUR register* calls is overriding the table
print(e.notes)         # resale source? undatable table? unpriced model?

import { prices } from '@cendor/core';

await prices.refresh(); // the cendor-prices feed (dated, per-row provenance)
// or a provider's own catalog:  await prices.refresh(undefined, { source: 'azure', region: 'eastus2' });
// or, when stale rates are worse than none:  await prices.refresh(undefined, { required: true });

const e = prices.explain('gpt-4o');
console.log(e.summary()); // gpt-4o: … — exact, from azure as of 2026-07-01
console.log(e.registered); // true if one of YOUR register* calls is overriding the table
console.log(e.notes); //     resale source? undatable table? unpriced model?

Cap spend and attribute it

from cendor.core import instrument
from cendor.tokenguard import budget, track, report

client = instrument(OpenAI())

@budget(usd=0.50, on_exceed="raise")          # trips the breaker before a runaway loop spends more
def answer(q: str) -> str:
    with track(feature="support", user_id="alice"):
        r = client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": q}])
        return r.choices[0].message.content

answer("Why was I charged twice?")
print(report(group_by=["feature"]))            # spend grouped by tag — for free

import { instrument } from '@cendor/core';
import { budget, track, report } from '@cendor/tokenguard';

const client = instrument(new OpenAI());

const answer = budget({ usd: 0.50, onExceed: 'raise' })(   // trips before a runaway loop spends more
  (q: string) => track({ feature: 'support', userId: 'alice' }, async () => {
    const r = await client.chat.completions.create({
      model: 'gpt-4o', messages: [{ role: 'user', content: q }] });
    return r.choices[0].message.content;
  }));

await answer('Why was I charged twice?');
console.log(report(['feature']));              // spend grouped by tag — for free

Assemble context within a budget

from cendor.contextkit import Context, Block

ctx = Context(budget_tokens=8000, model="gpt-4o", reserve_output=1000)
ctx.add(Block(SYSTEM_PROMPT, priority=10, pin=True, role="system"))
ctx.add(Block(retrieved_docs, priority=5, evict="compress"))   # squeeze, if installed
ctx.add(Block(user_msg, priority=9, pin=True, role="user"))

messages = ctx.assemble()      # guaranteed within budget
print(ctx.report())            # the receipt: kept / truncated / dropped

import { Context, Block } from '@cendor/contextkit';

const ctx = new Context({ budgetTokens: 8000, model: 'gpt-4o', reserveOutput: 1000 });
ctx.add(new Block(SYSTEM_PROMPT, { priority: 10, pin: true, role: 'system' }));
ctx.add(new Block(retrievedDocs, { priority: 5, evict: 'compress' }));  // @cendor/squeeze, if installed
ctx.add(new Block(userMsg, { priority: 9, pin: true, role: 'user' }));

const messages = await ctx.assemble();  // guaranteed within budget
console.log(ctx.report());              // the receipt: kept / truncated / dropped

Gate unsafe input and output

from cendor.guardrails import rules, evaluate, GuardrailTripped

gate = [rules.keyword_deny(["ignore previous instructions"], action="block")]
try:
    payload, decisions = evaluate(gate, "input", user_msg)   # runs the input-stage rules
    resp = client.chat.completions.create(model="gpt-4o", messages=messages)
except GuardrailTripped as trip:
    resp = None                                              # blocked pre-flight — $0
    print("blocked:", [d.guardrail for d in trip.decisions])

import { rules, evaluate, GuardrailTripped } from '@cendor/guardrails';

const gate = [rules.keywordDeny(['ignore previous instructions'], { action: 'block' })];
try {
  const { payload } = evaluate(gate, 'input', userMsg);    // runs the input-stage rules
  const resp = await client.chat.completions.create({ model: 'gpt-4o', messages });
  console.log(payload, resp);
} catch (trip) {
  if (trip instanceof GuardrailTripped) {                  // blocked pre-flight — $0
    console.log('blocked:', trip.decisions.map((d) => d.guardrail));
  }
}

Under the cendor-sdk agent loop you don’t call evaluate yourself — you pass Agent(guardrails=[…]) and it gates all four stages for you.

Make runs testable — and audited

from cendor import cassette
from cendor.acttrace import AuditLog

audit = AuditLog(system="support", risk_tier="limited")   # auto-logs every instrumented call

@cassette.use("tests/support.json")          # records once, then replays offline forever — no key
def test_support():
    out = answer("Why was I charged twice?")
    assert cassette.semantic_match(out, "explains the charge")

audit.export("evidence.jsonl", framework="eu_ai_act")     # tamper-evident; verify offline

import * as cassette from '@cendor/cassette';
import { AuditLog } from '@cendor/acttrace';

const audit = new AuditLog('support', { riskTier: 'limited' });  // auto-logs every instrumented call

test('support', () =>
  cassette.using('tests/support.json', async () => {  // records once, then replays offline — no key
    const out = await answer('Why was I charged twice?');
    expect(cassette.semanticMatch(out, 'explains the charge')).toBe(true);
  }));

audit.export('evidence.jsonl', 'eu_ai_act');           // tamper-evident; verify offline

Run a governed agent (SDK)

The other door: cendor-sdk gives you the whole agent loop with governance built in. This is the exact 10-line snippet from the SDK’s Getting Started — a budget cap, a PII-redacting guard, and a tamper-evident AuditLog, all on one run:

from cendor.sdk import Agent, tool, run, budget, guard, Policy, AuditLog

@tool
def get_weather(city: str) -> str:
    """Current weather for a city."""      # schema derived from type hints + docstring
    return f"Sunny in {city}"

agent = Agent(name="assistant", model="gpt-4o", tools=[get_weather],
              instructions="Answer using tools when helpful.")

log = AuditLog(system="support", risk_tier="limited", path="audit.jsonl")
with budget(usd=0.25, on_exceed="block"), guard(Policy.default(), audit=log):
    result = run(agent, "What's the weather in Paris?", audit=log)

print(result.output)                        # the final answer
print(result.cost, result.usage)            # Decimal money, real token usage
print([s.name for s in result.tool_steps])  # ["get_weather"]

import { Agent, tool, run, withBudget, guard, Policy, AuditLog } from '@cendor/sdk';
import { z } from 'zod';

const getWeather = tool(({ city }) => `Sunny in ${city}`, {
  name: 'get_weather',
  description: 'Current weather for a city',
  parameters: z.object({ city: z.string() }),   // TS has no runtime type hints — zod is the schema
});

const agent = new Agent({ name: 'assistant', model: 'gpt-4o', tools: [getWeather],
                          instructions: 'Answer using tools when helpful.' });

const audit = new AuditLog('support', { riskTier: 'limited', path: 'audit.jsonl' });
const result = await withBudget({ usd: 0.25, onExceed: 'block' }, () =>
  guard({ policy: Policy.default(), audit }, () =>
    run(agent, "What's the weather in Paris?", { audit })));

console.log(result.output);                          // the final answer
console.log(result.cost?.toString(), result.usage);  // decimal money, real token usage
console.log(result.toolSteps.map((s) => s.name));    // ["get_weather"]

budget/guard/AuditLog are the same library objects re-exported from cendor.sdk — the per-agent cap is Agent(max_usd=…), not a budget= field. Full walkthrough: SDK Getting Started.

Watch runs locally (Cendor Monitor)

The connection is one standard OTLP env var — there is no Cendor API, key, or endpoint to call, and no Cendor telemetry code: with an OpenTelemetry provider configured in your app, calls, run trees, spend and enforcement decisions flow on their own (core ≥ 1.13 / 0.15, sdk ≥ 1.19 / 0.22). CENDOR_TELEMETRY=off stops it; CENDOR_DEBUG_TELEMETRY=1 says why nothing is arriving. Your production default stays your own OTel backend (Azure Monitor / CloudWatch / Datadog / any OTLP); this is optional dev tooling. See Cendor Monitor.

# 1) run the monitor:  docker run --rm -p 3000:3000 -p 4318:4318 ghcr.io/cendorhq/cendor-monitor:0.15.0
# 2) point your app's OpenTelemetry at it (shell): export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
#    …plus your usual OTel SDK setup (a provider). No Cendor telemetry code.
from cendor.sdk import run

result = run(agent, "…")           # runs stream to Cendor Monitor at http://localhost:3000

// 1) run the monitor:  docker run --rm -p 3000:3000 -p 4318:4318 ghcr.io/cendorhq/cendor-monitor:0.15.0
// 2) point your app's OpenTelemetry at it (shell): export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
//    …plus your usual NodeSDK setup (a provider). No Cendor telemetry code.
import { run } from '@cendor/sdk';

const result = await run(agent, '…'); // runs stream to Cendor Monitor at http://localhost:3000

Prompt/response content is captured only if you opt in (otel.capture_content() — off by default; the monitor never enables it). The monitor is an operational copy — verify() still runs on the tamper-evident audit file, never on what the monitor shows. On older versions (core < 1.13 / 0.15) attach the emitters explicitly instead — otel.use_span_emitter(), use_sink(sinks.OTelSink()), live_spans() — see Observability.

Wire up your assistant — three ways

You don’t have to paste this page every time. Pick whichever fits how your assistant reads context — they stack, so use more than one:

• Rules files — drop a short cheatsheet into your repo (.github/copilot-instructions.md, .cursor/rules/cendor.mdc, AGENTS.md, CLAUDE.md, or .windsurf/rules) so your assistant reads the correct call-shapes on every edit. The copy-paste blocks are on Rules files.
• MCP server — if your assistant runs in agent mode (Claude Code, Cursor’s agent, Copilot agent, Windsurf Cascade), connect the read-only Cendor MCP server and it looks up the correct shape on demand — the same trap table above, served fresh. See MCP server.
• One command — npx @cendor/init (or uvx cendor-init) writes the rules files (and, with --mcp, the connect config) for you, idempotently. It also ships a doctor that static-checks your wiring for CI. See init CLI & doctor.

These rules files are a different artifact from Cendor’s own maintainer CLAUDE.md (which says things like “never create __init__.py”). Don’t copy that one — it’s about developing Cendor, not calling it.

Honest limits

• This page states call shapes, never performance numbers. Every benchmark-backed claim lives in Benchmarks; acttrace produces evidence, not a compliance guarantee.
• The type-level teaching is only as fresh as your installed version. If a shape here disagrees with what your editor shows on hover, trust the editor — it’s reading the version you actually have.
• Parity is documented, not version-coupled. Where a capability is Python-only (or shapes differ), the Languages & parity matrix is the source of truth.