traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/adapters/mapped_json.py

@@ -0,0 +1,297 @@
+"""Data-driven adapter for file-watch frameworks.
+
+Parses JSON events using a declarative YAML mapping config. Each framework
+gets a YAML file describing how to extract event type, timestamp, session ID,
+and payload fields — no custom Python code needed per framework.
+
+Frameworks with non-flat event schemas use a preprocessor that normalizes
+raw dicts into a flat {type_field: value, ...} shape before YAML mapping.
+Preprocessors live in the traceforge.preprocessors package.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from collections.abc import Iterator
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+from pydantic import Field
+
+from traceforge.adapters.base import JsonLineAdapter
+from traceforge.models import StrictModel
+from traceforge.preprocessors import get_preprocessor
+from traceforge.types import EventKind, EventMetadata, IngestionMode, SessionEvent, ToolMotivation
+
+logger = logging.getLogger(__name__)
+
+
+# ─── Dot-path access ─────────────────────────────────────────────────────────
+
+
+def _resolve_path(obj: Any, path: str) -> Any:
+    """Resolve a dot-separated path against a nested dict/list.
+
+    Supports: "foo.bar", "foo.0.bar" (integer index), "foo" (top-level).
+    Returns None if any segment is missing.
+    """
+    current = obj
+    for segment in path.split("."):
+        if current is None:
+            return None
+        if isinstance(current, dict):
+            current = current.get(segment)
+        elif isinstance(current, (list, tuple)):
+            try:
+                current = current[int(segment)]
+            except (ValueError, IndexError):
+                return None
+        else:
+            return None
+    return current
+
+
+# ─── Mapping Config ──────────────────────────────────────────────────────────
+
+
+class EventMapping(StrictModel):
+    """Mapping for a single raw event type → canonical kind + payload extraction."""
+
+    kind: str  # canonical EventKind string
+    payload: dict[str, str] = Field(default_factory=dict)  # field_name → dot-path
+
+
+class SpanMapping(StrictModel):
+    """Mapping for an OTel span name → canonical kind + attribute extraction."""
+
+    kind: str  # canonical EventKind string
+    attributes: dict[str, str] = Field(default_factory=dict)  # payload_field → otel_attr_key
+
+
+class MotivationSource(StrictModel):
+    """A single source of motivation text from the event stream."""
+
+    events: list[str]  # raw event type keys that carry this motivation
+    field: str = "content"  # payload field (after mapping) containing the text
+    role: Literal["intent", "reasoning"] = "intent"  # which slot this fills
+
+
+class MotivationConfig(StrictModel):
+    """Declarative motivation tracking configuration for a framework."""
+
+    sources: list[MotivationSource] = Field(default_factory=list)
+    targets: list[str] = Field(default_factory=lambda: ["tool.call.started", "tool.call.completed"])
+    source_window: int = Field(default=10, ge=1)  # max source_event_ids to keep (rolling window)
+
+
+class FrameworkMapping(StrictModel):
+    """Declarative mapping config for a framework's JSON events."""
+
+    framework: str  # e.g. "crewai", "openhands"
+    framework_version: str  # version of the framework's event format this mapping targets
+    ingestion_mode: IngestionMode  # must be explicit in YAML
+    type_field: str = "type"  # dot-path to event type in raw JSON
+    timestamp_field: str | None = None  # dot-path to timestamp
+    default_kind: str = EventKind.RAW  # kind for unmapped event types
+    preprocessor: str | None = None  # registered preprocessor name (optional)
+    events: dict[str, EventMapping] = Field(default_factory=dict)  # raw_type → mapping
+    spans: dict[str, SpanMapping] = Field(default_factory=dict)  # otel_span_name → mapping
+
+    # Motivation tracking config
+    motivation: MotivationConfig | None = None
+
+    def get_motivation_config(self) -> MotivationConfig:
+        """Return the effective MotivationConfig."""
+        if self.motivation is not None:
+            return self.motivation
+        return MotivationConfig()
+
+
+# ─── Adapter ─────────────────────────────────────────────────────────────────
+
+
+class MappedJsonAdapter(JsonLineAdapter):
+    """Generic adapter driven by a FrameworkMapping config.
+
+    Parses JSON lines using declarative dot-path extraction. Adding support
+    for a new framework requires only a YAML mapping file, not Python code.
+    """
+
+    def __init__(self, mapping: FrameworkMapping, session_id: str):
+        self._mapping = mapping
+        self._session_id = session_id
+        self._motivation_config = mapping.get_motivation_config()
+        # Build lookup: raw_type → list of (field, role) for quick matching
+        self._motivation_lookup: dict[str, list[tuple[str, str]]] = {}
+        for source in self._motivation_config.sources:
+            for event_type in source.events:
+                self._motivation_lookup.setdefault(event_type, []).append(
+                    (source.field, source.role)
+                )
+        self._target_kinds = frozenset(self._motivation_config.targets)
+        # Accumulated motivation state
+        self._latest_intent: str | None = None
+        self._latest_reasoning: str | None = None
+        self._source_event_ids: list[str] = []
+
+    @property
+    def framework(self) -> str:
+        return self._mapping.framework
+
+    def parse_dict(self, obj: dict[str, Any]) -> Iterator[SessionEvent]:
+        """Extract event type, timestamp, session, payload from JSON dict.
+
+        If a preprocessor is registered for this framework, the raw dict is
+        first normalized into one or more flat dicts before mapping.
+        """
+        # Apply preprocessor if configured
+        preprocessor_name = self._mapping.preprocessor
+        if preprocessor_name:
+            preprocessor = get_preprocessor(preprocessor_name)
+            if preprocessor:
+                normalized_dicts = preprocessor(obj)
+            else:
+                normalized_dicts = [obj]
+        else:
+            normalized_dicts = [obj]
+
+        for norm_obj in normalized_dicts:
+            yield from self._map_single(norm_obj)
+
+    def _map_single(self, obj: dict[str, Any]) -> Iterator[SessionEvent]:
+        """Map a single normalized dict to a SessionEvent."""
+        # Extract event type
+        raw_type = _resolve_path(obj, self._mapping.type_field)
+        if raw_type is None:
+            raw_type = "unknown"
+        raw_type = str(raw_type)
+
+        # Resolve mapping
+        event_mapping = self._mapping.events.get(raw_type)
+        kind = event_mapping.kind if event_mapping else self._mapping.default_kind
+        if event_mapping is None and not kind:
+            return
+
+        # Extract timestamp
+        timestamp = datetime.now(timezone.utc)
+        if self._mapping.timestamp_field:
+            ts_raw = _resolve_path(obj, self._mapping.timestamp_field)
+            if ts_raw is not None:
+                timestamp = self._parse_timestamp(ts_raw)
+
+        # Extract payload
+        payload: dict[str, Any] = {}
+        if event_mapping and event_mapping.payload:
+            for field_name, dot_path in event_mapping.payload.items():
+                if dot_path.startswith("literal:"):
+                    # Explicit literal value (not a path resolution)
+                    value = dot_path[len("literal:") :]
+                else:
+                    value = _resolve_path(obj, dot_path)
+                if value is not None:
+                    payload[field_name] = value
+
+        # For unmapped or RAW events, note the original type
+        if kind == EventKind.RAW or not event_mapping:
+            payload["original_type"] = raw_type
+
+        # Generate event ID upfront (needed for source_event_ids tracking)
+        event_id = str(uuid.uuid4())
+
+        # Track motivation from designated source events
+        if raw_type in self._motivation_lookup:
+            seen_this_event = False
+            for field, role in self._motivation_lookup[raw_type]:
+                text = self._extract_text(payload, field)
+                if role == "intent":
+                    self._latest_intent = text
+                else:
+                    self._latest_reasoning = text
+                # Record source event ID once per raw event (not per role)
+                if not seen_this_event:
+                    self._source_event_ids.append(event_id)
+                    seen_this_event = True
+            # Enforce rolling window
+            if len(self._source_event_ids) > self._motivation_config.source_window:
+                self._source_event_ids = self._source_event_ids[
+                    -self._motivation_config.source_window :
+                ]
+
+        # Build motivation for target events (None if no content in either slot)
+        motivation: ToolMotivation | None = None
+        if kind in self._target_kinds and (self._latest_intent or self._latest_reasoning):
+            motivation = ToolMotivation(
+                intent=self._latest_intent,
+                reasoning=self._latest_reasoning,
+                source_event_ids=tuple(self._source_event_ids),
+            )
+
+        metadata = EventMetadata(
+            source_framework=self._mapping.framework,
+            ingestion_mode=self._mapping.ingestion_mode,
+            raw_kind=raw_type,
+            motivation=motivation,
+        )
+
+        yield SessionEvent(
+            id=event_id,
+            kind=kind,
+            session_id=self._session_id,
+            timestamp=timestamp,
+            payload=payload,
+            metadata=metadata,
+        )
+
+    @staticmethod
+    def _extract_text(payload: dict[str, Any], field: str) -> str | None:
+        """Extract text from a payload field, handling list-type content."""
+        value = payload.get(field)
+        if value is None:
+            return None
+        # List-type content (e.g. Claude content blocks): join text items
+        if isinstance(value, list):
+            text_parts = [str(item) for item in value if item]
+            value = "\n".join(text_parts)
+        else:
+            value = str(value)
+        # Empty string → treat as None
+        if not value.strip():
+            return None
+        return value
+
+    @staticmethod
+    def _parse_timestamp(value: Any) -> datetime:
+        """Best-effort timestamp parsing."""
+        if isinstance(value, datetime):
+            return value
+        if isinstance(value, (int, float)):
+            try:
+                # Heuristic: >1e15 = nanoseconds, >1e12 = milliseconds
+                if value > 1e15:
+                    value = value / 1_000_000_000
+                elif value > 1e12:
+                    value = value / 1_000
+                return datetime.fromtimestamp(value, tz=timezone.utc)
+            except (OSError, OverflowError, ValueError):
+                return datetime.now(timezone.utc)
+        if isinstance(value, str):
+            # Try ISO format
+            try:
+                dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+                if dt.tzinfo is None:
+                    dt = dt.replace(tzinfo=timezone.utc)
+                return dt
+            except ValueError:
+                pass
+        return datetime.now(timezone.utc)
+
+    @classmethod
+    def from_yaml(cls, yaml_path: str, session_id: str) -> "MappedJsonAdapter":
+        """Load a MappedJsonAdapter from a YAML mapping file."""
+        import yaml
+
+        with open(yaml_path) as f:
+            data = yaml.safe_load(f)
+        mapping = FrameworkMapping.model_validate(data)
+        return cls(mapping=mapping, session_id=session_id)

