durable-agents 0.1.0__py3-none-any.whl

durable_agents/__init__.py

@@ -0,0 +1,126 @@
+"""An event-sourced runtime for durable, crash-resumable LLM agents.
+
+Everything an agent does — every model call, every tool call, every
+guardrail decision, every human approval — is appended to a log before
+and after it happens. State is a pure fold over that log, so a process
+that dies mid-run can be resumed by a different process that reads the
+log and finishes the job, without repeating side effects that already
+happened.
+
+    from durable_agents import Runtime, InMemoryEventStore, tool
+
+    @tool(side_effect=True)
+    async def issue_refund(order_id: str, amount: int, idempotency_key: str) -> dict:
+        return await payments.refund(order_id, amount, key=idempotency_key)
+
+    runtime = Runtime(store=InMemoryEventStore(), llm=my_client, tools=[issue_refund])
+    state = await runtime.start(goal="Refund order A-8891, item arrived damaged.")
+
+Swap InMemoryEventStore for PostgresEventStore when you want the run to
+outlive the process. See README.md for the full walkthrough.
+"""
+
+from durable_agents.events import (
+    ApprovalDenied,
+    ApprovalGranted,
+    ApprovalRequested,
+    Event,
+    GuardrailAction,
+    GuardrailLayer,
+    GuardrailTriggered,
+    LLMCallCompleted,
+    LLMCallFailed,
+    LLMCallRequested,
+    RunCompleted,
+    RunFailed,
+    RunFailureReason,
+    RunStarted,
+    ToolCallCompleted,
+    ToolCallFailed,
+    ToolCallInvocation,
+    ToolCallRequested,
+    hash_system_prompt,
+)
+from durable_agents.guardrails.decisions import PROFILES, GuardrailProfile, decide, get_profile
+from durable_agents.guardrails.types import GuardMatch, ScanResult
+from durable_agents.llm.protocol import LLMClient, LLMResponse
+from durable_agents.llm.scripted import ScriptedLLM
+from durable_agents.orchestrator import Orchestrator
+from durable_agents.runtime import Run, Runtime
+from durable_agents.state import (
+    GuardrailHit,
+    InFlightOp,
+    Message,
+    PendingApproval,
+    RunState,
+    RunStatus,
+    rebuild_state,
+)
+from durable_agents.storage.memory import InMemoryEventStore
+from durable_agents.storage.postgres import PostgresEventStore
+from durable_agents.storage.protocol import ConcurrencyConflict, EventStore
+from durable_agents.storage.schema import create_schema, schema_sql
+from durable_agents.tools.registry import Tool, idempotency_key, tool
+from durable_agents.worker import Worker
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # The five names most users need
+    "Runtime",
+    "Run",
+    "Worker",
+    "tool",
+    "InMemoryEventStore",
+    "PostgresEventStore",
+    "create_schema",
+    # Implement one of these to plug in your model provider
+    "LLMClient",
+    "LLMResponse",
+    "ScriptedLLM",
+    # Storage
+    "EventStore",
+    "ConcurrencyConflict",
+    "schema_sql",
+    # The loop itself, for anyone who wants it without the Runtime facade
+    "Orchestrator",
+    # Derived state
+    "RunState",
+    "RunStatus",
+    "Message",
+    "InFlightOp",
+    "PendingApproval",
+    "GuardrailHit",
+    "rebuild_state",
+    # Tools
+    "Tool",
+    "idempotency_key",
+    # Guardrails
+    "GuardrailProfile",
+    "PROFILES",
+    "decide",
+    "get_profile",
+    "GuardMatch",
+    "ScanResult",
+    # Events — the actual source of truth, worth having close to hand
+    "Event",
+    "RunStarted",
+    "RunCompleted",
+    "RunFailed",
+    "RunFailureReason",
+    "LLMCallRequested",
+    "LLMCallCompleted",
+    "LLMCallFailed",
+    "ToolCallInvocation",
+    "ToolCallRequested",
+    "ToolCallCompleted",
+    "ToolCallFailed",
+    "ApprovalRequested",
+    "ApprovalGranted",
+    "ApprovalDenied",
+    "GuardrailTriggered",
+    "GuardrailLayer",
+    "GuardrailAction",
+    "hash_system_prompt",
+    "__version__",
+]

