reactifact 0.6.0__py3-none-any.whl

reactifact/tracing/web.py

@@ -0,0 +1,117 @@
+"""FastAPI router for viewing traces (§54).
+
+Mounted in the app: `app.include_router(create_trace_router(store))`.
+Serves a JSON API (`/api/traces`, `/api/traces/{id}`), a `/traces` list, and a
+trace page `/traces/{id}` (templates in `templates/`). Polling provides "real
+time".
+
+The router works against any `TraceReader` — SQLite (`TraceStore`) or Postgres
+(`PostgresStore`) — both have async `query`/`get`.
+
+FastAPI is imported lazily inside `create_trace_router`: the module itself and the whole
+`tracing` package do not require fastapi installed — it is needed only where
+the router is created (a web app).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .store import TraceReader
+
+if TYPE_CHECKING:
+    from fastapi import APIRouter
+
+_TEMPLATES = Path(__file__).parent / "templates"
+
+
+def create_trace_router(
+    store: TraceReader,
+    *,
+    username: str | None = None,
+    password: str | None = None,
+) -> APIRouter:
+    """Router over a trace store (SQLite or Postgres).
+
+    Returns `fastapi.APIRouter`; fastapi is imported here (lazily)
+    so that `reactifact.tracing.web` works without it.
+
+    If `username`/`password` are set — all handlers (including UI pages)
+    are protected with HTTP Basic auth. Traces contain full prompts and
+    artifact contents — do not expose them without auth.
+    """
+    import secrets
+
+    from .._extras import require_extra
+
+    require_extra("tracing.web.create_trace_router", "fastapi", "web")
+
+    from fastapi import APIRouter, Depends, HTTPException, Query
+    from fastapi.responses import HTMLResponse
+    from fastapi.security import HTTPBasic, HTTPBasicCredentials
+
+    dependencies = []
+    if username is not None and password is not None:
+        security = HTTPBasic(auto_error=False)
+        expected_user = username
+        expected_pass = password
+
+        def _check(
+            credentials: HTTPBasicCredentials | None = Depends(  # noqa: B008
+                security
+            ),
+        ) -> None:
+            if credentials is None or not (
+                secrets.compare_digest(credentials.username, expected_user)
+                and secrets.compare_digest(credentials.password, expected_pass)
+            ):
+                raise HTTPException(
+                    status_code=401,
+                    detail="Unauthorized",
+                    headers={"WWW-Authenticate": "Basic"},
+                )
+
+        dependencies = [Depends(_check)]
+
+    router = APIRouter(dependencies=dependencies)
+
+    @router.get("/api/traces")
+    async def list_traces(
+        session_id: str | None = Query(default=None),
+        outcome: str | None = Query(default=None),
+        limit: int = Query(default=25, ge=1, le=200),
+        offset: int = Query(default=0, ge=0),
+    ) -> dict[str, Any]:
+        return await store.query(
+            session_id=session_id, outcome=outcome, limit=limit, offset=offset
+        )
+
+    @router.get("/api/traces/{trace_id}")
+    async def get_trace(trace_id: str) -> dict[str, Any]:
+        trace = await store.get(trace_id)
+        if trace is None:
+            raise HTTPException(status_code=404, detail="trace not found")
+        return trace.to_dict()
+
+    @router.get("/traces", response_class=HTMLResponse)
+    async def traces_list_page() -> str:
+        return (_TEMPLATES / "ui.html").read_text(encoding="utf-8")
+
+    @router.get("/traces/{trace_id}", response_class=HTMLResponse)
+    async def traces_run_page(trace_id: str) -> str:
+        from ..viz import trace_provenance_to_mermaid, trace_to_mermaid
+
+        trace = await store.get(trace_id)
+        mermaid = trace_to_mermaid(trace) if trace is not None else ""
+        provenance = trace_provenance_to_mermaid(trace) if trace is not None else ""
+        return (
+            (_TEMPLATES / "ui_run.html")
+            .read_text(encoding="utf-8")
+            .replace("__RUN_ID__", json.dumps(trace_id))
+            .replace("__MERMAID__", json.dumps(mermaid))
+            .replace("__MERMAID_GRAPH__", json.dumps(provenance))
+        )
+
+    return router

reactifact/triggers.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from .artifacts import Artifact
+from .context import Context
+from .events import Event, EventType
+
+
+class Trigger:
+    """Condition for launching an agent."""
+
+    def __init__(
+        self,
+        event_type: EventType,
+        artifact_type: type | None = None,
+        condition: Callable[[Artifact[Any]], bool] | None = None,
+    ):
+        self.event_type = event_type
+        self.artifact_type = artifact_type
+        self.condition = condition
+
+    def matches(self, event: Event, workspace: Context | None = None) -> bool:
+        """Checks whether the event matches this trigger.
+        If a condition is set, requires a workspace to fetch the artifact."""
+        if event.type != self.event_type:
+            return False
+        if self.artifact_type is not None and event.artifact_type != self.artifact_type:
+            return False
+        if self.condition is not None:
+            if workspace is None:
+                raise ValueError("Workspace is required to evaluate condition")
+            artifact = workspace.get(event.artifact_id)
+            if artifact is None:
+                return False  # the artifact may have been deleted
+            return self.condition(artifact)
+        return True
+
+    def __repr__(self) -> str:
+        return f"<Trigger {self.event_type.value} {self.artifact_type.__name__ if self.artifact_type else '*'}>"

reactifact/viz.py

@@ -0,0 +1,248 @@
+"""reactifact.viz — Mermaid diagram renderers (§72).
+
+Pure functions returning Mermaid source strings (no rendering dependency).
+Render them anywhere Mermaid works (GitHub, Notion, mermaid.live), or view the
+trace diagram directly in the dashboard and the CLI:
+
+    python -m reactifact graph examples.knowledge.agents
+    python -m reactifact context <sessions-db>
+    python -m reactifact trace traces.db [run_id]
+
+The two "graphs" here are honest to the architecture: `blueprint` is the
+*static map* (what agents can consume/produce), `context_to_mermaid` is the
+*dynamic state* — artifacts and their provenance relations (§72). There is no
+execution graph to draw; the runtime derives execution from state changes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from .agents import Agent
+from .context import Context
+
+if TYPE_CHECKING:
+    from .tracing.models import RunTrace
+
+
+def _esc(text: Any) -> str:
+    """Mermaid-safe inline label text (quotes/newlines are the danger zone)."""
+    return str(text).replace("\r", " ").replace("\n", " ").replace('"', "'").strip()
+
+
+def _artifact_node(lines: list[str], node_ids: dict[str, str], type_name: str) -> str:
+    """Returns (and registers) the mermaid node id for an artifact type."""
+    node = node_ids.get(type_name)
+    if node is None:
+        node = f"ART{len(node_ids)}"
+        node_ids[type_name] = node
+        lines.append(f'    {node}["{_esc(type_name)}"]')
+    return node
+
+
+def blueprint(
+    agents: Sequence[Agent],
+    *,
+    with_stages: bool = True,
+    title: str = "reactifact blueprint",
+) -> str:
+    """Static map of the system: artifact types = nodes, agents = edges.
+
+    For every `Agent` renders its `consumes` (input edge) and `produces`
+    (create edge; a `lifecycle` edge for `StatusMachine`-style produces).
+    """
+    lines: list[str] = ["flowchart LR"]
+    lines.append(f'    subgraph SG["{_esc(title)}"]')
+    lines.append("        direction LR")
+    node_ids: dict[str, str] = {}
+    seen: set[tuple[str, str, str]] = set()
+    for i, agent in enumerate(agents):
+        aid = f"A{i}"
+        produces = [
+            p
+            for p in agent.produces or ()
+            if getattr(p, "artifact_type", None) is not None
+        ]
+        agent_label = agent.name or f"agent{i}"
+        if with_stages and produces:
+            agent_label += "<br/>" + " · ".join(type(p).__name__ for p in produces)
+        lines.append(f'        {aid}["{_esc(agent_label)}"]')
+
+        for consume in agent.consumes or ():
+            tname = getattr(consume, "artifact_type", None)
+            if tname is None:
+                continue
+            node = _artifact_node(lines, node_ids, tname.__name__)
+            key = ("consume", node, aid)
+            if key in seen:
+                continue
+            seen.add(key)
+            lines.append(f"        {node} -.->|Consume| {aid}")
+
+        for produce in produces:
+            ptype = produce.artifact_type
+            if ptype is None:
+                continue
+            node = _artifact_node(
+                lines, node_ids, getattr(ptype, "__name__", type(ptype).__name__)
+            )
+            machine = hasattr(produce, "next_status") and hasattr(
+                produce, "status_field"
+            )
+            action = "lifecycle" if machine else "creates"
+            key = ("produce", aid, node)
+            if key in seen:
+                continue
+            seen.add(key)
+            lines.append(f"        {aid} ==>|{action}| {node}")
+
+    lines.append("    end")
+    return "\n".join(lines)
+
+
+def context_to_mermaid(
+    context: Context,
+    *,
+    relate: bool = True,
+    limit: int | None = None,
+) -> str:
+    """Live provenance graph of a context: artifacts grouped by type + relations.
+
+    The "graph" here is the *state* — artifacts and `patch.link` relations, not
+    orchestration (§72). With `limit` only the first N artifacts (in store order)
+    are shown and relations are restricted to them.
+    """
+    artifacts = context.list_artifacts()
+    if limit is not None and limit > 0:
+        artifacts = artifacts[:limit]
+
+    type_ids: dict[str, str] = {}
+    node_ids: dict[str, str] = {}
+    for i, artifact in enumerate(artifacts):
+        tname = artifact.data.__class__.__name__
+        type_ids.setdefault(tname, f"T{len(type_ids)}")
+        node_ids[artifact.id] = f"N{i}"
+
+    lines: list[str] = ["flowchart TD"]
+    by_type: dict[str, list[str]] = {}
+    for artifact in artifacts:
+        by_type.setdefault(artifact.data.__class__.__name__, []).append(artifact.id)
+    for tname, tid in type_ids.items():
+        lines.append(f'    subgraph {tid}["{_esc(tname)}"]')
+        for mid in by_type[tname]:
+            lines.append(f'        {node_ids[mid]}["{_esc(tname)}:{_esc(mid)}"]')
+        lines.append("    end")
+
+    if relate:
+        for rel in context.relations():
+            if rel.source_id not in node_ids or rel.target_id not in node_ids:
+                continue
+            lines.append(
+                f'    {node_ids[rel.source_id]} -->|"{_esc(rel.relation)}"| '
+                f"{node_ids[rel.target_id]}"
+            )
+    return "\n".join(lines)
+
+
+def trace_to_mermaid(trace: RunTrace) -> str:
+    """sequenceDiagram of one run: agent spans over time, writes, LLM calls."""
+    lines: list[str] = ["sequenceDiagram"]
+    lines.append("    participant RT as Runtime")
+    pid_of: dict[str, str] = {"__runtime__": "RT"}
+    has_llm = any(span.llm_calls for span in trace.spans)
+    for span in trace.spans:
+        if span.agent not in pid_of:
+            pid = f"A{len(pid_of) - 1}"
+            pid_of[span.agent] = pid
+            lines.append(f'    participant {pid} as "{_esc(span.agent)}"')
+    if has_llm:
+        lines.append('    participant LL as "LLM (recording)"')
+
+    for span in trace.spans:
+        pid = pid_of[span.agent]
+        pieces = [_esc(span.event_type) if span.event_type else "react"]
+        pieces.append(_plural(len(span.writes), "write"))
+        pieces.append(_plural(len(span.reads), "read"))
+        msg = " · ".join(pieces) + f" · {span.latency_ms:.0f} ms"
+        if span.error:
+            msg += f" · ⚠ {_esc(span.error)}"
+        lines.append(f"    {pid}->>{pid}: {msg}")
+        for call in span.llm_calls:
+            model = call.model or call.provider or "llm"
+            stat = (
+                f"{call.prompt_tokens} in → {call.completion_tokens} out · "
+                f"{call.latency_ms:.0f} ms"
+            )
+            span_msg = f"{_esc(model)} · {stat}"
+            lines.append(f"    {pid}->>LL: {span_msg}")
+
+    outcome = trace.outcome or "?"
+    lines.append(
+        f"    Note over RT: outcome={_esc(outcome)} · "
+        f"duration={trace.duration_ms:.0f} ms"
+    )
+    return "\n".join(lines)
+
+
+def trace_provenance_to_mermaid(trace: RunTrace) -> str:
+    """Mermaid provenance graph of one run: written artifacts + `patch.link` edges (§34).
+
+    Artifacts written by any span become nodes; the `relations` recorded by the
+    spans become the edges — a per-run "evidence graph" (`Answer →supported_by→
+    Claim →derived_from→ Evidence →extracted_from→ Doc`).
+    """
+
+    def _short(data_type: str) -> str:
+        return data_type.rsplit(".", 1)[-1] if data_type else "artifact"
+
+    nodes: dict[str, tuple[str, str]] = {}
+    for span in trace.spans:
+        for write in span.writes:
+            nodes.setdefault(
+                write.artifact_id, (_short(write.data_type), write.artifact_id)
+            )
+        for rel in span.relations:
+            nodes.setdefault(
+                rel.source_id, (rel.source_type or "artifact", rel.source_id)
+            )
+            nodes.setdefault(
+                rel.target_id, (rel.target_type or "artifact", rel.target_id)
+            )
+
+    for span in trace.spans:
+        for rel in span.relations:
+            if rel.source_id not in nodes:
+                nodes[rel.source_id] = (rel.source_type or "artifact", rel.source_id)
+            if rel.target_id not in nodes:
+                nodes[rel.target_id] = (rel.target_type or "artifact", rel.target_id)
+
+    if not nodes:
+        return 'flowchart TD\n    EMPTY["no provenance recorded"]'
+
+    lines: list[str] = ["flowchart TD"]
+    node_ids: dict[str, str] = {}
+    for index, (artifact_id, (tname, _)) in enumerate(nodes.items()):
+        node = f"N{index}"
+        node_ids[artifact_id] = node
+        lines.append(f'    {node}["{_esc(tname)}:{_esc(artifact_id)}"]')
+    for span in trace.spans:
+        for rel in span.relations:
+            if rel.source_id in node_ids and rel.target_id in node_ids:
+                lines.append(
+                    f'    {node_ids[rel.source_id]} -->|"{_esc(rel.relation)}"| '
+                    f"{node_ids[rel.target_id]}"
+                )
+    return "\n".join(lines)
+
+
+def _plural(n: int, word: str) -> str:
+    return f"{n} {word}" + ("s" if n != 1 else "")
+
+
+__all__ = [
+    "blueprint",
+    "context_to_mermaid",
+    "trace_provenance_to_mermaid",
+    "trace_to_mermaid",
+]

