conereplay 0.1.0__tar.gz

conereplay-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 Naveen Singh Dhillon and Rajvir Singh Dhillon.
+All rights reserved.
+
+Patent pending: U.S. Provisional Application CDRA-PROV-2026-001, filed with the
+United States Patent and Trademark Office.
+
+This source code and accompanying materials are proprietary and confidential.
+No license or permission is granted, expressly or by implication, to any person
+or entity to copy, modify, redistribute, sublicense, publicly perform, publicly
+display, or create derivative works of any portion of this repository, except
+as explicitly authorized in writing by the copyright holders.
+
+Unauthorized use, reproduction, or distribution constitutes infringement of
+copyright, trade secret, and/or pending patent rights and may be prosecuted to
+the fullest extent permitted by law.

conereplay-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: conereplay
+Version: 0.1.0
+Summary: Pre-deploy regression harness for multi-agent AI: cone-bounded divergent replay with counterfactual oracle. Patent pending (US Provisional CDRA-PROV-2026-001).
+Author: Naveen Singh Dhillon, Rajvir Singh Dhillon
+License: Proprietary
+Project-URL: Homepage, https://conereplay.com
+Project-URL: Repository, https://github.com/gitdhillonai/conereplay
+Keywords: llm,multi-agent,replay,counterfactual,observability,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=3.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pydantic-settings>=2.0
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Requires-Dist: langchain-core>=0.3; extra == "langgraph"
+Provides-Extra: providers
+Requires-Dist: anthropic>=0.40; extra == "providers"
+Requires-Dist: openai>=1.50; extra == "providers"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "server"
+Requires-Dist: sqlalchemy>=2.0; extra == "server"
+Requires-Dist: psycopg2-binary>=2.9; extra == "server"
+Requires-Dist: redis>=5.0; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: sqlalchemy>=2.0; extra == "dev"
+Requires-Dist: langgraph>=0.2; extra == "dev"
+Requires-Dist: langchain-core>=0.3; extra == "dev"
+Requires-Dist: anthropic>=0.40; extra == "dev"
+Requires-Dist: openai>=1.50; extra == "dev"
+Requires-Dist: tiktoken>=0.7; extra == "dev"
+Requires-Dist: opentelemetry-api>=1.20; extra == "dev"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "dev"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
+Provides-Extra: demo
+Requires-Dist: langgraph>=0.2; extra == "demo"
+Requires-Dist: langchain-core>=0.3; extra == "demo"
+Dynamic: license-file
+
+# ConeReplay
+
+Pre-deploy regression testing for multi-agent AI. Record traces from your
+production agent app, propose a change (new prompt, new tool response, new
+model), and replay only the events causally affected — everything else is
+served byte-identically from the recording.
+
+Patent pending (U.S. Provisional Application **64/043,722**). See
+[VERSIONING.md](VERSIONING.md) for SemVer commitments and
+[docs/trace-format.md](docs/trace-format.md) for the on-disk contract.
+
+## Install
+
+```bash
+pip install conereplay                   # core + CLI
+pip install conereplay[server]           # hosted trace-store server
+pip install conereplay[langgraph]        # LangGraph recording adapter
+pip install conereplay[providers]        # anthropic / openai oracle backends
+pip install conereplay[dev]              # dev tooling (pytest, ruff, mypy, pip-audit)
+```
+
+Requires Python 3.11+. Core has only two runtime deps (`networkx`,
+`pydantic`, `pydantic-settings`).
+
+## CLI quickstart
+
+```bash
+# Single-trace replay → Markdown report
+conereplay replay \
+  --trace examples/trace.json \
+  --modify examples/modify.json \
+  --report report.md
+
+# Corpus-mode regression harness → aggregate report (Markdown or HTML)
+conereplay corpus \
+  --traces examples/traces \
+  --modify examples/corpus-modify.json \
+  --report corpus.html \
+  --format html
+
+# Emit a Mermaid or Graphviz diagram of a trace's causal DAG
+conereplay diagram \
+  --trace examples/trace.json \
+  --modify examples/modify.json \
+  --format mermaid --out cone.mmd
+```
+
+See [docs/cli.md](docs/cli.md) for the full reference.
+
+## Library quickstart
+
+```python
+from conereplay import (
+    load_trace, ModificationSpec, selective_replay, compute_divergence,
+    render_markdown_report,
+)
+
+trace = load_trace("trace.json")
+mod = ModificationSpec(target_event_id="e3", substituted_output=b"POLICY: 5 days")
+divergent = selective_replay(trace, mod)
+report = compute_divergence(trace, divergent)
+print(render_markdown_report(trace, divergent, mod, report))
+```
+
+## Architecture
+
+Four layers. See [ARCHITECTURE.md](ARCHITECTURE.md) for the full picture.
+
+| Layer | Purpose | Modules |
+|---|---|---|
+| Core algorithms | Deterministic, pure-stdlib | `core/clock.py`, `core/cone.py`, `core/replay.py`, `core/diff.py` |
+| SDK | Recording + provenance | `sdk/recorder.py`, `sdk/provenance.py`, `sdk/langgraph.py` |
+| Presentation | Reports + diagrams | `core/report.py`, `core/corpus_report.py`, `core/corpus_html.py`, `core/diagram.py` |
+| Server | Hosted trace store | `server/app.py`, `server/models.py` |
+
+Supporting infrastructure:
+
+- `config.py` — validated runtime config (pydantic-settings, `CONEREPLAY_*` env)
+- `flags.py` — feature flags (`CONEREPLAY_FLAGS_*` env)
+- `logging_setup.py` — structured text/JSON logging
+- `audit.py` — append-only JSONL audit trail for compliance
+- `core/schemas.py` — pydantic contract models for trace + modification JSON
+
+## Configuration
+
+All configuration is env-driven with the `CONEREPLAY_` prefix. Defaults
+are safe for local use. Sample overrides:
+
+```bash
+export CONEREPLAY_LOG_LEVEL=debug
+export CONEREPLAY_LOG_FORMAT=json
+export CONEREPLAY_DATA_DIR=/var/lib/conereplay
+export CONEREPLAY_AUDIT_LOG_PATH=/var/log/conereplay/audit.jsonl
+export CONEREPLAY_ENABLE_AUDIT=true
+export CONEREPLAY_SERVER_DATABASE_URL=postgresql://...
+```
+
+See [docs/configuration.md](docs/configuration.md) (stub — coming soon) or
+`conereplay/config.py` for the full list.
+
+## Testing
+
+```bash
+make install-dev    # install runtime + dev deps (pytest, ruff, mypy)
+make test           # run full pytest suite
+make test-fast      # fail-fast + failed-first
+make test-cov       # with coverage report (htmlcov/)
+make lint           # ruff
+make typecheck      # mypy
+```
+
+CI (see [.github/workflows/](.github/workflows/)) runs tests + lint +
+typecheck on every push and PR against `main`. Integration tests that
+hit real LLM providers are gated behind `CONEREPLAY_INTEGRATION=1`.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for supply-chain posture and vulnerability
+disclosure. Patent-pending proprietary code; see [LICENSE](LICENSE).
+
+## Runbooks
+
+Operational procedures live in [runbooks/](runbooks/):
+
+- [deployment.md](runbooks/deployment.md) — releases + migrations
+- [on-call.md](runbooks/on-call.md) — incident triage
+- [disaster-recovery.md](runbooks/disaster-recovery.md) — backups + restore
+
+## Documentation
+<!-- generated-by: workspace-admin/doc-standardize -->
+- [Handoff](docs/HANDOFF.md)
+- [Backlog](docs/BACKLOG.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Local Development](docs/LOCAL_DEVELOPMENT.md)
+- [Testing](docs/TESTING.md)
+- [Infrastructure](docs/INFRASTRUCTURE.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Architecture Decisions](docs/decisions/)
+
+
+## Evidence and sample
+
+- [Sanitized end-to-end migration sample](examples/sanitized_migration/README.md)
+- [Reproducible attribution configuration](examples/sanitized_migration/bisect.json)
+- [Replay benchmark methodology](docs/BENCHMARKS.md)
+
+The sample is synthetic and labels fixture measurements separately from live-provider evidence.