traceforge/adapters/otel.py

@@ -0,0 +1,220 @@
+"""Adapter for Microsoft 365 Agents SDK (MAF) OTel spans.
+
+The Microsoft 365 Agents SDK emits OpenTelemetry spans, not JSON lines.
+This adapter ingests exported OTLP span data (as JSON dicts) and maps
+MAF span names to canonical traceforge event kinds.
+
+Span-to-kind mapping and attribute extraction rules are loaded from
+``mappings/maf.yaml`` — no hardcoded dispatch tables.
+
+Ingestion mode is always "stream" — spans are received from an OTel
+exporter (e.g., InMemorySpanExporter or OTLP collector).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from traceforge.adapters.base import Adapter
+from traceforge.types import EventKind, EventMetadata, IngestionMode, SessionEvent
+
+logger = logging.getLogger(__name__)
+
+# ─── Load span mapping from YAML ─────────────────────────────────────────────
+
+_MAPPINGS_DIR = Path(__file__).resolve().parent.parent / "mappings"
+
+
+def _load_maf_mapping() -> tuple[dict[str, str], dict[str, dict[str, str]]]:
+    """Load span kind map and attribute extractors from maf.yaml."""
+    yaml_path = _MAPPINGS_DIR / "maf.yaml"
+    with open(yaml_path) as f:
+        data = yaml.safe_load(f)
+
+    span_kind_map: dict[str, str] = {}
+    attribute_extractors: dict[str, dict[str, str]] = {}
+
+    for span_name, config in data.get("spans", {}).items():
+        span_kind_map[span_name] = config["kind"]
+        attrs = config.get("attributes")
+        if attrs:
+            attribute_extractors[span_name] = attrs
+
+    return span_kind_map, attribute_extractors
+
+
+_SPAN_KIND_MAP, _ATTRIBUTE_EXTRACTORS = _load_maf_mapping()
+
+# OTel status codes
+_STATUS_OK = 1
+_STATUS_ERROR = 2
+
+
+class OtelSpanAdapter(Adapter):
+    """Ingests OTel span dicts (exported from MAF) into canonical SessionEvents.
+
+    Accepts spans as dicts with standard OTel JSON export fields:
+    - name: span name
+    - start_time_unix_nano / end_time_unix_nano: timestamps
+    - status: {status_code: int}
+    - attributes: [{key, value}] or dict
+    - resource: {attributes: ...}
+
+    Works with both OTLP JSON export format and simplified dict format.
+    """
+
+    SOURCE_FRAMEWORK = "maf"
+
+    def __init__(self, ingestion_mode: IngestionMode, session_id: str) -> None:
+        self._session_id = session_id
+        self._ingestion_mode = ingestion_mode
+
+    def parse_span(self, span: dict[str, Any]) -> Iterator[SessionEvent]:
+        """Convert a single OTel span dict to SessionEvent(s).
+
+        Handles both snake_case (simplified) and camelCase (OTLP JSON) keys.
+        Never raises — logs and skips malformed spans.
+        """
+        try:
+            yield from self._parse_span_inner(span)
+        except Exception as exc:
+            logger.debug("OtelSpanAdapter: skipping malformed span: %s", exc)
+
+    def _parse_span_inner(self, span: dict[str, Any]) -> Iterator[SessionEvent]:
+        span_name = span.get("name", "")
+        if not span_name:
+            return
+
+        kind = _SPAN_KIND_MAP.get(span_name, EventKind.RAW)
+        attributes = _normalize_attributes(span.get("attributes", {}))
+        status = span.get("status", {})
+        status_code = (
+            status.get("status_code", _STATUS_OK) if isinstance(status, dict) else _STATUS_OK
+        )
+
+        # Timestamps — support both snake_case and camelCase keys, coerce strings
+        start_ns = (
+            span.get("start_time_unix_nano")
+            or span.get("startTimeUnixNano")
+            or span.get("start_time")
+        )
+        end_ns = (
+            span.get("end_time_unix_nano") or span.get("endTimeUnixNano") or span.get("end_time")
+        )
+        if start_ns is not None:
+            start_ns = int(start_ns)
+        if end_ns is not None:
+            end_ns = int(end_ns)
+
+        start_time = _ns_to_datetime(start_ns) if start_ns else datetime.now(timezone.utc)
+        end_time = _ns_to_datetime(end_ns) if end_ns else start_time
+
+        duration_ms: float | None = None
+        if start_ns and end_ns:
+            duration_ms = max(0.0, (end_ns - start_ns) / 1_000_000)
+
+        # Determine if this is an error
+        is_error = status_code == _STATUS_ERROR
+        if is_error:
+            kind = EventKind.ERROR
+
+        # Build payload from span attributes
+        payload = self._build_payload(span_name, attributes, duration_ms, is_error, status)
+
+        metadata = EventMetadata(
+            source_framework=self.SOURCE_FRAMEWORK,
+            ingestion_mode=self._ingestion_mode,
+            raw_kind=span_name,
+            duration_ms=duration_ms,
+        )
+
+        yield SessionEvent(
+            kind=kind,
+            session_id=self._session_id,
+            timestamp=end_time,
+            payload=payload,
+            metadata=metadata,
+            raw_event=span,
+        )
+
+    def parse(self, raw: str) -> Iterator[SessionEvent]:
+        """Parse a JSON string containing an OTel span."""
+        import json
+
+        try:
+            span = json.loads(raw)
+        except (json.JSONDecodeError, TypeError) as exc:
+            logger.debug("OtelSpanAdapter: JSON parse failed: %s", exc)
+            return
+
+        if isinstance(span, dict):
+            yield from self.parse_span(span)
+        elif isinstance(span, list):
+            for item in span:
+                if isinstance(item, dict):
+                    yield from self.parse_span(item)
+
+    def _build_payload(
+        self,
+        span_name: str,
+        attributes: dict[str, Any],
+        duration_ms: float | None,
+        is_error: bool,
+        status: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Build event payload from OTel span attributes."""
+        payload: dict[str, Any] = {}
+
+        # Extract known MAF attributes
+        attr_map = _ATTRIBUTE_EXTRACTORS.get(span_name)
+        if attr_map:
+            for payload_key, attr_key in attr_map.items():
+                val = attributes.get(attr_key)
+                if val is not None:
+                    payload[payload_key] = val
+
+        if is_error:
+            payload["message"] = status.get("message", "Unknown error")
+
+        if duration_ms is not None:
+            payload["duration_ms"] = duration_ms
+
+        # For unmapped spans, always include the span name
+        if span_name not in _SPAN_KIND_MAP:
+            payload["original_type"] = span_name
+
+        return payload
+
+
+# ─── Helpers ─────────────────────────────────────────────────────────────────
+
+
+def _ns_to_datetime(ns: int | float) -> datetime:
+    """Convert nanosecond unix timestamp to datetime."""
+    return datetime.fromtimestamp(ns / 1_000_000_000, tz=timezone.utc)
+
+
+def _normalize_attributes(attrs: Any) -> dict[str, Any]:
+    """Normalize OTel attributes from either list-of-dicts or flat dict format."""
+    if isinstance(attrs, dict):
+        return attrs
+    if isinstance(attrs, list):
+        result: dict[str, Any] = {}
+        for item in attrs:
+            if isinstance(item, dict) and "key" in item:
+                val = item.get("value", {})
+                if isinstance(val, dict):
+                    # OTel proto format: value is {stringValue: x} or {intValue: x}
+                    for v in val.values():
+                        result[item["key"]] = v
+                        break
+                else:
+                    result[item["key"]] = val
+        return result
+    return {}

