causallock 0.1.0__tar.gz

causallock-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: causallock
+Version: 0.1.0
+Summary: Deterministic Replay & Audit SDK for AI Agents
+Author: Guna
+Requires-Python: >=3.12
+Requires-Dist: pydantic
+Requires-Dist: orjson
+Requires-Dist: rich
+Requires-Dist: typer
+Requires-Dist: cryptography
+Requires-Dist: httpx
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: openai

causallock-0.1.0/README.md

@@ -0,0 +1,341 @@
+# causallock
+
+causallock is a deterministic execution recording, replay, and audit platform for AI agents.
+
+It provides:
+- deterministic trace capture (`.traj`)
+- hash-chain integrity verification
+- replay validation and divergence detection
+- regression testing at trace level
+- cryptographic signing support
+- UI control plane for replay/diff/VCR/redaction/trust workflows
+
+---
+
+## What This Project Is
+
+causallock is not a prompt evaluator.  
+It is execution infrastructure for reliability and auditability:
+
+- record each LLM/tool event
+- preserve event ordering and hashes
+- replay under deterministic constraints
+- detect divergence at payload/hash/order levels
+- expose trust evidence for compliance-style review
+
+---
+
+## Distribution Model (No Node Required for End Users)
+
+End users install and run with Python only:
+
+```bash
+pip install causallock
+causallock ui
+```
+
+This works because the built React dashboard is packaged into `causallock/ui/static` and served by FastAPI.
+
+You do **not** need `cd dashboard` as an end user.
+
+---
+
+## Install
+
+### From local source
+
+```bash
+pip install .
+```
+
+### Editable (contributors)
+
+```bash
+pip install -e .
+```
+
+### From GitHub
+
+```bash
+pip install "git+https://github.com/GunaShankar0213/CausalLock.git"
+```
+
+---
+
+## Quick Run
+
+```bash
+causallock init run .
+causallock ui
+```
+
+Open:
+- `http://127.0.0.1:8765/ui`
+
+Recommended server start options:
+
+```bash
+# Preferred
+causallock ui
+
+# Equivalent backend launch
+uvicorn causallock.ui.server:app --host 127.0.0.1 --port 8765
+```
+
+---
+
+## CLI Commands
+
+### Replay
+
+```bash
+causallock replay run regression/sample1.traj
+causallock replay run regression/sample1.traj --immutable --seed 1337
+causallock replay run regression/sample1.traj --immutable --force-env-mismatch
+```
+
+### Diff
+
+```bash
+causallock diff run regression/sample1.traj regression/sample2.traj
+causallock diff run regression/sample1.traj regression/sample2.traj --semantic
+```
+
+### Regression
+
+```bash
+causallock test run regression --workers 4 --json-output
+causallock test run regression --strict
+```
+
+### Freeze snapshots
+
+```bash
+causallock freeze run regression/
+```
+
+### Signing
+
+```bash
+causallock sign keygen --output keys
+causallock sign sign regression/sample1.traj keys/private.key
+causallock sign verify regression/sample1.traj
+causallock sign sign regression/sample1.traj keys/private.key --detached --signature-path regression/sample1.sig --key-id team-key-1
+causallock sign verify regression/sample1.traj --signature-path regression/sample1.sig
+```
+
+---
+
+## API Surface (`/api/*`)
+
+### Trace + search
+- `GET /api/traces`
+- `GET /api/trace/{trace_name}`
+- `GET /api/trace/{trace_name}/events`
+- `GET /api/trace/{trace_name}/event/{index}`
+- `GET /api/trace/{trace_name}/state?index=N`
+- `GET /api/search?q=...`
+
+### Replay control
+- `POST /api/replay/start`
+- `POST /api/replay/step`
+- `POST /api/replay/stop`
+- `GET /api/replay/status`
+- `GET /api/replay/progress/{session_id}` (SSE event: `replay_progress`)
+
+### Diff / VCR / redaction / trust
+- `GET /api/diff?traceA=...&traceB=...&semantic=true|false`
+- `GET /api/vcr/stats`
+- `GET /api/vcr/{tool_hash}`
+- `GET /api/redaction/rules`
+- `GET /api/trace/{trace_name}/redaction-log`
+- `GET /api/trust/{trace_name}`
+- `POST /api/test/run`
+
+---
+
+## UI Pages and Components
+
+The packaged dashboard includes:
+
+### 1. Explorer
+- grouped runs by `project_name -> agent_name`
+- trace cards (name/id/model/seed/signature/hash-chain/event count)
+- virtualized timeline
+- lazy payload inspector
+
+### 2. Replay
+- start/step/stop replay
+- immutable replay toggle
+- optional seed override
+- replay status panel
+- live SSE progress stream
+- deterministic state snapshot viewer
+
+### 3. Diff
+- trace A/B selection
+- semantic toggle
+- structured divergence result:
+  - `type`
+  - `summary`
+  - `field_deltas`
+  - `divergence_index`
+
+### 4. VCR
+- cache hit/miss totals
+- unique payload hash count
+- per-tool usage
+- lookup by tool payload hash
+
+### 5. Redaction
+- active rule listing
+- per-trace redaction marker log
+
+### 6. Trust
+- hash-chain status
+- signature status
+- environment mismatch fields
+- CAS presence check
+- strict regression run trigger
+
+---
+
+## UI Event Tags and Meanings
+
+Event row colors/types:
+- `llm_call`: discrete model invocation
+- `llm_stream`: streaming model output event
+- `tool_call`: tool execution capture/replay unit
+- generic fallback: non-categorized deterministic event
+
+Trace card tags:
+- `signed` / `unsigned`
+- `chain ok` / `chain bad`
+- `model <name>`
+- `seed <value>`
+
+---
+
+## Multi-Agent Grouping
+
+Trace schema fields:
+- `project_name`
+- `agent_name`
+
+UI groups using these fields.
+
+Backward compatibility for older traces:
+- inferred from filename patterns:
+  - `project__agent__...`
+  - `project-agent-...`
+
+---
+
+## Real-Time Example (Ollama Phi)
+
+```bash
+python scripts/ollama_realtime_example.py \
+  --model phi4 \
+  --project customer_support \
+  --agent planner \
+  --runs 5 \
+  --seed 1337 \
+  --show-ui
+```
+
+What this does:
+- live OpenAI-compatible calls to Ollama
+- deterministic trace capture
+- CAS write
+- immutable replay verification per run
+- auto-opens UI
+- file naming suitable for grouping:
+  - `project__agent__model__run_N.traj`
+
+After generating demo traces, replay one run:
+
+```bash
+causallock replay run regression/demo__planner__phi4__run_1.traj --immutable --seed 1337
+```
+
+---
+
+## Contributor Workflow (when editing UI)
+
+### Dev mode (HMR)
+
+```bash
+cd dashboard
+npm install
+npm run dev
+```
+
+### Sync built UI into Python package
+
+```bash
+python scripts/sync_dashboard_static.py
+```
+
+This builds `dashboard/dist` and copies it into `causallock/ui/static`.
+
+---
+
+## Release Automation
+
+Prepare release artifacts with one command:
+
+```bash
+python scripts/prepare_release.py
+```
+
+It runs:
+1. Python tests
+2. dashboard build + static sync
+3. `python -m build`
+
+---
+
+## Verification
+
+```bash
+python -m pytest -q
+python -m py_compile causallock/ui/server.py scripts/ollama_realtime_example.py
+cd dashboard && npm run build
+```
+
+---
+
+## Why Use causallock (Pros)
+
+- reproducible replay workflows for agent debugging
+- deterministic integrity model (hash-chain + root hash metadata)
+- fast CI-grade regression without paid model calls
+- strong auditability path (signature + trust diagnostics)
+- project/agent grouping for multi-agent systems
+- Python-first distribution (`pip install` + single `causallock ui`)
+
+---
+
+## Conclusion and Expansion Path
+
+causallock now supports a full local-first deterministic execution workflow:
+- record
+- replay
+- diff
+- regression
+- trust inspection
+
+Natural next expansion tracks:
+- WebGL graph layer for large trace topology
+- WASM diff/hashing accelerators
+- multi-user relay and RBAC
+- compliance bundle export pipeline
+ 
+---  
+ 
+## Troubleshooting  
+ 
+- Use `causallock ui` or `uvicorn causallock.ui.server:app --host 127.0.0.1 --port 8765` to start UI backend.  
+- Do not rely on `python -m causallock.ui.server` unless you explicitly add a module runner block.  
+- If replay says `Trace file not found`, first list available files: `dir regression` then replay with an exact filename.  
+- If `causallock` command is not found, use `python -m causallock.cli.main --help` or add Python Scripts path to PATH. 