conereplay-0.1.0/README.md

@@ -0,0 +1,151 @@
+# ConeReplay
+
+Pre-deploy regression testing for multi-agent AI. Record traces from your
+production agent app, propose a change (new prompt, new tool response, new
+model), and replay only the events causally affected — everything else is
+served byte-identically from the recording.
+
+Patent pending (U.S. Provisional Application **64/043,722**). See
+[VERSIONING.md](VERSIONING.md) for SemVer commitments and
+[docs/trace-format.md](docs/trace-format.md) for the on-disk contract.
+
+## Install
+
+```bash
+pip install conereplay                   # core + CLI
+pip install conereplay[server]           # hosted trace-store server
+pip install conereplay[langgraph]        # LangGraph recording adapter
+pip install conereplay[providers]        # anthropic / openai oracle backends
+pip install conereplay[dev]              # dev tooling (pytest, ruff, mypy, pip-audit)
+```
+
+Requires Python 3.11+. Core has only two runtime deps (`networkx`,
+`pydantic`, `pydantic-settings`).
+
+## CLI quickstart
+
+```bash
+# Single-trace replay → Markdown report
+conereplay replay \
+  --trace examples/trace.json \
+  --modify examples/modify.json \
+  --report report.md
+
+# Corpus-mode regression harness → aggregate report (Markdown or HTML)
+conereplay corpus \
+  --traces examples/traces \
+  --modify examples/corpus-modify.json \
+  --report corpus.html \
+  --format html
+
+# Emit a Mermaid or Graphviz diagram of a trace's causal DAG
+conereplay diagram \
+  --trace examples/trace.json \
+  --modify examples/modify.json \
+  --format mermaid --out cone.mmd
+```
+
+See [docs/cli.md](docs/cli.md) for the full reference.
+
+## Library quickstart
+
+```python
+from conereplay import (
+    load_trace, ModificationSpec, selective_replay, compute_divergence,
+    render_markdown_report,
+)
+
+trace = load_trace("trace.json")
+mod = ModificationSpec(target_event_id="e3", substituted_output=b"POLICY: 5 days")
+divergent = selective_replay(trace, mod)
+report = compute_divergence(trace, divergent)
+print(render_markdown_report(trace, divergent, mod, report))
+```
+
+## Architecture
+
+Four layers. See [ARCHITECTURE.md](ARCHITECTURE.md) for the full picture.
+
+| Layer | Purpose | Modules |
+|---|---|---|
+| Core algorithms | Deterministic, pure-stdlib | `core/clock.py`, `core/cone.py`, `core/replay.py`, `core/diff.py` |
+| SDK | Recording + provenance | `sdk/recorder.py`, `sdk/provenance.py`, `sdk/langgraph.py` |
+| Presentation | Reports + diagrams | `core/report.py`, `core/corpus_report.py`, `core/corpus_html.py`, `core/diagram.py` |
+| Server | Hosted trace store | `server/app.py`, `server/models.py` |
+
+Supporting infrastructure:
+
+- `config.py` — validated runtime config (pydantic-settings, `CONEREPLAY_*` env)
+- `flags.py` — feature flags (`CONEREPLAY_FLAGS_*` env)
+- `logging_setup.py` — structured text/JSON logging
+- `audit.py` — append-only JSONL audit trail for compliance
+- `core/schemas.py` — pydantic contract models for trace + modification JSON
+
+## Configuration
+
+All configuration is env-driven with the `CONEREPLAY_` prefix. Defaults
+are safe for local use. Sample overrides:
+
+```bash
+export CONEREPLAY_LOG_LEVEL=debug
+export CONEREPLAY_LOG_FORMAT=json
+export CONEREPLAY_DATA_DIR=/var/lib/conereplay
+export CONEREPLAY_AUDIT_LOG_PATH=/var/log/conereplay/audit.jsonl
+export CONEREPLAY_ENABLE_AUDIT=true
+export CONEREPLAY_SERVER_DATABASE_URL=postgresql://...
+```
+
+See [docs/configuration.md](docs/configuration.md) (stub — coming soon) or
+`conereplay/config.py` for the full list.
+
+## Testing
+
+```bash
+make install-dev    # install runtime + dev deps (pytest, ruff, mypy)
+make test           # run full pytest suite
+make test-fast      # fail-fast + failed-first
+make test-cov       # with coverage report (htmlcov/)
+make lint           # ruff
+make typecheck      # mypy
+```
+
+CI (see [.github/workflows/](.github/workflows/)) runs tests + lint +
+typecheck on every push and PR against `main`. Integration tests that
+hit real LLM providers are gated behind `CONEREPLAY_INTEGRATION=1`.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for supply-chain posture and vulnerability
+disclosure. Patent-pending proprietary code; see [LICENSE](LICENSE).
+
+## Runbooks
+
+Operational procedures live in [runbooks/](runbooks/):
+
+- [deployment.md](runbooks/deployment.md) — releases + migrations
+- [on-call.md](runbooks/on-call.md) — incident triage
+- [disaster-recovery.md](runbooks/disaster-recovery.md) — backups + restore
+
+## Documentation
+<!-- generated-by: workspace-admin/doc-standardize -->
+- [Handoff](docs/HANDOFF.md)
+- [Backlog](docs/BACKLOG.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Local Development](docs/LOCAL_DEVELOPMENT.md)
+- [Testing](docs/TESTING.md)
+- [Infrastructure](docs/INFRASTRUCTURE.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Architecture Decisions](docs/decisions/)
+
+
+## Evidence and sample
+
+- [Sanitized end-to-end migration sample](examples/sanitized_migration/README.md)
+- [Reproducible attribution configuration](examples/sanitized_migration/bisect.json)
+- [Replay benchmark methodology](docs/BENCHMARKS.md)
+
+The sample is synthetic and labels fixture measurements separately from live-provider evidence.

