@2.0.0
Theorem
A TypeScript kernel for typed agent profiles and deterministic turns.
A unified runtime
for agentic execution.
Theorem turns ad-hoc agent scripts into a typed execution kernel. One contract per agent — predictable at every boundary.
Pillars
Define a profile
A profile is the contract for one agent: identity, models, tools, inputs, outputs, and guardrails.
1 · Install
Add theorem to your project, then import the profile APIs.
npm install @theoremai/agents import { defineProfile, registerProfile } from "@theoremai/agents";
2 · Describe agent
Every profile has an id, a handle, and a system instruction the model receives each turn.
defineProfile({ : "mermaid", : { : "mermaid", chat: true, : "Turn requests into Mermaid diagrams. Ask when the request is too vague.", },
3 · Define models
Select a provider and the models this agent may use. Each model sets thinking levels,
token limits, provider builtins (builtInTools),
and optional compaction.
: { : { : "geminiInteractions", : "google", : "gemini-3.5-flash-lite", : { normal: "minimal", deep: "medium" }, : "normal", : true, : true, : 8192, : 1, : ["googleMaps", "urlContext"], }, : { : "geminiInteractions", : "google", : "gemini-2.5-flash", : { normal: "low", deep: "high" }, : "normal", : true, : true, : 8192, : 1, : ["googleSearch"], }, }, : "fast", : true, : 1,
4 · Configure tools
Register custom function tools once at startup, then list their ids in tools.allow.
: { : [], // T1: optional tools.t1Policy(ctx) => ["deferred_lookup"] },
5 · Allow inputs
Declare which text, file, and voice inputs the agent accepts on a turn.
: { : true, : { : ["image/png", "image/jpeg", "image/webp", "application/pdf", "text/plain", "text/markdown"], }, : { : ["audio/webm", "audio/wav", "audio/mpeg"], }, : 5, },
6 · Describe outputs
Configure how the agent responds: plain text, structured JSON, images, or speech.
: { : "mermaidTurn", : { : { : (source) => ({ isValid: typeof source === "string" && source.trim().length > 0, error: "diagram.mermaid must be a non-empty string", }), }, : 3, : "Return valid Mermaid only in diagram.mermaid.", }, : { : true, }, resume: { allowContinue: ["length", "stream_incomplete", "provider_error"], autoContinue: ["length", "stream_incomplete"], }, },
7 · Set guardrails
Canary fencing, input sanitization, sensitive-data redaction, quotas, and opt-in egress (standardEgressEnforce) — the same stack wired in Th30 Live and the playground default.
: { : true, : true, : true, : { : 20, }, },
Package map
──┬── ─────────┬── ──────────────────┬──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├── ────
│ │ ├──
│ │ └── ──────┬──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├── ────────────────┬──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├── ───────────────────┬──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├──
│ ├──
│ ├──
│ └──
│
├── ──────┬── ──────────────────┬──
│ │ ├──
│ │ ├── ┬──
│ │ │ ├──
│ │ │ └──
│ │ └── ────────┬──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├── ──────────────┬──
│ │ ├──
│ │ └── ──────┬──
│ │ ├──
│ │ └──
│ │
│ ├── ───────────────────┬──
│ │ └──
│ │
│ ├── ──────────────────┬──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├──
│ ├──
│ ├──
│ └──
│
├── ─────┬──
│ ├──
│ ├──
│ ├──
│ ├──
│ ├──
│ ├──
│ ├──
│ ├──
│ ├──
│ └──
│
├── ──┬──
│ ├──
│ ├──
│ ├──
│ ├──
│ └──
│
├── ───────────┬──
│ ├──
│ ├──
│ └──
│
├── ────────────┬── ────────────────┬──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├── ──────────────────┬──
│ │ └──
│ │
│ └──
│
└── ────────┬──
├── ──────────────────┬──
└──