Metadata-Version: 2.4
Name: chorusgraph
Version: 1.3.0
Summary: Native agent graph runtime with Prism cache, memory, swappable PrismRAG retrieval, and Route Ledger
Author: Insight IT Solutions
License: Apache-2.0
Project-URL: Homepage, https://github.com/insightitsGit/ChorusGraph
Project-URL: Documentation, https://github.com/insightitsGit/ChorusGraph/tree/master/docs
Project-URL: Repository, https://github.com/insightitsGit/ChorusGraph
Project-URL: Changelog, https://github.com/insightitsGit/ChorusGraph/blob/master/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/insightitsGit/ChorusGraph/issues
Keywords: agents,llm,semantic-cache,rag,prismrag,graph-runtime,orchestration
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.24
Requires-Dist: pydantic>=2.0
Requires-Dist: prismlang>=0.1.2
Requires-Dist: prismlib-plus>=0.8.0
Requires-Dist: prismresonance>=0.3.0
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2.0; extra == "langgraph"
Requires-Dist: langgraph-checkpoint-sqlite>=2.0; extra == "langgraph"
Provides-Extra: benchmark
Requires-Dist: chromadb>=0.4; extra == "benchmark"
Requires-Dist: langgraph>=0.2.0; extra == "benchmark"
Requires-Dist: langgraph-checkpoint-sqlite>=2.0; extra == "benchmark"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Provides-Extra: postgres-checkpoint
Requires-Dist: langgraph-checkpoint-postgres>=2.0; extra == "postgres-checkpoint"
Requires-Dist: langgraph>=0.2.0; extra == "postgres-checkpoint"
Provides-Extra: cortex
Requires-Dist: prismcortex[gemini,prism-plus]>=0.3.0; extra == "cortex"
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == "gemini"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: types-requests>=2.32; extra == "dev"
Requires-Dist: cyclonedx-bom>=4.0; extra == "dev"
Requires-Dist: pip-tools>=7.4; extra == "dev"
Requires-Dist: google-genai>=1.0; extra == "dev"
Provides-Extra: enterprise-ci
Requires-Dist: chorusgraph[benchmark,benchmark-healthcare,dev,gemini]; extra == "enterprise-ci"
Provides-Extra: benchmark-healthcare
Requires-Dist: chromadb>=0.4; extra == "benchmark-healthcare"
Provides-Extra: retrieval
Requires-Dist: chromadb>=0.4; extra == "retrieval"
Dynamic: license-file

# ChorusGraph

[![CI](https://github.com/insightitsGit/ChorusGraph/actions/workflows/ci.yml/badge.svg)](https://github.com/insightitsGit/ChorusGraph/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/chorusgraph.svg)](https://pypi.org/project/chorusgraph/1.3.0/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.3.0-informational)](https://pypi.org/project/chorusgraph/1.3.0/)

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

```bash
pip install "chorusgraph==1.3.0"
chorusgraph-demo
```

**Interactive demo:** [insightitsGit.github.io/ChorusGraph/demo.html](https://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`](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.

**AI assistants:** [docs/ai-overview.md](docs/ai-overview.md) · alias [docs/llm-context.md](docs/llm-context.md) · architecture [docs/architecture.md](docs/architecture.md) · IDE prompts [docs/AI_IDE_PROMPTS.md](docs/AI_IDE_PROMPTS.md).

### When NOT to use ChorusGraph

- 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.

---

## 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) |
| Concurrent identical misses (stampede) | Opt-in L1 single-flight — one leader computes; followers join ([ADR-006](docs/ADR-006-l1-single-flight.md)) |
| Stuck ReAct thrash (same tool+args) | Default `stop_on_repeated_action=True` — exact replay stops the loop ([ADR-007](docs/ADR-007-react-repeated-action-default.md)) |
| Need halt/verify **before** LLM tokens | Provider-boundary interceptors — `ctx.call_llm` + `register_interceptor` ([ADR-008](docs/ADR-008-llm-call-interceptors.md)) |
| 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 |

---

## Quick Start (30 seconds)

```bash
pip install chorusgraph
```

```python
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'}
```

```bash
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](https://insightitsGit.github.io/ChorusGraph/demo.html) — browser playground: type a query, run a mode, see Route Ledger + cache HIT on repeat.

**Developer guide:** [`docs/DEVELOPER_GUIDE.md`](docs/DEVELOPER_GUIDE.md) — planning & reasoning, domain performance (finance vs healthcare), code examples.

### Use cases (patterns, stack layers, multi-agent)

| 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/`](chorusgraph/examples/use_cases/) · [`docs/CACHE_PROFILES.md`](docs/CACHE_PROFILES.md) · [`docs/ADR-005-warm-chunk-vectors.md`](docs/ADR-005-warm-chunk-vectors.md).

Full install guide: [`docs/INSTALL.md`](docs/INSTALL.md) · AI IDE prompts: [`docs/AI_IDE_PROMPTS.md`](docs/AI_IDE_PROMPTS.md)

---

## Features

| 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](docs/ADR-008-llm-call-interceptors.md)); `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](docs/ADR-006-l1-single-flight.md)); 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](docs/ADR-005-warm-chunk-vectors.md)) |
| **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](docs/ADR-007-react-repeated-action-default.md)) |
| **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 |

---

## 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/COMPOSE.md) · [`docs/DEVELOPER_GUIDE.md`](docs/DEVELOPER_GUIDE.md)

---

## Plugin system

Four swappable ports on [`ChorusStack`](chorusgraph/compose/stack.py) (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 |

```python
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-005
```

Full plug-in guide: [`docs/PLUGINS.md`](docs/PLUGINS.md)

**New in 1.3.0 (PrismShine hooks):**
- [LLM call interceptors](docs/ADR-008-llm-call-interceptors.md) — `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`](docs/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` (via `prismlang.encoder.model_id()`)
- Ledger `kind` / `detail` (e.g. `shine.verdict`) — Sqlite round-trip + `chorusgraph-audit` custom-step visibility; cache-decision `created_at` from prismlib-plus ≥0.8.0 store metadata
- Optional `Graph.add_node(..., consumes=[...])` on `NodeContext`
- Floors: `prismlang≥0.1.2`, `prismlib-plus≥0.8.0`; cortex extra `prismcortex[prism-plus,gemini]≥0.3.0` (do not mix with `[prism]`)

