reactifact 0.6.0__py3-none-any.whl

reactifact/tools.py

@@ -0,0 +1,111 @@
+"""Tools: the \"function + schema\" contract for LLM agents (§46–47, §68).
+
+`@tool` turns an async function into a `FunctionTool` (name, description and JSON
+argument schema are derived from the signature). Tool usage — see `llm_agent.LLMAgent`:
+the \"which tool and with which arguments\" decision loop is driven by the LLM, the
+framework executes.
+
+Tools are capabilities; they are not part of consume/produce: those bind artifacts.
+"""
+
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import BaseModel, Field, create_model
+
+
+class ToolOutput(BaseModel):
+    """Tool execution result. `error` is set on failure (not an exception)."""
+
+    text: str = ""
+    data: dict[str, Any] = Field(default_factory=dict)
+    error: str = ""
+
+
+class Tool(ABC):
+    """Contract for an external operation: \"Do this operation\" (§46).
+
+    For an LLM agent (`LLMAgent`) a tool must provide a JSON schema of its
+    arguments (`schema`), from which the model picks the operation and arguments.
+    `@tool` builds it from the signature automatically.
+    """
+
+    name: str
+    description: str = ""
+    destructive: bool = False
+    schema: dict[str, Any] = {}
+
+    @abstractmethod
+    async def execute(self, args: dict[str, Any]) -> ToolOutput:
+        """Execute the operation; failure is an exception or `ToolOutput(error=...)`."""
+        ...
+
+
+def _args_model(fn: Callable[..., Any]) -> type[BaseModel]:
+    """Builds a Pydantic model of arguments from the function signature (→ JSON schema)."""
+    fields: dict[str, Any] = {}
+    for name, param in inspect.signature(fn).parameters.items():
+        if param.kind not in (
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.KEYWORD_ONLY,
+        ):
+            continue
+        annotation = (
+            param.annotation if param.annotation is not inspect.Parameter.empty else Any
+        )
+        if param.default is inspect.Parameter.empty:
+            fields[name] = (annotation, ...)  # required argument
+        else:
+            fields[name] = (annotation, param.default)
+    return create_model(f"args_{fn.__name__}", **fields)
+
+
+class FunctionTool(Tool):
+    """Tool from a plain async function: schema is derived from the signature."""
+
+    def __init__(
+        self,
+        fn: Callable[..., Any],
+        *,
+        name: str | None = None,
+        destructive: bool = False,
+        description: str | None = None,
+    ):
+        self._fn = fn
+        self.args_model = _args_model(fn)
+        self.name = name or fn.__name__
+        self.destructive = destructive
+        self.description = description or (fn.__doc__ or "").strip() or fn.__name__
+        self.schema = self.args_model.model_json_schema()
+
+    async def execute(self, args: dict[str, Any]) -> ToolOutput:
+        validated = self.args_model(**args)
+        result = await self._fn(**validated.model_dump())
+        if isinstance(result, ToolOutput):
+            return result
+        if isinstance(result, str):
+            return ToolOutput(text=result)
+        if isinstance(result, dict):
+            return ToolOutput(data=result)
+        return ToolOutput(text=str(result))
+
+
+def tool(
+    fn: Callable[..., Any] | None = None,
+    *,
+    name: str | None = None,
+    destructive: bool = False,
+    description: str | None = None,
+) -> Any:
+    """Decorator: turns an async function into a `FunctionTool` (schema from the signature)."""
+
+    def wrap(f: Callable[..., Any]) -> FunctionTool:
+        return FunctionTool(
+            f, name=name, destructive=destructive, description=description
+        )
+
+    return wrap(fn) if fn is not None else wrap

reactifact/tracing/__init__.py

@@ -0,0 +1,29 @@
+"""Observability: traces of runs (§54).
+
+Package: models (`models`), delivery (`tracer`), storage (`store`), UI
+(`web` + `templates/traces.html`). The public API is re-exported here —
+but without `web`, so that importing the package does not pull in FastAPI.
+"""
+
+from .langfuse import LangfuseTracer
+from .models import AgentSpan, ArtifactRef, LLMCall, RelationRef, RunTrace
+from .postgres import PostgresStore
+from .store import TraceReader, TraceSink, TraceStore
+from .tracer import CompositeTracer, RecordingLLM, RunTracer, Tracer
+
+__all__ = [
+    "AgentSpan",
+    "ArtifactRef",
+    "CompositeTracer",
+    "LLMCall",
+    "LangfuseTracer",
+    "PostgresStore",
+    "RecordingLLM",
+    "RelationRef",
+    "RunTrace",
+    "RunTracer",
+    "TraceReader",
+    "TraceSink",
+    "TraceStore",
+    "Tracer",
+]

