Native agent runtime with semantic cache, swappable retrieval (PrismRAG), auditable memory, and enterprise hardening — one pip install, five plug-in ports.
pip install "chorusgraph==1.3.0"
chorusgraph-demoInteractive demo: insightitsGit.github.io/ChorusGraph/demo.html — live playground (pick a mode, type a query, watch the ledger; repeat FX for cache HIT). No API key.
ChorusGraph = native engine + Prism stack · LangGraph = optional baseline for A/B comparison only (
docs/TERMINOLOGY.md)
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.
AI assistants: docs/ai-overview.md · alias docs/llm-context.md · architecture docs/architecture.md · IDE prompts docs/AI_IDE_PROMPTS.md.
- You want to stay on LangGraph APIs only and do not want a native runtime.
- You need a standalone vector database product (use your DB; attach via
RetrievalBackend). - You only need a single LLM call with no graph, cache, or audit requirements.
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) |
| Concurrent identical misses (stampede) | Opt-in L1 single-flight — one leader computes; followers join (ADR-006) |
| Stuck ReAct thrash (same tool+args) | Default stop_on_repeated_action=True — exact replay stops the loop (ADR-007) |
| Need halt/verify before LLM tokens | Provider-boundary interceptors — ctx.call_llm + register_interceptor (ADR-008) |
| Stale L1 answers after a fact correction | mark_revalidate → force_refresh (skip disabled until re-seed) |
| RAG re-encodes the corpus every turn | Warm chunk vectors + public get_chunk_vectors (384-d, zero re-embed) |
| RAG is another integration project | RetrievalBackend plug-in — keyword default, PrismRAG vector opt-in |
| “Why did the agent say that?” | Route Ledger + rule_chain + optional kind/detail (e.g. shine.verdict) |
| Orchestration + ops duct tape | Native scheduler, health endpoints, Docker/k8s packaging |
| “Will this save us money?” | chorusgraph-audit — cold log simulation + pilot ledger reports |
pip install chorusgraphfrom 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 # routing + ledger (LLM-free)
chorusgraph-use-cases # patterns + multi-agent + cache + warm chunks + cortex
chorusgraph-use-cases cache # L1 PrismCache: miss → seed → hit
chorusgraph-use-cases warm_chunks # L2 warm partitions (ADR-005)
chorusgraph-use-cases cortex # L3 right lifecycle (teaching stub)
chorusgraph-finance-patterns # live Gemini + cache_gate (needs GEMINI_API_KEY)
chorusgraph-finance-memory # live Cortex + checkpoints (needs GEMINI_API_KEY)
chorusgraph-audit --log your_queries.jsonl # semantic gate on your logs (no API key)Interactive demo: demo.html — browser playground: type a query, run a mode, see Route Ledger + cache HIT on repeat.
Developer guide: docs/DEVELOPER_GUIDE.md — planning & reasoning, domain performance (finance vs healthcare), code examples.
| Design | CLI | Best for |
|---|---|---|
| Built-in cache (L1) | chorusgraph-use-cases cache |
Repeat / paraphrase — skip LLM on hit |
| Warm chunks (L2) | chorusgraph-use-cases warm_chunks |
Stable KB RAG — index once, query-only retrieve |
| PrismCortex (L3) | chorusgraph-use-cases cortex |
User/session facts — recall ingress, async digest |
| ReAct | chorusgraph-use-cases react |
Unknown tool order, exploration |
| Plan-and-Solve | chorusgraph-use-cases plan_solve |
Fixed checklist, known tools |
| Reflection | chorusgraph-use-cases reflection |
Draft must pass a validator |
| Multi-agent | chorusgraph-use-cases multi_agent |
Researcher → Writer → Validator role graph |
ChorusStack.defaults() attaches PrismCache + Cortex memory by default. Opt into warm chunks with index(partition=, version=) + warm_retrieval(). Details: chorusgraph/examples/use_cases/ · docs/CACHE_PROFILES.md · docs/ADR-005-warm-chunk-vectors.md.
Full install guide: docs/INSTALL.md · AI IDE prompts: docs/AI_IDE_PROMPTS.md
| Feature | Description |
|---|---|
| Native graph engine | BSP scheduler, envelope channels, conditional routing — no LangGraph on product paths |
| LLM call interceptors | NodeContext.call_llm + register_interceptor — halt / reroute before tokens (ADR-008); Agent.with_interceptors |
| Semantic cache (L1) | Built-in PrismCache via ChorusStack.defaults() — two-stage gate; demo: chorusgraph-use-cases cache |
| Cache force-refresh | mark_revalidate(...) → Decision.force_refresh — REPLAY_SAFE skip unchanged until the bit is set |
| L1 single-flight | Opt-in miss coalescing for exact/fingerprint + global/tenant keys (ADR-006); default off |
| Retrieval (L2) | Keyword default; PrismRAGRetrievalBackend for vector + taxonomy (opt-in extra) |
| Warm chunk vectors (L2) | index(partition, version) + warm_retrieval + get_chunk_vectors / bump_partition_version (ADR-005) |
| Memory (L3) | PrismCortex ≥0.3.0 via chorusgraph[cortex] ([prism-plus]) — on_event / bind_cache_revalidate for corrections |
| Route Ledger | Per-hop audit: cache hits, scores, rule_chain, optional kind/detail (e.g. shine.verdict) |
| 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) |
| Agent patterns | ReAct, Plan-Solve, Reflection via chorusgraph.agents.Agent — ReAct stops exact tool+args thrash by default (ADR-007) |
| Multi-agent roles | Researcher / Writer / Validator on native Graph — FC2/HC2 + chorusgraph-use-cases multi_agent |
| Benchmark matrix | 8 scenarios (FL/FC/HL/HC) with fairness disclosure |
| Deploy packaging | Dockerfile, docker-compose, k8s manifests |
| 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.
┌─────────────────────────────────────────────────────────────┐
│ 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
Four swappable ports on ChorusStack (plus optional enterprise persistence) — 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) # opt-in speed: partition="kb_markdown", version=...
stack = (
ChorusStack.defaults(tenant_id="acme")
.with_retrieval(backend)
.with_cache(RedisCacheBackend(tenant_id="acme", redis_url="redis://localhost:6379/0"))
)
# stack.warm_retrieval(partition="kb_markdown") # process boot — see ADR-005Full plug-in guide: docs/PLUGINS.md
New in 1.3.0 (PrismShine hooks):
- LLM call interceptors —
NodeContext.call_llm+CompiledGraph.register_interceptor(before_llm/after_llm);Agent.with_interceptors; opt-in, inert when unused - Cache force-refresh —
mark_revalidate(...)→Decision.force_refresh(CACHE_PROFILES.md§9); REPLAY_SAFE skip unchanged when bit unset - Warm public API —
get_chunk_vectors(384-d) +bump_partition_version+encoder_artifact_id(viaprismlang.encoder.model_id()) - Ledger
kind/detail(e.g.shine.verdict) — Sqlite round-trip +chorusgraph-auditcustom-step visibility; cache-decisioncreated_atfrom prismlib-plus ≥0.8.0 store metadata - Optional
Graph.add_node(..., consumes=[...])onNodeContext - Floors:
prismlang≥0.1.2,prismlib-plus≥0.8.0; cortex extraprismcortex[prism-plus,gemini]≥0.3.0(do not mix with[prism])
New in 1.2.0:
- L1 single-flight (opt-in) —
CacheProfile(single_flight=True)orChorusStack.with_flight(FlightPolicy(enabled=True)) - ReAct anti-thrash default — exact repeated tool+args stops the loop; set
stop_on_repeated_action=Falseto opt out
New in 1.1.0 (optional): Warm chunk vectors — for production RAG that reuses a knowledge corpus, index once by partition/version, warm at worker boot, and retrieve with query-only embed (vector_64 on chunks for free Resonance rerank). Recommended when retrieve latency matters. Enable via warm_retrieval() + rerank_policy="vectors_only". Defaults stay 1.0.x-compatible — nothing above changes unless you opt in.
| Layer | Component | Role |
|---|---|---|
| L0 — hop | PrismLang ≥0.1.2 | 64-d state compression + rule_chain + encoder.model_id() |
| L1 — cache | PrismCache via prismlib-plus ≥0.8.0 | Semantic gate, Resonance recall, HitMeta / created_at |
| L2 — knowledge | Retrieval plug-in | Keyword default · vector + taxonomy opt-in |
| rerank | PrismResonance | Shared substrate rerank |
| L3 — memory | PrismCortex ≥0.3.0 ([prism-plus]) |
Structured memory + on_event corrections |
| 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. Install cortex with pip install "chorusgraph[cortex]" (uses [prism-plus]; do not also install prismcortex[prism]).
PrismGuard (0.1.4) is a separate package — not a ChorusStack port. Install it alongside ChorusGraph when you want an auditable prompt-injection check before retrieve / LLM hops:
pip install chorusgraph "prismguard[prism,guard-model]==0.1.4"
prismguard-model download # ~705 MB ONNX — not in the wheel; from GitHub Release v0.1.2from prismguard.integrations.chorusgraph import (
create_checker_from_env,
make_guard_handler,
route_after_guard,
)
checker = create_checker_from_env() # once per process
guard = make_guard_handler(checker)
# START → guard → [blocked → END | retrieve → …]
# Wire with Graph.add_node("guard", dict_node_adapter(guard, hop="guard"))
# Place guard before cache-gated hops so blocked prompts never seed cache| Link | URL |
|---|---|
| PyPI | https://pypi.org/project/prismguard/ · 0.1.4 |
| GitHub | https://github.com/insightitsGit/PrismGuard |
| Integration guide | https://github.com/insightitsGit/PrismGuard/blob/main/docs/integration-guide.md |
| ONNX model release | https://github.com/insightitsGit/PrismGuard/releases/tag/v0.1.2 |
See also docs/PLUGINS.md.
Fair A/B vs competent LangGraph baselines — same model, tools, prompts, workload.
| Tier | Run ID | Tasks/scenario | Role |
|---|---|---|---|
| Mid (canonical) | mid_20260708_111539 |
100 | Primary regression + outreach proof |
| Heavy (scale) | heavy_20260708_140300 |
300 | Scale validation + whitepaper / diligence |
| Smoke | light_20260708_101409 |
40 | CI / quick regression |
Start here: docs/BENCHMARK_RESULTS.md · archive index: benchmark/results/mvp_scenarios/README.md · machine pointer: benchmark/results/mvp_scenarios/latest.json
Methodology: benchmark/FAIRNESS_H9.md · consolidated tables: benchmark/results/BENCHMARK_LATENCY_LLM_SUMMARY.md
July 2026 methodology fixes (benchmark-only — no library release): FL2 researcher prompt uses annual_rate_pct (matches tool schema); comparison script counts agent/tool errors in LangGraph success denominators. Supersedes pre-fix runs that inflated FL2 vs FC2. Do not cite invalid quota run heavy_20260708_124337.
| Scenario | LangGraph | ChorusGraph | Delta |
|---|---|---|---|
| Finance single (FL1→FC1) | 87.0% | 98.0% | +11.0 pp |
| Finance multi (FL2→FC2) | 87.0% | 94.0% | +7.0 pp |
| Healthcare single (HL1→HC1) | 74.0% | 79.0% | +5.0 pp |
| Healthcare multi (HL2→HC2) | 59.0% | 85.0% | +26 pp |
| Scenario | LangGraph | ChorusGraph | Delta |
|---|---|---|---|
| Finance single (FL1→FC1) | 90.0% | 96.7% | +6.7 pp |
| Finance multi (FL2→FC2) | 89.0% | 93.0% | +4.0 pp |
| Healthcare single (HL1→HC1) | 73.7% | 84.0% | +10.3 pp |
| Healthcare multi (HL2→HC2) | 62.3% | 77.3% | +15 pp |
| Scenario | LLM calls (L → C) | Mean latency ms (L → C) | Cache hit (C) |
|---|---|---|---|
| FL1 / FC1 | 3.24 → 0.77 (−76%) | 4760 → 1348 (−72%) | 52% |
| FL2 / FC2 | 2.03 → 0.69 (−66%) | 3269 → 1085 (−67%) | 40% |
| HL1 / HC1 | 3.00 → 1.56 (−48%) | 7036 → 3990 (−43%) | 60% |
| HL2 / HC2 | 3.82 → 3.15 (−18%) | 10296 → 10753 (tie) | 51% |
| Scenario | LLM calls (L → C) | Mean latency ms (L → C) | Cache hit (C) |
|---|---|---|---|
| FL1 / FC1 | 3.33 → 0.80 (−76%) | 4972 → 1318 (−73%) | 49.7% |
| FL2 / FC2 | 2.04 → 0.75 (−63%) | 3081 → 1335 (−57%) | 34.7% |
| HL1 / HC1 | 2.94 → 1.33 (−55%) | 7105 → 3812 (−46%) | 72.7% |
| HL2 / HC2 | 3.85 → 2.67 (−31%) | 10354 → 9537 (−8%; p95 tie) | 79.0% |
Healthcare multi saves fewer LLM calls by design (facts-only cache, judgment hops re-run). Lead with accuracy (+26 pp mid / +15 pp heavy), not cost; disclose HC2 p95 wall-clock tie.
Each run ships a human report, run metadata, and a tarball of per-task JSONL traces.
| Tier | Comparison report | Raw results (results.tar.gz) |
Run metadata |
|---|---|---|---|
| Light (40) | light_20260708_101409/COMPARISON_REPORT.md |
results.tar.gz |
run_meta.json |
| Mid (100) | mid_20260708_111539/COMPARISON_REPORT.md |
results.tar.gz |
run_meta.json |
| Heavy (300) | heavy_20260708_140300/COMPARISON_REPORT.md |
results.tar.gz |
run_meta.json |
Extract raw traces: tar -xzf results.tar.gz — contains per-scenario *.jsonl and comparison.json.
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| 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
| Doc | Description |
|---|---|
docs/ai-overview.md |
Concise summary for humans and coding assistants (canonical) |
docs/llm-context.md |
Alias → ai-overview |
docs/architecture.md |
Stack placement diagram |
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/ADR-005-warm-chunk-vectors.md |
Optional L2 warm chunk vectors (1.1.0) — use cases & benefits |
docs/ADR-006-l1-single-flight.md |
Opt-in L1 single-flight miss coalescing (1.2.0) |
docs/ADR-007-react-repeated-action-default.md |
ReAct stop_on_repeated_action default on (1.2.0) |
docs/ADR-008-llm-call-interceptors.md |
LLM call port + register_interceptor (1.3.0) |
docs/COMPOSE.md |
ChorusStack composition patterns |
docs/WHITEPAPER.md |
Product thesis + technical depth |
docs/BENCHMARK.md |
Fairness methodology |
docs/BENCHMARK_RESULTS.md |
Published A/B results (mid + heavy) + artifact links |
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 |
- Use cases — ReAct, Plan-Solve, Reflection, multi-agent, PrismCache, warm chunks, PrismCortex lifecycle (LLM-free CLI)
- Local RAG with Chroma + ChorusGraph — offline vector RAG with native retrieve-to-answer graph
- Interactive walkthrough: website/demo.html (cache miss/hit · warm chunks · Cortex)
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 .githubContributing: CONTRIBUTING.md · workflow: docs/WORKFLOW.md · process: docs/PROCESS.md
| 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
Shipped in 1.0: native engine, semantic cache, retrieval plug-in, Route Ledger, SQLite persistence, benchmarks, deploy packaging, frozen public API.
Shipped in 1.1.0: optional warm chunk vectors (L2) — partition/version index, warm_retrieval, query-only retrieve, opt-in rerank_policy for RAG latency.
Shipped in 1.2.0:
- Opt-in L1 single-flight — coalesce concurrent exact/fingerprint misses (default off)
- Safer ReAct default —
stop_on_repeated_action=True; opt out for intentional same tool+args retries
Shipped in 1.3.0:
- LLM call interceptors at the provider boundary (
call_llm/register_interceptor) - PrismShine hooks:
mark_revalidate,get_chunk_vectors,bump_partition_version, ledgerkind/detail
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
Apache-2.0 — see LICENSE.
| Contributing | Dev setup, PR checklist, FC/HC vs FL/HL rules |
| Code of conduct | Contributor Covenant |
| Security policy | Private vulnerability reporting |
Built by Insight IT Solutions. Dogfooded in production agent hubs. Part of the Prism family (PrismLang, PrismCache, PrismCortex, PrismRAG, PrismGuard 0.1.4).
Questions / enterprise: open a GitHub issue or see docs/WHITEPAPER.md for commercial framing.