loopotel 0.1.0__tar.gz

loopotel-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install hatchling build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true

loopotel-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: test-loop-observability
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/checkout@v4
+        with:
+          repository: KanakMalpani/LoopGym
+          path: deps/loopgym
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and LoopGym
+        run: |
+          pip install -e ".[dev]"
+          pip install -e deps/loopgym
+
+      - name: Run tests
+        run: pytest tests/ -q
+
+      - name: Export sample LTF from LoopGym
+        run: python examples/export_loopgym_ltf.py examples/sample-trace.jsonl
+
+      - name: Validate sample trace
+        run: loopotel-validate examples/sample-trace.jsonl

loopotel-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.venv/
+venv/
+examples/sample-trace.jsonl

loopotel-0.1.0/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.

loopotel-0.1.0/PKG-INFO

@@ -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/PLAN.md

@@ -0,0 +1,51 @@
+# 07 — loop-observability
+
+## One-line purpose
+
+**Loop Trace Format (LTF)** and OpenTelemetry conventions for production loop monitoring.
+
+## Why this repo exists
+
+Industry adopts what they can **operate**. SREs need spans for iterations, evaluators, token burn, LES deltas — not raw chat logs.
+
+## Scope (in scope)
+
+- LTF JSON schema (one span per iteration, child spans per worker/evaluator)
+- OpenTelemetry semantic conventions draft (`loop.*` attributes)
+- Exporters: OTLP, JSONL, LoopNet trajectory export
+- Reference instrumentation for LoopGym / LangGraph
+- Dashboard templates (Grafana JSON v0.1)
+- LES time-series spec (point-in-loop metrics)
+
+## Scope (out of scope)
+
+- Full SaaS observability product
+- Log storage infrastructure
+
+## Deliverables v0.1
+
+- [x] `specs/ltf-0.1.schema.json`
+- [x] `specs/otel-semconv-loop.md`
+- [x] `loopotel/` Python package — `@trace_loop`, `emit_iteration()`
+- [x] `examples/grafana-dashboard.json`
+
+## Status
+
+✅ v0.1 shipped — see [STATUS.md](STATUS.md)
+
+## Dependencies
+
+- **01-loop-engineering-core** — LES dimensions, worker/evaluator IDs
+- **05-loopgym** — instrumentation target
+
+## Success criteria
+
+One LoopGym run exports valid LTF; Grafana dashboard shows iterations vs cumulative LES.
+
+## Agent instructions
+
+Design for **minimal overhead**; default off in SimEnv, on in LiveEnv.
+
+## Status
+
+🟡 Planning only

loopotel-0.1.0/PUBLISHING.md