traceforge/boundary/__init__.py

@@ -0,0 +1,46 @@
+"""Per-gap activity/step boundary classifier (production-loadable).
+
+Mirrors :mod:`traceforge.phase` but for the *segmentation* task: each gap between
+two consecutive events is labelled ``noise`` / ``activity-boundary`` /
+``step-boundary``. The featuriser is shared with the phase classifier
+(``traceforge.phase.features``) so there is no train/serve skew, and every
+feature is **causal** — a gap after event ``t`` is decided once ``t+1`` has
+arrived, using only trailing-window segmentation state.
+"""
+
+from __future__ import annotations
+
+from .decode import DecodeParams, StreamingBoundaryDecoder, decode_scores
+from .features import GapExample, build_gap_example, featurize_session_gaps
+from .inference import (
+    BOUNDARY_CLASSES,
+    DEFAULT_FEATURE_SET,
+    BoundaryModel,
+    decode_examples,
+    fit_boundary_model,
+    load,
+    predict_examples,
+    predict_session,
+    save,
+)
+from .inferencer import BoundaryInferencer, SessionBoundaryStream
+
+__all__ = [
+    "BOUNDARY_CLASSES",
+    "DEFAULT_FEATURE_SET",
+    "BoundaryInferencer",
+    "BoundaryModel",
+    "DecodeParams",
+    "GapExample",
+    "SessionBoundaryStream",
+    "StreamingBoundaryDecoder",
+    "build_gap_example",
+    "decode_examples",
+    "decode_scores",
+    "featurize_session_gaps",
+    "fit_boundary_model",
+    "load",
+    "predict_examples",
+    "predict_session",
+    "save",
+]