durable_agents/api/app.py

@@ -0,0 +1,226 @@
+from datetime import datetime, timezone
+from decimal import Decimal
+from typing import Any
+from uuid import UUID, uuid4
+
+from fastapi import Depends, FastAPI, HTTPException, Query, Request
+from pydantic import BaseModel, Field, field_validator
+
+from durable_agents.events import ApprovalDenied, ApprovalGranted, RunStarted
+from durable_agents.guardrails.decisions import get_profile
+from durable_agents.state import RunState, RunStatus, rebuild_state
+from durable_agents.storage.protocol import ConcurrencyConflict, EventStore
+
+
+class PendingApprovalResponse(BaseModel):
+    tool: str
+    arguments: dict[str, Any]
+    reason: str
+
+
+class PendingApprovalListItem(BaseModel):
+    run_id: UUID
+    tool: str
+    arguments: dict[str, Any]
+    reason: str
+
+
+class RunStatusResponse(BaseModel):
+    run_id: UUID
+    status: RunStatus
+    step: int
+    total_tokens: int
+    total_cost_usd: Decimal
+    pending_approval: PendingApprovalResponse | None
+    final_answer: str | None
+    failure_reason: str | None
+
+
+class StartRunRequest(BaseModel):
+    """Validated here rather than at execution time, because a run is
+    recorded into an append-only log: a value accepted now can never be
+    corrected, and the run it produces fails on its first execution with
+    a reason ("max_steps_exceeded") describing a cap that was never
+    reachable. A 422 at submission is far kinder than a 201 followed by
+    a corpse.
+    """
+
+    goal: str = Field(min_length=1, max_length=100_000)
+    requested_by: str = Field(default="unknown", max_length=500)
+    system_prompt: str = Field(default="", max_length=100_000)
+    model: str | None = Field(default=None, max_length=200)
+    max_steps: int | None = Field(default=None, ge=1, le=10_000)
+    max_cost_usd: Decimal | None = Field(default=None, gt=0, le=Decimal("1000000"))
+    guardrail_profile: str | None = None
+
+    @field_validator("guardrail_profile")
+    @classmethod
+    def _known_profile(cls, value: str | None) -> str | None:
+        # get_profile raises on an unknown name, but only when the run is
+        # executed — which for an API-created run is inside a worker,
+        # where it fails on every poll forever, logging a stack trace
+        # each time and never reaching a terminal state.
+        if value is not None:
+            get_profile(value)
+        return value
+
+
+class ApproveRequest(BaseModel):
+    approver: str
+
+
+class DenyRequest(BaseModel):
+    approver: str
+    reason: str
+
+
+def get_store(request: Request) -> EventStore:
+    return request.app.state.store  # type: ignore[no-any-return]
+
+
+async def _load_state(run_id: UUID, store: EventStore) -> tuple[RunState, int]:
+    """Returns the rebuilt state plus the event count (== next expected seq)."""
+    events = await store.read(run_id)
+    if not events:
+        raise HTTPException(status_code=404, detail="run not found")
+    return rebuild_state(events), len(events)
+
+
+def _status_response(run_id: UUID, state: RunState) -> RunStatusResponse:
+    return RunStatusResponse(
+        run_id=run_id,
+        status=state.status,
+        step=state.step,
+        total_tokens=state.total_tokens,
+        total_cost_usd=state.total_cost_usd,
+        pending_approval=(
+            PendingApprovalResponse(
+                tool=state.pending_approval.tool,
+                arguments=state.pending_approval.arguments,
+                reason=state.pending_approval.reason,
+            )
+            if state.pending_approval is not None
+            else None
+        ),
+        final_answer=state.final_answer,
+        failure_reason=state.failure_reason,
+    )
+
+
+def create_app(
+    store: EventStore,
+    *,
+    default_model: str = "unspecified",
+    default_max_steps: int = 25,
+    default_max_cost_usd: Decimal = Decimal("1.00"),
+    default_guardrail_profile: str = "validation",
+) -> FastAPI:
+    app = FastAPI(title="durable-agents")
+    app.state.store = store
+
+    @app.post("/runs", status_code=201, response_model=RunStatusResponse)
+    async def start_run(
+        body: StartRunRequest, store: EventStore = Depends(get_store)
+    ) -> RunStatusResponse:
+        # Records only — does not execute. An agent run can take minutes;
+        # blocking an HTTP request for that is fragile against timeouts,
+        # load balancers, and retries, and matches how approve/deny
+        # already work here (they record a decision, a separate process
+        # does the resuming). This mirrors Runtime.create(), not
+        # Runtime.start() — see DECISIONS.md's "API surface" section for
+        # the reasoning.
+        run_id = uuid4()
+        started = RunStarted(
+            seq=0,
+            created_at=datetime.now(timezone.utc),
+            goal=body.goal,
+            model=body.model or default_model,
+            system_prompt=body.system_prompt,
+            max_steps=body.max_steps if body.max_steps is not None else default_max_steps,
+            max_cost_usd=(
+                body.max_cost_usd if body.max_cost_usd is not None else default_max_cost_usd
+            ),
+            requested_by=body.requested_by,
+            guardrail_profile=body.guardrail_profile or default_guardrail_profile,
+        )
+        await store.append(run_id, 0, started)
+        return _status_response(run_id, rebuild_state([started]))
+
+    @app.get("/approvals", response_model=list[PendingApprovalListItem])
+    async def list_pending_approvals(
+        limit: int = Query(default=100, ge=1, le=1000),
+        store: EventStore = Depends(get_store),
+    ) -> list[PendingApprovalListItem]:
+        # An approver's dashboard needs to discover what needs a
+        # decision without already knowing a run_id for each one — that
+        # is the whole reason this exists. A dedicated resource rather
+        # than a filtered /runs, since this queue is not "runs,
+        # restricted somehow" — it's its own thing, and /runs?status=...
+        # would misleadingly read as a general run-lister that 400s on
+        # every value but one.
+        pending = await store.find_awaiting_approval(limit=limit)
+        return [
+            PendingApprovalListItem(
+                run_id=run_id,
+                tool=event.tool,
+                arguments=event.arguments,
+                reason=event.reason,
+            )
+            for run_id, event in pending
+        ]
+
+    @app.get("/runs/{run_id}", response_model=RunStatusResponse)
+    async def get_run_status(
+        run_id: UUID, store: EventStore = Depends(get_store)
+    ) -> RunStatusResponse:
+        state, _next_seq = await _load_state(run_id, store)
+        return _status_response(run_id, state)
+
+    @app.post("/runs/{run_id}/approve", status_code=204)
+    async def approve_run(
+        run_id: UUID, body: ApproveRequest, store: EventStore = Depends(get_store)
+    ) -> None:
+        state, next_seq = await _load_state(run_id, store)
+        if state.status != "awaiting_approval":
+            raise HTTPException(
+                status_code=409, detail=f"run is not awaiting approval (status={state.status})"
+            )
+        try:
+            await store.append(
+                run_id,
+                next_seq,
+                ApprovalGranted(
+                    seq=next_seq, created_at=datetime.now(timezone.utc), approver=body.approver
+                ),
+            )
+        except ConcurrencyConflict as exc:
+            raise HTTPException(
+                status_code=409, detail="run state changed concurrently, retry"
+            ) from exc
+
+    @app.post("/runs/{run_id}/deny", status_code=204)
+    async def deny_run(
+        run_id: UUID, body: DenyRequest, store: EventStore = Depends(get_store)
+    ) -> None:
+        state, next_seq = await _load_state(run_id, store)
+        if state.status != "awaiting_approval":
+            raise HTTPException(
+                status_code=409, detail=f"run is not awaiting approval (status={state.status})"
+            )
+        try:
+            await store.append(
+                run_id,
+                next_seq,
+                ApprovalDenied(
+                    seq=next_seq,
+                    created_at=datetime.now(timezone.utc),
+                    approver=body.approver,
+                    reason=body.reason,
+                ),
+            )
+        except ConcurrencyConflict as exc:
+            raise HTTPException(
+                status_code=409, detail="run state changed concurrently, retry"
+            ) from exc
+
+    return app

