loopotel 0.1.0__py3-none-any.whl

loopotel/__init__.py

@@ -0,0 +1,6 @@
+"""Loop Trace Format (LTF) instrumentation for loop runs."""
+
+from loopotel.tracer import LoopTracer, current_tracer, emit_iteration, trace_loop
+
+__version__ = "0.1.0"
+__all__ = ["LoopTracer", "current_tracer", "emit_iteration", "trace_loop", "__version__"]

loopotel/cli.py

@@ -0,0 +1,40 @@
+"""CLI for LTF validation."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from loopotel.validate import validate_trace
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate LTF trace JSON or JSONL")
+    parser.add_argument("path", type=Path)
+    args = parser.parse_args(argv)
+
+    if not args.path.exists():
+        print(f"Missing: {args.path}", file=sys.stderr)
+        return 1
+
+    lines = args.path.read_text(encoding="utf-8").strip().splitlines()
+    docs = [json.loads(line) for line in lines if line.strip()] if args.path.suffix == ".jsonl" else [json.loads(args.path.read_text(encoding="utf-8"))]
+
+    failed = False
+    for index, doc in enumerate(docs, start=1):
+        valid, errors = validate_trace(doc)
+        label = str(args.path) if len(docs) == 1 else f"{args.path}#{index}"
+        if valid:
+            print(f"VALID: {label}")
+        else:
+            failed = True
+            print(f"INVALID: {label}", file=sys.stderr)
+            for err in errors:
+                print(f"  - {err}", file=sys.stderr)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

loopotel/exporter/__init__.py

@@ -0,0 +1,6 @@
+"""Trace exporters."""
+
+from loopotel.exporter.jsonl import JsonlExporter
+from loopotel.exporter.loopnet import trajectory_from_trace
+
+__all__ = ["JsonlExporter", "trajectory_from_trace"]

loopotel/exporter/jsonl.py

@@ -0,0 +1,22 @@
+"""Write LTF traces to JSONL."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+class JsonlExporter:
+    """Append LTF trace documents to a JSONL file."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+
+    def export(self, trace: dict[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(trace, separators=(",", ":")) + "\n")
+
+    def export_tracer(self, tracer: Any) -> None:
+        self.export(tracer.build_trace())

loopotel/exporter/loopnet.py

@@ -0,0 +1,35 @@
+"""Map LTF iteration spans to LoopNet trajectory steps."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def trajectory_from_trace(trace: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract ln/record-v1-compatible trajectory steps from iteration spans."""
+    steps: list[dict[str, Any]] = []
+    for span in trace.get("spans") or []:
+        if span.get("kind") != "iteration":
+            continue
+        attrs = span.get("attributes") or {}
+        iteration = int(attrs.get("loop.iteration", len(steps) + 1))
+        goal_score = float(attrs.get("loop.goal_score", 0.0))
+        steps.append(
+            {
+                "iteration": iteration,
+                "goal_score": goal_score,
+                "primary_quality": goal_score,
+                "cost_usd": attrs.get("loop.cost_usd"),
+                "latency_seconds": (
+                    float(attrs["loop.latency_ms"]) / 1000.0
+                    if attrs.get("loop.latency_ms") is not None
+                    else None
+                ),
+                "tokens": attrs.get("loop.tokens_delta"),
+                "failure_codes": [],
+                "safety_events": 0,
+                "human_intervention": False,
+            }
+        )
+    steps.sort(key=lambda s: s["iteration"])
+    return steps

loopotel/exporter/otlp.py