conereplay-0.1.0/benchmarks/__init__.py

@@ -0,0 +1,20 @@
+"""ConeReplay performance benchmarks.
+
+Reproduces the performance bound recited in Claim 14 of U.S. Provisional
+Application 64/043,722 (see key_rotaton/supporting/claims.md):
+
+  Cone computation for a 100-agent-turn trace completes in < 1s on a
+  single modern CPU core; selective replay achieves >= 80% reduction in
+  events that must be re-executed vs naive full re-execution.
+
+Run from repo root:
+
+    python -m benchmarks
+"""
+
+from __future__ import annotations
+
+__all__ = ["synthesize_trace", "run_benchmarks", "render_results_markdown"]
+
+from .bench import render_results_markdown, run_benchmarks
+from .synth import synthesize_trace

conereplay-0.1.0/benchmarks/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m benchmarks`."""
+
+from .bench import main
+
+raise SystemExit(main())

conereplay-0.1.0/benchmarks/bench.py

@@ -0,0 +1,171 @@
+"""Benchmark runner for cone computation + selective replay.
+
+Runs a sweep of trace sizes, measures wall-clock time for
+``compute_causal_cone`` and ``selective_replay``, and reports the event-
+reduction ratio (events served byte-identically vs events re-executed) as
+a proxy for the Claim 14 token-reduction metric.
+
+Emits CSV to stdout and a human-readable Markdown summary if invoked as
+``python -m benchmarks``.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from conereplay.core.cone import compute_causal_cone
+from conereplay.core.replay import ModificationSpec, selective_replay
+
+from .synth import synthesize_trace
+
+# Sweep sizes: 50, 100 (Claim 14 target), 250, 500, 1000 total events over
+# representative agent counts (4-8). Target selection: the event at 25% of
+# the trace — far enough in that there are upstream ancestors, far enough
+# from the end that many events remain out-of-cone.
+DEFAULT_SWEEP = [(10, 5), (20, 5), (50, 5), (125, 4), (125, 8)]
+TARGET_FRACTION = 0.25
+
+
+@dataclass(frozen=True)
+class Row:
+    n_turns: int
+    n_agents: int
+    n_events: int
+    cone_size: int
+    event_reduction_pct: float
+    cone_time_ms: float
+    replay_time_ms: float
+
+
+def run_benchmarks(sweep: list[tuple[int, int]] | None = None) -> list[Row]:
+    """Run the benchmark sweep and return per-size rows."""
+    sweep = sweep or DEFAULT_SWEEP
+    out: list[Row] = []
+    for n_turns, n_agents in sweep:
+        trace = synthesize_trace(n_turns, n_agents)
+        target_idx = max(0, int(len(trace) * TARGET_FRACTION))
+        target_id = trace[target_idx].event_id
+        modification = ModificationSpec(
+            target_event_id=target_id,
+            substituted_output=b"MODIFIED_OUTPUT_FOR_BENCH",
+        )
+
+        # Warm-up + measure (single-shot is adequate for pure-Python algorithms).
+        t0 = time.perf_counter()
+        cone = compute_causal_cone(target_id, trace)
+        t1 = time.perf_counter()
+
+        t2 = time.perf_counter()
+        selective_replay(trace, modification)
+        t3 = time.perf_counter()
+
+        reduction = (1.0 - (len(cone) / len(trace))) * 100.0 if trace else 0.0
+        out.append(
+            Row(
+                n_turns=n_turns,
+                n_agents=n_agents,
+                n_events=len(trace),
+                cone_size=len(cone),
+                event_reduction_pct=reduction,
+                cone_time_ms=(t1 - t0) * 1000.0,
+                replay_time_ms=(t3 - t2) * 1000.0,
+            )
+        )
+    return out
+
+
+def rows_to_csv(rows: list[Row]) -> str:
+    buf = io.StringIO()
+    w = csv.writer(buf)
+    w.writerow(
+        [
+            "n_turns",
+            "n_agents",
+            "n_events",
+            "cone_size",
+            "event_reduction_pct",
+            "cone_time_ms",
+            "replay_time_ms",
+        ]
+    )
+    for r in rows:
+        w.writerow(
+            [
+                r.n_turns,
+                r.n_agents,
+                r.n_events,
+                r.cone_size,
+                f"{r.event_reduction_pct:.2f}",
+                f"{r.cone_time_ms:.3f}",
+                f"{r.replay_time_ms:.3f}",
+            ]
+        )
+    return buf.getvalue()
+
+
+def render_results_markdown(rows: list[Row]) -> str:
+    lines: list[str] = [
+        "# ConeReplay Benchmark Results",
+        "",
+        "Auto-generated by `python -m benchmarks`. Timings are wall-clock",
+        "single-shot measurements on the machine that built the commit; use",
+        "them as ballparks, not guarantees.",
+        "",
+        "The Claim 14 performance bound recited in U.S. Provisional 64/043,722",
+        "is **cone computation in under 1 second on a single core for a 100-",
+        "agent-turn trace**. This suite measures that bound directly plus the",
+        "end-to-end selective-replay time and the event-reduction ratio (events",
+        "served byte-identically vs events re-executed).",
+        "",
+        "The patent's second bound — ~85% token-cost reduction vs naive full",
+        "re-execution — is oracle-dependent and requires a Bounded-LLM oracle",
+        "plus real trace data to quantify. The identity oracle shipped in the",
+        "package does not make LLM calls, so a synthetic token benchmark here",
+        "would be misleading; see `docs/trace-format.md` for the measurement",
+        "methodology to use with a live BoundedLLMOracle.",
+        "",
+        "| n_turns | n_agents | n_events | cone_size | out-of-cone | cone (ms) | replay (ms) |",
+        "|---:|---:|---:|---:|---:|---:|---:|",
+    ]
+    for r in rows:
+        lines.append(
+            f"| {r.n_turns} | {r.n_agents} | {r.n_events} | {r.cone_size} | "
+            f"{r.event_reduction_pct:.1f}% | {r.cone_time_ms:.3f} | {r.replay_time_ms:.3f} |"
+        )
+    lines += [
+        "",
+        "## Claim 14 — cone-time gate",
+        "",
+    ]
+    hit_100 = [r for r in rows if r.n_events >= 100]
+    if hit_100:
+        slowest = max(r.cone_time_ms for r in hit_100)
+        fastest = min(r.cone_time_ms for r in hit_100)
+        status = "PASS" if slowest < 1000.0 else "FAIL"
+        lines.append(
+            f"- Cone time for n_events >= 100: range **{fastest:.3f} ms – "
+            f"{slowest:.3f} ms** across {len(hit_100)} sweep sizes "
+            f"(target < 1000 ms). **{status}**."
+        )
+    else:
+        lines.append("- Sweep did not include n_events >= 100.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    rows = run_benchmarks()
+    sys.stdout.write(rows_to_csv(rows))
+    results_path = Path(__file__).parent / "RESULTS.md"
+    results_path.write_text(render_results_markdown(rows), encoding="utf-8")
+    sys.stderr.write(f"benchmarks: wrote {results_path}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())