forgesight-fastapi 0.1.0__py3-none-any.whl

forgesight_fastapi/__init__.py

@@ -0,0 +1,28 @@
+"""ForgeSight FastAPI integration — request↔run correlation + flush-on-shutdown.
+
+```python
+from fastapi import FastAPI
+from forgesight_fastapi import AgentForgeMiddleware, sdk_lifespan
+
+app = FastAPI(lifespan=sdk_lifespan)
+app.add_middleware(AgentForgeMiddleware)
+```
+"""
+
+from __future__ import annotations
+
+from ._config import DEFAULT_EXCLUDE_PATHS, SPAN_KINDS, install
+from .lifespan import sdk_lifespan
+from .middleware import AgentForgeMiddleware, HTTPServerError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_EXCLUDE_PATHS",
+    "SPAN_KINDS",
+    "AgentForgeMiddleware",
+    "HTTPServerError",
+    "__version__",
+    "install",
+    "sdk_lifespan",
+]

forgesight_fastapi/_config.py

@@ -0,0 +1,98 @@
+"""Default resolution for the middleware: explicit kwarg → env → installed config → default.
+
+``install`` (the ``forgesight.integrations`` entry point) stashes the ``integrations.fastapi``
+config block so the middleware can read defaults from ``forgesight.yaml`` even though ASGI
+middleware must be added explicitly in app code (it can't be auto-injected).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Sequence
+from typing import Any
+
+_log = logging.getLogger("forgesight.fastapi")
+
+SPAN_KINDS = ("agent_run", "workflow_run")
+DEFAULT_SPAN_KIND = "agent_run"
+DEFAULT_RUN_ID_HEADER = "x-agentforge-run-id"
+DEFAULT_EXCLUDE_PATHS: tuple[str, ...] = (
+    "/health",
+    "/healthz",
+    "/metrics",
+    "/docs",
+    "/openapi.json",
+)
+
+_INSTALLED: dict[str, Any] = {}
+_CONTENT_LOGGED = False
+
+
+def install(config: dict[str, Any] | None = None) -> bool:
+    """Stash the ``integrations.fastapi`` config block as middleware defaults. Idempotent."""
+    cfg = dict(config or {})
+    if not cfg.get("enabled", True):
+        _INSTALLED.clear()
+        return False
+    _INSTALLED.clear()
+    _INSTALLED.update(cfg)
+    if cfg.get("capture_content"):
+        log_content_capture()
+    return True
+
+
+def log_content_capture() -> None:
+    """INFO-once so request/response body capture is never silently on (P7)."""
+    global _CONTENT_LOGGED
+    if not _CONTENT_LOGGED:
+        _log.info("forgesight-fastapi: HTTP body capture is ON (request/response bodies)")
+        _CONTENT_LOGGED = True
+
+
+def resolve_span_kind(value: str | None) -> str:
+    resolved = (
+        value or os.environ.get("FORGESIGHT_FASTAPI_SPAN_KIND") or _INSTALLED.get("span_kind")
+    )
+    resolved = str(resolved) if resolved else DEFAULT_SPAN_KIND
+    if resolved not in SPAN_KINDS:
+        raise ValueError(f"span_kind must be one of {SPAN_KINDS}, got {resolved!r}")
+    return resolved
+
+
+def resolve_exclude_paths(value: Sequence[str] | None) -> tuple[str, ...]:
+    if value is not None:
+        return tuple(str(p) for p in value)
+    env = os.environ.get("FORGESIGHT_FASTAPI_EXCLUDE")
+    if env:
+        return tuple(p.strip() for p in env.split(",") if p.strip())
+    installed = _INSTALLED.get("exclude_paths")
+    if installed:
+        return tuple(str(p) for p in installed)
+    return DEFAULT_EXCLUDE_PATHS
+
+
+def resolve_include_routes(value: Sequence[str] | None) -> tuple[str, ...] | None:
+    if value is not None:
+        return tuple(str(p) for p in value)
+    installed = _INSTALLED.get("include_routes")
+    return tuple(str(p) for p in installed) if installed else None
+
+
+def resolve_capture_content(value: bool | None) -> bool | None:
+    if value is not None:
+        return value
+    env = os.environ.get("FORGESIGHT_FASTAPI_CAPTURE_CONTENT")
+    if env is not None:
+        return env.strip().lower() in ("1", "true", "yes", "on")
+    if "capture_content" in _INSTALLED:
+        return bool(_INSTALLED["capture_content"])
+    return None  # inherit the global gate
+
+
+def resolve_run_id_header(value: str | None) -> str:
+    return (
+        value
+        or os.environ.get("FORGESIGHT_FASTAPI_RUN_ID_HEADER")
+        or str(_INSTALLED.get("run_id_header") or DEFAULT_RUN_ID_HEADER)
+    )

forgesight_fastapi/_w3c.py

@@ -0,0 +1,43 @@
+"""W3C ``traceparent`` extraction from ASGI request headers.
+
+A FastAPI service is a hop in a distributed trace: when a gateway or upstream already
+started a trace and sent ``traceparent``, the agent run must continue it (be a child),
+not open a disconnected root. This tiny pure module is the one place that parses the
+incoming header — malformed input degrades to ``None`` (a new local root), never raises.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+_TRACEPARENT = b"traceparent"
+
+
+def extract_parent(headers: Iterable[tuple[bytes, bytes]]) -> tuple[str, str] | None:
+    """Return ``(trace_id, span_id)`` from the request's ``traceparent``, or ``None``."""
+    for name, value in headers:
+        if name.lower() == _TRACEPARENT:
+            return _parse(value.decode("latin-1"))
+    return None
+
+
+def _parse(raw: str) -> tuple[str, str] | None:
+    parts = raw.split("-")
+    if len(parts) != 4:
+        return None
+    _version, trace_id, span_id, _flags = parts
+    if len(trace_id) != 32 or len(span_id) != 16:
+        return None
+    if not _is_hex(trace_id) or not _is_hex(span_id):
+        return None
+    if trace_id == "0" * 32 or span_id == "0" * 16:
+        return None
+    return trace_id, span_id
+
+
+def _is_hex(value: str) -> bool:
+    try:
+        int(value, 16)
+    except ValueError:
+        return False
+    return True