@@ -0,0 +1,57 @@
+"""Optional OTLP export (requires opentelemetry-sdk)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class OtlpExporter:
+    """Export LTF spans to an OTLP endpoint via OpenTelemetry SDK."""
+
+    def __init__(self, endpoint: str | None = None, service_name: str = "loop-runtime") -> None:
+        self.endpoint = endpoint
+        self.service_name = service_name
+        self._provider = None
+
+    def _ensure_provider(self) -> None:
+        if self._provider is not None:
+            return
+        try:
+            from opentelemetry import trace
+            from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+            from opentelemetry.sdk.resources import Resource
+            from opentelemetry.sdk.trace import TracerProvider
+            from opentelemetry.sdk.trace.export import BatchSpanProcessor
+        except ImportError as exc:
+            raise SystemExit(
+                "OTLP export requires: pip install loopotel[otlp]"
+            ) from exc
+
+        resource = Resource.create({"service.name": self.service_name})
+        provider = TracerProvider(resource=resource)
+        kwargs: dict[str, Any] = {}
+        if self.endpoint:
+            kwargs["endpoint"] = self.endpoint
+        exporter = OTLPSpanExporter(**kwargs)
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+        trace.set_tracer_provider(provider)
+        self._provider = provider
+
+    def export(self, trace_doc: dict[str, Any]) -> None:
+        """Best-effort map of LTF document to OTel spans."""
+        self._ensure_provider()
+        from opentelemetry import trace
+
+        otel = trace.get_tracer("loopotel")
+        root = next((s for s in trace_doc.get("spans", []) if s.get("kind") == "loop"), None)
+        if root is None:
+            return
+        with otel.start_as_current_span(root["name"]) as span:
+            for key, value in (root.get("attributes") or {}).items():
+                span.set_attribute(key, value)
+            for child in trace_doc.get("spans") or []:
+                if child.get("parent_span_id") != root.get("span_id"):
+                    continue
+                with otel.start_as_current_span(child["name"]) as child_span:
+                    for key, value in (child.get("attributes") or {}).items():
+                        child_span.set_attribute(key, value)

loopotel/integrations/__init__.py

@@ -0,0 +1,5 @@
+"""Third-party integrations."""
+
+from loopotel.integrations.loopgym import run_traced_episode, trace_live_episode
+
+__all__ = ["run_traced_episode", "trace_live_episode"]

loopotel/integrations/loopgym.py

@@ -0,0 +1,104 @@
+"""LoopGym integration — trace SimEnv / LiveEnv episodes."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from loopotel.tracer import LoopTracer
+
+
+def _worker_evaluator_ids(spec: dict[str, Any]) -> tuple[str | None, str | None]:
+    workers = spec.get("workers") or []
+    evaluators = spec.get("evaluators") or []
+    worker_id = str(workers[0]["id"]) if workers and workers[0].get("id") else None
+    evaluator_id = str(evaluators[0]["id"]) if evaluators and evaluators[0].get("id") else None
+    return worker_id, evaluator_id
+
+
+def _goal_target_from_spec(spec: dict[str, Any]) -> float:
+    term = spec.get("termination_conditions")
+    if isinstance(term, dict):
+        for success in term.get("success") or []:
+            if success.get("value") is not None:
+                return float(success["value"])
+    for ev in spec.get("evaluators") or []:
+        rubric = ev.get("rubric") or {}
+        if rubric.get("pass_threshold") is not None:
+            return float(rubric["pass_threshold"])
+    return 0.8
+
+
+def run_traced_episode(
+    env: Any,
+    *,
+    task_id: str = "",
+    seed: int | None = None,
+    enabled: bool = True,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Run a LoopGym episode and return (episode_result, ltf_trace).
+
+    Tracing is opt-in (`enabled=True`). Default off matches SimEnv policy;
+    pass `enabled=True` explicitly or use `trace_live=True` wrappers.
+    """
+    spec = getattr(env, "spec", {}) or {}
+    loop_name = str(spec.get("loop_name", "unknown-loop"))
+    goal_target = _goal_target_from_spec(spec)
+    worker_id, evaluator_id = _worker_evaluator_ids(spec)
+
+    tracer = LoopTracer(
+        loop_name=loop_name,
+        env_id=getattr(env, "env_id", None),
+        task_id=task_id or None,
+        goal_target=goal_target,
+        enabled=enabled,
+    )
+
+    with tracer:
+        obs = env.reset(task_id=task_id, seed=seed)
+        prev_tokens = 0
+        if getattr(env, "_runtime", None) and getattr(env._runtime, "llm", None):
+            prev_tokens = getattr(env._runtime.llm, "tokens_used", 0)
+
+        last_latency_ms = 0.0
+        while not env.done:
+            t0 = time.perf_counter()
+            obs, _reward, _done, info = env.step()
+            last_latency_ms = (time.perf_counter() - t0) * 1000.0
+            tokens_now = 0
+            if getattr(env, "_runtime", None) and getattr(env._runtime, "llm", None):
+                tokens_now = getattr(env._runtime.llm, "tokens_used", 0)
+            tokens_delta = max(0, tokens_now - prev_tokens)
+            prev_tokens = tokens_now
+
+            if obs.iteration > 0:
+                tracer.emit_iteration(
+                    iteration=obs.iteration,
+                    goal_score=obs.quality_score,
+                    goal_target=goal_target,
+                    tokens_delta=tokens_delta,
+                    latency_ms=round(last_latency_ms, 2),
+                    worker_id=worker_id,
+                    evaluator_id=evaluator_id,
+                )
+
+        outcome = "success" if info.get("success") else "failure"
+        tracer.finish(
+            outcome=outcome,
+            termination_reason=str(info.get("termination_reason", "")),
+        )
+
+    result = {
+        "task_id": task_id,
+        "seed": seed,
+        "env_id": getattr(env, "env_id", None),
+        "success": info.get("success", False),
+        "quality_score": obs.quality_score,
+        "termination_reason": info.get("termination_reason", ""),
+    }
+    return result, tracer.build_trace()
+
+
+def trace_live_episode(env: Any, **kwargs: Any) -> tuple[dict[str, Any], dict[str, Any]]:
+    """LiveEnv helper — tracing on by default."""
+    return run_traced_episode(env, enabled=True, **kwargs)

loopotel/les.py

@@ -0,0 +1,18 @@
+"""Point-in-loop LES proxies (v0.1 — effectiveness-focused)."""
+
+from __future__ import annotations
+
+DEFAULT_GOAL_TARGET = 0.8
+
+
+def effectiveness(goal_score: float, goal_target: float = DEFAULT_GOAL_TARGET) -> float:
+    if goal_target <= 0:
+        return 0.0
+    return max(0.0, min(1.0, goal_score / goal_target))
+
+
+def cumulative_les(scores: list[float], goal_target: float = DEFAULT_GOAL_TARGET) -> float:
+    if not scores:
+        return 0.0
+    values = [effectiveness(s, goal_target) for s in scores]
+    return round(sum(values) / len(values), 4)

loopotel/models.py

@@ -0,0 +1,71 @@
+"""LTF document builders and identifiers."""
+
+from __future__ import annotations
+
+import secrets
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def isoformat(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def new_trace_id() -> str:
+    return f"ltf-{uuid4()}"
+
+
+def new_span_id() -> str:
+    return secrets.token_hex(8)
+
+
+def spec_pins() -> dict[str, str]:
+    return {"lss": "lss@1.0.0", "les": "les@1.0.0", "ltf": "ltf@0.1.0"}
+
+
+def otel_attributes(
+    *,
+    loop_name: str,
+    env_id: str | None = None,
+    task_id: str | None = None,
+    iteration: int | None = None,
+    goal_score: float | None = None,
+    goal_target: float | None = None,
+    tokens_delta: int | None = None,
+    cost_usd: float | None = None,
+    latency_ms: float | None = None,
+    les_cumulative: float | None = None,
+    les_effectiveness: float | None = None,
+    worker_id: str | None = None,
+    evaluator_id: str | None = None,
+    outcome: str | None = None,
+    termination_reason: str | None = None,
+) -> dict[str, Any]:
+    attrs: dict[str, Any] = {"loop.name": loop_name}
+    mapping = {
+        "loop.env_id": env_id,
+        "loop.task_id": task_id,
+        "loop.iteration": iteration,
+        "loop.goal_score": goal_score,
+        "loop.goal_target": goal_target,
+        "loop.tokens_delta": tokens_delta,
+        "loop.cost_usd": cost_usd,
+        "loop.latency_ms": latency_ms,
+        "loop.les.cumulative_normalized": les_cumulative,
+        "loop.les.effectiveness": les_effectiveness,
+        "loop.worker.id": worker_id,
+        "loop.evaluator.id": evaluator_id,
+        "loop.outcome": outcome,
+        "loop.termination_reason": termination_reason,
+        "loop.lss_version": "1.0.0",
+        "loop.les_version": "1.0.0",
+    }
+    for key, value in mapping.items():
+        if value is not None:
+            attrs[key] = value
+    return attrs

loopotel/schemas/ltf-0.1.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://loop-engineering.org/schema/ltf-0.1.schema.json",
+  "title": "Loop Trace Format 0.1",
+  "description": "Canonical schema for loop execution traces: one root span per run, iteration spans with worker/evaluator events, and point-in-loop LES metrics.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "trace_id",
+    "loop_name",
+    "started_at",
+    "ended_at",
+    "spec_pins",
+    "spans"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "ltf/0.1"
+    },
+    "trace_id": {
+      "type": "string",
+      "pattern": "^ltf-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    },
+    "loop_name": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 64
+    },
+    "env_id": { "type": "string" },
+    "task_id": { "type": "string" },
+    "started_at": { "type": "string", "format": "date-time" },
+    "ended_at": { "type": "string", "format": "date-time" },
+    "outcome": {
+      "type": "string",
+      "enum": ["success", "failure", "partial", "unknown"]
+    },
+    "termination_reason": { "type": "string" },
+    "spec_pins": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lss", "les", "ltf"],
+      "properties": {
+        "lss": { "type": "string", "const": "lss@1.0.0" },
+        "les": { "type": "string", "const": "les@1.0.0" },
+        "ltf": { "type": "string", "const": "ltf@0.1.0" }
+      }
+    },
+    "spans": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/Span" }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "SpanKind": {
+      "type": "string",
+      "enum": ["loop", "iteration", "worker", "evaluator"]
+    },
+    "Span": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["span_id", "name", "kind", "start_time", "attributes"],
+      "properties": {
+        "span_id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{16}$"
+        },
+        "parent_span_id": {
+          "type": ["string", "null"]
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "kind": { "$ref": "#/$defs/SpanKind" },
+        "start_time": { "type": "string", "format": "date-time" },
+        "end_time": { "type": "string", "format": "date-time" },
+        "attributes": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "events": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SpanEvent" }
+        }
+      }
+    },
+    "SpanEvent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "timestamp"],
+      "properties": {
+        "name": { "type": "string" },
+        "timestamp": { "type": "string", "format": "date-time" },
+        "attributes": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    }
+  }
+}

loopotel/tracer.py

@@ -0,0 +1,235 @@
+"""LoopTracer — emit LTF spans for loop runs."""
+
+from __future__ import annotations
+
+import functools
+import time
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from loopotel import les as les_metrics
+from loopotel.models import isoformat, new_span_id, new_trace_id, otel_attributes, spec_pins, utc_now
+
+_current_tracer: ContextVar[LoopTracer | None] = ContextVar("loopotel_current_tracer", default=None)
+
+
+def current_tracer() -> LoopTracer | None:
+    return _current_tracer.get()
+
+
+def emit_iteration(
+    *,
+    iteration: int,
+    goal_score: float,
+    goal_target: float | None = None,
+    tokens_delta: int = 0,
+    cost_usd: float | None = None,
+    latency_ms: float | None = None,
+    worker_id: str | None = None,
+    evaluator_id: str | None = None,
+) -> None:
+    """Emit an iteration span on the active tracer (no-op if tracing disabled)."""
+    tracer = current_tracer()
+    if tracer is None or not tracer.enabled:
+        return
+    tracer.emit_iteration(
+        iteration=iteration,
+        goal_score=goal_score,
+        goal_target=goal_target,
+        tokens_delta=tokens_delta,
+        cost_usd=cost_usd,
+        latency_ms=latency_ms,
+        worker_id=worker_id,
+        evaluator_id=evaluator_id,
+    )
+
+
+@dataclass
+class LoopTracer:
+    """Collect LTF spans for one loop run."""
+
+    loop_name: str
+    env_id: str | None = None
+    task_id: str | None = None
+    goal_target: float = les_metrics.DEFAULT_GOAL_TARGET
+    enabled: bool = True
+    trace_id: str = field(default_factory=new_trace_id)
+    started_at: Any = field(default_factory=utc_now)
+    ended_at: Any | None = None
+    outcome: str = "unknown"
+    termination_reason: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+    _root_span_id: str = field(default_factory=new_span_id)
+    _goal_scores: list[float] = field(default_factory=list)
+    _spans: list[dict[str, Any]] = field(default_factory=list)
+    _token_total: int = 0
+
+    def __enter__(self) -> LoopTracer:
+        if self.enabled:
+            _current_tracer.set(self)
+            self._spans.append(
+                {
+                    "span_id": self._root_span_id,
+                    "parent_span_id": None,
+                    "name": "loop.run",
+                    "kind": "loop",
+                    "start_time": isoformat(self.started_at),
+                    "attributes": otel_attributes(
+                        loop_name=self.loop_name,
+                        env_id=self.env_id,
+                        task_id=self.task_id,
+                        goal_target=self.goal_target,
+                    ),
+                    "events": [],
+                }
+            )
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self.enabled:
+            self.finish(
+                outcome="failure" if exc else self.outcome,
+                termination_reason=self.termination_reason or ("error" if exc else ""),
+            )
+            _current_tracer.set(None)
+
+    def emit_iteration(
+        self,
+        *,
+        iteration: int,
+        goal_score: float,
+        goal_target: float | None = None,
+        tokens_delta: int = 0,
+        cost_usd: float | None = None,
+        latency_ms: float | None = None,
+        worker_id: str | None = None,
+        evaluator_id: str | None = None,
+    ) -> None:
+        if not self.enabled:
+            return
+        target = goal_target if goal_target is not None else self.goal_target
+        self._goal_scores.append(goal_score)
+        self._token_total += tokens_delta
+        eff = les_metrics.effectiveness(goal_score, target)
+        cumulative = les_metrics.cumulative_les(self._goal_scores, target)
+        now = utc_now()
+        span_id = new_span_id()
+        events: list[dict[str, Any]] = [
+            {
+                "name": "loop.iteration.start",
+                "timestamp": isoformat(now),
+                "attributes": {"loop.iteration": iteration},
+            }
+        ]
+        if worker_id:
+            events.append(
+                {
+                    "name": "loop.worker.complete",
+                    "timestamp": isoformat(now),
+                    "attributes": {"loop.worker.id": worker_id},
+                }
+            )
+        if evaluator_id:
+            events.append(
+                {
+                    "name": "loop.evaluator.complete",
+                    "timestamp": isoformat(now),
+                    "attributes": {"loop.evaluator.id": evaluator_id, "loop.goal_score": goal_score},
+                }
+            )
+        events.append(
+            {
+                "name": "loop.iteration.end",
+                "timestamp": isoformat(now),
+                "attributes": {"loop.iteration": iteration, "loop.goal_score": goal_score},
+            }
+        )
+        self._spans.append(
+            {
+                "span_id": span_id,
+                "parent_span_id": self._root_span_id,
+                "name": "loop.iteration",
+                "kind": "iteration",
+                "start_time": isoformat(now),
+                "end_time": isoformat(now),
+                "attributes": otel_attributes(
+                    loop_name=self.loop_name,
+                    env_id=self.env_id,
+                    task_id=self.task_id,
+                    iteration=iteration,
+                    goal_score=round(goal_score, 4),
+                    goal_target=target,
+                    tokens_delta=tokens_delta,
+                    cost_usd=cost_usd,
+                    latency_ms=latency_ms,
+                    les_cumulative=cumulative,
+                    les_effectiveness=round(eff, 4),
+                    worker_id=worker_id,
+                    evaluator_id=evaluator_id,
+                ),
+                "events": events,
+            }
+        )
+
+    def finish(
+        self,
+        *,
+        outcome: str = "unknown",
+        termination_reason: str = "",
+    ) -> None:
+        if not self.enabled:
+            return
+        self.outcome = outcome
+        self.termination_reason = termination_reason
+        self.ended_at = utc_now()
+        if self._spans:
+            root = self._spans[0]
+            root["end_time"] = isoformat(self.ended_at)
+            root["attributes"].update(
+                otel_attributes(
+                    loop_name=self.loop_name,
+                    env_id=self.env_id,
+                    task_id=self.task_id,
+                    outcome=outcome,
+                    termination_reason=termination_reason,
+                )
+            )
+            root["attributes"]["loop.tokens_total"] = self._token_total
+
+    def build_trace(self) -> dict[str, Any]:
+        if self.ended_at is None:
+            self.finish()
+        return {
+            "schema_version": "ltf/0.1",
+            "trace_id": self.trace_id,
+            "loop_name": self.loop_name,
+            "env_id": self.env_id,
+            "task_id": self.task_id,
+            "started_at": isoformat(self.started_at),
+            "ended_at": isoformat(self.ended_at or utc_now()),
+            "outcome": self.outcome,
+            "termination_reason": self.termination_reason,
+            "spec_pins": spec_pins(),
+            "spans": self._spans,
+            "metadata": dict(self.metadata),
+        }
+
+
+def trace_loop(
+    *,
+    loop_name: str,
+    env_id: str | None = None,
+    enabled: bool = True,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator: wrap a function in a LoopTracer context."""
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            with LoopTracer(loop_name=loop_name, env_id=env_id, enabled=enabled):
+                return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

loopotel/validate.py

@@ -0,0 +1,32 @@
+"""Validate LTF documents against ltf-0.1.schema.json."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+def load_schema() -> dict[str, Any]:
+    bundled = Path(__file__).resolve().parent / "schemas" / "ltf-0.1.schema.json"
+    repo = Path(__file__).resolve().parents[2] / "specs" / "ltf-0.1.schema.json"
+    path = bundled if bundled.exists() else repo
+    with path.open(encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def validate_trace(trace: dict[str, Any]) -> tuple[bool, list[str]]:
+    try:
+        import jsonschema
+    except ImportError as exc:
+        raise SystemExit("jsonschema required: pip install loopotel[dev]") from exc
+
+    schema = load_schema()
+    validator = jsonschema.Draft202012Validator(schema)
+    errors = sorted({f"{e.json_path}: {e.message}" for e in validator.iter_errors(trace)})
+    return len(errors) == 0, errors
+
+
+def validate_file(path: Path) -> tuple[bool, list[str]]:
+    with path.open(encoding="utf-8") as handle:
+        trace = json.load(handle)
+    return validate_trace(trace)

loopotel-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: loopotel
+Version: 0.1.0
+Summary: Loop Trace Format (LTF) instrumentation and exporters for loop observability
+Project-URL: Homepage, https://github.com/KanakMalpani/loop-observability
+Project-URL: Repository, https://github.com/KanakMalpani/loop-observability
+Project-URL: Loop Core Engineering, https://github.com/KanakMalpani/Loop-Core-Engineering
+Project-URL: LoopGym, https://github.com/KanakMalpani/LoopGym
+Author: Kanak Malpani
+License: MIT
+License-File: LICENSE
+Keywords: les,loop-engineering,ltf,observability,opentelemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: jsonschema>=4.21
+Provides-Extra: dev
+Requires-Dist: loopgym>=0.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: loopgym
+Requires-Dist: loopgym>=0.1.0; extra == 'loopgym'
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'otlp'
+Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otlp'
+Description-Content-Type: text/markdown
+
+# Loop Observability
+
+**Loop Trace Format (LTF)** and OpenTelemetry conventions for production loop monitoring.
+
+SREs need spans for iterations, evaluators, token burn, and LES deltas — not raw chat logs. This repo defines the format and ships `loopotel`, a minimal Python instrumentation library.
+
+[![CI](https://github.com/KanakMalpani/loop-observability/actions/workflows/test.yml/badge.svg)](https://github.com/KanakMalpani/loop-observability/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/loopotel.svg)](https://pypi.org/project/loopotel/)
+
+## Install
+
+```bash
+pip install loopotel
+pip install "loopotel[loopgym]"   # LoopGym episode tracing
+pip install "loopotel[otlp]"      # OTLP export
+```
+
+## Quick start — trace a LoopGym run
+
+```python
+import loopgym as lg
+from loopotel.integrations.loopgym import run_traced_episode
+from loopotel.exporter.jsonl import JsonlExporter
+
+env = lg.make("loopbench/code-repair-v1")
+result, trace = run_traced_episode(env, task_id="cr-001", seed=42, enabled=True)
+
+JsonlExporter("traces.jsonl").export(trace)
+print(result["success"], trace["trace_id"])
+```
+
+Or run the example:
+
+```bash
+pip install loopgym loopotel
+python examples/export_loopgym_ltf.py
+```
+
+## API
+
+```python
+from loopotel import LoopTracer, emit_iteration, trace_loop
+
+with LoopTracer(loop_name="my-loop", env_id="prod/agent") as tracer:
+    emit_iteration(iteration=1, goal_score=0.55, tokens_delta=120,
+                   worker_id="implementer", evaluator_id="rubric")
+    tracer.finish(outcome="success", termination_reason="goal_met")
+
+trace = tracer.build_trace()  # ltf/0.1 document
+```
+
+## Specs
+
+| Document | Purpose |
+|----------|---------|
+| [`specs/ltf-0.1.schema.json`](specs/ltf-0.1.schema.json) | LTF JSON schema |
+| [`specs/otel-semconv-loop.md`](specs/otel-semconv-loop.md) | `loop.*` OTel attributes |
+| [`specs/les-timeseries.md`](specs/les-timeseries.md) | Point-in-loop LES metrics |
+
+## Grafana
+
+Import [`examples/grafana-dashboard.json`](examples/grafana-dashboard.json) for iteration vs goal score, cumulative LES, and token burn panels (sample data included).
+
+## Validate
+
+```bash
+loopotel-validate examples/sample-trace.jsonl
+python scripts/validate_ltf.py path/to/trace.json
+```
+
+## Design
+
+- **Minimal overhead** — tracing off by default; pass `enabled=True` for SimEnv, use `trace_live_episode()` for LiveEnv
+- **Exporters** — JSONL (built-in), OTLP (optional), LoopNet trajectory mapping
+- **Pins** — `lss@1.0.0`, `les@1.0.0`, `ltf@0.1.0`
+
+## Links
+
+- [LoopNet end-to-end tutorial](https://github.com/KanakMalpani/loopnet/blob/main/guides/END-TO-END-TUTORIAL.md) — HF → replay → LoopBench
+- [Loop Core Engineering](https://github.com/KanakMalpani/Loop-Core-Engineering) — LES / LSS
+- [LoopGym](https://github.com/KanakMalpani/LoopGym) — instrumentation target
+- [LoopNet](https://github.com/KanakMalpani/loopnet) — trajectory corpus export
+- [Publishing](PUBLISHING.md) · [PyPI](https://pypi.org/project/loopotel/)

loopotel-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+loopotel/__init__.py,sha256=9gYQAUK1IZPf8lOTivqWkC6Dy_ORi3I_EjJrpZm0cJE,258
+loopotel/cli.py,sha256=U7EFR43OZC6CR5BLx-DPlBkxZDe5WXFh5ql6ulJwPpE,1232
+loopotel/les.py,sha256=dszwqZRczUehACvmXUNFK-cx9_E6bnK0TeTSREmkI6A,560
+loopotel/models.py,sha256=b2v2KlgpK5SUV5hBOZmK0Fkrk2PpZYdnTFyBHMLnLTA,2014
+loopotel/tracer.py,sha256=JKxVV9odJ1NOoV44B5ypBJdXMds8ORG7TBmVSnz8N90,7862
+loopotel/validate.py,sha256=og2kofmzMcgFABxIp7kNaidFKewd6F1XOV_Uz-7KQOI,1092
+loopotel/exporter/__init__.py,sha256=O-WCrPSQmxX4WgoHcGW7brJUm_dIS47s8Oj0IUyWrJ4,188
+loopotel/exporter/jsonl.py,sha256=7DczOf7LG9y7RICUyenLfO7HnbKQUV1-ennTYliCnQo,632
+loopotel/exporter/loopnet.py,sha256=DFQ85wCLXF62vEzEbeusyByzfov4MJV3xggLmv7dMzA,1290
+loopotel/exporter/otlp.py,sha256=bN00TdKgHOvR3jlis_B_1wVwn7FwZ8rWP7xbVfyqPM0,2367
+loopotel/integrations/__init__.py,sha256=fZk5P9F8WBVVHVglKzVHk6XY2i9HN7L7hdlVulsk4FU,170
+loopotel/integrations/loopgym.py,sha256=3sv5VZgpG0vwQwVxItZqZfWvAjm1s6ha7Odb7mrwbzQ,3730
+loopotel/schemas/ltf-0.1.schema.json,sha256=_z1Lz2IrVTRO-i-sEDGM3LZTvAd_Hgm9Uq0JH91ZiwM,3026
+loopotel-0.1.0.dist-info/METADATA,sha256=VONwjqQAYqkRvJ2hWliAz-Y7ArBk-DuYHsKGviTrKyU,4178
+loopotel-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+loopotel-0.1.0.dist-info/entry_points.txt,sha256=5ulPBAoYxBQi-fZ_4aeVTOvI4g1P3VWroct2OK5K21k,56
+loopotel-0.1.0.dist-info/licenses/LICENSE,sha256=evRYU4i8S6LPZ42e9jNkROkb-chKgbu-HyltWnYncvk,1069
+loopotel-0.1.0.dist-info/RECORD,,

loopotel-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

loopotel-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+loopotel-validate = loopotel.cli:main

loopotel-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KanakMalpani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.