continuous-intelligence-layer 0.1.0__py3-none-any.whl

continuous_intelligence_layer/__init__.py

@@ -0,0 +1,28 @@
+"""
+Continuous Intelligence Layer SDK
+==================================
+
+A zero-infrastructure, OpenTelemetry-based observability layer for agentic
+AI systems. Each supported agent framework has its own subpackage with its
+own ``init()`` — import the one matching your framework:
+
+    from continuous_intelligence_layer.langgraph import init   # LangGraph / LangChain
+    from continuous_intelligence_layer.crewai import init      # CrewAI
+    from continuous_intelligence_layer.openai import init      # direct OpenAI SDK
+
+Quick Start
+-----------
+    from continuous_intelligence_layer.langgraph import init
+
+    init(api_key="...")         # call ONCE, before your graph runs
+
+    graph.invoke(...)           # your agent code — unchanged
+
+Every framework's ``init()`` shares the same signature and return contract
+(``{"execution_id": str, "output_path": str}``), and every framework's spans
+flow through the same downstream pipeline (``graph_builder/``,
+``evaluators/``, ``rca_engine/``) regardless of which subpackage produced
+them — see each subpackage's docstring for framework-specific details.
+"""
+
+__version__ = "0.1.0"

continuous_intelligence_layer/_core/__init__.py

@@ -0,0 +1,6 @@
+"""Internal, framework-agnostic building blocks shared by every framework
+subpackage (``langgraph``, ``crewai``, ``openai``, ...).
+
+Not part of the public API — import from a framework subpackage instead
+(e.g. ``from continuous_intelligence_layer.langgraph import init``).
+"""

continuous_intelligence_layer/_core/exporter.py