forgesight_fastapi/lifespan.py

@@ -0,0 +1,47 @@
+"""``sdk_lifespan`` — configure the SDK on startup, flush cleanly on shutdown.
+
+The SDK buffers records and flushes on a timer (feat-003); a rolling deploy / SIGTERM that
+stops the process drops the in-flight batch unless someone flushes. ASGI servers run the
+lifespan shutdown phase on SIGTERM, so wiring this guarantees "telemetry is not lost on a
+clean deploy" by installation, not by discipline.
+
+Usable directly (``FastAPI(lifespan=sdk_lifespan)``) or composed inside a user lifespan
+(``async with sdk_lifespan(app): ...``). ``**configure_kwargs`` flow to ``configure()``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from forgesight_core import configure, get_runtime
+
+
+@asynccontextmanager
+async def sdk_lifespan(
+    app: Any = None,
+    *,
+    configure_sdk: bool = True,
+    flush_timeout_millis: int | None = None,
+    **configure_kwargs: Any,
+) -> AsyncIterator[None]:
+    """Lifespan: ``configure()`` on startup; ``force_flush()`` + ``shutdown()`` on shutdown.
+
+    ``configure_sdk=False`` skips startup configuration (respect an already-configured SDK).
+    ``flush_timeout_millis`` defaults to the runtime's bounded ``export_timeout_millis`` so a
+    wedged backend can't hang the shutdown.
+    """
+    if configure_sdk:
+        configure(**configure_kwargs)
+    try:
+        yield
+    finally:
+        runtime = get_runtime()
+        timeout = (
+            flush_timeout_millis
+            if flush_timeout_millis is not None
+            else runtime.config.export_timeout_millis
+        )
+        runtime.force_flush(timeout)
+        runtime.shutdown(timeout)

forgesight_fastapi/middleware.py

@@ -0,0 +1,187 @@
+"""``AgentForgeMiddleware`` — pure-ASGI middleware that correlates a request with an agent run.
+
+Per request it: continues an incoming W3C trace (or starts a root), opens an
+``agent_run`` / ``workflow_run`` span via the feat-002 runtime, binds it so the handler's
+llm/tool/mcp calls nest under it, attaches ``http.route`` / ``http.method`` / status as
+business metadata (FR-5), sets the ``run_id`` response header for correlation, and closes
+the span with the response status (5xx ⇒ ERROR; 4xx ⇒ recorded; unhandled exception ⇒
+ERROR + re-raise, FR-7).
+
+Implemented as **pure ASGI** (not ``BaseHTTPMiddleware``) to avoid its streaming / lifespan
+pitfalls (risk table §8). Request/response bodies are captured only when ``capture_content``
+resolves true (P7).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any
+
+from forgesight_core import RunScope, WorkflowScope, get_runtime
+from forgesight_core.context import (
+    TelemetryContext,
+    new_run_id,
+    reset_current_context,
+    set_current_context,
+)
+
+from ._config import (
+    log_content_capture,
+    resolve_capture_content,
+    resolve_exclude_paths,
+    resolve_include_routes,
+    resolve_run_id_header,
+    resolve_span_kind,
+)
+from ._w3c import extract_parent
+
+Scope = dict[str, Any]
+Receive = Callable[[], Awaitable[dict[str, Any]]]
+Send = Callable[[dict[str, Any]], Awaitable[None]]
+
+
+class HTTPServerError(Exception):
+    """Synthesised for a 5xx response so the run span records ``error.type`` (FR-7)."""
+
+
+class AgentForgeMiddleware:
+    """ASGI middleware: one agent-run span per request, correlated and flushed cleanly."""
+
+    def __init__(
+        self,
+        app: Any,
+        *,
+        span_kind: str | None = None,
+        agent_name: str | Callable[[Any], str] = "fastapi-app",
+        exclude_paths: Sequence[str] | None = None,
+        include_routes: Sequence[str] | None = None,
+        capture_content: bool | None = None,
+        run_id_header: str | None = None,
+    ) -> None:
+        self._app = app
+        self._span_kind = resolve_span_kind(span_kind)
+        self._agent_name = agent_name
+        self._exclude_paths = resolve_exclude_paths(exclude_paths)
+        self._include_routes = resolve_include_routes(include_routes)
+        self._capture_opt = resolve_capture_content(capture_content)
+        if self._capture_opt:
+            log_content_capture()
+        self._run_id_header = resolve_run_id_header(run_id_header).lower().encode("latin-1")
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") != "http" or not self._should_instrument(scope.get("path", "")):
+            await self._app(scope, receive, send)
+            return
+
+        token = self._bind_incoming_trace(scope)
+        try:
+            await self._handle(scope, receive, send)
+        finally:
+            if token is not None:
+                reset_current_context(token)
+
+    # --- internals --------------------------------------------------------
+    async def _handle(self, scope: Scope, receive: Receive, send: Send) -> None:
+        run_scope = self._open_scope(scope)
+        capture = self._resolve_capture()
+        status: dict[str, int] = {}
+        body_chunks: list[bytes] = []
+
+        async def send_wrapper(message: dict[str, Any]) -> None:
+            if message["type"] == "http.response.start":
+                status["code"] = message["status"]
+                headers = list(message.get("headers") or [])
+                headers.append((self._run_id_header, run_scope.run_id.encode("latin-1")))
+                message = {**message, "headers": headers}
+            await send(message)
+
+        async def receive_wrapper() -> dict[str, Any]:
+            message = await receive()
+            if message.get("type") == "http.request":
+                body_chunks.append(message.get("body", b""))
+            return message
+
+        downstream_receive = receive_wrapper if capture else receive
+        async with run_scope:
+            self._set_request_metadata(run_scope, scope)
+            try:
+                await self._app(scope, downstream_receive, send_wrapper)
+            finally:
+                self._finalize(run_scope, scope, status, capture, body_chunks)
+
+    def _bind_incoming_trace(self, scope: Scope) -> Any:
+        parent = extract_parent(scope.get("headers") or [])
+        if parent is None:
+            return None
+        trace_id, span_id = parent
+        return set_current_context(
+            TelemetryContext(run_id=new_run_id(), trace_id=trace_id, current_span_id=span_id)
+        )
+
+    def _open_scope(self, scope: Scope) -> RunScope | WorkflowScope:
+        name = self._resolve_agent_name(scope)
+        runtime = get_runtime()
+        if self._span_kind == "workflow_run":
+            return WorkflowScope(runtime, name=name)
+        return RunScope(runtime, name=name)
+
+    def _resolve_agent_name(self, scope: Scope) -> str:
+        if callable(self._agent_name):
+            from starlette.requests import Request
+
+            return str(self._agent_name(Request(scope)))
+        return self._agent_name
+
+    @staticmethod
+    def _set_request_metadata(run_scope: RunScope | WorkflowScope, scope: Scope) -> None:
+        run_scope.set_metadata(
+            **{"http.method": scope.get("method", ""), "http.target": scope.get("path", "")}
+        )
+
+    def _finalize(
+        self,
+        run_scope: RunScope | WorkflowScope,
+        scope: Scope,
+        status: dict[str, int],
+        capture: bool,
+        body_chunks: list[bytes],
+    ) -> None:
+        run_scope.set_metadata(**{"http.route": _route_template(scope)})
+        code = status.get("code")
+        if code is not None:
+            run_scope.set_metadata(**{"http.status_code": code})
+            if code >= 500:
+                run_scope.record_error(HTTPServerError(f"HTTP {code} server error"), code=str(code))
+        if capture and body_chunks:
+            body = b"".join(body_chunks).decode("utf-8", "replace")
+            if body:
+                run_scope.set_metadata(**{"http.request.body": body})
+
+    def _should_instrument(self, path: str) -> bool:
+        if any(path.startswith(prefix) for prefix in self._exclude_paths):
+            return False
+        if self._include_routes is not None:
+            return any(path.startswith(prefix) for prefix in self._include_routes)
+        return True
+
+    def _resolve_capture(self) -> bool:
+        if self._capture_opt is not None:
+            return self._capture_opt
+        try:
+            return bool(get_runtime().config.capture_content)
+        except Exception:  # pragma: no cover - runtime always present in practice
+            return False
+
+
+def _route_template(scope: Scope) -> str:
+    """Reconstruct the matched route template (``/agents/{id}/run``) for bounded cardinality.
+
+    Built from the raw path + ``path_params`` the router fills in after matching, so it
+    works regardless of whether the ASGI server exposes ``scope['route']``.
+    """
+    path = str(scope.get("path", ""))
+    params = scope.get("path_params") or {}
+    template = path
+    for name, value in params.items():
+        template = template.replace(str(value), "{" + name + "}", 1)
+    return template

