deed-runtime 0.1.1a0

Contractual runtime for AI agents — pre/post contracts, policy enforcement, credits metering, checkpoint & replay

DEED

Contractual runtime for AI agents.

pip install deed-runtime

Zero dependencies. Python 3.10+.

---

The problem

Your AI agent ran. Something unexpected happened. No pre-conditions checked. No audit trail. No rollback.

The answer

Every action passes through a contract:

agent score_agent
  contract score_contract
    pre  company_name_present
    post score_generated

  policy
    cap  budget_tokens <= 5000
    deny score_company if region == "restricted"
    allow score_company if company_name_present

• Pre-condition fails → action rejected, no side effects, no credits charged
• Post-condition fails → DLQ entry written, credits refunded
• Policy violation → blocked before execution

Five lines

from deed import DeedRuntime

runtime = DeedRuntime(".")
runtime.register("score_company", my_scorer, charge=1)
result = runtime.run("my_pipeline", "input/state.json")
print(result["score"])  # 0.82

What you get

• Pre/post contracts on every agent action
• Policy engine (cap / allow / deny) enforced before execution
• DEED Credits metering — charge per deed, refund on violation
• Checkpoint & replay — resume from last known good state
• DLQ — failed stages captured with full context

---

Examples

Mushroom Safety Triage — main working example

A four-stage safety-critical pipeline demonstrating contracts and the failure path.

cd examples/mushroom_safety
python run.py           # happy path → completed
python run.py --fail    # ContractViolation → DLQ

Stages: intake → taxonomy → risk → advisory

---

Sales Intelligence Agent — working example

A three-stage B2B sales pipeline with ICP scoring and outreach brief generation.

cd examples/sales_agent
python run.py               # happy path → completed, score 1.0
python run.py --restricted  # policy deny → failed (region == "restricted")

Stages: enrich → score → brief

---

Orchid Rescue Lab — .dd reference only

Agent specs and pipeline for a conservation triage workflow. No run.py — use the .dd files as reference for writing your own vertical.

examples/orchid_rescue/
├── deeds/agents/       legality_agent.dd, triage_agent.dd, curator_agent.dd
└── deeds/pipelines/    orchid_rescue_intelligence.dd

---

How register() works

runtime = DeedRuntime(
    project_root=".",           # must contain deeds/ with .dd files
    initial_credits=100,
    named_predicates_fn=my_fn,  # optional: callable(context) -> dict[str, bool]
)

(runtime
    .register("normalize",    normalize_fn,  charge=1)
    .register("score",        score_fn,      charge=1, retry=2)
    .register("send_alert",   alert_fn,      charge=1, idempotency_key="alert_id")
)

result = runtime.run("my_pipeline", "input/state.json")

---

.dd syntax

agent my_agent
  capabilities ["action_a", "action_b"]

  contract my_contract
    pre  input_present
    post result_generated

  policy
    cap  budget_tokens <= 3000
    deny action_b if region == "restricted"
    allow action_a if input_present

pipeline my_pipeline
  stage step_one
    agent my_agent
    -> action_a()
    checkpoint after
    on_error retry

  stage step_two
    agent my_agent
    -> action_b()
    on_error deadletter

---

Error types

from deed import ContractViolation, PolicyViolation, DeedError

try:
    result = runtime.run("my_pipeline", "input/state.json")
except ContractViolation as e:
    # pre or post condition failed
    # pre: action was NOT executed, no credits charged
    # post: action ran but outcome invalid, credits refunded
    print(e)
except PolicyViolation as e:
    # cap / deny / allow rule blocked the action
    # action was NOT executed, no credits charged
    print(e)

---

Replay after failure

# Resume from last checkpoint — skips completed steps, credits not re-charged
runtime = DeedRuntime(".", replay=True, initial_credits=100, ...)
runtime.register(...)
result = runtime.run("my_pipeline", "input/state.json")

---

Writing .dd files with an LLM

docs/MASTER_MANUAL_FOR_LLM.md is a complete authoring guide for generating .dd files. Use it as a system prompt to make any LLM produce idiomatic DEED agent specs from a domain description.

Includes: canonical model, naming conventions, anti-patterns, few-shot examples, validation checklist, templates for agent and pipeline blocks.

---

DEED Credits

Every deed execution costs credits (default: 1 credit per action, configurable per register()).

print(runtime.x402.credits)   # remaining balance
print(runtime.x402.spent)     # total spent this run

Credits are charged after the pre-condition passes and refunded automatically on post-condition failure. The metering layer uses the X402Client interface, which is designed for forward compatibility with the x402 payment protocol.

---

Docs

deed-docs.onrender.com

License

MIT — Deadly-Reiter