reactifact 0.6.0__tar.gz → 0.6.1__tar.gz

{reactifact-0.6.0/reactifact.egg-info → reactifact-0.6.1}/PKG-INFO

@@ -1,10 +1,21 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.6.0
+Version: 0.6.1
 Summary: Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/bzdvdn/reactifact
 Project-URL: Repository, https://github.com/bzdvdn/reactifact
 Project-URL: Documentation, https://github.com/bzdvdn/reactifact/tree/master/docs
+Project-URL: Changelog, https://github.com/bzdvdn/reactifact/blob/master/CHANGELOG.md
+Keywords: agents,llm,ai-agents,reactive,provenance,orchestration,agentic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -21,6 +32,8 @@ Requires-Dist: fastapi>=0.115; extra == "web"
 Requires-Dist: uvicorn[standard]>=0.30; extra == "web"
 Provides-Extra: pg
 Requires-Dist: psycopg[binary]>=3.2; extra == "pg"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.2; extra == "mcp"
 Dynamic: license-file
 
 # reactifact
@@ -41,6 +54,8 @@ reactifact flips the model. You describe **what artifacts exist and what agents
 do with them**; the runtime derives what runs next from **state changes**. Agents
 react to events — there is no graph, no node pipeline.
 
+![Left: a hand-wired fetch → verify → answer pipeline. Right: reactifact — search_agent and answer_agent each declare only what they consume and produce, wired together by Context, never each other.](docs/img/wiring.svg)
+
 ```bash
 pip install reactifact
 ```
@@ -107,6 +122,12 @@ print(answer.data.text)                     # "Refunds are available within 14 d
 print("supported_by:", evidence.data.text)  # provenance you can trace, not just a string in a log
 ```
 
+The same idea, live — the [`knowledge`](examples/knowledge) example's CLI answering a
+harder, multi-source question (docs + a CSV) with a real computed number and
+its sources, no LLM key required:
+
+![CLI demo: asking "how much does gpu cost in total?" — the runtime searches docs and a spreadsheet, computes the sum, verifies it, and answers with sources.](docs/img/knowledge-cli-demo.gif)
+
 ## How it works
 
 ```text
@@ -160,6 +181,10 @@ Full breakdown, including where reactifact is *not* the right choice:
   fallbacks instead of hallucinated answers; the model reasons, never "knows".
 - **Observability** — every run traces agent spans, reads/writes, LLM calls,
   tokens: SQLite store + web dashboard, exportable to Langfuse/Postgres (async sinks).
+- **MCP, both ways** — call any MCP server's tools as a `Tool`
+  (`mcp_stdio_tools`/`mcp_http_tools`), or expose your own `Tool`s and a live
+  `Context` as an MCP server (`create_mcp_server`) for Claude Desktop, Claude
+  Code, or another agent to call into (`mcp` extra).
 - **Budgets & replanning** — cap by runs/time/iterations/tool-calls, replan on decline.
 - **Branching & replay** — `context.branch()`, three-way `merge()`, deterministic
   `ReplayLLM`, all for audit and safe alternative states.

{reactifact-0.6.0 → reactifact-0.6.1}/README.md

@@ -16,6 +16,8 @@ reactifact flips the model. You describe **what artifacts exist and what agents
 do with them**; the runtime derives what runs next from **state changes**. Agents
 react to events — there is no graph, no node pipeline.
 
+![Left: a hand-wired fetch → verify → answer pipeline. Right: reactifact — search_agent and answer_agent each declare only what they consume and produce, wired together by Context, never each other.](docs/img/wiring.svg)
+
 ```bash
 pip install reactifact
 ```
@@ -82,6 +84,12 @@ print(answer.data.text)                     # "Refunds are available within 14 d
 print("supported_by:", evidence.data.text)  # provenance you can trace, not just a string in a log
 ```
 
+The same idea, live — the [`knowledge`](examples/knowledge) example's CLI answering a
+harder, multi-source question (docs + a CSV) with a real computed number and
+its sources, no LLM key required:
+
+![CLI demo: asking "how much does gpu cost in total?" — the runtime searches docs and a spreadsheet, computes the sum, verifies it, and answers with sources.](docs/img/knowledge-cli-demo.gif)
+
 ## How it works
 
 ```text
