varly 1.0.0__py3-none-any.whl

varly/adapters/__init__.py

@@ -0,0 +1,31 @@
+"""External-format adapters that translate telemetry into AIR traces."""
+
+from varly.adapters.capture.adapter import adapt_file as adapt_capture_file
+from varly.adapters.capture.adapter import adapt_payload as adapt_capture_payload
+from varly.adapters.errors import (
+    AdapterError,
+    AdapterValidationError,
+    UnsupportedFormatError,
+)
+from varly.adapters.json.adapter import adapt_file as adapt_json_file
+from varly.adapters.json.adapter import adapt_payload as adapt_json_payload
+from varly.adapters.langgraph.adapter import adapt_file as adapt_langgraph_file
+from varly.adapters.langgraph.adapter import (
+    adapt_payload as adapt_langgraph_payload,
+)
+from varly.adapters.openai.adapter import adapt_file as adapt_openai_file
+from varly.adapters.openai.adapter import adapt_payload as adapt_openai_payload
+
+__all__ = [
+    "AdapterError",
+    "AdapterValidationError",
+    "UnsupportedFormatError",
+    "adapt_capture_file",
+    "adapt_capture_payload",
+    "adapt_json_file",
+    "adapt_json_payload",
+    "adapt_langgraph_file",
+    "adapt_langgraph_payload",
+    "adapt_openai_file",
+    "adapt_openai_payload",
+]

varly/adapters/_mapping.py

@@ -0,0 +1,50 @@
+"""Shared event-type normalization for reference adapters."""
+
+from __future__ import annotations
+
+from varly.core.types import ControlEdgeKind, SemanticNodeType
+
+_EVENT_ALIASES: dict[str, str] = {
+    "run_start": "run_start",
+    "chain_start": "run_start",
+    "on_chain_start": "run_start",
+    "llm_invoke": "llm_invoke",
+    "llm_call": "llm_invoke",
+    "on_chat_model_start": "llm_invoke",
+    "on_chat_model_end": "llm_invoke",
+    "on_llm_start": "llm_invoke",
+    "on_llm_end": "llm_invoke",
+    "tool_call": "tool_call",
+    "on_tool_start": "tool_call",
+    "function_call": "tool_call",
+    "tool_return": "tool_return",
+    "tool_output": "tool_return",
+    "on_tool_end": "tool_return",
+    "function_call_output": "tool_return",
+    "run_end": "run_end",
+    "chain_end": "run_end",
+    "on_chain_end": "run_end",
+}
+
+
+def normalize_event_type(raw_type: str) -> str:
+    """Map a framework-specific event name to the AIR domain event_type."""
+    normalized = _EVENT_ALIASES.get(raw_type)
+    if normalized is None:
+        msg = f"Unsupported event type: {raw_type!r}"
+        raise ValueError(msg)
+    return normalized
+
+
+def semantic_type_for(event_type: str) -> str:
+    if event_type in {"tool_call", "tool_return"}:
+        return SemanticNodeType.RESOURCE
+    return SemanticNodeType.SEMANTIC
+
+
+def control_kind_for(source_event: str, target_event: str) -> ControlEdgeKind:
+    if target_event == "tool_call":
+        return ControlEdgeKind.INVOKES
+    if source_event == "tool_call" and target_event == "tool_return":
+        return ControlEdgeKind.PRODUCES
+    return ControlEdgeKind.CAUSES

varly/adapters/_payload.py

