forgesight-fastapi 0.1.0__tar.gz

forgesight_fastapi-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# venv / tooling
+.venv/
+venv/
+.uv/
+uv.lock
+
+# test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# secrets / local env (never commit)
+.env
+.env.*
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# local-only session working state (per the workspace pipeline)
+.claude/state/
+
+# local-only launch planning (not part of the published repo)
+/launch/

forgesight_fastapi-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,72 @@
+# 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/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "forgesight-fastapi"
+version = "0.1.0"
+description = "ForgeSight FastAPI integration — ASGI middleware + lifespan flush; request↔run correlation."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "kjoshi" }]
+keywords = ["observability", "fastapi", "asgi", "starlette", "ai-agents", "forgesight"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Topic :: System :: Monitoring",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["forgesight-core", "starlette>=0.37"]
+
+[project.entry-points."forgesight.integrations"]
+fastapi = "forgesight_fastapi:install"
+
+[project.urls]
+Homepage = "https://github.com/Scaffoldic/forgesight"
+Repository = "https://github.com/Scaffoldic/forgesight"
+Issues = "https://github.com/Scaffoldic/forgesight/issues"
+Changelog = "https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forgesight_fastapi"]
+
+[tool.uv.sources]
+forgesight-core = { workspace = true }

forgesight_fastapi-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_fastapi.py