forgesight_fastapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: forgesight-fastapi
+Version: 0.1.0
+Summary: ForgeSight FastAPI integration — ASGI middleware + lifespan flush; request↔run correlation.
+Project-URL: Homepage, https://github.com/Scaffoldic/forgesight
+Project-URL: Repository, https://github.com/Scaffoldic/forgesight
+Project-URL: Issues, https://github.com/Scaffoldic/forgesight/issues
+Project-URL: Changelog, https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md
+Author: kjoshi
+License-Expression: Apache-2.0
+Keywords: ai-agents,asgi,fastapi,forgesight,observability,starlette
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: forgesight-core
+Requires-Dist: starlette>=0.37
+Description-Content-Type: text/markdown
+
+# forgesight-fastapi
+
+The FastAPI integration for [ForgeSight](https://github.com/Scaffoldic/forgesight). Three
+lines wire request↔run correlation, incoming-trace continuation, and flush-on-shutdown into
+any FastAPI / Starlette app — no per-handler instrumentation.
+
+```bash
+pip install forgesight-fastapi
+```
+
+```python
+from fastapi import FastAPI
+from forgesight_fastapi import AgentForgeMiddleware, sdk_lifespan
+
+app = FastAPI(lifespan=sdk_lifespan)        # configure() on startup, flush on shutdown
+app.add_middleware(AgentForgeMiddleware)     # request → agent_run span, correlation
+
+@app.post("/agents/pr-reviewer/run")
+async def run(req: ReviewRequest):
+    # Unchanged agent code. The run span is already open and bound to this request;
+    # the agent's llm/tool/mcp calls nest under it automatically.
+    return await pr_reviewer.run(req.task)
+```
+
+Compose with an existing lifespan:
+
+```python
+from contextlib import asynccontextmanager
+from forgesight_fastapi import sdk_lifespan
+
+@asynccontextmanager
+async def lifespan(app):
+    async with sdk_lifespan(app):
+        await connect_db()
+        yield
+        await close_db()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+## What you get
+
+- **Request↔run link.** The HTTP request and the agent run share a `trace_id`; the response
+  carries the `run_id` (header `x-agentforge-run-id`), so "request X was slow" jumps straight
+  to the run's span tree and cost.
+- **Distributed traces just work.** An upstream `traceparent` is continued automatically —
+  the agent service is a child span, not a new root. No propagation code in the app.
+- **Zero lost telemetry on deploy.** `sdk_lifespan` calls `force_flush()` + `shutdown()` on
+  the shutdown phase (which ASGI servers run on SIGTERM), with a bounded timeout so a wedged
+  backend can't hang the deploy.
+- **Route-level metadata for free.** The matched route *template* (`/agents/{id}/run`, not
+  the raw path — bounded cardinality), method, and status land as span metadata (FR-5).
+- **Correct error mapping.** 5xx ⇒ span ERROR + `error.type`; an unhandled exception is
+  recorded and re-raised (FR-7); 4xx is recorded without erroring the span.
+
+Implemented as **pure ASGI** (not `BaseHTTPMiddleware`) to avoid streaming/lifespan pitfalls.
+Request/response bodies are captured only when `capture_content` resolves true (P7).
+
+## Configuration
+
+| Key | Env | Default |
+|---|---|---|
+| `span_kind` | `FORGESIGHT_FASTAPI_SPAN_KIND` | `agent_run` (or `workflow_run`) |
+| `exclude_paths` | `FORGESIGHT_FASTAPI_EXCLUDE` | `/health,/healthz,/metrics,/docs,/openapi.json` |
+| `capture_content` | `FORGESIGHT_FASTAPI_CAPTURE_CONTENT` | `false` |
+| `run_id_header` | `FORGESIGHT_FASTAPI_RUN_ID_HEADER` | `x-agentforge-run-id` |
+
+Constructor kwargs win over env / `forgesight.yaml` (`integrations.fastapi`).
+
+## License
+
+Apache-2.0

forgesight_fastapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+forgesight_fastapi/__init__.py,sha256=IO2wwqB-fQHwTDsQeUx9bEUOilBADL4MBY9xAGF6plU,665
+forgesight_fastapi/_config.py,sha256=2BbCSeBTnA8G7ng3-ztWRj6LGRpxcGNJ1NJC4Io24ts,3232
+forgesight_fastapi/_w3c.py,sha256=sUsv68OUZ8HH8EtZlq0dq8GHKjmQNWxSvSmtfK5DbxE,1379
+forgesight_fastapi/lifespan.py,sha256=fQIYGALsCzR2vd0Gg279VLnP6tXP9eE_RsbDV_MYjZs,1685
+forgesight_fastapi/middleware.py,sha256=rcpRYiPPqdalF4FwsybEREhKY622Ky5846IH-ZgZiP0,7293
+forgesight_fastapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+forgesight_fastapi-0.1.0.dist-info/METADATA,sha256=GvFmumEdzQYT5_FPkcpGR4HupwR5bturFN-pCiPV9G8,4053
+forgesight_fastapi-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+forgesight_fastapi-0.1.0.dist-info/entry_points.txt,sha256=-0vHJUHXV013Ob_tQ7S4Np1Tbu-u1ZubVQlOUwh_ZMw,63
+forgesight_fastapi-0.1.0.dist-info/RECORD,,

forgesight_fastapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

forgesight_fastapi-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[forgesight.integrations]
+fastapi = forgesight_fastapi:install