@@ -0,0 +1,30 @@
+"""Helpers to assemble canonical AIR JSON payloads from adapter inputs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from varly.core.types import AIR_SCHEMA_VERSION
+
+AirNode = dict[str, Any]
+AirEdge = dict[str, Any]
+AirRead = dict[str, str]
+
+
+def build_air_payload(
+    *,
+    trace_id: str,
+    root_id: str,
+    nodes: list[AirNode],
+    control_edges: list[AirEdge],
+    referential_edges: list[AirRead] | None = None,
+) -> dict[str, Any]:
+    """Build an AIR 1.0.0 payload ready for the parser."""
+    return {
+        "air_schema_version": AIR_SCHEMA_VERSION,
+        "trace_id": trace_id,
+        "root_id": root_id,
+        "nodes": nodes,
+        "control_edges": control_edges,
+        "referential_edges": referential_edges or [],
+    }

varly/adapters/_sequential.py

@@ -0,0 +1,129 @@
+"""Build AIR traces from ordered external event lists."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from varly.adapters._mapping import (
+    control_kind_for,
+    normalize_event_type,
+    semantic_type_for,
+)
+from varly.adapters._payload import build_air_payload
+from varly.adapters.errors import AdapterValidationError
+from varly.core.trace import Trace
+from varly.parser import build_trace
+
+ExternalEvent = Mapping[str, Any]
+ExternalRead = Mapping[str, str]
+
+
+def adapt_sequential_events(
+    *,
+    trace_id: str,
+    events: list[ExternalEvent],
+    reads: Sequence[ExternalRead] | None = None,
+    type_field: str,
+    tokens_field: str = "tokens",
+) -> Trace:
+    """Translate a linear external event log into a validated AIR trace."""
+    if not events:
+        msg = "Event log must contain at least one event"
+        raise AdapterValidationError(msg)
+
+    nodes: list[dict[str, Any]] = []
+    normalized_types: list[str] = []
+
+    for index, event in enumerate(events):
+        event_id = event.get("id")
+        raw_type = event.get(type_field)
+        if not isinstance(event_id, str) or not event_id:
+            msg = f"events[{index}].id must be a non-empty string"
+            raise AdapterValidationError(msg)
+        if not isinstance(raw_type, str) or not raw_type:
+            msg = f"events[{index}].{type_field} must be a non-empty string"
+            raise AdapterValidationError(msg)
+        try:
+            event_type = normalize_event_type(raw_type)
+        except ValueError as exc:
+            msg = f"events[{index}].{type_field}: {exc}"
+            raise AdapterValidationError(msg) from exc
+
+        labels: dict[str, Any] = {
+            "semantic_type": semantic_type_for(event_type),
+            "event_type": event_type,
+        }
+        timestamp_ms = event.get("timestamp_ms")
+        if isinstance(timestamp_ms, (int, float)) and not isinstance(
+            timestamp_ms, bool
+        ):
+            labels["timestamp_ms"] = timestamp_ms
+
+        name = event.get("name")
+        if isinstance(name, str) and name:
+            labels["name"] = name
+
+        tokens = _extract_tokens(event, tokens_field)
+        if tokens is not None and event_type == "llm_invoke":
+            labels["tokens"] = tokens
+
+        nodes.append({"id": event_id, "labels": labels})
+        normalized_types.append(event_type)
+
+    if normalized_types[0] != "run_start":
+        msg = "First event must represent run_start"
+        raise AdapterValidationError(msg)
+
+    root_id = str(events[0]["id"])
+    control_edges: list[dict[str, Any]] = []
+    for index in range(len(events) - 1):
+        source_id = str(events[index]["id"])
+        target_id = str(events[index + 1]["id"])
+        source_type = normalized_types[index]
+        target_type = normalized_types[index + 1]
+        control_edges.append(
+            {
+                "id": f"ec-{index:04d}",
+                "source": source_id,
+                "target": target_id,
+                "kind": control_kind_for(source_type, target_type),
+            }
+        )
+
+    referential_edges: list[dict[str, str]] = []
+    for read_index, read in enumerate(reads or ()):
+        source = read.get("source")
+        target = read.get("target")
+        if not isinstance(source, str) or not isinstance(target, str):
+            msg = f"reads[{read_index}] requires string source and target"
+            raise AdapterValidationError(msg)
+        referential_edges.append(
+            {
+                "id": f"er-{read_index:04d}",
+                "source": source,
+                "target": target,
+                "kind": "reads",
+            }
+        )
+
+    payload = build_air_payload(
+        trace_id=trace_id,
+        root_id=root_id,
+        nodes=nodes,
+        control_edges=control_edges,
+        referential_edges=referential_edges,
+    )
+    return build_trace(payload)
+
+
+def _extract_tokens(event: ExternalEvent, tokens_field: str) -> int | float | None:
+    direct = event.get(tokens_field)
+    if isinstance(direct, (int, float)) and not isinstance(direct, bool):
+        return direct
+    usage = event.get("usage")
+    if isinstance(usage, Mapping):
+        total = usage.get("total_tokens")
+        if isinstance(total, (int, float)) and not isinstance(total, bool):
+            return total
+    return None

varly/adapters/_source_hints.py

