Themis

Themis is a LangGraph StateGraph with six nodes wired as a directed acyclic graph:

Fan-out uses the LangGraph Send API — fanOutNode returns one Send per sub-task, and LangGraph executes them in parallel on separate graph branches.

Node Responsibilities

• specNode — Parse task + context, emit sub-tasks for specialist agents
• fanOutNode — Return Send[] for parallel dispatch
• skillAgentNode — Run createReactAgent for one sub-task; call skill phase fetch tool
• guardrailNode — Score each output; block/flag/pass based on content integrity
• synthesisNode — Reduce guardrailed results into structured report
• auditNode — Write metadata-only debrief to SQLite; strip findings

State is held in ThemisAnnotation (14 channels) using typed reducers:

• append — Accumulates sub-task results and guardrail outputs
• sum — Token counters (aggregate input/output tokens)
• last-write-wins — Final report and thread metadata
• dedup-union — Skill slug sets (avoid duplicates)
• first-write-wins — Task and context (set once, never mutated)

Checkpointing uses MemorySaver — state is in-RAM only, scoped to a thread_id. No external database, no network calls for checkpointing.

Themis supports multiple LLM providers with tiered model selection (fast/standard/power). Provider selection is determined at runtime based on available API keys:

• Anthropic — Set ANTHROPIC_API_KEY (Claude models)
• OpenAI — Set OPENAI_API_KEY (GPT-4, GPT-5 models)
• Google — Set GOOGLE_API_KEY (Gemini models)
• Mistral — Set MISTRAL_API_KEY (Mistral models)
• DeepSeek — Set DEEPSEEK_API_KEY (DeepSeek models)
• Qwen — Set QWEN_API_KEY (Qwen models)
• NVIDIA — Set NVIDIA_API_KEY (Nemotron models)

All LLM provider SDKs are restricted to lib/themis/provider.ts. No provider SDK may be imported elsewhere. This is enforced at the bundle level. For detailed model specifications, see the technical documentation.

Themis treats all inputs as untrusted and enforces five core security principles:

1. Every input is untrusted — Task content, LLM outputs, skill phase content are all treated as potentially adversarial
2. Sanitise before log — Loggers receive only metadata (hashes, token counts, durations). No user input or LLM output reaches a log line
3. Sanitise before client — All errors pass through safeError() which returns one of three fixed strings. No stack traces, paths, or model names reach the client
4. Memory ephemeral — No findings or task content is persisted to Redis, Supabase, or any external storage
5. Content integrity checks — All skill phase content is validated against blocked-content patterns (script injection, eval, data URIs) before reaching agents

Request

Response

Supports streaming: pass Accept: text/event-stream to receive node-name events as the graph executes. Node content and findings are never included in SSE events.

Each orchestration writes a metadata-only row to a local SQLite database:

• thread_id — Session correlation ID
• task_hash — SHA-256 of the task string (not the task itself)
• skill_slugs — JSON array of skills invoked
• guardrail_summary — { passed, flagged, blocked }
• total_input_tokens — Aggregated input token count
• total_output_tokens — Aggregated output token count
• duration_ms — Wall-clock duration
• created_at — UTC timestamp

Findings text and task content are never written to SQLite. The audit trail captures only what is necessary for operational visibility and compliance.

Themis is platform-agnostic and can be deployed as a self-hosted service, embedded in your application, or run locally. Choose the installation method that fits your architecture.

Option 1: Install as NPM Package

For JavaScript and Node.js projects:

Import and use:

Option 2: Docker Container

Deploy Themis as a containerized REST API:

The Themis API will be available at http://localhost:3000/api/themis

Option 3: Vercel Deployment

Deploy the full Aegis platform (Themis + skills) to Vercel:

Option 4: Self-Hosted on Linux/macOS

Run Themis locally or on your own infrastructure:

Environment Configuration

Themis requires at least one LLM provider API key. Set environment variables for your chosen provider:

Quick Start (Local)

Deployment Best Practices

• API keys in environment only — Never commit .env files. Always use platform-specific secret management (Vercel Secrets, AWS Secrets Manager, etc.).
• Set ulimit for file descriptors — Themis uses LangGraph checkpointing. On Linux/macOS: ulimit -n 4096
• Monitor memory usage — Findings are held in-memory during orchestration. For large tasks, allocate 2GB+ RAM.
• Enable request timeouts — Set reverse proxy timeouts to 90s+ (Themis can take 30-60s per task).
• Health check endpoint — GET /api/health returns 200 if server is ready.

See the Documentation page for getting started guides and API reference. For the complete technical specification, see TECHNICAL.md in the repository.