chorusgraph 1.0.3

Native agent graph runtime with Prism cache, memory, swappable PrismRAG retrieval, and Route Ledger

ChorusGraph

Native agent runtime with semantic cache, swappable retrieval (PrismRAG), auditable memory, and enterprise hardening — one pip install, five plug-in ports.

pip install chorusgraph
chorusgraph-demo

ChorusGraph = native engine + Prism stack · LangGraph = optional baseline for A/B comparison only (docs/TERMINOLOGY.md)

---

What is ChorusGraph?

ChorusGraph is not a LangGraph wrapper. It ships a native BSP graph engine (chorusgraph.core.Graph) with the Prism product stack attached by default: semantic cache, L2 retrieval, L3 memory, Route Ledger, checkpoints, and observability.

You define nodes, edges, and conditional routing on the native engine. Cache, retrieval, memory, and tools plug in through explicit ports on ChorusStack — swap Redis, vector RAG, or custom tool registries without rewriting orchestration.

ChorusGraph's own code has no LangGraph dependency on the product path. The scheduler and all plug-in ports never import LangGraph. (Core dependency prismlang uses LangGraph internally for its own checkpointing utilities — it appears in pip show, but the ChorusGraph engine never calls it.) Install chorusgraph[benchmark] only when running FL*/HL* comparison scenarios.

---

Why ChorusGraph?

Building production LLM agents usually means gluing six systems: orchestration, semantic cache, vector DB, reranker, checkpointing, and audit logs. ChorusGraph ships them as one runtime with explicit plug-in ports.

Pain	ChorusGraph answer
Repeat questions burn tokens	Two-stage semantic cache (coarse 64-d recall → full verify)
RAG is another integration project	RetrievalBackend plug-in — keyword default, PrismRAG vector opt-in
“Why did the agent say that?”	Route Ledger + rule_chain on every hop
Orchestration + ops duct tape	Native scheduler, health endpoints, Docker/k8s packaging
“Will this save us money?”	chorusgraph-audit — cold log simulation + pilot ledger reports

---

Quick Start (30 seconds)

pip install chorusgraph

from chorusgraph import Graph, START, END, ChorusStack
from chorusgraph.core.node import dict_node_adapter

stack = ChorusStack.defaults(tenant_id="demo")

g = Graph(tenant_id="demo", graph_id="hello")
g.add_node(
    "echo",
    dict_node_adapter(lambda s: {"reply": f"Hello, {s.get('name', 'world')}"}, hop="echo"),
)
g.add_edge(START, "echo")
g.add_edge("echo", END)

out = g.compile(stack=stack).invoke({"name": "ChorusGraph"})
print(out)  # {'reply': 'Hello, ChorusGraph'}

chorusgraph-demo                              # bundled walkthrough
chorusgraph-audit --log your_queries.jsonl    # simulated cache hit rate (no API key)

Full install guide: docs/INSTALL.md · AI IDE prompts: docs/AI_IDE_PROMPTS.md

---

Features

Feature	Description
Native graph engine	BSP scheduler, envelope channels, conditional routing — no LangGraph on product paths
Semantic cache (L1)	Two-stage gate: coarse recall → full verify; safe replay policies per domain
Retrieval (L2)	Keyword default; PrismRAGRetrievalBackend for vector + taxonomy (opt-in extra)
Memory (L3)	PrismCortex structured, replayable memory
Route Ledger	Per-hop audit trail: cache hits, scores, durations, rule_chain
Checkpoints	SQLite default; Postgres enterprise persistence (license-gated)
Tool registry	Allowlisted tools with sandbox; MCP-compatible patterns
Resilience	Timeouts, retries, circuit breakers, graceful node failure
Observability	Structured JSON logs, OpenTelemetry traces, health/metrics endpoints
Multi-tenant guards	Tenant isolation, resource limits, leakage tests
Cold audit CLI	chorusgraph-audit — estimate cache savings from query logs (no LLM calls)
Benchmark matrix	8 scenarios (FL/FC/HL/HC) with fairness disclosure
Deploy packaging	Dockerfile, docker-compose, k8s manifests

---

Comparison with LangGraph and DIY stacks

	LangGraph alone	DIY stack (orchestrator + Redis + vector DB + reranker + logs)	ChorusGraph