@@ -0,0 +1,41 @@
+"""Detect likely trace source from a JSON payload (onboarding hints)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Literal
+
+from varly.adapters.langgraph.normalize import (
+    is_langgraph_callbacks,
+    is_langgraph_run_v1,
+)
+from varly.adapters.openai.normalize import is_openai_responses, is_openai_run_v1
+from varly.capture.model import CAPTURE_EVENT_LOG_VERSION
+
+TraceSource = Literal["air", "capture", "langgraph", "openai"]
+
+
+def detect_trace_source(payload: Mapping[str, Any]) -> TraceSource | None:
+    """Return the most likely adapter source for a JSON object, if recognizable."""
+    if payload.get("format_version") == CAPTURE_EVENT_LOG_VERSION:
+        return "capture"
+    if is_openai_responses(payload) or is_openai_run_v1(payload):
+        return "openai"
+    if is_langgraph_callbacks(payload) or is_langgraph_run_v1(payload):
+        return "langgraph"
+    if "air_schema_version" in payload and "nodes" in payload:
+        return "air"
+    return None
+
+
+def wrong_source_message(
+    path: str,
+    *,
+    used: TraceSource,
+    detected: TraceSource,
+) -> str:
+    """Human-readable hint when --source does not match the file shape."""
+    return (
+        f"File {path!r} looks like a {detected} trace, but --source {used!r} was used. "
+        f"Try: varly verify {path} --source {detected} --contract <policy.yaml>"
+    )

varly/adapters/capture/__init__.py

@@ -0,0 +1 @@
+"""Capture event log adapter package."""

varly/adapters/capture/adapter.py

@@ -0,0 +1,66 @@
+"""Capture event log adapter."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from varly.adapters._sequential import adapt_sequential_events
+from varly.adapters.errors import AdapterValidationError, UnsupportedFormatError
+from varly.adapters.json.adapter import load_external_json
+from varly.capture import CAPTURE_EVENT_LOG_VERSION
+from varly.core.trace import Trace
+
+
+def adapt_file(path: Path) -> Trace:
+    """Translate a capture event log file into an AIR trace."""
+    payload = load_external_json(path)
+    return adapt_payload(payload)
+
+
+def adapt_payload(payload: Mapping[str, Any]) -> Trace:
+    """Translate a capture event log payload into an AIR trace."""
+    version = payload.get("format_version")
+    if version != CAPTURE_EVENT_LOG_VERSION:
+        msg = (
+            f"Unsupported capture format_version: {version!r} "
+            f"(expected {CAPTURE_EVENT_LOG_VERSION!r})"
+        )
+        raise UnsupportedFormatError(msg)
+
+    run_id = payload.get("run_id")
+    steps = payload.get("steps")
+    if not isinstance(run_id, str) or not run_id:
+        msg = "Capture payload requires non-empty string run_id"
+        raise AdapterValidationError(msg)
+    if not isinstance(steps, list) or not steps:
+        msg = "Capture payload requires non-empty steps list"
+        raise AdapterValidationError(msg)
+
+    reads_raw = payload.get("reads", [])
+    if reads_raw is None:
+        reads_raw = []
+    if not isinstance(reads_raw, list):
+        msg = "Capture payload field reads must be a list when provided"
+        raise AdapterValidationError(msg)
+
+    reads: list[dict[str, str]] = []
+    for index, item in enumerate(reads_raw):
+        if not isinstance(item, dict):
+            msg = f"reads[{index}] must be an object"
+            raise AdapterValidationError(msg)
+        source = item.get("source")
+        target = item.get("target")
+        if not isinstance(source, str) or not isinstance(target, str):
+            msg = f"reads[{index}] requires string source and target"
+            raise AdapterValidationError(msg)
+        reads.append({"source": source, "target": target})
+
+    return adapt_sequential_events(
+        trace_id=run_id,
+        events=steps,
+        reads=reads,
+        type_field="event_type",
+        tokens_field="total_tokens",
+    )

varly/adapters/errors.py

@@ -0,0 +1,17 @@
+"""Adapter translation errors."""
+
+from __future__ import annotations
+
+from varly.core.errors import VarlyError
+
+
+class AdapterError(VarlyError):
+    """Base error for adapter translation failures."""
+
+
+class UnsupportedFormatError(AdapterError):
+    """Raised when an external payload format is not recognized."""
+
+
+class AdapterValidationError(AdapterError):
+    """Raised when an external payload is missing required fields."""

varly/adapters/json/adapter.py

