avatar-runtime 0.1.0__py3-none-any.whl

avatar/__init__.py

@@ -0,0 +1,45 @@
+# Copyright 2026 Avatar Runtime Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Avatar — a durable execution engine for AI agents.
+
+"Temporal for AI agents." A crash-safe, append-only, replayable state machine
+for an LLM agent's ``plan → tool → observe → commit`` loop, backed entirely by
+Postgres. A worker can die at any point; another resumes from the ledger and no
+tool side effect is dispatched twice from Avatar's side.
+
+The developer-facing surface lives here::
+
+    from avatar import Avatar, agent, tool, Plan, State, ToolCall
+
+See ``avatar.sdk`` for the client and decorators, ``avatar.engine`` for the
+durable core, and ``avatar.api`` for the control API.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# Re-export the full documented SDK surface so the README/sdk examples
+# (``from avatar import Avatar, tool, Plan, ToolCall``) work off the top-level
+# package, not just ``avatar.sdk``.
+from avatar.sdk import (  # noqa: E402
+    Avatar,
+    Plan,
+    State,
+    ToolCall,
+    agent,
+    current_idempotency_key,
+    tool,
+)
+
+__all__ = [
+    "Avatar",
+    "agent",
+    "tool",
+    "Plan",
+    "State",
+    "ToolCall",
+    "current_idempotency_key",
+    "__version__",
+]

avatar/api/__init__.py

@@ -0,0 +1,10 @@
+# Copyright 2026 Avatar Runtime Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Avatar control API (FastAPI) — single-key auth + SSE."""
+
+from __future__ import annotations
+
+from avatar.api.app import create_app
+
+__all__ = ["create_app"]

avatar/api/app.py

@@ -0,0 +1,106 @@
+# Copyright 2026 Avatar Runtime Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""FastAPI application factory: lifespan (DB), single-key auth, routes, dashboard."""
+
+from __future__ import annotations
+
+import contextlib
+import hmac
+from pathlib import Path
+
+from fastapi import FastAPI, Header, HTTPException, Request
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from avatar.api.ratelimit import TokenBucket
+from avatar.config import Settings, check_startup_safety, load_settings
+from avatar.engine.db import create_engine, create_session_factory, init_db
+
+# Ships inside the package (avatar/dashboard/) so it is present on a `pip
+# install` as well as in the Docker image — not just in a source checkout.
+_DASHBOARD_DIR = Path(__file__).resolve().parent.parent / "dashboard"
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or load_settings()
+    # Fail fast on an insecure production configuration (default API key, etc.).
+    check_startup_safety(settings)
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app: FastAPI):
+        engine = create_engine(settings.database_url, settings)
+        if settings.is_sqlite:
+            await init_db(engine)
+        app.state.engine = engine
+        app.state.session_factory = create_session_factory(engine)
+        app.state.settings = settings
+        app.state.rate_limiter = TokenBucket(
+            settings.rate_limit_per_second, settings.rate_limit_burst
+        )
+        # Load developer agents/tools if configured (harmless if none).
+        with contextlib.suppress(Exception):
+            from avatar.engine.registry import load_app
+
+            load_app()
+        yield
+        await engine.dispose()
+
+    app = FastAPI(title="Avatar", version="0.1.0", lifespan=lifespan)
+
+    from avatar.api.routes import router
+
+    app.include_router(router)
+
+    # Marketing landing at `/` (static), the developer dashboard at `/app`.
+    if _DASHBOARD_DIR.exists():
+        @app.get("/", response_class=HTMLResponse)
+        async def landing() -> str:
+            landing_file = _DASHBOARD_DIR / "landing.html"
+            if landing_file.exists():
+                return landing_file.read_text()
+            return _dashboard_html(settings)
+
+        @app.get("/app", response_class=HTMLResponse)
+        async def dashboard_index() -> str:
+            return _dashboard_html(settings)
+
+        app.mount(
+            "/static", StaticFiles(directory=str(_DASHBOARD_DIR)), name="static"
+        )
+
+    return app
+
+
+def _dashboard_html(settings: Settings) -> str:
+    """Render the dashboard. The static API key is injected ONLY in dev mode;
+    in production the page ships with no key and prompts the operator for one
+    (kept in localStorage), so the key is never embedded in served HTML."""
+    html = (_DASHBOARD_DIR / "index.html").read_text()
+    injected = settings.api_key if settings.dev_mode else ""
+    return html.replace("__AVATAR_API_KEY__", injected)
+
+
+# --- shared dependencies -----------------------------------------------------
+
+
+async def require_auth(request: Request, authorization: str = Header(default="")) -> None:
+    """Single static API key. ``Authorization: Bearer <key>``. Nothing else.
+
+    Uses a constant-time comparison to avoid leaking the key via timing.
+    """
+    settings: Settings = request.app.state.settings
+    expected = f"Bearer {settings.api_key}"
+    if not hmac.compare_digest(authorization, expected):
+        raise HTTPException(status_code=401, detail="invalid or missing API key")
+
+
+async def get_session(request: Request) -> AsyncSession:
+    factory = request.app.state.session_factory
+    async with factory() as session:
+        yield session
+
+
+# Re-export for routes module convenience.
+__all__ = ["create_app", "require_auth", "get_session"]