@@ -0,0 +1,41 @@
+# Publishing loopotel to PyPI
+
+## One-time setup
+
+1. Register the project name **`loopotel`** at [pypi.org](https://pypi.org/).
+2. **Preferred:** [trusted publishing](https://docs.pypi.org/trusted-publishers/) on PyPI:
+   - **Project:** `loopotel`
+   - **Owner:** `KanakMalpani`
+   - **Repository:** `loop-observability`
+   - **Workflow:** `publish.yml`
+3. **Fallback:** add **`PYPI_API_TOKEN`** to [loop-observability Actions secrets](https://github.com/KanakMalpani/loop-observability/settings/secrets/actions) (reuse the same upload token as LoopGym/LoopBench).
+
+## Publish
+
+Release tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+gh release create v0.1.0 --title "v0.1.0" --notes "Initial loopotel release"
+```
+
+Or **Actions → Publish to PyPI → Run workflow**.
+
+## Install
+
+```bash
+pip install loopotel
+pip install "loopotel[loopgym]"   # LoopGym integration
+pip install "loopotel[otlp]"       # OTLP export
+```
+
+## Verify locally
+
+```bash
+pip install build
+python -m build
+pip install dist/loopotel-*.whl
+loopotel-validate --help
+pytest tests/ -q
+```

loopotel-0.1.0/README.md

@@ -0,0 +1,83 @@
+# 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/STATUS.md

@@ -0,0 +1,30 @@
+# Status
+
+| Field | Value |
+|-------|-------|
+| **Phase** | v0.1 shipped |
+| **Symbol** | ✅ |
+| **Notes** | LTF schema, loopotel package, LoopGym integration, Grafana template |
+
+## Completion checklist
+
+- [x] `specs/ltf-0.1.schema.json`
+- [x] `specs/otel-semconv-loop.md`
+- [x] `specs/les-timeseries.md`
+- [x] `loopotel/` — `LoopTracer`, `@trace_loop`, `emit_iteration()`
+- [x] Exporters: JSONL, OTLP (optional), LoopNet trajectory
+- [x] `loopotel.integrations.loopgym` — `run_traced_episode()`
+- [x] `examples/grafana-dashboard.json`
+- [x] `examples/export_loopgym_ltf.py`
+- [x] CI: pytest + LTF validation
+- [ ] PyPI publish `loopotel` — add `PYPI_API_TOKEN` secret or trusted publisher, then run [Publish to PyPI](https://github.com/KanakMalpani/loop-observability/actions/workflows/publish.yml) (see [PUBLISHING.md](PUBLISHING.md))
+
+## Success criteria
+
+- [x] One LoopGym run exports valid LTF
+- [x] Grafana dashboard template for iterations vs cumulative LES
+
+## Links
+
+- Parent workspace: [../README.md](../README.md)
+- Plan: [PLAN.md](PLAN.md)

loopotel-0.1.0/SYNC.md

@@ -0,0 +1,10 @@
+# Sync policy
+
+| Artifact | Canonical home | This repo |
+|----------|----------------|-----------|
+| LSS / LES specs | [Loop Core Engineering](https://github.com/KanakMalpani/Loop-Core-Engineering) | Pins only in LTF |
+| LTF schema | **This repo** `specs/ltf-0.1.schema.json` | Bundled copy in `loopotel/schemas/` |
+| LoopNet trajectory | [loopnet](https://github.com/KanakMalpani/loopnet) | Export via `trajectory_from_trace()` |
+| LoopGym runtime | [LoopGym](https://github.com/KanakMalpani/LoopGym) | Integration in `loopotel.integrations.loopgym` |
+
+Do not fork LSS/LES schemas here. Reference pins in every LTF document via `spec_pins`.

loopotel-0.1.0/examples/export_loopgym_ltf.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Export a LoopGym SimEnv run as valid LTF JSONL."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_OUT = ROOT / "examples" / "sample-trace.jsonl"
+
+
+def main() -> int:
+    try:
+        import loopgym as lg
+    except ImportError:
+        print("Install loopgym: pip install loopgym", file=sys.stderr)
+        return 1
+
+    from loopotel.exporter.jsonl import JsonlExporter
+    from loopotel.integrations.loopgym import run_traced_episode
+    from loopotel.validate import validate_trace
+
+    env = lg.make("loopbench/code-repair-v1")
+    _result, trace = run_traced_episode(env, task_id="cr-001", seed=42, enabled=True)
+
+    valid, errors = validate_trace(trace)
+    if not valid:
+        print("LTF validation failed:", file=sys.stderr)
+        for err in errors:
+            print(f"  - {err}", file=sys.stderr)
+        return 1
+
+    out_path = Path(sys.argv[1]) if len(sys.argv) > 1 else DEFAULT_OUT
+    JsonlExporter(out_path).export(trace)
+
+    iterations = sum(1 for s in trace["spans"] if s["kind"] == "iteration")
+    last_les = next(
+        (
+            s["attributes"].get("loop.les.cumulative_normalized")
+            for s in reversed(trace["spans"])
+            if s["kind"] == "iteration"
+        ),
+        0,
+    )
+    print(f"Wrote LTF trace -> {out_path}")
+    print(f"  trace_id: {trace['trace_id']}")
+    print(f"  iterations: {iterations}")
+    print(f"  cumulative LES: {last_les}")
+    print(f"  outcome: {trace['outcome']}")
+    print()
+    print("Iteration series (for Grafana):")
+    for span in trace["spans"]:
+        if span["kind"] != "iteration":
+            continue
+        attrs = span["attributes"]
+        print(
+            f"  iter={attrs['loop.iteration']} "
+            f"goal={attrs['loop.goal_score']:.3f} "
+            f"les={attrs['loop.les.cumulative_normalized']:.3f}"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

loopotel-0.1.0/examples/grafana-dashboard.json

@@ -0,0 +1,134 @@
+{
+  "annotations": {
+    "list": [
+      {
+        "builtIn": 1,
+        "enable": true,
+        "hide": true,
+        "iconColor": "rgba(0, 211, 255, 1)",
+        "name": "Annotations & Alerts",
+        "type": "dashboard"
+      }
+    ]
+  },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 0,
+  "id": null,
+  "links": [],
+  "panels": [
+    {
+      "datasource": { "type": "grafana-testdata-datasource", "uid": "grafana" },
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": {
+            "axisBorderShow": false,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "lineWidth": 2,
+            "pointSize": 6,
+            "showPoints": "always"
+          },
+          "unit": "none"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
+      "id": 1,
+      "options": {
+        "legend": { "displayMode": "list", "placement": "bottom" },
+        "tooltip": { "mode": "single" }
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "scenarioId": "csv_content",
+          "csvContent": "iteration,goal_score\n1,0.57\n2,0.69\n3,0.81\n4,0.88",
+          "csvFileName": "goal_score.csv"
+        }
+      ],
+      "title": "Goal score by iteration",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "grafana-testdata-datasource", "uid": "grafana" },
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": {
+            "axisBorderShow": false,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "lineWidth": 2,
+            "pointSize": 6,
+            "showPoints": "always"
+          },
+          "max": 1,
+          "min": 0,
+          "unit": "none"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
+      "id": 2,
+      "options": {
+        "legend": { "displayMode": "list", "placement": "bottom" },
+        "tooltip": { "mode": "single" }
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "scenarioId": "csv_content",
+          "csvContent": "iteration,les_cumulative\n1,0.71\n2,0.78\n3,0.84\n4,0.88",
+          "csvFileName": "les_cumulative.csv"
+        }
+      ],
+      "title": "Cumulative LES (normalized)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "grafana-testdata-datasource", "uid": "grafana" },
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": {
+            "axisBorderShow": false,
+            "drawStyle": "bars",
+            "fillOpacity": 80,
+            "lineWidth": 1
+          },
+          "unit": "none"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 24, "x": 0, "y": 8 },
+      "id": 3,
+      "options": {
+        "legend": { "displayMode": "list", "placement": "bottom" },
+        "tooltip": { "mode": "single" }
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "scenarioId": "csv_content",
+          "csvContent": "iteration,tokens_delta\n1,159\n2,159\n3,159\n4,159",
+          "csvFileName": "tokens.csv"
+        }
+      ],
+      "title": "Token burn per iteration",
+      "type": "timeseries"
+    }
+  ],
+  "refresh": "",
+  "schemaVersion": 39,
+  "tags": ["loop-engineering", "ltf", "les"],
+  "templating": { "list": [] },
+  "time": { "from": "now-6h", "to": "now" },
+  "timepicker": {},
+  "timezone": "browser",
+  "title": "Loop Engineering — LTF v0.1",
+  "uid": "loop-ltf-v01",
+  "version": 1,
+  "description": "Sample dashboard for loop.iteration metrics. Replace testdata with LTF JSONL → Prometheus/Loki pipeline or Grafana Infinity datasource."
+}

loopotel-0.1.0/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-0.1.0/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())