Skip to main content

ChatCortex

CI PyPI version Python 3.10+ License: MIT

ChatCortex is a framework for automated synthesis and optimization of AI agent architectures — think AutoML for AI agents.

Instead of manually wiring LLM pipelines (retrieval → LLM → verifier → tool), ChatCortex treats agent design as a multi-objective architecture search problem and automatically discovers architectures that optimize cost, latency, and reliability simultaneously.

Task Specification → Architecture Search → Pareto-Optimal Architectures

ChatCortex re-synthesizes your architecture from what was measured. Execution telemetry is calibrated back into the component registry, so every new synthesis round runs against observed behavior instead of declared guesses. examples/closed_loop.py tests this offline against a hidden ground truth: the starting registry is wrong about four components, and the simulator draws outcomes from true values the loop never sees. After four iterations (alpha 0.4, seed 42):

Component Field Declared Calibrated Truth
retrieval_speedster reliability 0.78 0.542 0.55
retrieval_budget reliability 0.82 0.908 0.95
generation_balanced latency (ms) 180 301.9 320
verification_reliable cost per call 0.006 0.0086 0.009

What this does and does not show. The mis-declared values move toward the truth, and mean error across all twelve components falls for latency (11.67 → 1.51 ms) and cost. Reliability is the exception: its mean error rises (0.030 → 0.041), because a handful of pass/fail probes is a noisy measurement. Treat calibrated reliability as approximate until you have many runs per component.

Installation

pip install chatcortex

Or from source:

git clone https://github.com/siddharth1012/chatCortex
cd chatCortex
pip install -e .

Quickstart

from chatcortex import (
    TaskSpecification,
    BeamSynthesizer,
    build_demo_registry,
)

# A registry of components with cost/latency/reliability tradeoffs
registry = build_demo_registry(
    capabilities=("retrieval", "generation", "verification")
)

# The task: an ordered capability chain with hard constraints
task = TaskSpecification(
    required_capabilities=["retrieval", "generation", "verification"],
    max_cost=0.02,
    max_latency=1500,
)

# Synthesize Pareto-optimal architectures
synth = BeamSynthesizer(registry, beam_width=5)
for arch in synth.synthesize(task):
    print(
        f"cost=${arch.total_cost:.4f} "
        f"latency={arch.total_latency:.0f}ms "
        f"reliability={arch.total_reliability:.3f}"
    )

Or run the full demo comparing three synthesis strategies:

python examples/quickstart.py

To see the full loop — load a JSON registry, synthesize a frontier, execute one architecture, and calibrate the registry's metadata from real telemetry — run:

python examples/registry_from_json.py

Run the flagship closed loop — synthesize → execute → calibrate → re-synthesize, four iterations of measured behavior flowing back into the registry:

python examples/closed_loop.py

With an OpenAI key you can run the same loop against real backends:

pip install "chatcortex[real]"
export OPENAI_API_KEY=...   # every reply spends your credits
python examples/closed_loop_real.py

To search over your own components, build a CapabilityRegistry and register ComponentMetadata describing each model, tool, or verifier — see examples/ for complete walkthroughs.

Registry packs

A registry ships as a JSON pack in the loader's document shape. Saving it proves the round-trip, and one command validates any pack offline:

from chatcortex import build_demo_registry, save_registry, validate_registry_file

save_registry(build_demo_registry(), "registry.json")  # writes, then reloads to prove it
print(validate_registry_file("registry.json").valid)   # True
chatcortex-registry validate registry.json
#   components validated: 12
#   result: VALID          (exit 0; issues and duplicates are named when invalid)

How It Works

ChatCortex is organized as a layered architecture synthesis system:

TaskSpecification → CapabilityRegistry → Synthesis Engine → AgentGraph (DAG)
    → Execution Engine → Telemetry → Evaluation Harness → Pareto Optimization

Core concepts:

  • ComponentMetadata — declarative description of an agent component (model, retriever, tool, verifier, memory) with cost per call, latency, reliability score, and privacy level.
  • CapabilityRegistry — stores components and filters candidates by capability and privacy constraints.
  • TaskSpecification — the synthesis problem: an ordered capability chain plus hard constraints (max cost, max latency, privacy) and objective weights.
  • AgentGraph — architectures represented as DAGs; cost is additive, latency sequential, reliability multiplicative.
  • Synthesizers — search strategies that map a task to an (approximate) Pareto frontier.

Available synthesizers:

Synthesizer Strategy
HeuristicSynthesizer Greedy deterministic construction
RandomSynthesizer Random baseline
BeamSynthesizer Budget-aware beam search
ParetoPartialBeamSynthesizer Beam search with per-stage Pareto pruning
ProgressiveParetoBeamSynthesizer Depth-aware beam widening (best Pareto recovery)
ExhaustiveSynthesizer Exact Pareto frontier (small spaces)

Approximation quality is measured with Pareto coverage, hypervolume loss, and average regret — see docs/BENCHMARKS.md.

Documentation

Research Context

ChatCortex is a controlled experimental platform for studying automated agent architecture synthesis: multi-objective optimization, architecture search, reliability–cost tradeoffs, and AutoML-style agent design. Experiments cover 5-stage pipelines with Pareto frontiers up to 95 architectures and evaluation budgets from 20 to 180 evaluations; progressive beam widening shows improved Pareto recovery over static beam strategies.

If you use ChatCortex in your research, please cite it (see CITATION.cff).

Roadmap

  • Component modeling, capability registry, task specification, DAG representation
  • Exact Pareto frontier computation (exhaustive search)
  • Budget-aware beam search with Pareto pruning and progressive widening
  • Graph-structured (non-chain) agent synthesis
  • Real model / tool integrations (OpenAI chat-completions backend already available behind the chatcortex[real] extra; more backends planned)
  • Registry loading from JSON (load_registry, with error messages naming the failing field); YAML planned

Status

Research framework under active development (alpha). APIs may change between minor versions.

License

MIT — developed by Siddharth Saraswat

Metadata

Release files for chatcortex 0.8.0

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

Source distribution (sdist)

Source distribution for chatcortex 0.8.0
File Size Uploaded Provenance Actions
chatcortex-0.8.0.tar.gz 54.7 kB With provenance Details for chatcortex-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for chatcortex 0.8.0
File Interpreter ABI Platform Actions
chatcortex-0.8.0-py3-none-any.whl Python 3 none any Details for chatcortex-0.8.0-py3-none-any.whl

Total release size: 99.3 kB

Release files / chatcortex-0.8.0.tar.gz

Download URL chatcortex-0.8.0.tar.gz
Size 54.7 kB
Tags Source
SHA-256 checksum
How to use checksums
f058a993db520a66db81a22e0d4bb6249a91bd18624fdda22599ed0cda6286b5
BLAKE2b-256 checksum
How to use checksums
e0bcbaadb12ee91be158984dcf74e3e22e7e9ec6490ead8f7daf15f07846042a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / chatcortex-0.8.0-py3-none-any.whl

Download URL chatcortex-0.8.0-py3-none-any.whl
Size 44.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d56e3e8a66e0884056bf1cb37399564fe38ddc3d51255d00f449825358a1bae3
BLAKE2b-256 checksum
How to use checksums
9e458e524da6451863724b6d5ace7732839ff83a06581c332e16b0f635951fdf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for chatcortex 0.8.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for chatcortex-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

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.

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