Consequent

Consequent is an open-source consequence gate for autonomous agents.

Agents do not execute actions directly. They submit structured requests with predicted outcomes, rollback plans, confidence, and irreversibility scores. Consequent evaluates the request, runs a separate adversarial critic pass, applies deterministic policy, executes only approved actions, records a tamper-evident ledger, reconciles predicted state against actual state, and automatically adjusts agent autonomy.

This repository is an alpha. The goal is to build the accountability layer between agents and the real world.

Core Invariant

agent -> execution contract -> consequence engine -> critic -> gate -> Consequent-owned executor -> world model

No action reaches an executor unless the gate allows it or a configured human approval path permits it.

What Works Today

• Async FastAPI service
• Pydantic v2 execution contracts
• SQLite default persistence through async SQLAlchemy
• Append-only world model
• Tamper-evident commitment ledger with hash-chain verification
• Separate consequence and critic calls through a provider-neutral evaluator interface
• Offline local evaluator for deterministic development
• Autonomy throttle based on prediction divergence
• Idempotent action submission
• API-key hook via X-Consequent-Key
• Typed executor plugin registry
• Async Python SDK
• Docker, demo script, and tests

Quickstart

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
uvicorn consequent.main:app --host 127.0.0.1 --port 8000

Open:

• API docs: http://127.0.0.1:8000/docs
• Current state: http://127.0.0.1:8000/state/current

Run the demo in another terminal:

python examples/demo_flow.py

Agent integration examples are in docs/AGENT_INTEGRATION.md.

Optional API Key

By default, local development runs without an API key. To require one:

export CONSEQUENT_API_KEYS="dev-secret"
uvicorn consequent.main:app --host 127.0.0.1 --port 8000

Then send:

X-Consequent-Key: dev-secret

Submit an Action

curl -s -X POST http://127.0.0.1:8000/action/submit \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "agent-a",
    "idempotency_key": "demo-1",
    "contract": {
      "action": {"type": "world_state", "set": {"task.done": true}},
      "predicted_world_state_after": {"task.done": true},
      "acceptable_failure_modes": [],
      "unacceptable_failure_modes": [],
      "rollback_plan": {"set": {"task.done": false}},
      "confidence": 0.9,
      "irreversibility_score": 0.2
    }
  }'

Approve:

curl -s -X POST http://127.0.0.1:8000/action/approve \
  -H 'Content-Type: application/json' \
  -d '{"action_id": "ACTION_ID_FROM_SUBMIT"}'

Verify the ledger:

curl -s http://127.0.0.1:8000/ledger/verify/hash-chain

Model Providers

Consequent is not tied to any model vendor.

Production deployments can implement StructuredEvaluator and return the same Pydantic objects used by the built-in evaluator. Prompt bundles and JSON schemas are exposed in ConsequentPrompts so OpenAI-compatible endpoints, local models, hosted LLMs, or another agent can plug in without changing the gate, ledger, or executor path.

Roadmap

• Postgres production profile
• Queue-backed execution workers
• First-party executor plugins for GitHub, email, shell sandbox, browser, and cloud APIs
• Policy packs for organizations
• Human approval UI
• Signed ledger export
• Evaluation benchmark suite

Development

pytest
ruff check .

License

MIT