causallock-0.1.0/causallock/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version 
+ 
+try: 
+    __version__ = version('causallock') 
+except PackageNotFoundError:  # pragma: no cover 
+    __version__ = '0.0.0'

causallock-0.1.0/causallock/cache/tool_vcr.py

@@ -0,0 +1,115 @@
+# causallock/cache/tool_vcr.py
+
+from typing import Callable, Any, Dict, Optional
+from functools import wraps
+import hashlib
+
+from causallock.interceptor.mode import AuditMode
+from causallock.core.trace import TraceBuilder
+from causallock.core.serializer import canonical_dumps
+from causallock.replay.engine import ReplayEngine, ReplayDivergenceError
+
+
+class ToolDivergenceError(Exception):
+    pass
+
+
+class ToolVCR:
+    """
+    Deterministic Tool VCR layer.
+
+    RECORD mode:
+        - Executes tool
+        - Stores input/output in trace
+
+    REPLAY mode:
+        - Skips execution
+        - Returns cached output
+        - Enforces strict divergence detection
+    """
+
+    def __init__(
+        self,
+        mode: AuditMode,
+        trace_builder: Optional[TraceBuilder] = None,
+        replay_engine: Optional[ReplayEngine] = None,
+        tool_version: str = "1",
+        deterministic: bool = True,
+        allow_side_effects_in_replay: bool = False,
+    ):
+        self._mode = mode
+        self._trace_builder = trace_builder
+        self._replay_engine = replay_engine
+        self._tool_version = tool_version
+        self._deterministic = deterministic
+        self._allow_side_effects_in_replay = allow_side_effects_in_replay
+
+    def wrap(self, func: Callable[..., Any]) -> Callable[..., Any]:
+        """
+        Decorator to wrap deterministic tool execution.
+        """
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+
+            payload: Dict[str, Any] = {
+                "args": args,
+                "kwargs": kwargs,
+                "tool_version": self._tool_version,
+                "deterministic": self._deterministic,
+            }
+            payload_hash = hashlib.sha256(canonical_dumps(payload)).hexdigest()
+
+            # ---------------------------
+            # REPLAY MODE
+            # ---------------------------
+            if self._mode == AuditMode.REPLAY:
+
+                if self._replay_engine is None:
+                    raise RuntimeError(
+                        "Replay engine not provided in REPLAY mode."
+                    )
+
+                try:
+                    event_output = self._replay_engine.next_tool_call(payload)
+                except ReplayDivergenceError as e:
+                    raise ToolDivergenceError(str(e)) from e
+
+                if "result" not in event_output:
+                    raise ToolDivergenceError(
+                        "Malformed tool replay payload: missing 'result'."
+                    )
+                if not self._deterministic and not self._allow_side_effects_in_replay:
+                    raise ToolDivergenceError(
+                        "Replay disallowed for non-deterministic side-effect tool."
+                    )
+                if event_output.get("payload_hash") != payload_hash:
+                    raise ToolDivergenceError(
+                        "Tool payload hash mismatch during replay."
+                    )
+
+                return event_output["result"]
+
+            # ---------------------------
+            # RECORD MODE
+            # ---------------------------
+            result = func(*args, **kwargs)
+
+            if self._trace_builder is None:
+                raise RuntimeError(
+                    "TraceBuilder not provided in RECORD mode."
+                )
+
+            self._trace_builder.add_event(
+                event_type="tool_call",
+                input_data=payload,
+                output_data={
+                    "result": result,
+                    "payload_hash": payload_hash,
+                    "tool_version": self._tool_version,
+                },
+            )
+
+            return result
+
+        return wrapper