Orchestration	✅ StateGraph	You integrate	✅ Native Graph
Semantic cache	❌ Roll your own	Separate service + glue	✅ Built-in L1, swappable
Retrieval / RAG	❌ External	Chroma/Pinecone + custom code	✅ RetrievalBackend port
Audit / explainability	Limited	Custom logging	✅ Route Ledger per hop
Safe cache replay	Your problem	Your problem	✅ Domain profiles (e.g. facts-only in healthcare)
Benchmark proof	N/A	N/A	✅ Published A/B vs LangGraph
LangGraph dependency	Required	Optional	None on product path

ChorusGraph includes LangGraph baselines (benchmark/fl*, benchmark/hl*) for fair apples-to-apples comparison — same model, tools, prompts, workload. Native scenarios (benchmark/fc*, benchmark/hc*) compile with chorusgraph.core.Graph only.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Your graph — nodes, edges, conditional routing              │
├─────────────────────────────────────────────────────────────┤
│  ChorusStack — swappable ports                               │
│  ┌──────────┬──────────┬──────────┬──────────────────────┐  │
│  │ Cache    │ Memory   │ Tools    │ Retrieval (L2)       │  │
│  │ Prism /  │ Cortex   │ Registry │ Keyword / PrismRAG   │  │
│  │ Redis    │          │          │                      │  │
│  └──────────┴──────────┴──────────┴──────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│  Engine (fixed): BSP scheduler · envelopes · Resonance · JL  │
├─────────────────────────────────────────────────────────────┤
│  Route Ledger · checkpoints · tenant guards · observability  │
└─────────────────────────────────────────────────────────────┘

Details: docs/COMPOSE.md · docs/DEVELOPER_GUIDE.md

---

Plugin system

Four swappable ports on ChorusStack — engine and scheduler stay fixed.

Port	Default	Swap examples	Method
Cache (CacheBackend)	PrismCacheBackend	RedisCacheBackend	with_cache()
Memory (MemoryBackend)	CortexMemoryBackend	Disable with enable_memory=False	stack field
Tools (ToolBackend)	Finance tool registry	Custom ToolRegistry, MCP	resolve_tools()
Retrieval (RetrievalBackend)	KeywordRetrievalBackend	PrismRAGRetrievalBackend	with_retrieval()
Persistence (enterprise)	SqlitePersistenceBackend	PostgresPersistenceBackend	license-gated 5th port

from chorusgraph.compose import ChorusStack, PrismRAGRetrievalBackend, RedisCacheBackend
from chorusgraph.embedders import PrismlangOnnxEmbedder

backend = PrismRAGRetrievalBackend(
    embedder=PrismlangOnnxEmbedder(),
    mapping={"categories": [...], "rules": [...]},
)
backend.index(your_corpus)

stack = (
    ChorusStack.defaults(tenant_id="acme")
    .with_retrieval(backend)
    .with_cache(RedisCacheBackend(tenant_id="acme", redis_url="redis://localhost:6379/0"))
)

Full plug-in guide: docs/PLUGINS.md

---

Prism ecosystem

Layer	Component	Role
L0 — hop	PrismLang	64-d state compression + rule_chain audit
L1 — cache	PrismCache	Semantic gate, Resonance-scored recall
L2 — knowledge	Retrieval plug-in	Keyword default · vector + taxonomy opt-in
rerank	PrismResonance	Shared substrate rerank
L3 — memory	PrismCortex	Structured, replayable memory
transport	CHORUS / PrismAPI	Cross-node envelopes · federation hooks

ChorusGraph is the integration runtime for the Prism family — PrismLang, PrismCache, PrismCortex, PrismRAG ship as defaults or opt-in extras, not separate science projects.

---

Benchmarks

Fair A/B vs competent LangGraph baselines — same model, tools, prompts, workload. Canonical run: 20260704_212111 (post–HC2 Bug-1 fix). See benchmark/FAIRNESS_H9.md.

Task success (LangGraph → ChorusGraph)

Scenario	LangGraph	ChorusGraph	Delta
Finance single (FL1→FC1)	87.5%	100%	+12.5 pp
Finance multi (FL2→FC2)	75%	87.5%	+12.5 pp
Healthcare single (HL1→HC1)	72.5%	72.5%	tie
Healthcare multi (HL2→HC2)	57.5%	87.5%	+30 pp

Cost and LLM calls (portfolio, equal-weight)

