dreamguard 0.1.0__tar.gz

dreamguard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manojkumar V
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dreamguard-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE README.md
+recursive-include dreamguard/static *

dreamguard-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: dreamguard
+Version: 0.1.0
+Summary: Reversible memory compilation for AI agents: compress memory without losing the raw data, and roll back when recall drops.
+Author: Manojkumar V
+License: MIT
+Project-URL: Homepage, https://github.com/manojkumar16122/dreamguard
+Project-URL: Issues, https://github.com/manojkumar16122/dreamguard/issues
+Keywords: ai,agents,llm,memory,rollback,context-compression
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: groq
+Requires-Dist: groq>=0.11; extra == "groq"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn>=0.29; extra == "server"
+Requires-Dist: python-dotenv>=1.0; extra == "server"
+Requires-Dist: groq>=0.11; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# 🛡️ DreamGuard
+
+**Reversible memory compilation for AI agents.**
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](#) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Tests](https://img.shields.io/badge/tests-pytest-brightgreen)](#testing)
+
+Long-running agents need to compress their memory ("dreaming" / consolidation) or the context window bloats. The common approach rewrites memory **in place**: once a detail is summarised away, it is gone for good.
+
+DreamGuard compiles raw *episodic* memory into compact *semantic* memory like a build step: **the raw episodes are never deleted**, and every compressed fact is linked back to its source episodes. If recall quality drops, you **roll back** and the exact raw context is restored.
+
+```
+ record() ──► episodes (immutable)
+                 │  dream()
+                 ▼
+         semantic_memories ──provenance──► episodes
+                 │  rollback()
+                 ▼
+     compressed facts deactivated, raw context restored
+```
+
+## Demo
+
+Run the dashboard and open <http://localhost:8000>. It plots detail-recall accuracy over 50 turns for three systems and lets you trigger a rollback:
+
+| System | What it does | Behaviour in the demo |
+|---|---|---|
+| Full raw context (reference) | Never compresses | 100%, but context grows without bound |
+| In-place dreaming | Rewrites memory, deletes raw data | Loss compounds, cannot recover |
+| **DreamGuard** | Compresses, keeps raw + provenance | Same loss as in-place, then **recovers to 100%** on rollback |
+
+> 📸 Add a screenshot or GIF here: `docs/demo.gif`
+
+## Install
+
+```bash
+pip install dreamguard                 # core library, zero dependencies
+pip install "dreamguard[server]"       # + dashboard, API and Groq support
+pip install "dreamguard[groq]"         # + Groq compressor only
+```
+
+## Quick start
+
+```bash
+pip install "dreamguard[server]"
+echo "GROQ_API_KEY=gsk_..." > .env     # only needed for the /live demo
+dreamguard serve                       # open http://localhost:8000
+dreamguard benchmark                   # offline simulation in the terminal
+```
+
+Development setup: `git clone ... && pip install -e ".[dev,server]" && pytest`.
+
+### Use it as a library
+
+```python
+from dreamguard import MemoryEngine, HeuristicCompressor
+
+mem = MemoryEngine(HeuristicCompressor(retention=0.7), destructive=False)
+mem.record(1, "api_port=8421")
+mem.record(2, "region=ap-south-1")
+
+mem.dream()              # compress; raw episodes + provenance are kept
+print(mem.context())     # what your agent would see (digest)
+mem.rollback()           # back to exact raw episodes
+print(mem.context())
+```
+
+### Live demo with a real LLM (Groq)
+
+```bash
+# .env
+GROQ_API_KEY=gsk_...
+```
+Run `uvicorn dreamguard.api:app --reload`, open <http://localhost:8000/live>, then click:
+**1 Load scenario → 2 Evaluate → 3 Dream → 2 Evaluate → 4 Rollback → 2 Evaluate.**
+
+Groq compresses 12 engineering-log episodes into a short digest, then answers 8 factual questions (ports, ticket owners, hosts...) using *only* each system's remaining memory. Answers are graded against known ground truth. Both the in-place and DreamGuard engines get the same input; only DreamGuard can roll back. Set `GROQ_MODEL` to change the model (default `llama-3.1-8b-instant`).
+
+Results are real LLM output, so they vary by model and run: a strong model may retain some details after compression. The rollback guarantee does not vary, because it restores the raw text.
+
+### Real LLM compression (optional)
+
+```bash
+# .env
+COMPRESSOR=groq
+GROQ_API_KEY=gsk_...
+```
+
+Uses Groq's `llama-3.1-8b-instant` to produce the digest. Note: the built-in **benchmark** always uses the heuristic compressor so that its results are reproducible.
+
+## How it works
+
+| Table | Purpose |
+|---|---|
+| `episodes` | Raw, append-only memory (`turn`, `content`) |
+| `semantic_memories` | Compressed digests, with an `active` flag |
+| `provenance` | `memory_id → episode_id` links from each digest to its sources |
+
+- `record(turn, content)` appends an episode.
+- `dream()` compresses episodes not yet covered by an active digest.
+- `rollback()` sets all digests to inactive. Their episodes become "uncovered" again, so `context()` returns the raw text.
+- `context()` is what an agent reads: active digests plus any uncovered raw episodes.
+- With `destructive=True` the engine mimics in-place dreaming: it deletes raw data and re-compresses digests together with new episodes, so loss compounds.
+
+## Benchmark methodology (read this before quoting numbers)
+
+The benchmark is a **synthetic simulation**, not a measurement of any production system:
+
+1. Each turn records one exact detail, e.g. `param_7=48213`.
+2. Every 10 turns the memory is compressed with a seeded lossy compressor that keeps each value with probability 0.7 and otherwise keeps only the key.
+3. After every turn, **recall** = fraction of all details seen so far that appear verbatim (`key=value`) in the agent's visible context.
+
+What this shows: *if* compression is lossy, an irreversible design loses information permanently, while a design that keeps raw data can restore it. What it does **not** show: how any specific LLM, product, or published system behaves. The absolute accuracy numbers come from the chosen retention parameter, not from real-world measurement.
+
+**Known trade-off:** after a rollback, the agent context is raw again and therefore larger. The benefit of compression (smaller context) is traded for recall until the next dream.
+
+## API
+
+| Method | Path | Description |
+|---|---|---|
+| POST | `/api/record` | `{"content": "..."}` record an episode |
+| POST | `/api/dream` | Compress uncovered episodes |
+| POST | `/api/rollback` | Deactivate compressed memory |
+| POST | `/api/reset` | Clear the live engine |
+| POST | `/api/demo/seed?n=10` | Add demo episodes |
+| GET | `/api/memory` | Episodes, facts, provenance, context size |
+| GET | `/api/benchmark` | Run benchmark (`seed`, `retention`, `auto_rollback`, `rollback_at`) |
+
+Interactive docs at `/docs`.
+
+## Project layout
+
+```
+dreamguard/
+├── dreamguard/
+│   ├── db.py          # SQLite schema
+│   ├── compiler.py    # Heuristic + Groq compressors
+│   ├── engine.py      # record / dream / rollback / evaluate
+│   ├── benchmark.py   # reproducible simulation
+│   ├── live.py        # live demo: Groq compression + Groq QA grading
+│   ├── api.py         # FastAPI app
+│   ├── cli.py         # `dreamguard` command
+│   └── static/        # dashboard (HTML + CSS + Chart.js, no build step)
+├── tests/
+└── pyproject.toml
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev,server]"
+pytest
+```
+
+## Roadmap
+
+- [ ] Selective rollback (restore only the episodes behind a specific fact)
+- [ ] Benchmark with real LLM compression and an LLM-answered QA task
+- [ ] Pluggable storage backends (Postgres, vector DBs)
+- [ ] Rollback triggers driven by task-level eval signals
+
+## Contributing
+
+Issues and PRs are welcome. Please run `pytest` before submitting.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Built by [Manojkumar V](https://github.com/manojkumar16122).

dreamguard-0.1.0/README.md

@@ -0,0 +1,167 @@
+# 🛡️ DreamGuard
+
+**Reversible memory compilation for AI agents.**
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](#) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Tests](https://img.shields.io/badge/tests-pytest-brightgreen)](#testing)
+
+Long-running agents need to compress their memory ("dreaming" / consolidation) or the context window bloats. The common approach rewrites memory **in place**: once a detail is summarised away, it is gone for good.
+
+DreamGuard compiles raw *episodic* memory into compact *semantic* memory like a build step: **the raw episodes are never deleted**, and every compressed fact is linked back to its source episodes. If recall quality drops, you **roll back** and the exact raw context is restored.
+
+```
+ record() ──► episodes (immutable)
+                 │  dream()
+                 ▼
+         semantic_memories ──provenance──► episodes
+                 │  rollback()
+                 ▼
+     compressed facts deactivated, raw context restored
+```
+
+## Demo
+
+Run the dashboard and open <http://localhost:8000>. It plots detail-recall accuracy over 50 turns for three systems and lets you trigger a rollback:
+
+| System | What it does | Behaviour in the demo |
+|---|---|---|
+| Full raw context (reference) | Never compresses | 100%, but context grows without bound |
+| In-place dreaming | Rewrites memory, deletes raw data | Loss compounds, cannot recover |
+| **DreamGuard** | Compresses, keeps raw + provenance | Same loss as in-place, then **recovers to 100%** on rollback |
+
+> 📸 Add a screenshot or GIF here: `docs/demo.gif`
+
+## Install
+
+```bash
+pip install dreamguard                 # core library, zero dependencies
+pip install "dreamguard[server]"       # + dashboard, API and Groq support
+pip install "dreamguard[groq]"         # + Groq compressor only
+```
+
+## Quick start
+
+```bash
+pip install "dreamguard[server]"
+echo "GROQ_API_KEY=gsk_..." > .env     # only needed for the /live demo
+dreamguard serve                       # open http://localhost:8000
+dreamguard benchmark                   # offline simulation in the terminal
+```
+
+Development setup: `git clone ... && pip install -e ".[dev,server]" && pytest`.
+
+### Use it as a library
+
+```python
+from dreamguard import MemoryEngine, HeuristicCompressor
+
+mem = MemoryEngine(HeuristicCompressor(retention=0.7), destructive=False)
+mem.record(1, "api_port=8421")
+mem.record(2, "region=ap-south-1")
+
+mem.dream()              # compress; raw episodes + provenance are kept
+print(mem.context())     # what your agent would see (digest)
+mem.rollback()           # back to exact raw episodes
+print(mem.context())
+```
+
+### Live demo with a real LLM (Groq)
+
+```bash
+# .env
+GROQ_API_KEY=gsk_...
+```
+Run `uvicorn dreamguard.api:app --reload`, open <http://localhost:8000/live>, then click:
+**1 Load scenario → 2 Evaluate → 3 Dream → 2 Evaluate → 4 Rollback → 2 Evaluate.**
+
+Groq compresses 12 engineering-log episodes into a short digest, then answers 8 factual questions (ports, ticket owners, hosts...) using *only* each system's remaining memory. Answers are graded against known ground truth. Both the in-place and DreamGuard engines get the same input; only DreamGuard can roll back. Set `GROQ_MODEL` to change the model (default `llama-3.1-8b-instant`).
+
+Results are real LLM output, so they vary by model and run: a strong model may retain some details after compression. The rollback guarantee does not vary, because it restores the raw text.
+
+### Real LLM compression (optional)
+
+```bash
+# .env
+COMPRESSOR=groq
+GROQ_API_KEY=gsk_...
+```
+
+Uses Groq's `llama-3.1-8b-instant` to produce the digest. Note: the built-in **benchmark** always uses the heuristic compressor so that its results are reproducible.
+
+## How it works
+
+| Table | Purpose |
+|---|---|
+| `episodes` | Raw, append-only memory (`turn`, `content`) |
+| `semantic_memories` | Compressed digests, with an `active` flag |
+| `provenance` | `memory_id → episode_id` links from each digest to its sources |
+
+- `record(turn, content)` appends an episode.
+- `dream()` compresses episodes not yet covered by an active digest.
+- `rollback()` sets all digests to inactive. Their episodes become "uncovered" again, so `context()` returns the raw text.
+- `context()` is what an agent reads: active digests plus any uncovered raw episodes.
+- With `destructive=True` the engine mimics in-place dreaming: it deletes raw data and re-compresses digests together with new episodes, so loss compounds.
+
+## Benchmark methodology (read this before quoting numbers)
+
+The benchmark is a **synthetic simulation**, not a measurement of any production system:
+
+1. Each turn records one exact detail, e.g. `param_7=48213`.
+2. Every 10 turns the memory is compressed with a seeded lossy compressor that keeps each value with probability 0.7 and otherwise keeps only the key.
+3. After every turn, **recall** = fraction of all details seen so far that appear verbatim (`key=value`) in the agent's visible context.
+
+What this shows: *if* compression is lossy, an irreversible design loses information permanently, while a design that keeps raw data can restore it. What it does **not** show: how any specific LLM, product, or published system behaves. The absolute accuracy numbers come from the chosen retention parameter, not from real-world measurement.
+
+**Known trade-off:** after a rollback, the agent context is raw again and therefore larger. The benefit of compression (smaller context) is traded for recall until the next dream.
+
+## API
+
+| Method | Path | Description |
+|---|---|---|
+| POST | `/api/record` | `{"content": "..."}` record an episode |
+| POST | `/api/dream` | Compress uncovered episodes |
+| POST | `/api/rollback` | Deactivate compressed memory |
+| POST | `/api/reset` | Clear the live engine |
+| POST | `/api/demo/seed?n=10` | Add demo episodes |
+| GET | `/api/memory` | Episodes, facts, provenance, context size |
+| GET | `/api/benchmark` | Run benchmark (`seed`, `retention`, `auto_rollback`, `rollback_at`) |
+
+Interactive docs at `/docs`.
+
+## Project layout
+
+```
+dreamguard/
+├── dreamguard/
+│   ├── db.py          # SQLite schema
+│   ├── compiler.py    # Heuristic + Groq compressors
+│   ├── engine.py      # record / dream / rollback / evaluate
+│   ├── benchmark.py   # reproducible simulation
+│   ├── live.py        # live demo: Groq compression + Groq QA grading
+│   ├── api.py         # FastAPI app
+│   ├── cli.py         # `dreamguard` command
+│   └── static/        # dashboard (HTML + CSS + Chart.js, no build step)
+├── tests/
+└── pyproject.toml
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev,server]"
+pytest
+```
+
+## Roadmap
+
+- [ ] Selective rollback (restore only the episodes behind a specific fact)
+- [ ] Benchmark with real LLM compression and an LLM-answered QA task
+- [ ] Pluggable storage backends (Postgres, vector DBs)
+- [ ] Rollback triggers driven by task-level eval signals
+
+## Contributing
+
+Issues and PRs are welcome. Please run `pytest` before submitting.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Built by [Manojkumar V](https://github.com/manojkumar16122).

dreamguard-0.1.0/dreamguard/__init__.py

@@ -0,0 +1,6 @@
+"""DreamGuard: reversible memory compilation for AI agents."""
+from .engine import MemoryEngine
+from .compiler import HeuristicCompressor, GroqCompressor, get_compressor
+
+__version__ = "0.1.0"
+__all__ = ["MemoryEngine", "HeuristicCompressor", "GroqCompressor", "get_compressor"]

dreamguard-0.1.0/dreamguard/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

dreamguard-0.1.0/dreamguard/api.py

@@ -0,0 +1,141 @@
+"""FastAPI backend + static dashboard. Run: uvicorn dreamguard.api:app --reload"""
+from pathlib import Path
+
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+from .benchmark import run_benchmark
+from .compiler import get_compressor
+from .engine import MemoryEngine
+from .live import LiveDemo
+
+load_dotenv()
+STATIC = Path(__file__).resolve().parent / "static"
+
+app = FastAPI(title="DreamGuard", version="0.1.0")
+app.mount("/static", StaticFiles(directory=STATIC), name="static")
+
+_state = {"engine": None, "turn": 0}
+
+
+def _engine() -> MemoryEngine:
+    if _state["engine"] is None:
+        _state["engine"] = MemoryEngine(get_compressor(), destructive=False)
+    return _state["engine"]
+
+
+class Episode(BaseModel):
+    content: str = Field(min_length=1, max_length=2000)
+
+
+@app.get("/")
+def index():
+    return FileResponse(STATIC / "index.html")
+
+
+@app.post("/api/record")
+def record(ep: Episode):
+    _state["turn"] += 1
+    _engine().record(_state["turn"], ep.content)
+    return {"turn": _state["turn"]}
+
+
+@app.post("/api/dream")
+def dream():
+    try:
+        fact = _engine().dream()
+    except Exception as e:  # e.g. missing GROQ key / network error
+        raise HTTPException(500, f"Compression failed: {e}")
+    return {"fact": fact}
+
+
+@app.post("/api/rollback")
+def rollback():
+    return {"rolled_back": _engine().rollback()}
+
+
+@app.post("/api/reset")
+def reset():
+    _state.update(engine=None, turn=0)
+    return {"ok": True}
+
+
+@app.post("/api/demo/seed")
+def seed(n: int = 10):
+    eng = _engine()
+    for _ in range(n):
+        _state["turn"] += 1
+        t = _state["turn"]
+        eng.record(t, f"param_{t}={(t * 7919) % 90000 + 10000}")
+    return {"turn": _state["turn"]}
+
+
+@app.get("/api/memory")
+def memory():
+    return _engine().snapshot()
+
+
+@app.get("/api/benchmark")
+def benchmark(seed: int = 42, retention: float = 0.7, auto_rollback: bool = False,
+              rollback_at: int | None = 40):
+    return run_benchmark(seed=seed, retention=retention, auto_rollback=auto_rollback,
+                         rollback_at=None if auto_rollback else rollback_at)
+
+
+# ---- live demo (real Groq compression + Groq question answering) ----------
+_live: dict = {"demo": None}
+
+
+def _demo() -> LiveDemo:
+    if _live["demo"] is None:
+        raise HTTPException(400, "Click 'Load scenario' first.")
+    return _live["demo"]
+
+
+def _guard(fn):
+    try:
+        return fn()
+    except HTTPException:
+        raise
+    except Exception as e:  # missing key, rate limit, network, bad JSON...
+        raise HTTPException(502, f"Groq error: {e}")
+
+
+@app.get("/live")
+def live_page():
+    return FileResponse(STATIC / "live.html")
+
+
+@app.post("/api/live/start")
+def live_start():
+    _live["demo"] = _guard(LiveDemo)
+    return _live["demo"].state()
+
+
+@app.post("/api/live/dream")
+def live_dream():
+    d = _demo()
+    _guard(d.dream)
+    return d.state()
+
+
+@app.post("/api/live/rollback")
+def live_rollback():
+    d = _demo()
+    d.rollback()
+    return d.state()
+
+
+@app.post("/api/live/evaluate")
+def live_evaluate(label: str = "check"):
+    d = _demo()
+    _guard(lambda: d.evaluate(label[:40]))
+    return d.state()
+
+
+@app.get("/api/live/state")
+def live_state():
+    return _demo().state()

dreamguard-0.1.0/dreamguard/benchmark.py

@@ -0,0 +1,76 @@
+"""Synthetic detail-retention benchmark.
+
+Each turn the agent records an episode containing one exact detail
+(`param_7=48213`). Every `dream_every` turns the memory is compressed. After
+each turn we probe recall of ALL details seen so far (exact match against the
+agent's visible context). No LLM is involved, so results are deterministic.
+
+Systems compared:
+  raw         - never compresses (accuracy reference; context grows unbounded)
+  in_place    - compresses by rewriting memory, raw data deleted
+  dreamguard  - same compressor, raw data kept. Rolls back either manually at
+                `rollback_at` (default: turn 40, for a visible drop-and-recovery
+                demo) or automatically when probe accuracy < threshold
+                (`auto_rollback=True`). Dreaming then pauses for `cooldown` turns.
+"""
+import json
+import random
+import sys
+
+from .compiler import HeuristicCompressor
+from .engine import MemoryEngine
+
+
+def run_benchmark(turns: int = 50, dream_every: int = 10, retention: float = 0.7,
+                  threshold: float = 0.85, cooldown: int = 15, seed: int = 42,
+                  auto_rollback: bool = False, rollback_at: int | None = 40) -> dict:
+    rng = random.Random(seed)
+    mk = lambda destructive: MemoryEngine(HeuristicCompressor(retention, seed), destructive)
+    systems = {"raw": mk(False), "in_place": mk(True), "dreamguard": mk(False)}
+    truth: dict[str, str] = {}
+    rows, events = [], []
+    paused_until = 0
+
+    for t in range(1, turns + 1):
+        key, val = f"param_{t}", str(rng.randint(10000, 99999))
+        truth[key] = val
+        for eng in systems.values():
+            eng.record(t, f"{key}={val}")
+
+        if t % dream_every == 0:
+            systems["in_place"].dream()
+            if t >= paused_until:
+                systems["dreamguard"].dream()
+                events.append({"turn": t, "type": "dream"})
+
+        dg = systems["dreamguard"]
+        manual = rollback_at is not None and t == rollback_at
+        auto = auto_rollback and t >= paused_until and dg.evaluate(truth) < threshold
+        if manual or auto:
+            dg.rollback()
+            paused_until = t + cooldown
+            events.append({"turn": t, "type": "rollback"})
+
+        rows.append({
+            "turn": t,
+            **{f"{n}_acc": round(100 * e.evaluate(truth), 1) for n, e in systems.items()},
+            **{f"{n}_chars": len(e.context()) for n, e in systems.items()},
+        })
+
+    return {"config": {"turns": turns, "dream_every": dream_every, "retention": retention,
+                       "threshold": threshold, "cooldown": cooldown, "seed": seed,
+                       "auto_rollback": auto_rollback, "rollback_at": rollback_at},
+            "rows": rows, "events": events}
+
+
+if __name__ == "__main__":
+    auto = "--auto" in sys.argv
+    res = run_benchmark(auto_rollback=auto, rollback_at=None if auto else 40)
+    print(f"{'turn':>4} {'raw':>6} {'in_place':>9} {'dreamguard':>11}")
+    for r in res["rows"]:
+        if r["turn"] % 5 == 0:
+            print(f"{r['turn']:>4} {r['raw_acc']:>5}% {r['in_place_acc']:>8}% {r['dreamguard_acc']:>10}%")
+    print("events:", res["events"])
+    if "--json" in sys.argv:
+        with open("benchmark_results.json", "w") as f:
+            json.dump(res, f, indent=2)

dreamguard-0.1.0/dreamguard/cli.py

@@ -0,0 +1,34 @@
+"""Command line: `dreamguard serve` | `dreamguard benchmark [--auto]`."""
+import argparse
+import sys
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="dreamguard", description="Reversible memory compilation for AI agents")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("serve", help="start the dashboard + API")
+    s.add_argument("--host", default="127.0.0.1")
+    s.add_argument("--port", type=int, default=8000)
+    b = sub.add_parser("benchmark", help="run the offline simulation")
+    b.add_argument("--auto", action="store_true", help="auto-rollback instead of manual at turn 40")
+    args = p.parse_args(argv)
+
+    if args.cmd == "serve":
+        try:
+            import uvicorn
+            from .api import app
+        except ImportError:
+            sys.exit('Server extras missing. Install with: pip install "dreamguard[server]"')
+        uvicorn.run(app, host=args.host, port=args.port)
+    else:
+        from .benchmark import run_benchmark
+        res = run_benchmark(auto_rollback=args.auto, rollback_at=None if args.auto else 40)
+        print(f"{'turn':>4} {'raw':>6} {'in_place':>9} {'dreamguard':>11}")
+        for r in res["rows"]:
+            if r["turn"] % 5 == 0:
+                print(f"{r['turn']:>4} {r['raw_acc']:>5}% {r['in_place_acc']:>8}% {r['dreamguard_acc']:>10}%")
+        print("events:", res["events"])
+
+
+if __name__ == "__main__":
+    main()