Skip to main content

Computational Theseus Toolkit (CT Toolkit)

Identity Continuity Guardrails for Agentic Systems

Python 3.11+ License: Apache 2.0 PyPI version Documentation PyPI Downloads

CT Toolkit is an open-source security layer that keeps AI agents aligned with their original constitution over time. It watches what your agents say and do, reviews the tool calls they ask for, and records everything in a tamper-evident provenance chain you can inspect in a web dashboard.

CT Toolkit Web Audit & Telemetry Dashboard


Quick Start

# Core install: the library, the ct-toolkit CLI, the web dashboard and the tool-call guard
pip install ct-toolkit

# Optional extras: ml (torch, fastembed), postgres, observability, structured, vision, all
pip install "ct-toolkit[all]"

Wrap your model client in one line:

from ct_toolkit import TheseusWrapper, WrapperConfig

# Protect against silent provider context compression
config = WrapperConfig(compression_passive_detection=True)

# One-line injection for any LLM provider
client = TheseusWrapper(provider="openai", config=config)

# Sync or async (`await client.achat(...)`) with automatic drift analysis
response = client.chat("What are your core security axioms?")

print(response.content)
print(f"Divergence Score: {response.divergence_score}")

Open the dashboard on the provenance vault your wrapper writes to:

ct-toolkit dashboard --web --vault ./ct_provenance.db --port 8001
# then open http://127.0.0.1:8001/dashboard

To put the tool-call guard in front of a coding agent, run the local proxy and point the agent's base URL at it. The OpenCode with AWS Bedrock guide shows the full setup.

ct-toolkit proxy --upstream https://api.openai.com --port 8788 --tool-guard-mode observe

Why CT Toolkit?

In complex agentic workflows, LLMs tend to "drift" from their original instructions. CT Toolkit provides the mathematical and cryptographic guardrails to ensure your agents remain aligned with their core constitution, even across deep hierarchies.

  • Tool-Call Guard: Reviews the tool calls an agent asks for before the harness runs them: undeclared tools, hosts the conversation never mentions, and risky commands or credential reads. Runs without a second model; observe records findings, enforce removes high-severity calls. Available as a library wrapper, a local proxy (ct-toolkit proxy) and the guardrail server.
  • Provenance Ledger of All Traffic: Every request that passes through the proxy is recorded: model turns, other API calls and each tool-call decision. Text is stored as hashes only, and the chain is HMAC-signed, so you can audit what went through CT Toolkit and verify that no entry was changed.
  • Contrastive Semantic L1 Engine: Provider-independent embeddings (litellm, ollama, local fastembed) with positive/negative anchor analysis and semantic rule conflict detection. Divergence is graded into L1, L2 and L3 tiers.
  • Staged Approval (Cooldown): Verify risky kernel updates in a sandbox via shadow requests before production promotion.
  • Async & Streaming Guardrails (achat): Native async/await and streaming (stream=True) support with non-blocking background execution for shadow requests and L3 ICM probes.
  • Passive Context Compression Detection: Automatically detects silent provider-side history compression (e.g., OpenAI/Anthropic).
  • Constitutional Kernels & Distributed Propagation: Axiomatic identity anchors with HMAC-SHA256 signed HTTP header propagation (propagate_headers / from_headers).
  • Standalone Auditor & Status CLI: Rapidly audit any LLM endpoint (ct-toolkit audit) and inspect provenance integrity & divergence tiers (ct-toolkit status / dashboard).
  • Autonomous Self-Correction: Active L2->L1 feedback loop that retries and corrects divergent responses before they reach the user.
  • Enterprise Provenance & Observability: Immutable HMAC-signed hash chain supporting SQLite and PostgreSQL/SQLAlchemy with paginated verification and OpenTelemetry (OTel) spans/metrics.

CLI & Web Dashboard

Audit any LLM endpoint (OpenAI, Ollama, LM Studio) and inspect your provenance chain directly from your terminal or in the interactive Web Audit Dashboard. The dashboard shows the divergence timeline and tier breakdown, the staged kernel rules, the provenance ledger and the tool-call guard decisions, with paging, sorting and filtering on each table.

Example output of ct-toolkit status:

$ ct-toolkit status

  _______ _    _ ______  _____ ______ _    _  _____    _____ _    _          _____  _____  
 |__   __| |  | |  ____|/ ____|  ____| |  | |/ ____|  / ____| |  | |   /\   |  __ \|  __ \ 
    | |  | |__| | |__  | (___ | |__  | |  | | (___   | |  __| |  | |  /  \  | |__) | |  | |
    | |  |  __  |  __|  \___ \|  __| | |  | |\___ \  | | |_ | |  | | / /\ \ |  _  /| |  | |
    | |  | |  | | |____ ____) | |____| |__| |____) | | |__| | |__| |/ ____ \| | \ \| |__| |
    |_|  |_|  |_|______|_____/|______|_____/|_____/   \_____|\____//_/    \_\_|  \_\_____/ 

  Computational Theseus Toolkit (CT Toolkit) v0.5.1
  Identity Continuity Guardrails for Agentic Systems

╭──────────────────── CT Toolkit Audit & Telemetry Status ─────────────────────╮
│ Vault: ./ct_provenance.db (local)                                            │
│ Chain Integrity: VALID (HMAC Verified)                                       │
│ Verified Active Entries: 4 (showing last 4)                                  │
│ Divergence Score (Avg / Max): 0.1525 / 0.3800                                │
│ Head Hash: 9c64cb51a479c52c207b7fa8c3197a75...                               │
╰──────────────────────────────────────────────────────────────────────────────╯

    Divergence Tier Breakdown (L1 / L2 / L3)    