@@ -0,0 +1,25 @@
+"""Static JSON adapter for canonical AIR trace files."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from varly.core.trace import Trace
+from varly.parser import load_json_object, parse_trace_file, parse_trace_payload
+
+
+def adapt_file(path: Path) -> Trace:
+    """Load a canonical AIR JSON trace file."""
+    return parse_trace_file(path)
+
+
+def adapt_payload(payload: Mapping[str, Any]) -> Trace:
+    """Build a trace from an in-memory canonical AIR payload."""
+    return parse_trace_payload(payload)
+
+
+def load_external_json(path: Path) -> dict[str, Any]:
+    """Load a JSON object from disk without assuming AIR schema."""
+    return load_json_object(path)

varly/adapters/langgraph/adapter.py

@@ -0,0 +1,73 @@
+"""LangGraph reference adapter."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from varly.adapters._sequential import adapt_sequential_events
+from varly.adapters.errors import AdapterValidationError, UnsupportedFormatError
+from varly.adapters.json.adapter import load_external_json
+from varly.adapters.langgraph.normalize import (
+    LANGGRAPH_RUN_V1,
+    is_langgraph_callbacks,
+    is_langgraph_run_v1,
+    normalize_callbacks_payload,
+)
+from varly.core.trace import Trace
+
+
+def adapt_file(path: Path) -> Trace:
+    """Translate a LangGraph run export file into an AIR trace."""
+    payload = load_external_json(path)
+    return adapt_payload(payload)
+
+
+def adapt_payload(payload: Mapping[str, Any]) -> Trace:
+    """Translate a LangGraph run export payload into an AIR trace."""
+    if is_langgraph_callbacks(payload):
+        payload = normalize_callbacks_payload(payload)
+    elif not is_langgraph_run_v1(payload):
+        version = payload.get("format_version")
+        msg = (
+            "Unsupported LangGraph payload: expected format_version "
+            f"{LANGGRAPH_RUN_V1!r} or callback events "
+            f"(got format_version={version!r})"
+        )
+        raise UnsupportedFormatError(msg)
+
+    run_id = payload.get("run_id")
+    events = payload.get("events")
+    if not isinstance(run_id, str) or not run_id:
+        msg = "LangGraph payload requires non-empty string run_id"
+        raise AdapterValidationError(msg)
+    if not isinstance(events, list) or not events:
+        msg = "LangGraph payload requires non-empty events list"
+        raise AdapterValidationError(msg)
+
+    reads_raw = payload.get("reads", [])
+    if reads_raw is None:
+        reads_raw = []
+    if not isinstance(reads_raw, list):
+        msg = "LangGraph payload field reads must be a list when provided"
+        raise AdapterValidationError(msg)
+
+    reads: list[dict[str, str]] = []
+    for index, item in enumerate(reads_raw):
+        if not isinstance(item, dict):
+            msg = f"reads[{index}] must be an object"
+            raise AdapterValidationError(msg)
+        source = item.get("source")
+        target = item.get("target")
+        if not isinstance(source, str) or not isinstance(target, str):
+            msg = f"reads[{index}] requires string source and target"
+            raise AdapterValidationError(msg)
+        reads.append({"source": source, "target": target})
+
+    return adapt_sequential_events(
+        trace_id=run_id,
+        events=events,
+        reads=reads,
+        type_field="type",
+    )

varly/adapters/langgraph/normalize.py