reactifact/tracing/langfuse.py

@@ -0,0 +1,125 @@
+"""Langfuse sink: pushes `RunTrace` to Langfuse via the HTTP Public API.
+
+Mapping: RunTrace → trace (`POST /api/public/traces`), AgentSpan → SPAN observation,
+LLMCall → GENERATION observation (`POST /api/public/observations`). Authentication is
+Basic (public_key:secret_key). Only `on_turn_end`; the sink requires network — Langfuse
+is external.
+
+Uses httpx (base dependency). For tests you can inject `client`.
+"""
+
+from __future__ import annotations
+
+import base64
+from datetime import datetime
+from typing import Any
+
+from .models import RunTrace
+from .tracer import Tracer
+
+
+def _iso(value: datetime | None) -> str | None:
+    return value.isoformat() if value is not None else None
+
+
+def _type_summary(refs: list[Any]) -> dict[str, int]:
+    summary: dict[str, int] = {}
+    for ref in refs:
+        kind = getattr(ref, "data_type", None) or type(ref).__name__
+        summary[kind] = summary.get(kind, 0) + 1
+    return summary
+
+
+class LangfuseTracer(Tracer):
+    """Observer that exports traces to Langfuse."""
+
+    def __init__(
+        self,
+        *,
+        public_key: str,
+        secret_key: str,
+        host: str = "https://cloud.langfuse.com",
+        api_url: str | None = None,
+        client: Any | None = None,
+    ):
+        self._base = (api_url or host).rstrip("/") + "/api/public"
+        token = base64.b64encode(f"{public_key}:{secret_key}".encode()).decode()
+        self._headers = {"Authorization": f"Basic {token}"}
+        if client is not None:
+            self._client = client
+        else:
+            import httpx
+
+            self._client = httpx.AsyncClient(headers=self._headers)
+
+    async def on_turn_end(self, trace: RunTrace) -> None:
+        await self._post(
+            "/traces",
+            {
+                "id": trace.id,
+                "name": "reactifact run",
+                "timestamp": _iso(trace.started_at),
+                "sessionId": trace.session_id or None,
+                "metadata": {
+                    "duration_ms": trace.duration_ms,
+                    "outcome": trace.outcome,
+                    "spans": len(trace.spans),
+                },
+            },
+        )
+        for span in trace.spans:
+            await self._post(
+                "/observations",
+                {
+                    "id": f"{trace.id}:span:{span.agent}",
+                    "traceId": trace.id,
+                    "name": span.agent,
+                    "type": "SPAN",
+                    "startTime": _iso(span.started_at),
+                    # Meaningful input/output for the Langfuse UI: what the agent
+                    # received (reads) and what it produced (writes), with
+                    # per-type counts that mirror the trace dashboard grouping.
+                    "input": {
+                        "reads": [r.model_dump() for r in span.reads],
+                        "read_summary": _type_summary(span.reads),
+                    },
+                    "output": {
+                        "writes": [w.model_dump() for w in span.writes],
+                        "write_summary": _type_summary(span.writes),
+                    },
+                    "metadata": {
+                        "event_type": span.event_type,
+                        "latency_ms": span.latency_ms,
+                        "error": span.error,
+                        "reads": [r.model_dump() for r in span.reads],
+                        "writes": [w.model_dump() for w in span.writes],
+                    },
+                },
+            )
+            for call in span.llm_calls:
+                await self._post(
+                    "/observations",
+                    {
+                        "id": f"{trace.id}:llm:{call.agent}:{span.agent}",
+                        "traceId": trace.id,
+                        "name": f"llm:{call.model or call.provider}",
+                        "type": "GENERATION",
+                        "model": call.model or None,
+                        "input": {"messages": call.messages},
+                        "output": call.response or None,
+                        "usage": {
+                            "input": call.prompt_tokens,
+                            "output": call.completion_tokens,
+                            "unit": "TOKENS",
+                        },
+                        "metadata": {
+                            "agent": call.agent,
+                            "provider": call.provider,
+                            "latency_ms": call.latency_ms,
+                            "error": call.error,
+                        },
+                    },
+                )
+
+    async def _post(self, path: str, payload: dict[str, Any]) -> None:
+        await self._client.post(self._base + path, json=payload)

reactifact/tracing/models.py