┏━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━┓
┃ Tier       ┃ Count ┃ Share ┃
┡━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━┩
│ OK         │     1 │ 33.3% │
│ L1_WARNING │     1 │ 33.3% │
│ L2_JUDGE   │     1 │ 33.3% │
│ L3_ICM     │     0 │  0.0% │
└────────────┴───────┴───────┘

                     Staged Kernel Rules (Sandbox Cooldown)                     
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Endorsement ID ┃ Commitment       ┃ Rule Text          ┃ Status              ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ end-9f8a7b6c   │ fin_integrity_01 │ Require dual       │ ACTIVE COOLDOWN     │
│                │                  │ sign-off for       │ (1799s left)        │
│                │                  │ adjustments > $10k │                     │
└────────────────┴──────────────────┴────────────────────┴─────────────────────┘

Common commands:

# View Provenance Chain integrity, L1/L2/L3 tier breakdown, and staged rules in terminal
ct-toolkit status --vault ./ct_provenance.db

# Launch the interactive Web Audit & Telemetry Dashboard at http://127.0.0.1:8001/dashboard
ct-toolkit dashboard --web --vault ./ct_provenance.db --port 8001

# Audit a local Ollama model
ct-toolkit audit --url http://localhost:11434/v1 --kernel defense

# Review the tool calls in a saved model response (exit code 1 on a high-severity finding)
ct-toolkit tool-guard check ./response.json --mode enforce

# Run a local tool-call proxy that removes risky calls; point the harness's base URL at http://127.0.0.1:8788
ct-toolkit proxy --upstream https://api.openai.com --port 8788 --tool-guard-mode enforce

# List, count and inspect tool-call decisions in the provenance vault
ct-toolkit tool-guard list --vault ./ct_provenance.db --verdict blocked
ct-toolkit tool-guard stats --vault ./ct_provenance.db

# Redact credentials, emails, home directories and public IPs from a trajectory (dry run without --out)
ct-toolkit scrub ./trajectories --out ./trajectories_clean

# List available kernels and templates
ct-toolkit list-kernels
ct-toolkit list-templates

# Download a verified profile from the official repository
ct-toolkit setup personal_kernel --dest ./config

Security Hardening

The profile setup command fails closed by default. Downloaded kernel, identity, and probe files must match the trusted SHA-256 manifest packaged with CT Toolkit before they are written to disk. HTTPS certificate validation is enabled and redirects to another host or scheme are rejected.

The L2 judge does not evaluate Jinja2 expressions in user requests or model responses. Rule validation normalizes Unicode input and requires configured conflict keywords to match complete words, preventing simple substring and keyword-boundary bypasses.


📖 Documentation & Examples

For full API reference, architecture details, examples, and integration guides, visit our documentation site: 👉 https://theseus-guard.github.io/ct-toolkit/

If you want a runnable application example instead of a CLI-only flow, see ct-toolkit-fastapi, a small FastAPI validation project that developers can use to test CT Toolkit locally with automated endpoints and pytest coverage.

For Deep Agents workflows, see ct-toolkit-deep-agents, a reference integration project for validating CT Toolkit in multi-agent orchestration scenarios.


🚦 Project Health & Status

Metric Status
Tests ✅ 617 passed, 13 skipped
Downloads PyPI Downloads
Last Phase ✅ v0.5.1: tool-call guard host check, proxy stream fixes, provenance migration, dashboard DNS-rebinding guard

Framework & Model Support

Seamlessly integrate with your favorite frameworks and local models:

  • Local Models: Support for LM Studio, Ollama, and local Qwen/Llama endpoints.
  • LangChain & Deep Agents: wrap_deep_agent_factory.
  • CrewAI: TheseusCrewMiddleware.apply_to_crew.
  • AutoGen: register_reply hooks.

Theoretical Foundation

Translating the framework proposed in The Computational Theseus (2025) into engineering practice.


Community


License

Apache License 2.0.

Metadata

Release files for ct-toolkit 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ct-toolkit 0.5.1
File Size Uploaded Provenance Actions
ct_toolkit-0.5.1.tar.gz 186.8 kB Without provenance Details for ct_toolkit-0.5.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ct-toolkit 0.5.1
File Interpreter ABI Platform Actions
ct_toolkit-0.5.1-py3-none-any.whl Python 3 none any Details for ct_toolkit-0.5.1-py3-none-any.whl

Total release size: 372.7 kB

Release files / ct_toolkit-0.5.1.tar.gz

Download URL ct_toolkit-0.5.1.tar.gz
Size 186.8 kB
Tags Source
SHA-256 checksum
How to use checksums
8b9bc4ce7a668c2eccdf08050bd7cbcedc067c2d59e5207e2668d0e326082ff4
BLAKE2b-256 checksum
How to use checksums
d17842167ab09cf302db2184adcbb07986f36e60eaca291ec82a1485f678c281
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / ct_toolkit-0.5.1-py3-none-any.whl

Download URL ct_toolkit-0.5.1-py3-none-any.whl
Size 185.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1572ff3d69d57a28423f6fe4fff3fbb37d3ae02e3c6a442c5e17945d81e57bde
BLAKE2b-256 checksum
How to use checksums
0f158a656e8a845f8b74b94eb4c649148a22cbd8be65bb6846bbf13df0934a5b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for ct-toolkit 0.5.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page