durable_agents/cli.py

@@ -0,0 +1,187 @@
+import argparse
+import asyncio
+import os
+import sys
+from urllib.parse import urlsplit, urlunsplit
+from uuid import UUID
+
+from durable_agents.orchestrator import Orchestrator
+from durable_agents.replay_view import Style, render, should_use_colour
+from durable_agents.state import rebuild_state
+from durable_agents.storage.postgres import PostgresEventStore
+from durable_agents.storage.schema import create_schema
+
+# OpenAICompatibleClient is imported inside the one subcommand that uses
+# it, not here. It pulls in httpx, which lives in the optional "openai"
+# extra — importing it at module scope meant `pip install
+# durable-agents` followed by `durable-agents --help` died with
+# ModuleNotFoundError, i.e. the entry point every doc points at was
+# broken on a plain install.
+#
+# Every subcommand here is generic. The fixed refund demo used to live
+# alongside them as `durable-agents demo`; it is now
+# examples/crash_resume_demo.py, since a library's console script has no
+# business shipping a scripted demo of someone else's domain — and it
+# could not have kept working anyway once the refund modules stopped
+# being part of the package.
+
+DEFAULT_DSN = "postgresql://durable_agents:durable_agents@localhost:5432/durable_agents"
+
+
+def redact_dsn(dsn: str) -> str:
+    """A connection string with the password starred out, safe to print.
+
+    Which database was touched is genuinely useful to see; the password
+    sitting next to it is not, and stdout is exactly where credentials
+    escape — terminal scrollback, CI logs, screen shares. An
+    unparseable string is reported as-is minus everything before the
+    "@", since guessing at its structure risks leaking the very thing
+    this exists to hide.
+    """
+
+    try:
+        parts = urlsplit(dsn)
+    except ValueError:
+        return dsn.rsplit("@", 1)[-1]
+
+    # urlsplit does not raise on a malformed connection string — given
+    # "postgres//user:pw@host/db" (one slash missing) it happily reports
+    # no netloc and no password, and returning the input unchanged would
+    # then print the password in full. A visible "@" with nothing parsed
+    # around it means the structure is not what it looks like, so drop
+    # everything before it rather than trusting the parse.
+    if not parts.netloc:
+        return dsn.rsplit("@", 1)[-1] if "@" in dsn else dsn
+
+    if parts.password is None:
+        return dsn
+
+    host = parts.hostname or ""
+    if parts.port:
+        host = f"{host}:{parts.port}"
+    userinfo = f"{parts.username}:***@" if parts.username else "***@"
+    return urlunsplit((parts.scheme, f"{userinfo}{host}", parts.path, parts.query, parts.fragment))
+
+
+
+async def _replay(run_id: UUID, dsn: str, *, colour: bool | None, show_thinking: bool) -> None:
+    store = await PostgresEventStore.connect(dsn)
+    events = await store.read(run_id)
+
+    if not events:
+        print(f"No events found for run {run_id}")
+        return
+
+    style = Style.enabled() if should_use_colour(colour) else Style()
+    print(render(run_id, events, rebuild_state(events), style, show_thinking))
+
+
+async def _resume(run_id: UUID, dsn: str) -> None:
+    """Resume ANY run — including one created over the API with an
+    arbitrary goal — using a real LLM client.
+
+    Configured entirely through environment variables (LLM_API_KEY /
+    LLM_BASE_URL / LLM_MODEL), the same convention tests/live and the
+    examples/live_*.py scripts already use, rather than a hardcoded
+    provider — see DECISIONS.md's "Provider client" section for why.
+
+    Runs with NO tools: this command has no way to know what functions a
+    specific deployment wants wired up for a given run, so it only
+    handles pure conversational/reasoning goals. A run that needs real
+    tools needs a real script wired against Runtime/Orchestrator
+    directly — see README.md's "Bring your own model" section.
+    """
+
+    try:
+        from durable_agents.llm.openai_compatible import OpenAICompatibleClient
+    except ImportError as exc:
+        print(f"This command needs the 'openai' extra: pip install 'durable-agents[openai]'  ({exc})")
+        sys.exit(1)
+
+    api_key = os.environ.get("LLM_API_KEY")
+    if not api_key:
+        print("Set LLM_API_KEY to resume a run with a real LLM (a free Groq key works).")
+        print("This command runs with no tools — only goals that need pure reasoning,")
+        print("no tool calls, will complete. For anything else, write a script against")
+        print("Runtime/Orchestrator directly (see README.md).")
+        sys.exit(1)
+
+    base_url = os.environ.get("LLM_BASE_URL", "https://api.groq.com/openai/v1")
+    model = os.environ.get("LLM_MODEL", "openai/gpt-oss-120b")
+
+    store = await PostgresEventStore.connect(dsn)
+    llm = OpenAICompatibleClient(base_url=base_url, model=model, api_key=api_key)
+    try:
+        orchestrator = Orchestrator(store=store, llm=llm, tools={})
+        final_state = await orchestrator.run(run_id)
+    finally:
+        await llm.aclose()
+
+    print(f"Run {run_id}: {final_state.status}")
+    print(f"(see the full trace with: durable-agents replay {run_id})")
+
+
+def main() -> None:
+    # Windows consoles still default to a legacy codepage (cp1252),
+    # which raises UnicodeEncodeError on any non-ASCII character in a
+    # goal, tool result, or final answer — i.e. on most of the world's
+    # text. Printing a run's own recorded content must not depend on
+    # the operator's locale.
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+    parser = argparse.ArgumentParser(prog="durable-agents")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    replay_parser = subparsers.add_parser(
+        "replay", help="Print the full event trace for a run"
+    )
+    replay_parser.add_argument("run_id", type=UUID)
+    replay_parser.add_argument(
+        "--dsn", default=os.environ.get("DATABASE_URL", DEFAULT_DSN)
+    )
+    replay_parser.add_argument(
+        "--thinking",
+        action="store_true",
+        help="Include LLMCallRequested events (hidden by default as noise)",
+    )
+    replay_parser.add_argument(
+        "--no-color", action="store_true", help="Disable coloured output"
+    )
+
+    init_db_parser = subparsers.add_parser(
+        "init-db", help="Create the events table (idempotent, safe to re-run)"
+    )
+    init_db_parser.add_argument(
+        "--dsn", default=os.environ.get("DATABASE_URL", DEFAULT_DSN)
+    )
+
+    resume_parser = subparsers.add_parser(
+        "resume",
+        help="Resume ANY run with a real LLM (needs LLM_API_KEY; no tools wired up)",
+    )
+    resume_parser.add_argument("run_id", type=UUID)
+    resume_parser.add_argument(
+        "--dsn", default=os.environ.get("DATABASE_URL", DEFAULT_DSN)
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "init-db":
+        asyncio.run(create_schema(args.dsn))
+        print(f"Schema ready on {redact_dsn(args.dsn)}")
+    elif args.command == "replay":
+        asyncio.run(
+            _replay(
+                args.run_id,
+                args.dsn,
+                colour=False if args.no_color else None,
+                show_thinking=args.thinking,
+            )
+        )
+    elif args.command == "resume":
+        asyncio.run(_resume(args.run_id, args.dsn))
+
+
+if __name__ == "__main__":
+    main()