GET STARTED

Getting started

This page runs what exists in the repository today: the test suites, one model-backed deliberation from a script, and the same deliberation from Claude Desktop over MCP. Each deliberation makes four model calls and writes a JSON receipt.

Prerequisites

Install and run the tests

The tests use scripted model calls, so they need no key and cost nothing.

git clone https://github.com/verdaca/VERDACA.git
cd VERDACA
uv sync --all-packages

# contract suite (CI: 442 passed, 19 skipped)
uv run pytest tests/ -q

# deliberation acceptance tests only
(cd kernel/mac && uv run --no-sync python -m pytest tests/mac/deliberation -q)

Run one deliberation from a script

The example input asks whether the project’s own +47% benchmark headline can be cited as validated evidence, with four lines of the benchmark report as evidence. All three models default to claude-haiku-4-5; the recorded runs used Claude Sonnet for the reviewer:

VERDACA_REVIEWER_MODEL=claude-sonnet-5-5 \
  uv run python scripts/live/deliberate_live.py scripts/live/deliberation_example.json

# prints: outcome=... reason=... calls=4 cost_usd=... receipt=docs/receipts/receipt-<id>.json

COST

This makes four paid model calls. The three recorded runs with this setup cost $0.026–$0.031 each. That is three runs of one question, not a typical cost.

Call it from Claude Desktop (MCP)

Add the server to Claude Desktop’s claude_desktop_config.json, restart Claude Desktop, and ask it to call verdaca_deliberate with a question and a list of evidence items (id, source, text).

"mcpServers": {
  "verdaca": {
    "command": "uv",
    "args": ["run", "--directory", "/path/to/VERDACA",
             "python", "scripts/live/deliberate_mcp_server.py"],
    "env": { "VERDACA_REVIEWER_MODEL": "claude-sonnet-5-5" }
  }
}

Every tool call is logged to docs/receipts/mcp-server.log, and the receipt is written next to it. The tool exists only on this server; the default MCP server keeps its five tools.

Read and verify a receipt

A receipt holds the question, the evidence, the draft, the critique, the diff from draft to final answer, the typed outcome, the state log, and for each model call the role, model, tokens, cost, latency and stop reason. Calls cut off by the output cap are listed in truncated_calls. To check that a stored receipt hasn’t been edited:

uv run python -c "from pathlib import Path; \
from praxis.kernel.mac.deliberation.receipt import verify_receipt_json; \
[print(p.name, verify_receipt_json(p.read_text())) for p in sorted(Path('docs/receipts').glob('*.json'))]"

ADVISORY

Known limits, seen in the recorded runs: in the Claude Desktop run the synthesizer dropped some of the reviewer’s hedges, and the reviewer critiques the draft against its own counterargument. Deliberation runs from the script or the MCP tool only; it is not yet wired behind the gateway or the Teams and Slack channels.

Next steps