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

graph_builder/builder.py

@@ -0,0 +1,212 @@
+"""
+builder.py
+----------
+Converts a flat list of execution spans (from the continuous_intelligence_layer
+SDK or from TraceStore) into an ExecutionGraph of ExecutionNodes and ExecutionEdges.
+
+Algorithm:
+1. Sort spans by timestamp.
+2. Each span → ExecutionNode (reading from the continuous_intelligence_layer
+   exporter schema, shared by every framework subpackage).
+3. For every span with a parent_span_id, create an edge:
+     parent → child  (EdgeType.CALLS)
+4. Additionally create NEXT edges between sibling nodes (same parent)
+   ordered by timestamp.
+
+Span field mapping (continuous_intelligence_layer exporter → ExecutionNode):
+  "span_id"        → node_id
+  "parent_span_id" → parent_id
+  "execution_id"   → execution_id
+  "session_id"     → session_id
+  "trace_id"       → trace_id
+  "node_type"      → node_type
+  "operation"      → name          ← was wrongly "name" before
+  "model"          → model
+  "tool_name"      → tool_name
+  "tool_desc"      → tool_desc
+  "retrieved_docs" → retrieved_docs
+  "available_tools"→ available_tools
+  "tool_calls"     → tool_calls
+  "input"          → input
+  "output"         → output
+  "prompt"         → prompt
+  "response"       → response
+  "latency_ms"     → latency_ms
+  "tokens"         → tokens
+  "error"          → error
+  "timestamp"      → timestamp
+  "end_timestamp"  → end_timestamp
+  "metadata"       → metadata      ← was wrongly "attributes" before
+  "status"         → status
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .models import (
+    EdgeType,
+    ExecutionEdge,
+    ExecutionGraph,
+    ExecutionNode,
+    NodeType,
+    TokenUsage,
+)
+
+
+def _safe_str(val: Any, max_len: int = 4000) -> str | None:
+    """Safely convert any value to a string, capping length."""
+    if val is None:
+        return None
+    if isinstance(val, str):
+        return val[:max_len]
+    try:
+        return json.dumps(val, default=str)[:max_len]
+    except Exception:
+        return str(val)[:max_len]
+
+
+def _node_type(raw: str) -> NodeType:
+    mapping = {
+        "llm":       NodeType.LLM,
+        "tool":      NodeType.Tool,
+        "retriever": NodeType.Retriever,
+        "agent":     NodeType.Agent,
+        "memory":    NodeType.Memory,
+        "router":    NodeType.Router,
+        "embedding": NodeType.Embedding,
+        "reranker":  NodeType.Reranker,
+        "guardrail": NodeType.Guardrail,
+    }
+    return mapping.get(raw.lower(), NodeType.Unknown)
+
+
+class TraceToGraphBuilder:
+    """
+    Converts a list of span dicts (from continuous_intelligence_layer SDK
+    output) into an ExecutionGraph ready to be persisted in MongoDB.
+
+    Usage:
+        from graph_builder.builder import TraceToGraphBuilder
+        from continuous_intelligence_layer.langgraph import load_traces
+
+        spans = load_traces("./execution_trace.jsonl")
+        graph = TraceToGraphBuilder().build(spans, execution_id="abc123")
+    """
+
+    def build(
+        self,
+        spans: list[dict],
+        execution_id: str,
+        session_id: str | None = None,
+    ) -> ExecutionGraph:
+        if not spans:
+            return ExecutionGraph(execution_id=execution_id, session_id=session_id)
+
+        # ── 1. Sort by timestamp ───────────────────────────────────────────
+        sorted_spans = sorted(
+            spans,
+            key=lambda s: s.get("timestamp") or "",
+        )
+
+        # ── 2. Build nodes ────────────────────────────────────────────────
+        node_map: dict[str, ExecutionNode] = {}
+        for span in sorted_spans:
+            node = self._span_to_node(span, session_id=session_id)
+            node_map[node.node_id] = node
+
+        # ── 3. Build CALLS edges (parent → child) ─────────────────────────
+        edges: list[ExecutionEdge] = []
+        for node in node_map.values():
+            if node.parent_id and node.parent_id in node_map:
+                edges.append(ExecutionEdge(
+                    source_id=node.parent_id,
+                    target_id=node.node_id,
+                    edge_type=EdgeType.CALLS,
+                ))
+
+        # ── 4. Build NEXT edges between siblings ──────────────────────────
+        # Group by parent_id — siblings are nodes sharing the same parent
+        siblings: dict[str | None, list[ExecutionNode]] = {}
+        for node in node_map.values():
+            siblings.setdefault(node.parent_id, []).append(node)
+
+        for group in siblings.values():
+            ordered = sorted(group, key=lambda n: n.timestamp or "")
+            for i in range(len(ordered) - 1):
+                edges.append(ExecutionEdge(
+                    source_id=ordered[i].node_id,
+                    target_id=ordered[i + 1].node_id,
+                    edge_type=EdgeType.NEXT,
+                ))
+
+        graph = ExecutionGraph(
+            execution_id=execution_id,
+            session_id=session_id,
+            nodes=list(node_map.values()),
+            edges=edges,
+        )
+        return graph
+
+    # ── Private helpers ────────────────────────────────────────────────────
+
+    def _span_to_node(
+        self,
+        span: dict,
+        session_id: str | None = None,
+    ) -> ExecutionNode:
+        tokens_raw = span.get("tokens", {}) or {}
+        token_usage = TokenUsage(
+            prompt=tokens_raw.get("prompt"),
+            completion=tokens_raw.get("completion"),
+            total=tokens_raw.get("total"),
+        )
+
+        # session_id: prefer what's on the span, fall back to caller-supplied
+        s_id = span.get("session_id") or session_id
+
+        return ExecutionNode(
+            node_id=span["span_id"],
+            parent_id=span.get("parent_span_id"),
+            execution_id=span.get("execution_id", "unknown"),
+            session_id=s_id,
+            project_id=span.get("project_id"),
+            trace_id=span.get("trace_id", ""),
+
+            # ── Classification ──────────────────────────────────────────
+            node_type=_node_type(span.get("node_type", "Unknown")),
+            name=span.get("operation") or span.get("name") or "unnamed",  # Fixed: was "name" only
+
+            # ── LLM-specific ────────────────────────────────────────────
+            model=span.get("model"),
+
+            # ── Tool-specific ───────────────────────────────────────────
+            tool_name=span.get("tool_name"),
+            tool_desc=_safe_str(span.get("tool_desc"), max_len=500),
+            retrieved_docs=_safe_str(span.get("retrieved_docs"), max_len=2000),
+
+            # ── Tool-calling decision (node-local) ─────────────────────
+            available_tools=span.get("available_tools"),
+            tool_calls=span.get("tool_calls"),
+
+            # ── I/O ─────────────────────────────────────────────────────
+            input=_safe_str(span.get("input")),
+            output=_safe_str(span.get("output")),
+            prompt=_safe_str(span.get("prompt")),
+            response=_safe_str(span.get("response")),
+
+            # ── Metrics ─────────────────────────────────────────────────
+            latency_ms=span.get("latency_ms", 0.0),
+            tokens=token_usage,
+            error=span.get("error"),
+
+            # ── Temporal ────────────────────────────────────────────────
+            timestamp=span.get("timestamp"),
+            end_timestamp=span.get("end_timestamp"),
+
+            # ── Metadata ────────────────────────────────────────────────
+            # Fixed: was span.get("attributes") — exporter writes "metadata"
+            metadata=span.get("metadata") or {},
+            status=span.get("status", "UNSET"),
+        )

graph_builder/models.py

@@ -0,0 +1,159 @@
+"""
+models.py
+---------
+Pydantic models for the execution graph.
+
+  ExecutionNode  — represents a single span in the graph
+  ExecutionEdge  — represents a relationship between two nodes
+  ExecutionGraph — container for nodes + edges with helper methods
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class NodeType(str, Enum):
+    LLM       = "LLM"
+    Tool      = "Tool"
+    Retriever = "Retriever"
+    Agent     = "Agent"
+    Memory    = "Memory"
+    Router    = "Router"
+    Embedding = "Embedding"
+    Reranker  = "Reranker"
+    Guardrail = "Guardrail"
+    Unknown   = "Unknown"
+
+
+class EdgeType(str, Enum):
+    CALLS   = "CALLS"
+    RETURNS = "RETURNS"
+    USES    = "USES"
+    READS   = "READS"
+    WRITES  = "WRITES"
+    NEXT    = "NEXT"
+
+
+class TokenUsage(BaseModel):
+    prompt:     Optional[int] = None
+    completion: Optional[int] = None
+    total:      Optional[int] = None
+
+
+class ExecutionNode(BaseModel):
+    """One execution span = one graph node."""
+
+    # ── Identity ────────────────────────────────────────────────────────────
+    node_id:       str
+    parent_id:     Optional[str] = None
+    execution_id:  str           # one graph.invoke() call
+    session_id:    Optional[str] = None  # one user conversation / thread
+    project_id:    Optional[str] = None  # for multi-tenancy
+    trace_id:      str
+
+    # ── Classification ─────────────────────────────────────────────────────
+    node_type:     NodeType = NodeType.Unknown
+    name:          str      # operation name (e.g. "supervisor", "ChatOpenAI")
+
+    # ── LLM-specific ───────────────────────────────────────────────────────
+    model:         Optional[str] = None   # e.g. "gpt-4o-mini"
+
+    # ── Tool / Retriever-specific ──────────────────────────────────────────
+    tool_name:      Optional[str] = None
+    tool_desc:      Optional[str] = None
+    retrieved_docs: Optional[str] = None  # JSON-serialised list of docs
+
+    # ── Tool-calling decision (LLM-node-local; no child Tool span needed) ──
+    available_tools: Optional[list[Any]] = None   # tool schemas offered to the model
+    tool_calls:      Optional[list[dict]] = None  # tool(s) the model actually chose
+
+    # ── Execution data ─────────────────────────────────────────────────────
+    input:         Optional[Any] = None
+    output:        Optional[Any] = None
+    prompt:        Optional[str] = None
+    response:      Optional[str] = None
+
+    # ── Runtime metrics ────────────────────────────────────────────────────
+    latency_ms:    float = 0.0
+    tokens:        TokenUsage = Field(default_factory=TokenUsage)
+    error:         Optional[str] = None
+
+    # ── Temporal ──────────────────────────────────────────────────────────
+    timestamp:     Optional[str] = None
+    end_timestamp: Optional[str] = None
+
+    # ── Extra attributes ──────────────────────────────────────────────────
+    metadata:      dict[str, Any] = Field(default_factory=dict)
+    status:        str = "UNSET"
+
+    # ── Validation state (filled by Validator Engine) ─────────────────────
+    validation_results: list[dict] = Field(default_factory=list)
+
+    class Config:
+        use_enum_values = True
+
+
+class ExecutionEdge(BaseModel):
+    """Directed relationship between two nodes."""
+
+    source_id:  str
+    target_id:  str
+    edge_type:  EdgeType = EdgeType.CALLS
+    metadata:   dict[str, Any] = Field(default_factory=dict)
+
+    class Config:
+        use_enum_values = True
+
+
+class ExecutionGraph(BaseModel):
+    """Container for the full execution graph of one run."""
+
+    execution_id: str
+    session_id:   Optional[str] = None
+    project_id:   Optional[str] = None
+    nodes:        list[ExecutionNode] = Field(default_factory=list)
+    edges:        list[ExecutionEdge] = Field(default_factory=list)
+
+    # ── Helpers ────────────────────────────────────────────────────────────
+
+    def get_node(self, node_id: str) -> Optional[ExecutionNode]:
+        for node in self.nodes:
+            if node.node_id == node_id:
+                return node
+        return None
+
+    def get_children(self, node_id: str) -> list[ExecutionNode]:
+        """Return all nodes whose parent is node_id."""
+        return [n for n in self.nodes if n.parent_id == node_id]
+
+    def get_root_nodes(self) -> list[ExecutionNode]:
+        """Return nodes with no parent (top-level spans)."""
+        return [n for n in self.nodes if n.parent_id is None]
+
+    def get_nodes_by_type(self, node_type: NodeType | str) -> list[ExecutionNode]:
+        nt = node_type.value if isinstance(node_type, NodeType) else node_type
+        return [n for n in self.nodes if n.node_type == nt]
+
+    def get_failed_nodes(self) -> list[ExecutionNode]:
+        return [n for n in self.nodes if n.error or n.status == "ERROR"]
+
+    def summary(self) -> dict:
+        total_latency = sum(n.latency_ms for n in self.nodes)
+        total_tokens  = sum((n.tokens.total or 0) for n in self.nodes)
+        return {
+            "execution_id":     self.execution_id,
+            "session_id":       self.session_id,
+            "total_nodes":      len(self.nodes),
+            "total_edges":      len(self.edges),
+            "total_latency_ms": round(total_latency, 2),
+            "total_tokens":     total_tokens,
+            "failed_nodes":     len(self.get_failed_nodes()),
+            "node_type_counts": {
+                nt: len(self.get_nodes_by_type(nt))
+                for nt in [e.value for e in NodeType]
+            },
+        }