avatar/api/ratelimit.py

@@ -0,0 +1,36 @@
+# Copyright 2026 Avatar Runtime Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""A tiny in-process token-bucket rate limiter for the control API.
+
+Single static key ⇒ a single global bucket is sufficient (per-key == global).
+This guards the write path (enqueue) against a client flooding the queue. It is
+intentionally process-local: with multiple API replicas, set the limit per
+replica or front the API with a gateway. For per-tenant limits, see the
+Avatar Cloud roadmap.
+"""
+
+from __future__ import annotations
+
+import time
+
+
+class TokenBucket:
+    def __init__(self, rate_per_second: float, burst: int) -> None:
+        self.rate = max(0.0, rate_per_second)
+        self.capacity = max(1, burst)
+        self.tokens = float(self.capacity)
+        self.updated = time.monotonic()
+
+    def allow(self, cost: float = 1.0) -> bool:
+        """Consume ``cost`` tokens if available. Returns False when throttled.
+        A non-positive rate disables limiting (always allow)."""
+        if self.rate <= 0:
+            return True
+        now = time.monotonic()
+        self.tokens = min(self.capacity, self.tokens + (now - self.updated) * self.rate)
+        self.updated = now
+        if self.tokens >= cost:
+            self.tokens -= cost
+            return True
+        return False

avatar/api/routes.py

@@ -0,0 +1,350 @@
+# Copyright 2026 Avatar Runtime Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Control API endpoints (§ control surface).
+
+All ``/v1`` routes require the single static API key. SSE streams the ledger as
+steps commit. The dashboard and SDK are both pure clients of these routes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import PlainTextResponse, StreamingResponse
+from pydantic import BaseModel, Field
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from avatar.api.app import get_session, require_auth
+from avatar.engine.models import (
+    RUN_STATUSES,
+    TERMINAL_STATUSES,
+    AgentRun,
+    AgentRunStep,
+    Approval,
+    utcnow,
+)
+from avatar.engine.replay import fork_run
+
+router = APIRouter()
+
+
+async def rate_limit(request: Request) -> None:
+    """Throttle the write path so a client cannot flood the queue."""
+    limiter = getattr(request.app.state, "rate_limiter", None)
+    if limiter is not None and not limiter.allow():
+        raise HTTPException(
+            status_code=429,
+            detail="rate limit exceeded",
+            headers={"Retry-After": "1"},
+        )
+
+
+# --- request/response models -------------------------------------------------
+
+
+class CreateRun(BaseModel):
+    agent_ref: str
+    input: dict[str, Any] = Field(default_factory=dict)
+    budget_cap_cents: int | None = None
+    idempotency_key: str | None = None
+
+
+class ReplayReq(BaseModel):
+    from_seq: int
+
+
+def _run_summary(r: AgentRun) -> dict:
+    return {
+        "id": r.id,
+        "agent_ref": r.agent_ref,
+        "status": r.status,
+        "attempt": r.attempt,
+        "cursor_seq": r.cursor_seq,
+        "budget_cap_cents": r.budget_cap_cents,
+        "budget_used_cents": r.budget_used_cents,
+        "error_class": r.error_class,
+        "output": r.output,
+        "forked_from": r.forked_from,
+        "fork_seq": r.fork_seq,
+        "created_at": r.created_at.isoformat() if r.created_at else None,
+        "updated_at": r.updated_at.isoformat() if r.updated_at else None,
+    }
+
+
+def _step_dict(s: AgentRunStep) -> dict:
+    return {
+        "seq": s.seq,
+        "type": s.type,
+        "payload": s.payload,
+        "tool_call_id": s.tool_call_id,
+        "idempotency_key": s.idempotency_key,
+        "cost_cents": s.cost_cents,
+        "worker_id": s.worker_id,
+        "attempt": s.attempt,
+        "created_at": s.created_at.isoformat() if s.created_at else None,
+    }
+
+
+async def _get_run(db: AsyncSession, run_id: str) -> AgentRun:
+    run = (
+        await db.execute(select(AgentRun).where(AgentRun.id == run_id))
+    ).scalar_one_or_none()
+    if run is None:
+        raise HTTPException(status_code=404, detail="run not found")
+    return run
+
+
+# --- endpoints ---------------------------------------------------------------
+
+
+@router.post(
+    "/v1/runs",
+    status_code=202,
+    dependencies=[Depends(require_auth), Depends(rate_limit)],
+)
+async def create_run(
+    body: CreateRun, request: Request, db: AsyncSession = Depends(get_session)
+) -> dict:
+    if body.idempotency_key:
+        existing = (
+            await db.execute(
+                select(AgentRun).where(AgentRun.idempotency_key == body.idempotency_key)
+            )
+        ).scalar_one_or_none()
+        if existing is not None:
+            return {"id": existing.id, "status": existing.status}
+    # Backpressure: refuse new work when the queue is already saturated.
+    cap = request.app.state.settings.max_queue_depth
+    if cap > 0:
+        queued = (
+            await db.execute(
+                select(func.count())
+                .select_from(AgentRun)
+                .where(AgentRun.status == "queued")
+            )
+        ).scalar_one()
+        if queued >= cap:
+            raise HTTPException(
+                status_code=429,
+                detail=f"queue is full ({queued} queued, cap {cap})",
+                headers={"Retry-After": "5"},
+            )
+    run = AgentRun(
+        agent_ref=body.agent_ref,
+        input=body.input,
+        budget_cap_cents=body.budget_cap_cents,
+        idempotency_key=body.idempotency_key,
+        status="queued",
+    )
+    db.add(run)
+    await db.commit()
+    return {"id": run.id, "status": run.status}
+
+
+@router.get("/v1/runs", dependencies=[Depends(require_auth)])
+async def list_runs(
+    status: str | None = None,
+    limit: int = 50,
+    db: AsyncSession = Depends(get_session),
+) -> dict:
+    q = select(AgentRun).order_by(AgentRun.created_at.desc()).limit(min(limit, 200))
+    if status:
+        q = q.where(AgentRun.status == status)
+    rows = (await db.execute(q)).scalars().all()
+    return {"runs": [_run_summary(r) for r in rows]}
+
+
+@router.get("/v1/runs/{run_id}", dependencies=[Depends(require_auth)])
+async def get_run(run_id: str, db: AsyncSession = Depends(get_session)) -> dict:
+    return _run_summary(await _get_run(db, run_id))
+
+
+@router.get("/v1/runs/{run_id}/steps", dependencies=[Depends(require_auth)])
+async def get_steps(run_id: str, db: AsyncSession = Depends(get_session)) -> list[dict]:
+    await _get_run(db, run_id)
+    rows = (
+        await db.execute(
+            select(AgentRunStep)
+            .where(AgentRunStep.run_id == run_id)
+            .order_by(AgentRunStep.seq)
+        )
+    ).scalars().all()
+    return [_step_dict(s) for s in rows]
+
+
+@router.post("/v1/runs/{run_id}/cancel", dependencies=[Depends(require_auth)])
+async def cancel_run(run_id: str, db: AsyncSession = Depends(get_session)) -> dict:
+    run = await _get_run(db, run_id)
+    if run.status in TERMINAL_STATUSES:
+        return _run_summary(run)
+    run.cancel_requested = True
+    # If it never started, cancel immediately.
+    if run.status == "queued":
+        run.status = "failed"
+        run.error_class = "cancelled"
+        run.output = {"error": "cancelled before start"}
+    await db.commit()
+    return _run_summary(run)
+
+
+@router.post("/v1/runs/{run_id}/approve", dependencies=[Depends(require_auth)])
+async def approve_run(run_id: str, db: AsyncSession = Depends(get_session)) -> dict:
+    return await _resolve_approval(db, run_id, "approved")
+
+
+@router.post("/v1/runs/{run_id}/reject", dependencies=[Depends(require_auth)])
+async def reject_run(run_id: str, db: AsyncSession = Depends(get_session)) -> dict:
+    return await _resolve_approval(db, run_id, "rejected")
+
+
+async def _resolve_approval(db: AsyncSession, run_id: str, decision: str) -> dict:
+    run = await _get_run(db, run_id)
+    if run.status != "approval_wait":
+        raise HTTPException(status_code=409, detail="run is not awaiting approval")
+    appr = (
+        await db.execute(
+            select(Approval)
+            .where(Approval.run_id == run_id, Approval.status == "pending")
+            .order_by(Approval.created_at.desc())
+        )
+    ).scalars().first()
+    if appr is None:
+        raise HTTPException(status_code=409, detail="no pending approval")
+    appr.status = decision
+    appr.decided_at = utcnow()
+    # Re-queue so a worker resumes and either dispatches or records the rejection.
+    run.status = "queued"
+    run.lease_owner = None
+    run.lease_expires_at = None
+    await db.commit()
+    return _run_summary(run)
+
+
+@router.post("/v1/runs/{run_id}/replay", dependencies=[Depends(require_auth)])
+async def replay_run(
+    run_id: str, body: ReplayReq, db: AsyncSession = Depends(get_session)
+) -> dict:
+    source = await _get_run(db, run_id)
+    new_run = await fork_run(db, source, body.from_seq)
+    return {"id": new_run.id, "status": new_run.status,
+            "forked_from": run_id, "fork_seq": body.from_seq}
+
+
+@router.get("/v1/runs/{run_id}/stream", dependencies=[Depends(require_auth)])
+async def stream_run(run_id: str, request: Request) -> StreamingResponse:
+    factory = request.app.state.session_factory
+
+    async def event_gen():
+        last_seq = 0
+        # Replay existing steps first, then tail new ones.
+        while True:
+            if await request.is_disconnected():
+                return
+            async with factory() as db:
+                run = (
+                    await db.execute(select(AgentRun).where(AgentRun.id == run_id))
+                ).scalar_one_or_none()
+                if run is None:
+                    yield _sse({"event": "error", "detail": "run not found"})
+                    return
+                steps = (
+                    await db.execute(
+                        select(AgentRunStep)
+                        .where(AgentRunStep.run_id == run_id, AgentRunStep.seq > last_seq)
+                        .order_by(AgentRunStep.seq)
+                    )
+                ).scalars().all()
+                for s in steps:
+                    last_seq = s.seq
+                    yield _sse({"event": "step", **_step_dict(s)})
+                if run.status in TERMINAL_STATUSES or run.status == "approval_wait":
+                    yield _sse({"event": "status", "status": run.status,
+                                "output": run.output})
+                    return
+            await asyncio.sleep(0.3)
+
+    return StreamingResponse(event_gen(), media_type="text/event-stream")
+
+
+def _sse(obj: dict) -> str:
+    return f"data: {json.dumps(obj, default=str)}\n\n"
+
+
+@router.get("/healthz")
+async def healthz() -> dict:
+    return {"ok": True}
+
+
+@router.get("/readyz")
+async def readyz(request: Request) -> dict:
+    factory = request.app.state.session_factory
+    try:
+        async with factory() as db:
+            await db.execute(select(AgentRun.id).limit(1))
+        return {"ready": True}
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=503, detail=f"db not ready: {exc}") from exc
+
+
+async def _fleet_stats(db: AsyncSession) -> dict:
+    """Operational snapshot: runs by status, dead count, oldest-queued age."""
+    rows = (
+        await db.execute(
+            select(AgentRun.status, func.count()).group_by(AgentRun.status)
+        )
+    ).all()
+    by_status = {s: 0 for s in RUN_STATUSES}
+    by_status.update({status: n for status, n in rows})
+    oldest_queued = (
+        await db.execute(
+            select(func.min(AgentRun.created_at)).where(AgentRun.status == "queued")
+        )
+    ).scalar_one_or_none()
+    age = (utcnow() - oldest_queued).total_seconds() if oldest_queued else 0.0
+    return {
+        "by_status": by_status,
+        "queue_depth": by_status.get("queued", 0),
+        "running": by_status.get("leased", 0) + by_status.get("running", 0),
+        "dead": by_status.get("dead", 0),
+        "oldest_queued_age_seconds": round(age, 1),
+    }
+
+
+@router.get("/v1/stats", dependencies=[Depends(require_auth)])
+async def stats(db: AsyncSession = Depends(get_session)) -> dict:
+    return await _fleet_stats(db)
+
+
+@router.get("/metrics", response_class=PlainTextResponse)
+async def metrics(request: Request) -> str:
+    """Prometheus text exposition. Unauthenticated by convention so a scraper
+    can reach it; put it behind your network policy / reverse proxy."""
+    factory = request.app.state.session_factory
+    async with factory() as db:
+        s = await _fleet_stats(db)
+    lines = [
+        "# HELP avatar_runs Total runs by status.",
+        "# TYPE avatar_runs gauge",
+    ]
+    for status, n in s["by_status"].items():
+        lines.append(f'avatar_runs{{status="{status}"}} {n}')
+    lines += [
+        "# HELP avatar_queue_depth Runs currently queued.",
+        "# TYPE avatar_queue_depth gauge",
+        f"avatar_queue_depth {s['queue_depth']}",
+        "# HELP avatar_runs_running Runs currently leased/running.",
+        "# TYPE avatar_runs_running gauge",
+        f"avatar_runs_running {s['running']}",
+        "# HELP avatar_runs_dead Dead-lettered (poison) runs.",
+        "# TYPE avatar_runs_dead gauge",
+        f"avatar_runs_dead {s['dead']}",
+        "# HELP avatar_oldest_queued_age_seconds Age of the oldest queued run.",
+        "# TYPE avatar_oldest_queued_age_seconds gauge",
+        f"avatar_oldest_queued_age_seconds {s['oldest_queued_age_seconds']}",
+    ]
+    return "\n".join(lines) + "\n"