reactifact/web.py

@@ -0,0 +1,117 @@
+"""reactifact.web — web adapter over the chat layer (FastAPI, SSE).
+
+Because every app already owns its FastAPI instance, this module ships an
+`APIRouter`, not an app. Mount it wherever:
+
+    from reactifact import ChatAssistant, SessionStore
+    from reactifact.web import create_chat_router
+
+    app.include_router(create_chat_router(assistant))
+
+The wire contract is the canonical chat (owned by `reactifact.chat`):
+``session`` → ``status``… → ``message`` over Server-Sent Events, plus the
+standard runs (list) / deletion endpoints.
+
+If your `ChatAssistant` was built with a *shared* `resources=` instance (not
+a callable — see its docstring), that instance's provider owns an HTTP
+client for the app's lifetime; close it in your own FastAPI shutdown, since
+this module owns only the router, not the app:
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        yield
+        await resources.aclose()
+
+    app = FastAPI(lifespan=lifespan)
+
+FastAPI is imported lazily (via `reactifact._extras`): the module imports without
+fastapi installed, and only `create_chat_router` requires the `web` extra —
+`pip install "reactifact[web]"`.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+from ._extras import require_extra
+from .chat import ChatAssistant
+
+if TYPE_CHECKING:
+    from fastapi import APIRouter
+    from fastapi.responses import JSONResponse, StreamingResponse
+
+
+class ChatMessage(BaseModel):
+    """Wire shape of an incoming user turn."""
+
+    message: str
+    session_id: str = ""
+
+
+def sse(event_type: str, data: dict[str, Any]) -> str:
+    """Formats one Server-Sent-Events frame."""
+    return f"event: {event_type}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"
+
+
+def create_chat_router(
+    assistant: ChatAssistant,
+    *,
+    prefix: str = "/api",
+    with_health: bool = True,
+) -> APIRouter:
+    """Builds the chat router on top of a `ChatAssistant`.
+
+    Routes (default prefix `/api`):
+      POST   /api/chat/stream       — SSE turn (session → status… → message)
+      GET    /api/runs/{id}         — reconstructed chat thread
+      DELETE /api/runs/{id}         — delete a session's history
+      GET    /api/health            — liveness (opt-out via `with_health=False`)
+    """
+    # Readable error when the `web` extra is missing — then a regular
+    # (mypy-visible) import for the real types.
+    require_extra("web.create_chat_router", "fastapi", "web")
+    from fastapi import APIRouter
+    from fastapi.responses import JSONResponse, StreamingResponse
+
+    router = APIRouter(prefix=prefix)
+
+    if with_health:
+
+        @router.get("/health")
+        async def health() -> dict[str, bool]:
+            return {"ok": True}
+
+    @router.post("/chat/stream")
+    async def chat_stream(req: ChatMessage) -> StreamingResponse:
+        async def stream() -> AsyncIterator[str]:
+            async for event in assistant.stream(req.message, req.session_id):
+                if event.kind == "session":
+                    yield sse("session", {"session_id": event.session_id})
+                elif event.kind == "status":
+                    yield sse("status", {"message": event.message})
+                elif event.kind == "message":
+                    yield sse("message", event.payload or {"reply": ""})
+
+        return StreamingResponse(
+            stream(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+
+    @router.get("/runs/{session_id}")
+    async def runs(session_id: str) -> JSONResponse:
+        return JSONResponse(await assistant.history(session_id))
+
+    @router.delete("/runs/{session_id}")
+    async def run_delete(session_id: str) -> dict[str, bool]:
+        await assistant.store.delete_session(session_id)
+        return {"ok": True}
+
+    return router
+
+
+__all__ = ["ChatMessage", "create_chat_router", "sse"]