ai-effectlog

effect-log

Semantic side-effect tracking for AI agents.

When an AI agent crashes mid-task, what happens on restart? Without effect-log, irreversible actions (emails, payments, deployments) get repeated. With effect-log, the system knows what completed and what didn't — it returns sealed results for finished work and resumes from where it left off.

The Core Idea

Every tool declares its effect kind at registration time. This drives all recovery behavior:

Quick Start

from effect_log import EffectKind, EffectLog, ToolDef

def send_email(args):
    return smtp.send(args["to"], args["subject"], args["body"])

tools = [
    ToolDef("read_file",  EffectKind.ReadOnly,         read_file),
    ToolDef("send_email", EffectKind.IrreversibleWrite, send_email),
    ToolDef("upsert",     EffectKind.IdempotentWrite,   upsert_record),
]

log = EffectLog(execution_id="task-001", tools=tools, storage="sqlite:///effects.db")
log.execute("read_file",  {"path": "/tmp/report.csv"})
log.execute("send_email", {"to": "ceo@co.com", "subject": "Report", "body": "..."})
log.execute("upsert",     {"id": "report-001", "data": data})

Recovery — just add recover=True, re-run the same steps:

log = EffectLog(execution_id="task-001", tools=tools, storage="sqlite:///effects.db", recover=True)
log.execute("read_file",  {"path": "/tmp/report.csv"})  # Replayed (fresh data)
log.execute("send_email", {"to": "ceo@co.com", ...})    # Sealed — NOT re-sent
log.execute("upsert",     {"id": "report-001", ...})    # Replayed (idempotent)

Framework Integration

Built-in middleware for major agent frameworks:

See examples/ for runnable demos:

• crash_recovery.py — Core crash recovery demo (Phase 1 milestone)
• langgraph_integration.py — LangGraph ToolNode + tool wrapping
• openai_agents_integration.py — OpenAI Agents SDK wrapping
• crewai_integration.py — CrewAI tool + crew wrapping

How It Works

A write-ahead log with two record types:

1. Intent — written before execution (tool name, effect kind, input, cursor)
2. Completion — written after execution (outcome, sealed response)

Intent without completion = crash detected. The recovery engine uses the effect kind to decide: replay, return sealed, compensate, or escalate.

Building from Source

# Rust
cargo build --release
cargo test --workspace --all-features

# Python
cd bindings/python
pip install maturin
maturin develop --all-features
pytest tests/ -v

Roadmap

• Core library — WAL engine, recovery engine, SQLite + in-memory backends
• Python bindings — PyO3 + maturin
• Framework middleware — LangGraph, OpenAI Agents SDK, CrewAI
• TypeScript bindings — napi-rs, Vercel AI SDK
• Additional backends — RocksDB, S3, Restate journal
• Auto-classification — infer effect kind from HTTP methods / API metadata

Inspiration

The idea behind this project was inspired by a blog post from Guanlan Dai. He introduced the concepts of effect log and semantic correctness.

License

Apache-2.0