@@ -0,0 +1,366 @@
+"""Tests for the FastAPI integration: correlation, propagation, errors, lifespan flush."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse, PlainTextResponse
+from starlette.routing import Route
+from starlette.testclient import TestClient
+
+from forgesight_api import Kind, RunStatus
+from forgesight_core import InMemoryExporter, configure, get_runtime, reset_runtime, telemetry
+from forgesight_fastapi import AgentForgeMiddleware, sdk_lifespan
+from forgesight_fastapi._config import install
+
+TRACE = "4bf92f3577b34da6a3ce929d0e0e4736"
+SPAN = "00f067aa0ba902b7"
+
+
+@pytest.fixture
+def sink() -> Iterator[InMemoryExporter]:
+    exporter = InMemoryExporter()
+    configure(exporters=[exporter], sync_export=True)
+    try:
+        yield exporter
+    finally:
+        reset_runtime()
+
+
+def _build_app(sink: InMemoryExporter, **mw: object) -> Starlette:
+    async def run_handler(request: Request) -> JSONResponse:
+        await request.body()  # read the body so capture (when on) sees the chunks
+        # the request span is open and bound — a child llm call nests under it
+        run = telemetry.current_run()
+        if run is not None:  # None under workflow_run span_kind
+            with run.llm_call("anthropic", "claude-sonnet-4-5") as call:
+                call.record_usage(input=10, output=5)
+        return JSONResponse({"ok": True})
+
+    async def boom(request: Request) -> JSONResponse:
+        raise RuntimeError("handler exploded")
+
+    async def server_error(request: Request) -> PlainTextResponse:
+        return PlainTextResponse("nope", status_code=503)
+
+    async def bad_request(request: Request) -> PlainTextResponse:
+        return PlainTextResponse("bad", status_code=422)
+
+    async def health(request: Request) -> PlainTextResponse:
+        return PlainTextResponse("ok")
+
+    app = Starlette(
+        routes=[
+            Route("/agents/{agent_id}/run", run_handler, methods=["POST"]),
+            Route("/boom", boom, methods=["GET"]),
+            Route("/server-error", server_error, methods=["GET"]),
+            Route("/bad", bad_request, methods=["GET"]),
+            Route("/health", health, methods=["GET"]),
+        ]
+    )
+    app.add_middleware(AgentForgeMiddleware, **mw)
+    return app
+
+
+# --- correlation + mapping ----------------------------------------------------
+def test_request_opens_run_span_with_route_template(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink))
+    response = client.post("/agents/pr-reviewer/run")
+    assert response.status_code == 200
+    assert response.headers["x-agentforge-run-id"]  # run_id correlation header
+
+    runs = [r for r in sink.records if r.kind is Kind.AGENT]
+    assert len(runs) == 1
+    run = runs[0]
+    assert run.attributes["http.route"] == "/agents/{agent_id}/run"  # template, not raw path
+    assert run.attributes["http.method"] == "POST"
+    assert run.attributes["http.status_code"] == 200
+    assert run.status is RunStatus.OK
+    # the header run_id matches the run record
+    assert response.headers["x-agentforge-run-id"] == run.run_id
+
+
+def test_child_calls_nest_under_request_run(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink))
+    client.post("/agents/x/run")
+    run = next(r for r in sink.records if r.kind is Kind.AGENT)
+    llm = next(r for r in sink.records if r.kind is Kind.LLM)
+    assert llm.trace_id == run.trace_id  # same trace
+    assert llm.parent_span_id == run.span_id  # nested under the request span
+
+
+def test_workflow_span_kind(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink, span_kind="workflow_run"))
+    client.post("/agents/x/run")
+    assert any(r.kind is Kind.WORKFLOW for r in sink.records)
+
+
+def test_agent_name_callable(sink: InMemoryExporter) -> None:
+    app = _build_app(sink, agent_name=lambda req: f"svc:{req.url.path}")
+    TestClient(app).post("/agents/x/run")
+    run = next(r for r in sink.records if r.kind is Kind.AGENT)
+    assert run.name == "svc:/agents/x/run"
+
+
+# --- exclude / include --------------------------------------------------------
+def test_excluded_path_gets_no_span(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink))
+    client.get("/health")
+    assert [r for r in sink.records if r.kind is Kind.AGENT] == []
+
+
+def test_include_routes_allow_list(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink, include_routes=["/agents"]))
+    client.get("/bad")  # not in include list ⇒ no span
+    client.post("/agents/x/run")  # included
+    runs = [r for r in sink.records if r.kind is Kind.AGENT]
+    assert len(runs) == 1
+    assert runs[0].attributes["http.target"] == "/agents/x/run"
+
+
+# --- propagation --------------------------------------------------------------
+def test_incoming_traceparent_continued(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink))
+    client.post("/agents/x/run", headers={"traceparent": f"00-{TRACE}-{SPAN}-01"})
+    run = next(r for r in sink.records if r.kind is Kind.AGENT)
+    assert run.trace_id == TRACE  # request run is a child of the upstream trace
+    assert run.parent_span_id == SPAN
+
+
+def test_malformed_traceparent_starts_new_root(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink))
+    client.post("/agents/x/run", headers={"traceparent": "garbage"})
+    run = next(r for r in sink.records if r.kind is Kind.AGENT)
+    assert run.trace_id != TRACE
+    assert run.parent_span_id is None  # new root, not a broken child
+
+
+# --- error mapping ------------------------------------------------------------
+def test_5xx_marks_span_error(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink))
+    client.get("/server-error")
+    run = next(r for r in sink.records if r.kind is Kind.AGENT)
+    assert run.status is RunStatus.ERROR
+    assert run.error is not None
+    assert run.attributes["http.status_code"] == 503
+
+
+def test_4xx_recorded_without_error(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink))
+    client.get("/bad")
+    run = next(r for r in sink.records if r.kind is Kind.AGENT)
+    assert run.status is RunStatus.OK  # 4xx is the caller's fault, not a server error
+    assert run.attributes["http.status_code"] == 422
+
+
+def test_unhandled_exception_recorded_and_reraised(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink), raise_server_exceptions=False)
+    client.get("/boom")
+    run = next(r for r in sink.records if r.kind is Kind.AGENT)
+    assert run.status is RunStatus.ERROR
+    assert run.error is not None
+    assert run.error.error_type == "RuntimeError"
+
+
+# --- content gate (P7) --------------------------------------------------------
+def test_body_absent_by_default(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink))
+    client.post("/agents/x/run", content=b'{"task": "secret"}')
+    run = next(r for r in sink.records if r.kind is Kind.AGENT)
+    assert "http.request.body" not in run.attributes
+
+
+def test_body_captured_when_opted_in(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink, capture_content=True))
+    client.post("/agents/x/run", content=b'{"task": "do it"}')
+    run = next(r for r in sink.records if r.kind is Kind.AGENT)
+    assert "do it" in str(run.attributes["http.request.body"])
+
+
+# --- lifespan flush -----------------------------------------------------------
+class RetainingExporter:
+    """Like InMemoryExporter but does NOT clear on shutdown — so a test can assert the
+    flushed batch *after* the lifespan shutdown that drains it."""
+
+    def __init__(self) -> None:
+        self.records: list[object] = []
+
+    def export(self, records: object) -> object:
+        from forgesight_api import ExportResult
+
+        self.records.extend(records)  # type: ignore[arg-type]
+        return ExportResult.SUCCESS
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        return True
+
+    def shutdown(self, timeout_millis: int = 30_000) -> None:
+        return None  # retain across shutdown
+
+
+def test_lifespan_configures_and_flushes() -> None:
+    exporter = RetainingExporter()
+
+    async def handler(request: Request) -> JSONResponse:
+        with telemetry.agent_run("x"):
+            pass
+        return JSONResponse({"ok": True})
+
+    def lifespan(app: Starlette):  # type: ignore[no-untyped-def]
+        return sdk_lifespan(app, exporters=[exporter], sync_export=False)
+
+    app = Starlette(routes=[Route("/agents/x/run", handler, methods=["POST"])], lifespan=lifespan)
+    app.add_middleware(AgentForgeMiddleware)
+
+    with TestClient(app) as client:  # __enter__ runs startup, __exit__ runs shutdown
+        client.post("/agents/x/run")
+    # after shutdown, the buffered batch has been flushed (force_flush + shutdown) to the exporter
+    assert any(getattr(r, "kind", None) is Kind.AGENT for r in exporter.records)
+    reset_runtime()
+
+
+def test_lifespan_respects_already_configured() -> None:
+    exporter = InMemoryExporter()
+    configure(exporters=[exporter], sync_export=True)
+    try:
+        runtime_before = get_runtime()
+
+        async def cm() -> None:
+            async with sdk_lifespan(configure_sdk=False):
+                with telemetry.agent_run("x"):
+                    # assert the record landed BEFORE shutdown clears the InMemoryExporter
+                    pass
+                assert any(r.kind is Kind.AGENT for r in exporter.records)
+                assert get_runtime() is runtime_before  # not reconfigured
+
+        import anyio
+
+        anyio.run(cm)
+    finally:
+        reset_runtime()
+
+
+# --- config / install ---------------------------------------------------------
+def test_install_provides_defaults(sink: InMemoryExporter) -> None:
+    try:
+        assert install({"enabled": True, "span_kind": "workflow_run"}) is True
+        client = TestClient(_build_app(sink))  # no explicit span_kind ⇒ from install()
+        client.post("/agents/x/run")
+        assert any(r.kind is Kind.WORKFLOW for r in sink.records)
+    finally:
+        install({"enabled": False})  # clear
+
+
+def test_install_disabled_returns_false() -> None:
+    assert install({"enabled": False}) is False
+
+
+def test_invalid_span_kind_rejected(sink: InMemoryExporter) -> None:
+    with pytest.raises(ValueError, match="span_kind must be"):
+        AgentForgeMiddleware(_build_app(sink), span_kind="teleport")
+
+
+def test_non_http_scope_passes_through() -> None:
+    # a lifespan/websocket scope must not be instrumented
+    configure(exporters=[InMemoryExporter()], sync_export=True)
+    try:
+        seen = {}
+
+        async def app(scope, receive, send):  # type: ignore[no-untyped-def]
+            seen["type"] = scope["type"]
+
+        mw = AgentForgeMiddleware(app)
+
+        async def run() -> None:
+            await mw({"type": "lifespan"}, _noop_receive, _noop_send)
+
+        import anyio
+
+        anyio.run(run)
+        assert seen["type"] == "lifespan"
+    finally:
+        reset_runtime()
+
+
+async def _noop_receive() -> dict[str, object]:
+    return {"type": "noop"}
+
+
+async def _noop_send(message: dict[str, object]) -> None:
+    return None
+
+
+def test_run_id_header_custom(sink: InMemoryExporter) -> None:
+    client = TestClient(_build_app(sink, run_id_header="x-run"))
+    response = client.post("/agents/x/run")
+    assert "x-run" in response.headers
+    assert get_runtime() is not None
+
+
+# --- _w3c unit coverage -------------------------------------------------------
+def test_w3c_extract_valid_and_missing() -> None:
+    from forgesight_fastapi._w3c import extract_parent
+
+    headers = [(b"traceparent", f"00-{TRACE}-{SPAN}-01".encode())]
+    assert extract_parent(headers) == (TRACE, SPAN)
+    assert extract_parent([(b"content-type", b"application/json")]) is None  # no traceparent
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "garbage",  # wrong part count
+        f"00-{TRACE}-tooShort-01",  # wrong span length
+        "00-" + "g" * 32 + "-" + "0" * 16 + "-01",  # non-hex
+        "00-" + "0" * 32 + "-" + SPAN + "-01",  # all-zero trace
+    ],
+)
+def test_w3c_rejects_bad_traceparent(value: str) -> None:
+    from forgesight_fastapi._w3c import extract_parent
+
+    assert extract_parent([(b"traceparent", value.encode())]) is None
+
+
+# --- _config resolver coverage ------------------------------------------------
+def test_config_env_resolvers(monkeypatch: pytest.MonkeyPatch) -> None:
+    from forgesight_fastapi._config import (
+        resolve_exclude_paths,
+        resolve_run_id_header,
+        resolve_span_kind,
+    )
+
+    monkeypatch.setenv("FORGESIGHT_FASTAPI_EXCLUDE", "/a, /b")
+    monkeypatch.setenv("FORGESIGHT_FASTAPI_RUN_ID_HEADER", "x-corr")
+    monkeypatch.setenv("FORGESIGHT_FASTAPI_SPAN_KIND", "workflow_run")
+    assert resolve_exclude_paths(None) == ("/a", "/b")
+    assert resolve_run_id_header(None) == "x-corr"
+    assert resolve_span_kind(None) == "workflow_run"
+
+
+def test_config_install_include_routes_and_run_id() -> None:
+    from forgesight_fastapi._config import resolve_include_routes, resolve_run_id_header
+
+    try:
+        install({"include_routes": ["/agents"], "run_id_header": "x-from-yaml"})
+        assert resolve_include_routes(None) == ("/agents",)
+        assert resolve_run_id_header(None) == "x-from-yaml"
+    finally:
+        install({"enabled": False})
+
+
+def test_config_capture_content_resolution(monkeypatch: pytest.MonkeyPatch) -> None:
+    from forgesight_fastapi._config import resolve_capture_content
+
+    monkeypatch.setenv("FORGESIGHT_FASTAPI_CAPTURE_CONTENT", "true")
+    assert resolve_capture_content(None) is True  # env path
+    monkeypatch.delenv("FORGESIGHT_FASTAPI_CAPTURE_CONTENT")
+    try:
+        install({"capture_content": True})  # logs once + sets installed default
+        install({"capture_content": True})  # already logged ⇒ no second log
+        assert resolve_capture_content(None) is True  # installed path
+    finally:
+        install({"enabled": False})
+    assert resolve_capture_content(None) is None  # nothing set ⇒ inherit global gate