@@ -0,0 +1,194 @@
+"""Normalize recorded LangGraph callback dumps into langgraph.run.v1."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from varly.adapters.errors import AdapterValidationError
+
+LANGGRAPH_RUN_V1 = "langgraph.run.v1"
+
+
+def is_langgraph_run_v1(payload: Mapping[str, Any]) -> bool:
+    return payload.get("format_version") == LANGGRAPH_RUN_V1
+
+
+def is_langgraph_callbacks(payload: Mapping[str, Any]) -> bool:
+    if payload.get("object") == "langgraph.callback_events":
+        return isinstance(payload.get("events"), list)
+    events = payload.get("events")
+    if not isinstance(events, list) or not events:
+        return False
+    first = events[0]
+    return isinstance(first, dict) and "event" in first and "type" not in first
+
+
+def normalize_callbacks_payload(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """Translate LangChain/LangGraph callback events into langgraph.run.v1."""
+    events_raw = payload.get("events")
+    if not isinstance(events_raw, list) or not events_raw:
+        msg = "LangGraph callback payload requires a non-empty events list"
+        raise AdapterValidationError(msg)
+
+    run_id = payload.get("run_id")
+    if not isinstance(run_id, str) or not run_id:
+        run_id = _root_run_id(events_raw)
+    if not isinstance(run_id, str) or not run_id:
+        msg = "LangGraph callback payload requires a run_id"
+        raise AdapterValidationError(msg)
+
+    events: list[dict[str, Any]] = []
+    llm_index: dict[str, int] = {}
+    timestamp_ms = 0
+    last_llm_id: str | None = None
+    reads: list[dict[str, str]] = []
+
+    for index, item in enumerate(events_raw):
+        if not isinstance(item, dict):
+            msg = f"events[{index}] must be an object"
+            raise AdapterValidationError(msg)
+        event_name = item.get("event")
+        if not isinstance(event_name, str) or not event_name:
+            msg = f"events[{index}].event must be a non-empty string"
+            raise AdapterValidationError(msg)
+
+        item_run_id = item.get("run_id")
+        if not isinstance(item_run_id, str) or not item_run_id:
+            item_run_id = f"{run_id}:event-{index}"
+
+        if event_name == "on_chain_start" and _is_root(item):
+            events.append(
+                {
+                    "id": f"{run_id}:start",
+                    "type": "chain_start",
+                    "timestamp_ms": timestamp_ms,
+                }
+            )
+            timestamp_ms += 100
+        elif event_name in {"on_chat_model_start", "on_llm_start"}:
+            last_llm_id = item_run_id
+            events.append(
+                {
+                    "id": item_run_id,
+                    "type": "on_chat_model_start",
+                    "timestamp_ms": timestamp_ms,
+                }
+            )
+            llm_index[item_run_id] = len(events) - 1
+            timestamp_ms += 100
+        elif event_name in {"on_chat_model_end", "on_llm_end"}:
+            tokens = _tokens_from_callback(item)
+            existing = llm_index.get(item_run_id)
+            if existing is not None:
+                if tokens is not None:
+                    events[existing]["tokens"] = tokens
+            else:
+                last_llm_id = item_run_id
+                event: dict[str, Any] = {
+                    "id": item_run_id,
+                    "type": "on_chat_model_start",
+                    "timestamp_ms": timestamp_ms,
+                }
+                if tokens is not None:
+                    event["tokens"] = tokens
+                events.append(event)
+                timestamp_ms += 100
+        elif event_name == "on_tool_start":
+            name = _callback_name(item, index, "on_tool_start")
+            events.append(
+                {
+                    "id": item_run_id,
+                    "type": "on_tool_start",
+                    "name": name,
+                    "timestamp_ms": timestamp_ms,
+                }
+            )
+            if last_llm_id is not None:
+                reads.append({"source": item_run_id, "target": last_llm_id})
+            timestamp_ms += 300
+        elif event_name == "on_tool_end":
+            name = _callback_name(item, index, "on_tool_end")
+            events.append(
+                {
+                    "id": f"{item_run_id}:end",
+                    "type": "on_tool_end",
+                    "name": name,
+                    "timestamp_ms": timestamp_ms,
+                }
+            )
+            timestamp_ms += 100
+        elif event_name == "on_chain_end" and _is_root(item):
+            events.append(
+                {
+                    "id": f"{run_id}:end",
+                    "type": "chain_end",
+                    "timestamp_ms": timestamp_ms,
+                }
+            )
+        elif event_name in {"on_chain_start", "on_chain_end"}:
+            continue
+        else:
+            msg = f"events[{index}] has unsupported event: {event_name!r}"
+            raise AdapterValidationError(msg)
+
+    if not events:
+        msg = "LangGraph callback payload produced no mapped events"
+        raise AdapterValidationError(msg)
+
+    return {
+        "format_version": LANGGRAPH_RUN_V1,
+        "run_id": run_id,
+        "events": events,
+        "reads": reads,
+    }
+
+
+def _is_root(item: Mapping[str, Any]) -> bool:
+    parent_ids = item.get("parent_ids")
+    if parent_ids is None:
+        return True
+    if isinstance(parent_ids, list):
+        return len(parent_ids) == 0
+    return False
+
+
+def _root_run_id(events: list[object]) -> str | None:
+    for item in events:
+        if isinstance(item, dict) and item.get("event") == "on_chain_start":
+            if _is_root(item):
+                run_id = item.get("run_id")
+                if isinstance(run_id, str) and run_id:
+                    return run_id
+    return None
+
+
+def _callback_name(item: Mapping[str, Any], index: int, event_name: str) -> str:
+    name = item.get("name")
+    if isinstance(name, str) and name:
+        return name
+    msg = f"events[{index}] {event_name} requires a non-empty name"
+    raise AdapterValidationError(msg)
+
+
+def _tokens_from_callback(item: Mapping[str, Any]) -> int | float | None:
+    data = item.get("data")
+    if not isinstance(data, Mapping):
+        return None
+    output = data.get("output")
+    if not isinstance(output, Mapping):
+        return None
+    for usage_container in (
+        output.get("llm_output"),
+        output.get("usage"),
+        output,
+    ):
+        if not isinstance(usage_container, Mapping):
+            continue
+        usage = usage_container.get("token_usage", usage_container)
+        if not isinstance(usage, Mapping):
+            continue
+        total = usage.get("total_tokens")
+        if isinstance(total, (int, float)) and not isinstance(total, bool):
+            return total
+    return None