**New in 1.2.0:**
- [L1 single-flight](docs/ADR-006-l1-single-flight.md) (opt-in) — `CacheProfile(single_flight=True)` or `ChorusStack.with_flight(FlightPolicy(enabled=True))`
- ReAct [anti-thrash default](docs/ADR-007-react-repeated-action-default.md) — exact repeated tool+args stops the loop; set `stop_on_repeated_action=False` to opt out

**New in 1.1.0 (optional):** [Warm chunk vectors](docs/ADR-005-warm-chunk-vectors.md) — 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.

---

## Prism ecosystem

| 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]`).

### Companion: PrismGuard (prompt-injection firewall)

[PrismGuard](https://pypi.org/project/prismguard/) ([0.1.4](https://pypi.org/project/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:

```bash
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.2
```

```python
from 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](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`](docs/PLUGINS.md#companion-prismguard).

---

## Benchmarks

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`](docs/BENCHMARK_RESULTS.md) · archive index: [`benchmark/results/mvp_scenarios/README.md`](benchmark/results/mvp_scenarios/README.md) · machine pointer: [`benchmark/results/mvp_scenarios/latest.json`](benchmark/results/mvp_scenarios/latest.json)

Methodology: [`benchmark/FAIRNESS_H9.md`](benchmark/FAIRNESS_H9.md) · consolidated tables: [`benchmark/results/BENCHMARK_LATENCY_LLM_SUMMARY.md`](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`.

### Task success (LangGraph → ChorusGraph) — mid tier, n=100

| 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** |

### Task success — heavy tier, n=300

| 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** |

### LLM calls and latency (mid tier, mean per task)

| 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% |

### LLM calls and latency (heavy tier, mean per task)

| 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.

### Full reports and raw data (reproducible artifacts)

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`](benchmark/results/azure_light_20260708_101409/mvp_scenarios/light_20260708_101409/COMPARISON_REPORT.md) | [`results.tar.gz`](benchmark/results/azure_light_20260708_101409/mvp_scenarios/light_20260708_101409/results.tar.gz) | [`run_meta.json`](benchmark/results/azure_light_20260708_101409/mvp_scenarios/light_20260708_101409/run_meta.json) |
| **Mid (100)** | [`mid_20260708_111539/COMPARISON_REPORT.md`](benchmark/results/azure_mid_20260708_111539/mvp_scenarios/mid_20260708_111539/COMPARISON_REPORT.md) | [`results.tar.gz`](benchmark/results/azure_mid_20260708_111539/mvp_scenarios/mid_20260708_111539/results.tar.gz) | [`run_meta.json`](benchmark/results/azure_mid_20260708_111539/mvp_scenarios/mid_20260708_111539/run_meta.json) |
| **Heavy (300)** | [`heavy_20260708_140300/COMPARISON_REPORT.md`](benchmark/results/azure_heavy_20260708_140300/mvp_scenarios/heavy_20260708_140300/COMPARISON_REPORT.md) | [`results.tar.gz`](benchmark/results/azure_heavy_20260708_140300/mvp_scenarios/heavy_20260708_140300/results.tar.gz) | [`run_meta.json`](benchmark/results/azure_heavy_20260708_140300/mvp_scenarios/heavy_20260708_140300/run_meta.json) |

