Metadata-Version: 2.4
Name: veripoint
Version: 0.8.1
Summary: TCP for AI agents: autosave, verification gates, and a time machine for long-running agent work.
Author: Veripoint
License: Apache-2.0
Project-URL: Homepage, https://feruzkarimovv.github.io/veripoint/
Project-URL: Repository, https://github.com/feruzkarimovv/veripoint
Project-URL: Changelog, https://github.com/feruzkarimovv/veripoint/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/feruzkarimovv/veripoint/issues
Keywords: ai,agents,reliability,checkpointing,verification,llm,mcp,audit,undo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# Veripoint

[![CI](https://github.com/feruzkarimovv/veripoint/actions/workflows/ci.yml/badge.svg)](https://github.com/feruzkarimovv/veripoint/actions/workflows/ci.yml)

**Autosave + fact-check + a time machine for AI agents.**

AI agents are brilliant for 10 minutes and unreliable for 10 hours. One small early
mistake quietly poisons everything after it — the agent keeps going, confidently
wrong, and fails silently at hour three. Today's tools that "save progress" make it
worse: they replay the saved history, poison included, and repeat the same failure.

Veripoint keeps the agent's progress and facts **outside** the agent, verifies each chunk
of work **before** accepting it (only work that can actually be checked — code that
runs, numbers that reconcile), and when the agent goes off the rails, rewinds to the
last verified-good save and restarts a fresh agent from clean notes — not the
poisoned memory.

> The internet runs on unreliable wires, yet your files arrive perfectly, because a
> protocol sits on top catching and resending errors. Veripoint wants to be TCP for AI
> agents: unreliable model underneath, dependable work on top.

```bash
pip install veripoint      # zero runtime dependencies — stdlib only
```

---

## The one-minute version

| Without Veripoint | With Veripoint |
|---|---|
| Agent misreads data at minute 9; nothing notices | `ReconcileGate` proves the numbers wrong; chunk rejected |
| Poisoned context drives every later step | Failed approach is quarantined as *known-bad* |
| "Resume" replays poisoned history → same failure | Rewind restores last verified workspace; fresh attempt gets clean notes |
| Wrong output ships with exit code 0 | Session fails honestly — or recovers and ships verified work |

## Quickstart

```bash
pip install veripoint

# or from source (development):
git clone https://github.com/feruzkarimovv/veripoint && cd veripoint
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python examples/flaky-agent-demo/baseline.py   # ships inflated numbers silently
.venv/bin/python examples/flaky-agent-demo/job.py        # same agent under veripoint: caught & repaired
```

### Use it from Claude Code / Cursor (MCP)

```jsonc
// .mcp.json
{ "mcpServers": { "veripoint": {
    "command": "veripoint",
    "args": ["mcp", "--job", "veripoint_job.py", "--workspace", "."] } } }
```

Author `veripoint_job.py` with `GOAL` + `SLOTS` (gates are operator-owned — agents can't
weaken their own acceptance criteria), and your agent gets `briefing`,
`submit_work`, `rewind` and friends as native tools. See
[docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).

Then wire your own agent:

```python
from veripoint import Veripoint, Slot
from veripoint.drivers import SubprocessDriver          # wraps claude -p / codex exec / aider / ...
from veripoint.verifiers import CommandGate, ReconcileGate, FilesExistGate

k = Veripoint("./.veripoint")
report = k.run(
    goal="Migrate billing service to v2 API",
    driver=SubprocessDriver("claude -p --output-format json"),
    slots=[
        Slot("map endpoints", verifiers=[CommandGate("pytest tests/test_mapping.py -q")]),
        # DAG: independent slots run in parallel, each in its own workspace
        Slot("migrate charges", key="charges", depends_on=["map endpoints"],
             verifiers=[CommandGate("pytest tests/charges -q")]),
        Slot("migrate refunds", key="refunds", depends_on=["map endpoints"],
             verifiers=[CommandGate("pytest tests/refunds -q"),
                        ReconcileGate("refund_report.json", {
                            "counts match": lambda d: d["migrated"] == d["source_total"],
                        })]),
        Slot("cutover", key="cut", depends_on=["charges", "refunds"],
             verifiers=[CommandGate("./scripts/smoke.sh")]),
    ],
)
print(report.summary_line())
# [OK] session=ses_8f21… slots=5/5 attempts=6 rejected=1 time=18m02s
```

## What's in the box

```
src/veripoint/
├── store.py         hash-chained SQLite ledger: sessions, chunks, verdicts,
│                    checkpoints, quarantine, content-addressed artifacts
├── snapshots.py     workspace time machine (snapshot / restore / clear)
├── verifiers/       gates that fail closed: command, python, files, content,
│                    JSON-schema subset, numeric reconcile, all_of/any_of, shadow mode
├── notes.py         clean-notes compiler (briefings from verified history only)
├── watchdog.py      poison-spiral detection: repeated outputs/errors, budgets
├── drivers/         mock · subprocess (any CLI agent) · HTTP (OpenAI-compatible,
│                    Anthropic, Ollama)
├── dag.py           DAG validation: refs, cycles, blocked propagation
├── async_runner.py  parallel DAG execution with per-slot isolated workspaces
├── pricing.py       model price table for cost estimates (USD per 1M tokens)
├── mcp_server.py    MCP stdio server: Veripoint tools for Claude Code/Cursor/etc.
├── engine.py        Veripoint facade (run / run_plan / arun_plan / resume / submit_chunk)
├── cli.py           init run status log show diff gates retry checkpoints rewind
│                    brief cost gc doctor report serve mcp
└── server.py + ui/  zero-dependency local dashboard (timeline, gates, spend, click-to-rewind)
```

- **Gate packs**: `from veripoint.packs import code` — curated SRE chain (tests, compile, sweep, runbook, smoke)
- **Live example**: `examples/live_agent/live.py` (uses ANTHROPIC_API_KEY / OPENAI_API_KEY when present; skips otherwise)
- **Docs**: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) · [docs/PROTOCOL.md](docs/PROTOCOL.md) · [docs/GATES.md](docs/GATES.md) · [docs/CLI.md](docs/CLI.md) · [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md)
- **Website**: [website/index.html](website/index.html) (`python3 -m http.server -d website`)
- **Tests**: `pytest` — 157 tests covering ledger tamper-detection, gate semantics, rewind guarantees, DAG parallelism/isolation, budgets, GC, drivers, MCP protocol, dashboard API.

## The guarantee, precisely

1. **Nothing unverifiable commits.** A chunk becomes part of session truth only after
   every required gate passes. Gates fail closed: crashes, timeouts, unreadable
   artifacts are rejections.
2. **Poison cannot leak forward.** Every attempt starts from the newest verified
   snapshot (or an empty room). Files written by rejected attempts are gone.
3. **Restarts get lessons, not luggage.** Briefings are compiled deterministically
   from accepted history + quarantined approaches. Raw transcripts never return.
4. **History is immutable and auditable.** Events form a SHA-256 hash chain;
   `veripoint doctor` detects tampering. Checkpoints are never rewritten.
5. **Honest failure.** If verification can't be satisfied within budget, the session
   ends failed with evidence — never a plausible wrong answer.
6. **Spend is visible and bounded.** Every attempt's token usage is recorded
   (rejected attempts included); session/slot budget caps refuse further work once
   crossed; snapshot GC prunes weight without touching history.

## Status

v0.8.0 — verification gates, clean restarts, MCP server (8 tools), async DAG
execution, cost accounting with hard budgets, snapshot GC, benchmark suite,
live-API dogfood verified. Roadmap: Postgres/S3 ledger backends (see
ARCHITECTURE.md backend seam), more gate packs per domain, hosted read-only
audit sharing.

## Platform notes

POSIX (macOS/Linux) is the supported platform for v1: gate commands and the
MCP/subprocess drivers assume a POSIX shell. Windows works via WSL.

## License

Apache-2.0