@@ -0,0 +1,93 @@
+"""Trace models (§54).
+
+`RunTrace` is a run: metadata + agent spans. Each `AgentSpan` carries
+`reads`/`writes` as `ArtifactRef` (with type and truncated content) and a list
+of `LLMCall` (prompt/response/tokens). `RunTrace.llm_calls` is a flat projection
+of all run model calls.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ArtifactRef(BaseModel):
+    """Reference to an artifact with data for inspection (§54).
+
+    `data` is truncated JSON (string), so as not to drag the entire content into the trace.
+    """
+
+    artifact_id: str
+    version: int = 0
+    op_type: str = ""
+    data_type: str = ""
+    data: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump()
+
+
+class LLMCall(BaseModel):
+    """One model call: request, response, tokens, latency (§54)."""
+
+    agent: str = ""
+    provider: str = ""
+    model: str = ""
+    messages: list[dict[str, Any]] = Field(default_factory=list)
+    response: str = ""
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    latency_ms: float = 0.0
+    error: str | None = None
+
+
+class RelationRef(BaseModel):
+    """A provenance edge recorded for a span (`source —relation→ target`, §34)."""
+
+    source_id: str
+    relation: str
+    target_id: str
+    source_type: str = ""
+    target_type: str = ""
+
+
+class AgentSpan(BaseModel):
+    """A single agent execution within a run (§54)."""
+
+    agent: str
+    event_type: str = ""
+    reads: list[ArtifactRef] = Field(default_factory=list)
+    writes: list[ArtifactRef] = Field(default_factory=list)
+    relations: list[RelationRef] = Field(default_factory=list)
+    llm_calls: list[LLMCall] = Field(default_factory=list)
+    latency_ms: float = 0.0
+    error: str | None = None
+    started_at: datetime | None = None
+
+
+class RunTrace(BaseModel):
+    """Trace of a single run (turn): agent executions + outcome."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    session_id: str = ""
+    started_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    duration_ms: float = 0.0
+    outcome: str = ""
+    spans: list[AgentSpan] = Field(default_factory=list)
+
+    @property
+    def llm_calls(self) -> list[LLMCall]:
+        calls: list[LLMCall] = []
+        for span in self.spans:
+            calls.extend(span.llm_calls)
+        return calls
+
+    def add_span(self, span: AgentSpan) -> None:
+        self.spans.append(span)
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(mode="json")

reactifact/tracing/postgres.py