Extract raw traces: `tar -xzf results.tar.gz` — contains per-scenario `*.jsonl` and `comparison.json`.

```bash
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`](docs/DEPLOY.md) |
| Frozen public API 1.0 | ✅ [`docs/API_1_0.md`](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`](docs/ENTERPRISE_READINESS.md) · threat model: [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md)

---

## Documentation

| Doc | Description |
|-----|-------------|
| **[`docs/ai-overview.md`](docs/ai-overview.md)** | Concise summary for humans and coding assistants (canonical) |
| **[`docs/llm-context.md`](docs/llm-context.md)** | Alias → ai-overview |
| [`docs/architecture.md`](docs/architecture.md) | Stack placement diagram |
| [`docs/INSTALL.md`](docs/INSTALL.md) | pip extras, PrismRAG walkthrough, audit CLI |
| [`docs/DEVELOPER_GUIDE.md`](docs/DEVELOPER_GUIDE.md) | Build agents on native `Graph` |
| [`docs/PLUGINS.md`](docs/PLUGINS.md) | Cache, memory, tools, retrieval ports |
| [`docs/ADR-005-warm-chunk-vectors.md`](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`](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`](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`](docs/ADR-008-llm-call-interceptors.md) | LLM call port + `register_interceptor` (1.3.0) |
| [`docs/COMPOSE.md`](docs/COMPOSE.md) | `ChorusStack` composition patterns |
| [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md) | Product thesis + technical depth |
| [`docs/BENCHMARK.md`](docs/BENCHMARK.md) | Fairness methodology |
| [`docs/BENCHMARK_RESULTS.md`](docs/BENCHMARK_RESULTS.md) | Published A/B results (mid + heavy) + artifact links |
| [`docs/CACHE_PROFILES.md`](docs/CACHE_PROFILES.md) | Safe replay policies by domain |
| [`docs/STABILITY.md`](docs/STABILITY.md) | 1.0 API stability guarantee |
| [`docs/TERMINOLOGY.md`](docs/TERMINOLOGY.md) | ChorusGraph vs LangGraph naming policy |
| [`benchmark/SCENARIOS.md`](benchmark/SCENARIOS.md) | FL/FC/HL/HC scenario matrix |
| [`docs/AI_IDE_PROMPTS.md`](docs/AI_IDE_PROMPTS.md) | Cursor / Copilot install & migration prompts |

---

## Examples

- [Use cases](chorusgraph/examples/use_cases/) — ReAct, Plan-Solve, Reflection, multi-agent, **PrismCache**, **warm chunks**, **PrismCortex** lifecycle (LLM-free CLI)
- [Local RAG with Chroma + ChorusGraph](chorusgraph/examples/chroma_local_rag/) — offline vector RAG with native retrieve-to-answer graph
- Interactive walkthrough: [website/demo.html](https://insightitsGit.github.io/ChorusGraph/demo.html) (cache miss/hit · warm chunks · Cortex)

---

## Development

```bash
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: [`CONTRIBUTING.md`](CONTRIBUTING.md) · workflow: [`docs/WORKFLOW.md`](docs/WORKFLOW.md) · process: [`docs/PROCESS.md`](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`](CHANGELOG.md) · [`docs/RELEASE.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.

**Shipped in 1.1.0:** optional [warm chunk vectors](docs/ADR-005-warm-chunk-vectors.md) (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](docs/ADR-006-l1-single-flight.md) — coalesce concurrent exact/fingerprint misses (default off)
- Safer ReAct default — [`stop_on_repeated_action=True`](docs/ADR-007-react-repeated-action-default.md); opt out for intentional same tool+args retries

**Shipped in 1.3.0:**
- [LLM call interceptors](docs/ADR-008-llm-call-interceptors.md) at the provider boundary (`call_llm` / `register_interceptor`)
- PrismShine hooks: `mark_revalidate`, `get_chunk_vectors`, `bump_partition_version`, ledger `kind`/`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`](docs/WHITEPAPER.md) §9 · [`docs/ENTERPRISE_READINESS.md`](docs/ENTERPRISE_READINESS.md)

---

## License

Apache-2.0 — see [LICENSE](LICENSE).

## Community

| | |
|---|---|
| [Contributing](CONTRIBUTING.md) | Dev setup, PR checklist, FC/HC vs FL/HL rules |
| [Code of conduct](CODE_OF_CONDUCT.md) | Contributor Covenant |
| [Security policy](SECURITY.md) | Private vulnerability reporting |

Built by [Insight IT Solutions](https://github.com/insightitsGit). Dogfooded in production agent hubs. Part of the Prism family (PrismLang, PrismCache, PrismCortex, PrismRAG, [PrismGuard 0.1.4](https://pypi.org/project/prismguard/0.1.4/)).

**Questions / enterprise:** open a [GitHub issue](https://github.com/insightitsGit/ChorusGraph/issues) or see [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md) for commercial framing.