causallock-0.1.0/causallock/cli/commands/diff.py

@@ -0,0 +1,44 @@
+# causallock/cli/commands/diff.py
+
+import typer
+from pathlib import Path
+from rich.console import Console
+
+from causallock.core.storage import TraceStorage
+from causallock.diff.engine import TraceDiffer
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command()
+def run(
+    trace_a: Path,
+    trace_b: Path,
+    semantic: bool = typer.Option(
+        False, help="Ignore non-impacting metadata fields (timestamps, etc)."
+    ),
+):
+    """
+    Diff two .traj files.
+    """
+
+    if not trace_a.exists() or not trace_b.exists():
+        console.print("[red]Trace file not found.[/red]")
+        raise typer.Exit(code=1)
+
+    t1 = TraceStorage.load(trace_a, verify_integrity=True)
+    t2 = TraceStorage.load(trace_b, verify_integrity=True)
+
+    result = TraceDiffer.diff(t1, t2, semantic=semantic)
+
+    if result.diverged:
+        console.print("[red]Traces diverged.[/red]")
+        console.print(f"Index: {result.index}")
+        console.print(f"Reason: {result.reason}")
+        console.print(f"Classification: {result.classification}")
+        if result.details:
+            console.print(f"Details: {result.details}")
+        raise typer.Exit(code=1)
+
+    console.print("[green]Traces are identical.[/green]")