@@ -0,0 +1,220 @@
+# mypy: ignore-errors
+"""PostgreSQL trace sink: pushes `RunTrace` to PG and can serve it back.
+
+Requires the ``pg`` extra (psycopg async): imported lazily, so the `tracing`
+package works without it. Schema mirrors the SQLite sink: `runs`/`spans` tables
+with reads/writes/relations/llm_calls as jsonb.
+
+Both write (`export`) and read (`query`/`get`) are async — this is what lets the
+web dashboard in `create_trace_router` read from Postgres directly.
+
+Connections are short-lived (opened per operation via
+`psycopg.AsyncConnection`), so the store is not bound to any event loop and can
+be shared across requests.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC
+from typing import Any
+
+from .models import AgentSpan, ArtifactRef, LLMCall, RelationRef, RunTrace
+
+
+class PostgresStore:
+    """Postgres trace sink with async write + read. Requires the `pg` extra."""
+
+    def __init__(self, dsn: str):
+        from .._extras import require_extra
+
+        self._psycopg = require_extra("PostgresStore", "psycopg", "pg")
+        self.dsn = dsn
+        self._schema_ready = False
+
+    async def _ensure_schema(self) -> None:
+        if self._schema_ready:
+            return
+        conn = await self._psycopg.AsyncConnection.connect(self.dsn)
+        try:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS runs (
+                        id TEXT PRIMARY KEY,
+                        session_id TEXT NOT NULL DEFAULT '',
+                        started_at TIMESTAMPTZ NOT NULL,
+                        duration_ms REAL NOT NULL,
+                        outcome TEXT NOT NULL
+                    )
+                    """
+                )
+                await cur.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS spans (
+                        id BIGSERIAL PRIMARY KEY,
+                        run_id TEXT NOT NULL REFERENCES runs(id),
+                        agent TEXT NOT NULL,
+                        event_type TEXT NOT NULL DEFAULT '',
+                        latency_ms REAL NOT NULL DEFAULT 0,
+                        error TEXT,
+                        reads JSONB NOT NULL DEFAULT '[]',
+                        writes JSONB NOT NULL DEFAULT '[]',
+                        relations JSONB NOT NULL DEFAULT '[]',
+                        llm_calls JSONB NOT NULL DEFAULT '[]'
+                    )
+                    """
+                )
+                await cur.execute(
+                    "CREATE INDEX IF NOT EXISTS idx_spans_run ON spans(run_id)",
+                )
+            await conn.commit()
+        finally:
+            await conn.close()
+        self._schema_ready = True
+
+    async def export(self, trace: RunTrace) -> None:
+
+        import psycopg.types.json
+
+        await self._ensure_schema()
+        started = trace.started_at
+        if started is not None and started.tzinfo is None:
+            started = started.replace(tzinfo=UTC)
+        conn = await self._psycopg.AsyncConnection.connect(self.dsn)
+        try:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    "INSERT INTO runs (id, session_id, started_at, duration_ms, outcome) "
+                    "VALUES (%s, %s, %s, %s, %s)",
+                    (
+                        trace.id,
+                        trace.session_id,
+                        started,
+                        trace.duration_ms,
+                        trace.outcome,
+                    ),
+                )
+                for span in trace.spans:
+                    await cur.execute(
+                        "INSERT INTO spans (run_id, agent, event_type, latency_ms, error, "
+                        "reads, writes, relations, llm_calls) "
+                        "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)",
+                        (
+                            trace.id,
+                            span.agent,
+                            span.event_type,
+                            span.latency_ms,
+                            span.error,
+                            psycopg.types.json.Jsonb(
+                                [r.model_dump(mode="json") for r in span.reads]
+                            ),
+                            psycopg.types.json.Jsonb(
+                                [w.model_dump(mode="json") for w in span.writes]
+                            ),
+                            psycopg.types.json.Jsonb(
+                                [r.model_dump(mode="json") for r in span.relations]
+                            ),
+                            psycopg.types.json.Jsonb(
+                                [c.model_dump(mode="json") for c in span.llm_calls]
+                            ),
+                        ),
+                    )
+            await conn.commit()
+        finally:
+            await conn.close()
+
+    async def query(
+        self,
+        *,
+        session_id: str | None = None,
+        outcome: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        await self._ensure_schema()
+        where: list[str] = []
+        args: list[Any] = []
+        if session_id is not None:
+            where.append("session_id = %s")
+            args.append(session_id)
+        if outcome is not None:
+            where.append("outcome = %s")
+            args.append(outcome)
+        where_sql = (" WHERE " + " AND ".join(where)) if where else ""
+
+        conn = await self._psycopg.AsyncConnection.connect(self.dsn)
+        try:
+            async with conn.cursor() as cur:
+                await cur.execute(f"SELECT COUNT(*) FROM runs{where_sql}", tuple(args))
+                total = (await cur.fetchone())[0]
+                await cur.execute(
+                    f"SELECT id, session_id, started_at, duration_ms, outcome, "
+                    f"(SELECT COUNT(*) FROM spans WHERE run_id = runs.id) AS spans_count "
+                    f"FROM runs{where_sql} ORDER BY started_at DESC LIMIT %s OFFSET %s",
+                    (*args, limit, offset),
+                )
+                rows = await cur.fetchall()
+        finally:
+            await conn.close()
+
+        items = [
+            {
+                "id": r[0],
+                "session_id": r[1],
+                "started_at": r[2],
+                "duration_ms": round(r[3], 1),
+                "outcome": r[4],
+                "spans": r[5],
+            }
+            for r in rows
+        ]
+        return {"items": items, "total": total}
+
+    async def get(self, trace_id: str) -> RunTrace | None:
+        from datetime import UTC
+
+        await self._ensure_schema()
+        conn = await self._psycopg.AsyncConnection.connect(self.dsn)
+        try:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    "SELECT id, session_id, started_at, duration_ms, outcome "
+                    "FROM runs WHERE id = %s",
+                    (trace_id,),
+                )
+                row = await cur.fetchone()
+                if row is None:
+                    return None
+                await cur.execute(
+                    "SELECT agent, event_type, latency_ms, error, reads, writes, "
+                    "relations, llm_calls FROM spans WHERE run_id = %s ORDER BY id",
+                    (trace_id,),
+                )
+                span_rows = await cur.fetchall()
+        finally:
+            await conn.close()
+
+        spans = [
+            AgentSpan(
+                agent=r[0],
+                event_type=r[1],
+                latency_ms=r[2],
+                error=r[3],
+                reads=[ArtifactRef(**d) for d in r[4]],
+                writes=[ArtifactRef(**d) for d in r[5]],
+                relations=[RelationRef(**d) for d in r[6]],
+                llm_calls=[LLMCall(**d) for d in r[7]],
+            )
+            for r in span_rows
+        ]
+        started = row[2]
+        if started.tzinfo is None:
+            started = started.replace(tzinfo=UTC)
+        return RunTrace(
+            id=row[0],
+            session_id=row[1],
+            started_at=started,
+            duration_ms=row[3],
+            outcome=row[4],
+            spans=spans,
+        )