traceforge/boundary/decode.py

@@ -0,0 +1,87 @@
+"""Causal, streamable decoding of per-gap boundary scores into a session TOC.
+
+The classifier (:mod:`traceforge.boundary.inference`) emits per-gap class scores.
+Taking ``argmax`` over them floods false positives (boundaries are 1-4% of gaps,
+and the balanced estimator over-predicts the minority classes) and clusters
+several predictions around each true boundary. This module turns scores into
+labels with two data-derived levers, both applied **causally** so the same code
+runs live as events stream:
+
+* per-class **threshold** ``t_c`` (learned as the F1-optimal point of the
+  precision-recall curve at persist time) instead of ``argmax``; and
+* a per-class **refractory min-gap** ``g_c`` (learned from the gold spacing
+  distribution) that suppresses a fresh boundary of class ``c`` within ``g_c``
+  events of the previously emitted one — the streamable analogue of non-max
+  suppression.
+
+The decoder is O(1) per gap and holds only one integer per class (the index of
+the last emitted boundary), so it adds no measurable CPU/memory footprint over
+the existing per-gap inference.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+#: Coarser-first priority: at a gap that clears multiple thresholds, the coarser
+#: class claims it (and its refractory decides emit-vs-noise).
+DEFAULT_PRIORITY: tuple[str, ...] = ("activity-boundary", "step-boundary")
+
+
+@dataclass
+class DecodeParams:
+    """Learned decode levers, persisted in the model bundle.
+
+    ``thresholds`` and ``min_gaps`` are keyed by non-``noise`` class. A class
+    absent from ``thresholds`` falls back to never firing on threshold; a class
+    absent from ``min_gaps`` uses a refractory of 1 (no suppression).
+    """
+
+    thresholds: dict[str, float] = field(default_factory=dict)
+    min_gaps: dict[str, int] = field(default_factory=dict)
+    priority: tuple[str, ...] = DEFAULT_PRIORITY
+
+
+class StreamingBoundaryDecoder:
+    """Stateful causal decoder. Feed per-gap scores in seq order via :meth:`push`.
+
+    Holds only ``i`` (the current gap index) and the last-emitted index per
+    class, so it is safe to run indefinitely on a live event stream.
+    """
+
+    def __init__(self, params: DecodeParams) -> None:
+        self._p = params
+        self._i = -1
+        self._last: dict[str, int] = {c: -(10**9) for c in params.priority}
+
+    def push(self, scores: dict[str, float]) -> str:
+        """Return the decoded label for the next gap given its class scores."""
+        self._i += 1
+        for c in self._p.priority:
+            t = self._p.thresholds.get(c)
+            if t is None or scores.get(c, 0.0) < t:
+                continue
+            # This class claims the gap; the refractory decides emit vs. noise so
+            # a suppressed coarser boundary is never relabelled as a finer one.
+            if self._i - self._last[c] >= self._p.min_gaps.get(c, 1):
+                self._last[c] = self._i
+                return c
+            return "noise"
+        return "noise"
+
+
+def decode_scores(params: DecodeParams, classes: tuple[str, ...], scores: np.ndarray) -> list[str]:
+    """Decode a session's per-gap score matrix (``n_gaps x n_classes``, aligned
+    to ``classes``) into labels, causally and in order."""
+    dec = StreamingBoundaryDecoder(params)
+    idx = {c: i for i, c in enumerate(classes)}
+    cols = {c: idx[c] for c in params.priority if c in idx}
+    out: list[str] = []
+    for row in scores:
+        out.append(dec.push({c: float(row[j]) for c, j in cols.items()}))
+    return out
+
+
+__all__ = ["DEFAULT_PRIORITY", "DecodeParams", "StreamingBoundaryDecoder", "decode_scores"]