causallock-0.1.0/causallock/cli/commands/freeze.py

@@ -0,0 +1,35 @@
+import os
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command()
+def run(
+    directory: Path,
+    dry_run: bool = typer.Option(False, help="Preview files without changing mode."),
+):
+    """
+    Freeze regression snapshots by making .traj files read-only.
+    """
+    if not directory.exists():
+        console.print("[red]Directory not found.[/red]")
+        raise typer.Exit(code=1)
+
+    files = sorted(directory.glob("*.traj"), key=lambda p: p.name.lower())
+    if not files:
+        console.print("[yellow]No .traj files found.[/yellow]")
+        raise typer.Exit(code=0)
+
+    for file in files:
+        if dry_run:
+            console.print(f"[cyan]would-freeze[/cyan] {file}")
+            continue
+        mode = file.stat().st_mode
+        file.chmod(mode & ~os.W_OK)
+        console.print(f"[green]frozen[/green] {file}")

causallock-0.1.0/causallock/cli/commands/init.py

@@ -0,0 +1,37 @@
+import typer
+from pathlib import Path
+from rich.console import Console
+
+from causallock.cli.trajignore import ensure_trajignore
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command()
+def run(
+    project_root: Path = typer.Argument(
+        Path("."),
+        help="Project directory for causallock initialization.",
+    )
+):
+    """
+    Initialize causallock project defaults.
+    """
+    root = project_root.resolve()
+    root.mkdir(parents=True, exist_ok=True)
+
+    regression_dir = root / "regression"
+    cas_dir = root / "storage"
+    regression_dir.mkdir(parents=True, exist_ok=True)
+    cas_dir.mkdir(parents=True, exist_ok=True)
+
+    changed = ensure_trajignore(root)
+
+    console.print(f"[green]Initialized causallock at {root}[/green]")
+    console.print(f"Regression dir: {regression_dir}")
+    console.print(f"CAS storage dir: {cas_dir}")
+    if changed:
+        console.print("[green].trajignore updated[/green]")
+    else:
+        console.print("[yellow].trajignore already up to date[/yellow]")

causallock-0.1.0/causallock/cli/commands/replay.py

@@ -0,0 +1,61 @@
+# causallock/cli/commands/replay.py
+
+import typer
+from pathlib import Path
+from rich.console import Console
+
+from causallock.core.storage import TraceStorage
+from causallock.replay.engine import ReplayEngine
+from causallock.cli.trajignore import ensure_trajignore
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command()
+def run(
+    trace_path: Path,
+    immutable: bool = typer.Option(
+        False, help="Enable immutable replay mode."
+    ),
+    force_env_mismatch: bool = typer.Option(
+        False, help="Allow replay even when environment fingerprint differs."
+    ),
+    seed: int | None = typer.Option(
+        None, help="Expected deterministic seed recorded in the trace."
+    ),
+):
+    """
+    Replay a .traj file and verify integrity.
+    """
+    if not trace_path.exists():
+        console.print("[red]Trace file not found.[/red]")
+        raise typer.Exit(code=1)
+
+    ensure_trajignore(Path.cwd())
+
+    try:
+        stat_before = trace_path.stat()
+        trace = TraceStorage.load(
+            trace_path,
+            verify_integrity=True,
+            verify_signature=immutable,
+        )
+        ReplayEngine(
+            trace,
+            strict=immutable,
+            immutable=immutable,
+            force_env_mismatch=force_env_mismatch,
+            expected_seed=seed,
+        )
+        if immutable:
+            stat_after = trace_path.stat()
+            if (stat_before.st_mtime_ns != stat_after.st_mtime_ns) or (
+                stat_before.st_size != stat_after.st_size
+            ):
+                raise RuntimeError("Immutable replay violation: trace file changed during replay.")
+
+        console.print("[green]Replay validation successful.[/green]")
+    except Exception as e:
+        console.print(f"[red]Replay failed:[/red] {e}")
+        raise typer.Exit(code=1)