@@ -135,6 +143,10 @@ Full breakdown, including where reactifact is *not* the right choice:
   fallbacks instead of hallucinated answers; the model reasons, never "knows".
 - **Observability** — every run traces agent spans, reads/writes, LLM calls,
   tokens: SQLite store + web dashboard, exportable to Langfuse/Postgres (async sinks).
+- **MCP, both ways** — call any MCP server's tools as a `Tool`
+  (`mcp_stdio_tools`/`mcp_http_tools`), or expose your own `Tool`s and a live
+  `Context` as an MCP server (`create_mcp_server`) for Claude Desktop, Claude
+  Code, or another agent to call into (`mcp` extra).
 - **Budgets & replanning** — cap by runs/time/iterations/tool-calls, replan on decline.
 - **Branching & replay** — `context.branch()`, three-way `merge()`, deterministic
   `ReplayLLM`, all for audit and safe alternative states.

{reactifact-0.6.0 → reactifact-0.6.1}/pyproject.toml

@@ -4,10 +4,23 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.6.0"
+version = "0.6.1"
 description = "Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context"
 readme = "README.md"
 requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["agents", "llm", "ai-agents", "reactive", "provenance", "orchestration", "agentic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
 dependencies = [
     "pydantic>=2.13.4",
     "httpx>=0.27",
@@ -18,6 +31,7 @@ dependencies = [
 Homepage = "https://github.com/bzdvdn/reactifact"
 Repository = "https://github.com/bzdvdn/reactifact"
 Documentation = "https://github.com/bzdvdn/reactifact/tree/master/docs"
+Changelog = "https://github.com/bzdvdn/reactifact/blob/master/CHANGELOG.md"
 
 [project.optional-dependencies]
 dev = [
@@ -33,10 +47,16 @@ web = [
 pg = [
     "psycopg[binary]>=3.2",
 ]
+mcp = [
+    "mcp>=2.2",
+]
 
 # uv-native groups mirror the extras so `uv run`/`uv sync` installs the web demo
 # deps by default (no `--extra` flag needed to boot the examples). Extras stay
-# for PyPI (`pip install reactifact[web]`).
+# for PyPI (`pip install reactifact[web]`). `mcp` joins the default groups too —
+# unlike `pg`, its tests need no external service (in-memory MCP transport), so
+# there's no reason not to run them for real in CI. `pg` stays opt-in; its own
+# test only checks the graceful ImportError path without psycopg installed.
 [dependency-groups]
 dev = [
     "ruff>=0.8",
@@ -51,9 +71,12 @@ web = [
 pg = [
     "psycopg[binary]>=3.2",
 ]
+mcp = [
+    "mcp>=2.2",
+]
 
 [tool.uv]
-default-groups = ["dev", "web"]
+default-groups = ["dev", "web", "mcp"]
 
 # Публикация: в wheel едет только пакет `reactifact`; examples/tests остаются
 # в репозитории для демо и разработки, но не попадают в дистрибутив.

{reactifact-0.6.0 → reactifact-0.6.1}/reactifact/__init__.py

@@ -48,7 +48,7 @@ from .session import Session, SessionStore
 from .tools import FunctionTool, Tool, ToolOutput, tool
 from .triggers import Trigger
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"
 
 __all__ = [
     "Agent",

reactifact-0.6.1/reactifact/mcp/__init__.py

@@ -0,0 +1,18 @@
+"""MCP integration: talk to external MCP servers, or serve reactifact `Tool`s
+and `Context` artifacts as one. Requires the `mcp` extra — nothing here is
+imported by reactifact's core, so a bare `pip install reactifact` never pulls
+in the `mcp` SDK.
+"""
+
+from __future__ import annotations
+
+from .client import MCPTool, mcp_http_tools, mcp_stdio_tools, mcp_tools
+from .server import create_mcp_server
+
+__all__ = [
+    "MCPTool",
+    "create_mcp_server",
+    "mcp_http_tools",
+    "mcp_stdio_tools",
+    "mcp_tools",
+]

reactifact-0.6.1/reactifact/mcp/client.py

@@ -0,0 +1,104 @@
+"""MCP client: turns tools exposed by an external MCP server into `Tool`s, so
+`ToolUse`/`ToolUseHITL`/`LLMAgent` call remote MCP tools the same way they
+call local ones — no separate code path for "MCP tool" vs. `@tool`. Requires
+the `mcp` extra.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from .._extras import require_extra
+from ..tools import Tool, ToolOutput
+
+
+class MCPTool(Tool):
+    """One tool from a connected `mcp.ClientSession`, wrapped as a `Tool`."""
+
+    def __init__(
+        self,
+        session: Any,
+        *,
+        name: str,
+        description: str,
+        schema: dict[str, Any],
+        destructive: bool = False,
+    ):
+        self._session = session
+        self.name = name
+        self.description = description
+        self.schema = schema
+        self.destructive = destructive
+
+    async def execute(self, args: dict[str, Any]) -> ToolOutput:
+        result = await self._session.call_tool(self.name, args)
+        return _to_tool_output(result)
+
+
+def _to_tool_output(result: Any) -> ToolOutput:
+    texts = [block.text for block in result.content if getattr(block, "text", None)]
+    text = "\n".join(texts)
+    if result.is_error:
+        return ToolOutput(text=text, error=text or "MCP tool call failed")
+    data = dict(result.structured_content) if result.structured_content else {}
+    return ToolOutput(text=text, data=data)
+
+
+async def mcp_tools(session: Any) -> list[Tool]:
+    """Lists tools on a connected, initialized `mcp.ClientSession` and wraps each as a `Tool`."""
+    listed = await session.list_tools()
+    return [
+        MCPTool(
+            session,
+            name=t.name,
+            description=t.description or t.name,
+            schema=t.input_schema,
+            destructive=bool(t.annotations and t.annotations.destructive_hint),
+        )
+        for t in listed.tools
+    ]
+
+
+@asynccontextmanager
+async def mcp_stdio_tools(
+    command: str,
+    args: list[str] | None = None,
+    *,
+    env: dict[str, str] | None = None,
+) -> AsyncGenerator[list[Tool], None]:
+    """Spawns an MCP server over stdio and yields its tools as `Tool`s.
+
+    Example: `mcp_stdio_tools("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])`.
+    The connection stays open for the `async with` block; tools called after
+    it exits will fail.
+    """
+    require_extra("mcp_stdio_tools", "mcp", "mcp")
+    from mcp.client.stdio import StdioServerParameters, stdio_client
+
+    from mcp import ClientSession
+
+    params = StdioServerParameters(command=command, args=args or [], env=env)
+    async with (
+        stdio_client(params) as (read, write),
+        ClientSession(read, write) as session,
+    ):
+        await session.initialize()
+        yield await mcp_tools(session)
+
+
+@asynccontextmanager
+async def mcp_http_tools(url: str) -> AsyncGenerator[list[Tool], None]:
+    """Connects to an MCP server over streamable HTTP and yields its tools as `Tool`s."""
+    require_extra("mcp_http_tools", "mcp", "mcp")
+    from mcp.client.streamable_http import streamable_http_client
+
+    from mcp import ClientSession
+
+    async with (
+        streamable_http_client(url) as (read, write),
+        ClientSession(read, write) as session,
+    ):
+        await session.initialize()
+        yield await mcp_tools(session)

reactifact-0.6.1/reactifact/mcp/server.py

@@ -0,0 +1,162 @@
+"""MCP server: exposes reactifact `Tool`s as MCP tools, and a `Context`'s
+artifacts as MCP resources — so any MCP client (Claude Desktop, Claude Code,
+another agent) can call into a running reactifact app. Requires the `mcp`
+extra.
+
+Tool schemas come from `Tool.schema` (already a JSON schema — every `Tool`
+has one, hand-written or `@tool`-derived). The `mcp` SDK's own `add_tool`
+only accepts a plain Python function and derives the schema from its
+*signature*, so each `Tool` is bridged through a small function synthesized
+from its schema (`exec`, §below) rather than reduced to a single opaque
+`**kwargs` parameter — the point of serving these over MCP is that a caller
+sees real argument names and types, not a blind bag of kwargs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from .._extras import require_extra
+from ..context import Context
+from ..tools import Tool
+
+_JSON_TYPE_TO_PY = {
+    "string": "str",
+    "integer": "int",
+    "number": "float",
+    "boolean": "bool",
+    "array": "list",
+    "object": "dict",
+}
+
+
+def create_mcp_server(
+    tools: Sequence[Tool] = (),
+    *,
+    context: Context | None = None,
+    name: str = "reactifact",
+    instructions: str = "",
+) -> Any:
+    """Builds an `mcp.server.mcpserver.MCPServer` exposing `tools`.
+
+    With `context=`, two read-only resources are added so an MCP client can
+    inspect a running Context: `context://artifacts/{artifact_type}` (list,
+    e.g. `context://artifacts/Answer`) and `context://artifact/{artifact_id}`
+    (one artifact, its current data and version).
+
+    Run it with `server.run_stdio_async()`, or mount `server.streamable_http_app()`
+    on a FastAPI app alongside `create_trace_router` / `create_chat_router`.
+    """
+    require_extra("create_mcp_server", "mcp", "mcp")
+    from mcp.server.mcpserver import MCPServer
+
+    server = MCPServer(name=name, instructions=instructions or None)
+    for t in tools:
+        _register_tool(server, t)
+    if context is not None:
+        _register_context_resources(server, context)
+    return server
+
+
+def _register_tool(server: Any, t: Tool) -> None:
+    from mcp.types import ToolAnnotations
+
+    fn = _bridge_function(t)
+    annotations = ToolAnnotations(destructive_hint=True) if t.destructive else None
+    server.add_tool(fn, name=t.name, description=t.description, annotations=annotations)
+
+
+def _bridge_function(t: Tool) -> Callable[..., Any]:
+    """Synthesizes a real Python function matching `t.schema`'s properties,
+    so `add_tool`'s signature-introspection publishes `t`'s actual argument
+    names and types instead of one opaque `**kwargs`.
+    """
+    properties: dict[str, Any] = t.schema.get("properties", {}) or {}
+    required = set(t.schema.get("required", []) or [])
+    param_names = list(properties.keys())
+
+    params = []
+    dict_entries = []
+    for pname in param_names:
+        json_type = (properties[pname] or {}).get("type")
+        py_type = (
+            _JSON_TYPE_TO_PY.get(json_type, "Any")
+            if isinstance(json_type, str)
+            else "Any"
+        )
+        if pname in required:
+            params.append(f"{pname}: {py_type}")
+        else:
+            params.append(f"{pname}: {py_type} | None = None")
+        dict_entries.append(f"{pname!r}: {pname}")
+    signature = ", ".join(params)
+    call_dict = "{" + ", ".join(dict_entries) + "}"
+    src = f"async def _bridge({signature}):\n    return await _call({call_dict})\n"
+
+    async def _call(args: dict[str, Any]) -> Any:
+        from mcp.server.mcpserver.exceptions import ToolError
+
+        # optional params default to None above; drop unset ones so `Tool`s
+        # with real (non-None) defaults in their own schema see those instead
+        args = {k: v for k, v in args.items() if v is not None or k in required}
+        result = await t.execute(args)
+        if result.error:
+            # `ToolError`, not a bare exception: an anticipated `Tool` failure
+            # reaches the MCP client as `is_error=True` with this message —
+            # any other exception type is masked to "Error executing tool …".
+            raise ToolError(result.error)
+        return result.data or result.text
+
+    namespace: dict[str, Any] = {"_call": _call, "Any": Any}
+    exec(src, namespace)  # noqa: S102 — schema-derived source, no user input
+    fn: Callable[..., Any] = namespace["_bridge"]
+    fn.__name__ = t.name
+    fn.__doc__ = t.description
+    return fn
+
+
+def _register_context_resources(server: Any, context: Context) -> None:
+    import json
+
+    async def list_artifacts_resource(artifact_type: str) -> str:
+        matches = [
+            a
+            for a in context.list_artifacts()
+            if type(a.data).__name__ == artifact_type
+        ]
+        return json.dumps(
+            [
+                {
+                    "id": a.id,
+                    "type": artifact_type,
+                    "version": a.version,
+                    "data": a.data.model_dump(),
+                }
+                for a in matches
+            ],
+            default=str,
+        )
+
+    async def get_artifact_resource(artifact_id: str) -> str:
+        artifact = context.get(artifact_id)
+        if artifact is None:
+            return json.dumps({"error": f"no artifact with id {artifact_id!r}"})
+        return json.dumps(
+            {
+                "id": artifact.id,
+                "type": type(artifact.data).__name__,
+                "version": artifact.version,
+                "data": artifact.data.model_dump(),
+            },
+            default=str,
+        )
+
+    server.resource(
+        "context://artifacts/{artifact_type}",
+        description="Lists artifacts of one type currently in the Context, newest first.",
+    )(list_artifacts_resource)
+    server.resource(
+        "context://artifact/{artifact_id}",
+        description="Reads one artifact by id: its type, version, and current data.",
+    )(get_artifact_resource)

reactifact-0.6.1/reactifact/tracing/langfuse.py

@@ -0,0 +1,227 @@
+"""Langfuse sink: pushes `RunTrace` via OTLP/HTTP (`POST /api/public/otel/v1/traces`).
+
+Langfuse's legacy REST ingestion (`POST /api/public/traces`,
+`POST /api/public/observations`) is deprecated: it already 404s/400s on
+Langfuse v4, and Langfuse Cloud sunsets it 2026-11-16. OTLP/HTTP is the only
+forward-compatible path for a plain HTTP client (not an official SDK) — see
+https://langfuse.com/integrations/native/opentelemetry/migration-to-v4.
+
+Mapping: one OTLP span per `AgentSpan` (`langfuse.observation.type=span`), one
+child span per `LLMCall` (`type=generation`, `gen_ai.*` attributes for model/
+usage). Trace-level attributes (`langfuse.session.id`, trace metadata) are
+copied onto every span, since Langfuse only aggregates by them when present on
+each observation, not just the root.
+
+Uses httpx (base dependency). For tests you can inject `client`.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from datetime import datetime, timedelta
+from typing import Any
+
+from .models import AgentSpan, LLMCall, RunTrace
+from .tracer import Tracer
+
+
+def _unix_nanos(value: datetime) -> str:
+    return str(int(value.timestamp() * 1_000_000_000))
+
+
+def _trace_id(seed: str) -> str:
+    return hashlib.sha256(f"trace:{seed}".encode()).hexdigest()[:32]
+
+
+def _span_id(seed: str) -> str:
+    return hashlib.sha256(f"span:{seed}".encode()).hexdigest()[:16]
+
+
+def _attr(key: str, value: Any) -> dict[str, Any]:
+    if isinstance(value, bool):
+        otlp_value: dict[str, Any] = {"boolValue": value}
+    elif isinstance(value, int):
+        otlp_value = {"intValue": str(value)}
+    elif isinstance(value, float):
+        otlp_value = {"doubleValue": value}
+    else:
+        if value is None:
+            value = ""
+        elif not isinstance(value, str):
+            value = json.dumps(value, default=str)
+        otlp_value = {"stringValue": value}
+    return {"key": key, "value": otlp_value}
+
+
+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 via OTLP/HTTP."""
+
+    def __init__(
+        self,
+        *,
+        public_key: str,
+        secret_key: str,
+        host: str = "https://cloud.langfuse.com",
+        api_url: str | None = None,
+        client: Any | None = None,
+    ):
+        base = (api_url or host).rstrip("/")
+        self._url = base + "/api/public/otel/v1/traces"
+        token = base64.b64encode(f"{public_key}:{secret_key}".encode()).decode()
+        self._headers = {
+            "Authorization": f"Basic {token}",
+            "x-langfuse-ingestion-version": "4",
+            "Content-Type": "application/json",
+        }
+        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:
+        trace_id = _trace_id(trace.id)
+        run_start = trace.started_at
+        run_end = run_start + timedelta(milliseconds=trace.duration_ms)
+        root_span_id = _span_id(f"{trace.id}:root")
+
+        # Propagated to every span: Langfuse only aggregates trace-level
+        # fields (session, metadata) when they're present on each observation.
+        trace_attrs = [
+            _attr("langfuse.trace.name", "reactifact run"),
+            _attr("langfuse.trace.metadata.outcome", trace.outcome),
+            _attr("langfuse.trace.metadata.span_count", len(trace.spans)),
+        ]
+        if trace.session_id:
+            trace_attrs.append(_attr("langfuse.session.id", trace.session_id))
+
+        spans: list[dict[str, Any]] = [
+            {
+                "traceId": trace_id,
+                "spanId": root_span_id,
+                "name": "reactifact run",
+                "kind": 1,  # SPAN_KIND_INTERNAL
+                "startTimeUnixNano": _unix_nanos(run_start),
+                "endTimeUnixNano": _unix_nanos(run_end),
+                "attributes": [
+                    *trace_attrs,
+                    _attr("langfuse.observation.type", "span"),
+                ],
+            }
+        ]
+
+        for i, span in enumerate(trace.spans):
+            spans.append(
+                self._agent_span(
+                    trace_id, root_span_id, trace_attrs, run_start, i, span
+                )
+            )
+            span_start = span.started_at or run_start
+            agent_span_id = _span_id(f"{trace_id}:span:{i}:{span.agent}")
+            for j, call in enumerate(span.llm_calls):
+                spans.append(
+                    self._llm_span(
+                        trace_id,
+                        agent_span_id,
+                        trace_attrs,
+                        span_start,
+                        i,
+                        j,
+                        span.agent,
+                        call,
+                    )
+                )
+
+        body = {
+            "resourceSpans": [
+                {
+                    "resource": {"attributes": []},
+                    "scopeSpans": [{"scope": {"name": "reactifact"}, "spans": spans}],
+                }
+            ]
+        }
+        await self._client.post(self._url, json=body)
+
+    def _agent_span(
+        self,
+        trace_id: str,
+        parent_span_id: str,
+        trace_attrs: list[dict[str, Any]],
+        run_start: datetime,
+        index: int,
+        span: AgentSpan,
+    ) -> dict[str, Any]:
+        start = span.started_at or run_start
+        end = start + timedelta(milliseconds=span.latency_ms)
+        attrs = [
+            *trace_attrs,
+            _attr("langfuse.observation.type", "span"),
+            _attr("langfuse.observation.input", [r.model_dump() for r in span.reads]),
+            _attr("langfuse.observation.output", [w.model_dump() for w in span.writes]),
+            _attr("langfuse.observation.metadata.event_type", span.event_type),
+            _attr(
+                "langfuse.observation.metadata.read_summary", _type_summary(span.reads)
+            ),
+            _attr(
+                "langfuse.observation.metadata.write_summary",
+                _type_summary(span.writes),
+            ),
+        ]
+        if span.error:
+            attrs.append(_attr("langfuse.observation.metadata.error", span.error))
+        return {
+            "traceId": trace_id,
+            "spanId": _span_id(f"{trace_id}:span:{index}:{span.agent}"),
+            "parentSpanId": parent_span_id,
+            "name": span.agent,
+            "kind": 1,
+            "startTimeUnixNano": _unix_nanos(start),
+            "endTimeUnixNano": _unix_nanos(end),
+            "attributes": attrs,
+        }
+
+    def _llm_span(
+        self,
+        trace_id: str,
+        parent_span_id: str,
+        trace_attrs: list[dict[str, Any]],
+        span_start: datetime,
+        span_index: int,
+        call_index: int,
+        agent: str,
+        call: LLMCall,
+    ) -> dict[str, Any]:
+        end = span_start + timedelta(milliseconds=call.latency_ms)
+        attrs = [
+            *trace_attrs,
+            _attr("langfuse.observation.type", "generation"),
+            _attr("langfuse.observation.input", call.messages),
+            _attr("langfuse.observation.output", call.response),
+            _attr("gen_ai.request.model", call.model or call.provider),
+            _attr("gen_ai.usage.input_tokens", call.prompt_tokens),
+            _attr("gen_ai.usage.output_tokens", call.completion_tokens),
+            _attr("langfuse.observation.metadata.provider", call.provider),
+        ]
+        if call.error:
+            attrs.append(_attr("langfuse.observation.metadata.error", call.error))
+        return {
+            "traceId": trace_id,
+            "spanId": _span_id(f"{trace_id}:llm:{span_index}:{call_index}:{agent}"),
+            "parentSpanId": parent_span_id,
+            "name": f"llm:{call.model or call.provider}",
+            "kind": 1,
+            "startTimeUnixNano": _unix_nanos(span_start),
+            "endTimeUnixNano": _unix_nanos(end),
+            "attributes": attrs,
+        }