@@ -0,0 +1,517 @@
+"""
+exporter.py
+-----------
+Custom OpenTelemetry SpanExporter — the core of the SDK.
+
+Role in the pipeline
+--------------------
+OTel SDK calls export() synchronously (via SimpleSpanProcessor) for every span
+that finishes anywhere in the Python process.  We receive a ReadableSpan object,
+extract every useful field, and append one JSON line to a JSONL file.
+
+Why a custom exporter instead of Jaeger / Phoenix / Opik?
+----------------------------------------------------------
+  • No external process or server needed — zero infrastructure.
+  • Full control over the output schema.
+  • JSONL is trivially grep-able, streamable, and loadable with pandas.
+  • Swappable: to send spans to any backend, replace this class with an
+    HTTPSpanExporter that POSTs the same dict to a REST endpoint.
+
+What OpenInference writes onto spans
+-------------------------------------
+OpenInference follows a published semantic convention spec:
+  https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md
+
+The keys we extract are listed below under "OpenInference Attribute Keys".
+
+What IS automatically captured
+--------------------------------
+  ✅ LLM calls          — kind=LLM, model name, prompt messages, response,
+                           token counts (prompt / completion / total)
+  ✅ Agent/Chain nodes  — kind=CHAIN or AGENT, input.value, output.value,
+                           latency, parent-child hierarchy
+  ✅ Tool calls         — kind=TOOL, tool.name, input, output, errors
+  ✅ Retriever calls    — kind=RETRIEVER, input query, retrieved documents
+  ✅ Errors             — exception events on the span → error field
+  ✅ Latency            — computed from start_time / end_time nanoseconds
+  ✅ Trace / Span IDs   — standard OTel identifiers (128-bit / 64-bit hex)
+  ✅ Parent-child links — parent_span_id enables call-tree reconstruction
+
+What is NOT automatically captured (and why)
+---------------------------------------------
+  ⚠  Memory operations  — LangChain's in-memory stores (ConversationBufferMemory
+                           etc.) do NOT go through LangChain's callback system that
+                           OpenInference hooks into, so no spans are emitted.
+                           Workaround: wrap memory reads/writes in a custom tool.
+
+  ⚠  Handover semantics — OpenInference captures parent-child spans which *imply*
+                           handovers, but there is no dedicated "handover" span kind.
+                           The supervisor → sub-agent relationship is visible via
+                           parent_span_id, but is not labelled "HANDOVER" explicitly.
+
+  ⚠  Agent role / name  — The span name comes from LangGraph's node name
+                           (e.g. "research_agent", "writer_agent") which is set
+                           by the developer.  We surface it as 'operation'.
+
+  ⚠  Intermediate state — LangGraph's StateGraph state dict is NOT captured
+                           automatically.  Only the final input/output of each
+                           node that goes through the LangChain callback layer is.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import threading
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Sequence
+
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# OpenInference Semantic Convention Attribute Keys
+# Reference: https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Core I/O — present on every span kind
+_OI_INPUT              = "input.value"              # serialized input to this node
+_OI_OUTPUT             = "output.value"             # serialized output from this node
+
+# LLM-specific
+_OI_LLM_IN_MESSAGES    = "llm.input_messages"       # list of role+content dicts (newer OI)
+_OI_LLM_OUT_MESSAGES   = "llm.output_messages"      # list of role+content dicts (newer OI)
+_OI_LLM_PROMPTS        = "llm.prompts"              # legacy key (older OI versions)
+_OI_LLM_RESPONSES      = "llm.responses"            # legacy key (older OI versions)
+_OI_MODEL_NAME         = "llm.model_name"           # e.g. "gpt-4o-mini"
+_OI_TOK_PROMPT         = "llm.token_count.prompt"
+_OI_TOK_COMPLETION     = "llm.token_count.completion"
+_OI_TOK_TOTAL          = "llm.token_count.total"
+_OI_TEMPERATURE        = "llm.invocation_parameters" # JSON string with temperature etc.
+
+# Tool-specific
+_OI_TOOL_NAME          = "tool.name"
+_OI_TOOL_DESCRIPTION   = "tool.description"
+_OI_TOOL_PARAMETERS    = "tool.parameters"
+
+# Retriever-specific
+_OI_RETRIEVAL_DOCS     = "retrieval.documents"      # list of retrieved documents
+
+# Span kind — drives node_type classification
+_OI_SPAN_KIND          = "openinference.span.kind"  # LLM | CHAIN | TOOL | RETRIEVER | AGENT
+
+# Tool-calling decision — present directly on the LLM span itself (not a child
+# span), so this is available regardless of framework or whether the
+# framework's instrumentor also emits a separate TOOL-kind execution span.
+# OTel attributes are flat, so OpenInference flattens nested lists into
+# dotted+indexed keys, e.g. "llm.tools.0.tool.json_schema" and
+# "llm.output_messages.0.message.tool_calls.0.tool_call.function.name".
+_OI_TOOL_SCHEMA_RE     = re.compile(r"^llm\.tools\.(\d+)\.tool\.json_schema$")
+_OI_TOOL_CALL_NAME_RE  = re.compile(
+    r"^llm\.output_messages\.(\d+)\.message\.tool_calls\.(\d+)\.tool_call\.function\.name$"
+)
+_OI_TOOL_CALL_ARGS_RE  = re.compile(
+    r"^llm\.output_messages\.(\d+)\.message\.tool_calls\.(\d+)\.tool_call\.function\.arguments$"
+)
+
+# All known OI keys — anything else goes into 'metadata'
+_ALL_OI_KEYS = {
+    _OI_INPUT, _OI_OUTPUT,
+    _OI_LLM_IN_MESSAGES, _OI_LLM_OUT_MESSAGES,
+    _OI_LLM_PROMPTS, _OI_LLM_RESPONSES,
+    _OI_MODEL_NAME, _OI_TOK_PROMPT, _OI_TOK_COMPLETION, _OI_TOK_TOTAL,
+    _OI_TEMPERATURE, _OI_TOOL_NAME, _OI_TOOL_DESCRIPTION, _OI_TOOL_PARAMETERS,
+    _OI_RETRIEVAL_DOCS, _OI_SPAN_KIND,
+}
+
+# Mapping from OpenInference span kind → our node_type vocabulary
+_KIND_TO_NODE_TYPE: dict[str, str] = {
+    "LLM":       "LLM",
+    "CHAIN":     "Agent",
+    "TOOL":      "Tool",
+    "RETRIEVER": "Retriever",
+    "AGENT":     "Agent",
+    "MEMORY":    "Memory",
+    "EMBEDDING": "Embedding",
+    "RERANKER":  "Reranker",
+    "GUARDRAIL": "Guardrail",
+}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Exporter
+# ─────────────────────────────────────────────────────────────────────────────
+
+class ExecutionSpanExporter(SpanExporter):
+    """
+    Writes every finished OTel span to a JSONL file.
+
+    Thread-safe: a threading.Lock guards file writes.
+
+    The JSONL format means:
+      - Each line is a valid, standalone JSON object.
+      - Files can be tailed in real-time: ``tail -f execution_trace.jsonl | jq .``
+      - Trivially loadable: ``pd.read_json("execution_trace.jsonl", lines=True)``
+
+    Swappability
+    ------------
+    To send spans to a backend instead of a file, subclass this and override
+    _write() to POST the record dict to an HTTP endpoint.
+    """
+
+    def __init__(self, output_path: str, execution_id: str | None = None, session_id: str | None = None):
+        """
+        Parameters
+        ----------
+        output_path :
+            Absolute or relative path to the JSONL file.
+            Parent directories are created if they don't exist.
+        execution_id :
+            Short identifier for this pipeline run.  Stamped on every record.
+        session_id :
+            Identifier for the conversational session/thread.
+        """
+        self.output_path  = Path(output_path)
+        self.execution_id = execution_id or str(uuid.uuid4())[:12]
+        self.session_id   = session_id
+        self._lock        = threading.Lock()
+
+        # Ensure the directory exists before the first write
+        self.output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # ── SpanExporter interface ────────────────────────────────────────────
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        """
+        Receive a batch of finished spans from the OTel SDK.
+
+        With SimpleSpanProcessor (which we use), this is called with exactly
+        ONE span per invocation, immediately when span.end() is called.
+        With BatchSpanProcessor it would be called in batches.
+
+        We extract every field we care about and write one JSON line per span.
+        We catch all exceptions internally — the agent must never crash because
+        of a tracing failure.
+        """
+        for span in spans:
+            try:
+                record = self._extract(span)
+                self._write(record)
+            except Exception as exc:
+                # Degrade gracefully — print but never propagate
+                print(f"[ExecutionSpanExporter] ⚠  Failed to export span "
+                      f"'{span.name}': {type(exc).__name__}: {exc}")
+        return SpanExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        """Called when TracerProvider.shutdown() is invoked."""
+        pass
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        """All writes are synchronous, so there is nothing to flush."""
+        return True
+
+    # ── Span extraction ───────────────────────────────────────────────────
+
+    def _extract(self, span: ReadableSpan) -> dict:
+        """
+        Convert a raw ReadableSpan into our structured dict.
+
+        ReadableSpan fields used
+        ------------------------
+        span.context.trace_id    — 128-bit int → 32-char hex
+        span.context.span_id     — 64-bit int → 16-char hex
+        span.parent.span_id      — parent's 64-bit int (None if root span)
+        span.name                — the operation name set by the instrumentation
+        span.attributes          — dict of all OTel + OpenInference attributes
+        span.start_time          — int, nanoseconds since epoch (UTC)
+        span.end_time            — int, nanoseconds since epoch (UTC)
+        span.status.status_code  — StatusCode enum: OK | ERROR | UNSET
+        span.events              — list of SpanEvent (exception events live here)
+        """
+        attrs      = dict(span.attributes or {})
+        ctx        = span.context
+        parent_ctx = span.parent
+
+        # ── IDs ──────────────────────────────────────────────────────────
+        trace_id  = _fmt_trace_id(ctx.trace_id)
+        span_id   = _fmt_span_id(ctx.span_id)
+        parent_id = _fmt_span_id(parent_ctx.span_id) if parent_ctx else None
+
+        # ── Timestamps & latency ─────────────────────────────────────────
+        start_ns   = span.start_time or 0
+        end_ns     = span.end_time   or 0
+        latency_ms = round((end_ns - start_ns) / 1_000_000, 3) if (start_ns and end_ns) else 0.0
+
+        # ── Node type (from OpenInference span kind or name heuristic) ───
+        oi_kind   = _get(attrs, _OI_SPAN_KIND, "")
+        node_type = _KIND_TO_NODE_TYPE.get(
+            oi_kind.upper(),
+            _infer_node_type_from_name(span.name),
+        )
+
+        # ── Status & errors ──────────────────────────────────────────────
+        #
+        # OTel stores exceptions as SpanEvents with name="exception".
+        # We surface the exception.message as our error field.
+        #
+        status_code = span.status.status_code.name if span.status else "UNSET"
+        error_msg: str | None = None
+        for event in span.events or []:
+            if event.name == "exception":
+                error_msg = str(event.attributes.get("exception.message", ""))
+                if not error_msg:
+                    error_msg = str(event.attributes.get("exception.type", "Unknown error"))
+                break
+        if not error_msg and status_code == "ERROR":
+            error_msg = getattr(span.status, "description", None) or "Unknown error"
+
+        # ── LLM token usage ──────────────────────────────────────────────
+        tok_prompt = _get(attrs, _OI_TOK_PROMPT)
+        tok_comp   = _get(attrs, _OI_TOK_COMPLETION)
+        tok_total  = _get(attrs, _OI_TOK_TOTAL)
+        # Compute total if missing (older OI versions don't set it)
+        if tok_total is None and tok_prompt is not None and tok_comp is not None:
+            tok_total = tok_prompt + tok_comp
+
+        # ── Prompt & response: support both old and new OI key names ─────
+        prompt   = _get(attrs, _OI_LLM_IN_MESSAGES) or _get(attrs, _OI_LLM_PROMPTS)
+        response = _get(attrs, _OI_LLM_OUT_MESSAGES) or _get(attrs, _OI_LLM_RESPONSES)
+
+        # ── Tool-calling decision (available tools + what was chosen) ────
+        available_tools = _extract_available_tools(attrs)
+        tool_calls      = _extract_tool_calls(attrs, _get(attrs, _OI_OUTPUT))
+
+        # ── Remaining attributes → metadata ──────────────────────────────
+        metadata = {
+            k: v for k, v in attrs.items()
+            if k not in _ALL_OI_KEYS
+            and not _OI_TOOL_SCHEMA_RE.match(k)
+            and not _OI_TOOL_CALL_NAME_RE.match(k)
+            and not _OI_TOOL_CALL_ARGS_RE.match(k)
+        }
+
+        # The UUID is saved as project.id
+        project_id = str(span.resource.attributes.get("project.id", span.resource.attributes.get("service.name", ""))) if span.resource and span.resource.attributes else None
+
+        return {
+            # ── Run identity ──────────────────────────────────────────
+            "execution_id":   self.execution_id,
+            "session_id":     self.session_id,
+            "project_id":     project_id,
+
+            # ── Span identity & hierarchy ────────────────────────────
+            "trace_id":       trace_id,
+            "span_id":        span_id,
+            "parent_span_id": parent_id,       # None = root span
+
+            # ── What happened ────────────────────────────────────────
+            "operation":      span.name,        # e.g. "ChatOpenAI", "web_search", "planner"
+            "node_type":      node_type,        # LLM | Tool | Agent | Retriever | ...
+
+            # ── Timing ───────────────────────────────────────────────
+            "timestamp":      _ns_to_iso(start_ns),
+            "end_timestamp":  _ns_to_iso(end_ns),
+            "latency_ms":     latency_ms,
+
+            # ── I/O (generic — present on all span kinds) ────────────
+            "input":          _get(attrs, _OI_INPUT),
+            "output":         _get(attrs, _OI_OUTPUT),
+
+            # ── LLM-specific ─────────────────────────────────────────
+            "prompt":         prompt,           # full message list or prompt string
+            "response":       response,         # full message list or response string
+            "model":          _get(attrs, _OI_MODEL_NAME),
+            "tokens": {
+                "prompt":     tok_prompt,
+                "completion": tok_comp,
+                "total":      tok_total,
+            },
+
+            # ── Tool-specific ────────────────────────────────────────
+            "tool_name":      _get(attrs, _OI_TOOL_NAME),
+            "tool_desc":      _get(attrs, _OI_TOOL_DESCRIPTION),
+
+            # ── Tool-calling decision (populated on LLM nodes, node-local —
+            #    doesn't require a separate child TOOL span to exist) ─────
+            "available_tools": available_tools,
+            "tool_calls":      tool_calls,
+
+            # ── Retriever-specific ───────────────────────────────────
+            "retrieved_docs": _get(attrs, _OI_RETRIEVAL_DOCS),
+
+            # ── Status & errors ──────────────────────────────────────
+            "status":         status_code,      # OK | ERROR | UNSET
+            "error":          error_msg,
+
+            # ── Everything else from OTel/OI attributes ──────────────
+            "metadata":       metadata,
+        }
+
+    def _write(self, record: dict) -> None:
+        """Append one JSON line to the JSONL file. Thread-safe."""
+        with self._lock:
+            with open(self.output_path, "a", encoding="utf-8") as fh:
+                fh.write(json.dumps(record, default=str) + "\n")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _fmt_trace_id(trace_id: int) -> str:
+    """128-bit trace ID as 32-char lowercase hex string."""
+    return format(trace_id, "032x")
+
+
+def _fmt_span_id(span_id: int) -> str:
+    """64-bit span ID as 16-char lowercase hex string."""
+    return format(span_id, "016x")
+
+
+def _ns_to_iso(ns: int) -> str | None:
+    """Convert nanosecond epoch timestamp to ISO-8601 UTC string."""
+    if not ns:
+        return None
+    return datetime.fromtimestamp(ns / 1e9, tz=timezone.utc).isoformat()
+
+
+def _get(attrs: dict, key: str, default: Any = None) -> Any:
+    """Safely get an attribute value; returns default if absent or None."""
+    val = attrs.get(key)
+    return val if val is not None else default
+
+
+def _extract_available_tools(attrs: dict) -> list[Any] | None:
+    """
+    Reconstruct the list of tool schemas offered to the model from flattened
+    "llm.tools.<i>.tool.json_schema" attributes. Framework-agnostic: this
+    comes from the model request itself, not from any framework wrapping.
+    """
+    schemas: dict[int, Any] = {}
+    for key, val in attrs.items():
+        m = _OI_TOOL_SCHEMA_RE.match(key)
+        if not m:
+            continue
+        idx = int(m.group(1))
+        if isinstance(val, str):
+            try:
+                val = json.loads(val)
+            except (TypeError, ValueError):
+                pass
+        schemas[idx] = val
+    if not schemas:
+        return None
+    return [schemas[i] for i in sorted(schemas)]
+
+
+def _extract_tool_calls(attrs: dict, output_value: str | None = None) -> list[dict] | None:
+    """
+    Reconstruct the tool-call decision(s) the model actually made from
+    flattened "llm.output_messages.<i>.message.tool_calls.<j>.tool_call.function.*"
+    attributes. This lives directly on the LLM span — no separate TOOL-kind
+    child span is required, so it works for raw OpenAI/Anthropic SDK agents
+    (which never emit a tool-execution span) just as well as for LangChain.
+
+    Falls back to parsing `output_value` (the full raw response JSON, always
+    present on an LLM span) when the flattened attributes are absent or
+    incomplete. Observed in practice: for some model/param combinations
+    (e.g. a custom model alias + `reasoning_effort`), the instrumentor emits
+    `tool_call.id` but never emits `tool_call.function.name`/`.arguments` —
+    so `calls` below ends up empty even though the model genuinely made a
+    tool call and it's fully present in the raw response. Without this
+    fallback that tool call becomes invisible to ToolAgentEvaluator, which
+    gates on `node.tool_calls` being truthy — not a "no tool call happened"
+    case, but a "the tracing library only wrote half its notes" case.
+    """
+    calls: dict[tuple[int, int], dict] = {}
+    for key, val in attrs.items():
+        m = _OI_TOOL_CALL_NAME_RE.match(key)
+        if m:
+            idx = (int(m.group(1)), int(m.group(2)))
+            calls.setdefault(idx, {})["name"] = val
+            continue
+        m = _OI_TOOL_CALL_ARGS_RE.match(key)
+        if m:
+            idx = (int(m.group(1)), int(m.group(2)))
+            args = val
+            if isinstance(args, str):
+                try:
+                    args = json.loads(args)
+                except (TypeError, ValueError):
+                    pass
+            calls.setdefault(idx, {})["arguments"] = args
+    if calls:
+        return [calls[k] for k in sorted(calls)]
+    return _fallback_tool_calls_from_output(output_value)
+
+
+def _fallback_tool_calls_from_output(output_value: str | None) -> list[dict] | None:
+    """
+    Reconstruct tool calls directly from the raw serialized LLM response,
+    for the small number of known provider response shapes, when the
+    flattened OpenInference attributes didn't carry them. Best-effort: any
+    parse failure or unrecognized shape just means "nothing to add", not an
+    error — the caller already has no tool calls from the primary path.
+    """
+    if not output_value:
+        return None
+    try:
+        data = json.loads(output_value)
+    except (TypeError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+
+    calls: list[dict] = []
+
+    # OpenAI Chat Completions shape:
+    #   {"choices": [{"message": {"tool_calls": [{"function": {"name", "arguments"}}]}}]}
+    for choice in data.get("choices") or []:
+        if not isinstance(choice, dict):
+            continue
+        message = choice.get("message") or {}
+        for tc in message.get("tool_calls") or []:
+            if not isinstance(tc, dict):
+                continue
+            fn = tc.get("function") or {}
+            name = fn.get("name")
+            if not name:
+                continue
+            args = fn.get("arguments")
+            if isinstance(args, str):
+                try:
+                    args = json.loads(args)
+                except (TypeError, ValueError):
+                    pass
+            calls.append({"name": name, "arguments": args})
+
+    # Anthropic Messages shape:
+    #   {"content": [{"type": "tool_use", "name": ..., "input": {...}}]}
+    for block in data.get("content") or []:
+        if isinstance(block, dict) and block.get("type") == "tool_use":
+            calls.append({"name": block.get("name"), "arguments": block.get("input")})
+
+    return calls or None
+
+
+def _infer_node_type_from_name(name: str) -> str:
+    """
+    Fallback node-type classification when OpenInference span kind is absent.
+    Uses simple keyword matching on the span operation name.
+    """
+    n = name.lower()
+    if any(kw in n for kw in ("llm", "chat", "completion", "generate", "openai", "anthropic", "gemini")):
+        return "LLM"
+    if any(kw in n for kw in ("tool", "function", "search", "api", "execute", "run_tool")):
+        return "Tool"
+    if any(kw in n for kw in ("retriev", "fetch", "vector", "embed", "document", "store")):
+        return "Retriever"
+    if any(kw in n for kw in ("memory", "buffer", "history", "remember", "recall")):
+        return "Memory"
+    if any(kw in n for kw in ("route", "router", "supervisor", "handoff", "delegate")):
+        return "Router"
+    return "Agent"  # default: assume it's an agent node

continuous_intelligence_layer/_core/graph_exporter.py

@@ -0,0 +1,92 @@
+"""
+graph_exporter.py
+-----------------
+An optional SpanExporter that buffers spans in memory and flushes them
+as a complete ExecutionGraph to the API's /traces/ingest endpoint upon
+shutdown. The API process is the only thing that talks to MongoDB directly;
+agent machines only need an api_key.
+"""
+
+import threading
+from typing import Sequence
+
+import requests
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+
+from graph_builder.builder import TraceToGraphBuilder
+from .exporter import ExecutionSpanExporter
+
+
+class GraphSpanExporter(SpanExporter):
+    """
+    Buffers spans during execution and POSTs them as a graph to the API
+    when the TracerProvider shuts down (i.e. at the end of the script).
+    """
+
+    def __init__(
+        self,
+        jsonl_exporter: ExecutionSpanExporter,
+        session_id: str | None = None,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        project_id: str | None = None,
+        run_evaluations: bool = True,
+    ):
+        """
+        Takes an instance of ExecutionSpanExporter to reuse its _extract logic.
+        """
+        self._jsonl_exporter = jsonl_exporter
+        self._session_id = session_id
+        self._base_url = base_url
+        self._api_key = api_key
+        self._project_id = project_id
+        self._run_evaluations = run_evaluations
+        self._spans_buffer: list[dict] = []
+        self._lock = threading.Lock()
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        with self._lock:
+            for span in spans:
+                try:
+                    record = self._jsonl_exporter._extract(span)
+                    self._spans_buffer.append(record)
+                except Exception as exc:
+                    print(f"[GraphSpanExporter] ⚠ Failed to extract span: {exc}")
+        return SpanExportResult.SUCCESS
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
+    def shutdown(self) -> None:
+        """
+        Build the graph from buffered spans and POST it to the API.
+        """
+        with self._lock:
+            if not self._spans_buffer:
+                return
+
+            try:
+                builder = TraceToGraphBuilder()
+                # execution_id is shared across all spans from this run
+                execution_id = self._spans_buffer[0].get("execution_id", "unknown")
+                graph = builder.build(
+                    self._spans_buffer,
+                    execution_id=execution_id,
+                    session_id=self._session_id
+                )
+                graph.project_id = self._project_id or graph.project_id
+
+                res = requests.post(
+                    f"{self._base_url}/traces/ingest",
+                    json=graph.model_dump(mode="json"),
+                    params={"run_evaluations": self._run_evaluations},
+                    headers={"x-api-key": self._api_key},
+                    timeout=30,
+                )
+                res.raise_for_status()
+                print(f"[GraphSpanExporter] ✓ Successfully sent graph {execution_id} to API.")
+            except Exception as exc:
+                print(f"[GraphSpanExporter] ⚠ Failed to send graph to API: {exc}")
+            finally:
+                self._spans_buffer.clear()