Metric	Overall	Finance	Healthcare
Fewer LLM calls	~44%	~66%	~22%
Lower modeled Gemini cost	~35%	~64%	~6%

Healthcare multi saves modest cost by design (facts-only cache, judgment hops always re-run). Lead with accuracy (+30 pp), not cost. Do not use pre-fix run 20260703_042206 for HC2 cost claims.

Full report: benchmark/results/azure_20260704_212111/.../COMPARISON_REPORT.md · audit numbers: handoffs/handoffbackaudit.md

pip install -e ".[benchmark,gemini]"
python -m benchmark.run_scenarios --tier light --scenarios all   # needs GEMINI_API_KEY
chorusgraph-audit --log tests/fixtures/audit_cold_queries.jsonl  # no API key

---

Enterprise features

Capability	Status
Native engine (no LangGraph on product path)	✅
CI — 329+ tests, deterministic tier (no live keys)	✅
Resilience, security, observability	✅
Docker / k8s deploy	✅ docs/DEPLOY.md
Frozen public API 1.0	✅ docs/API_1_0.md
SQLite durable graph (free tier)	✅
Postgres persistence + enterprise license	✅ license-gated
External security audit / production SLO soak	🟡 Phase 2

Readiness scorecard: docs/ENTERPRISE_READINESS.md · threat model: docs/THREAT_MODEL.md

---

Documentation

Doc	Description
docs/INSTALL.md	pip extras, PrismRAG walkthrough, audit CLI
docs/DEVELOPER_GUIDE.md	Build agents on native Graph
docs/PLUGINS.md	Cache, memory, tools, retrieval ports
docs/COMPOSE.md	ChorusStack composition patterns
docs/WHITEPAPER.md	Product thesis + technical depth
docs/BENCHMARK.md	Fairness methodology
docs/CACHE_PROFILES.md	Safe replay policies by domain
docs/STABILITY.md	1.0 API stability guarantee
docs/TERMINOLOGY.md	ChorusGraph vs LangGraph naming policy
benchmark/SCENARIOS.md	FL/FC/HL/HC scenario matrix
docs/AI_IDE_PROMPTS.md	Cursor / Copilot install & migration prompts

---

Development

git clone https://github.com/insightitsGit/ChorusGraph.git
cd ChorusGraph
pip install -e ".[dev,benchmark,gemini,retrieval]"
pytest                    # deterministic tier — no API keys
pytest -m live            # live Gemini (needs GEMINI_API_KEY)
ruff check tests .github

Contributing workflow: docs/WORKFLOW.md · process: docs/PROCESS.md

---

Extras

Extra	Purpose
retrieval	Chroma + PrismRAGRetrievalBackend
gemini	Live Gemini examples
cortex	PrismCortex L3 memory
benchmark	LangGraph baselines (FL/HL) + chromadb
benchmark-healthcare	Healthcare benchmark scenarios (HC1/HC2)
postgres	Postgres DSN paths in deploy docs
postgres-checkpoint	LangGraph Postgres checkpointer (optional)
langgraph	Baselines / compat tests — not required for core product
dev	pytest, ruff, mypy, coverage
enterprise-ci	Full CI matrix locally

Lockfile: requirements-lock.txt · release notes: CHANGELOG.md · docs/RELEASE.md

---

Roadmap

Shipped in 1.0: native engine, semantic cache, retrieval plug-in, Route Ledger, SQLite persistence, benchmarks, deploy packaging, frozen public API.

Phase 2 (documented, in progress):

Item	Status
Postgres-native Cortex GraphStore	🟡 SQLite ships today
Ledger token fields for live dollar reporting in chorusgraph-audit --ledger	🟡 schema sign-off pending
CHORUS cipher external audit	TLS default; cipher opt-in
Production Azure soak SLO sign-off	harness shipped
External penetration test certification	pre-regulated-customer
Prebuilt agent nodes (ReAct / supervisor)	roadmap primitive

Details: docs/WHITEPAPER.md §9 · docs/ENTERPRISE_READINESS.md

---

License

Apache-2.0 — see LICENSE.

Built by Insight IT Solutions. Dogfooded in production agent hubs. Part of the Prism family (PrismLang, PrismCache, PrismCortex, PrismRAG).

Questions / enterprise: open a GitHub issue or see docs/WHITEPAPER.md for commercial framing.