Recording and imports

Recorder writes live activity into a v3 repository. It starts with code, dirty patch, environment, policy, budget, and pricing manifests, then appends immutable events and advances a ref.

record.py

1from opentine import Recorder, Repo, TraceEvent
2
3repo = Repo.open(".")
4recording = Recorder.start(repo, ref="heads/main")
5recording.append(TraceEvent(
6    kind="model",
7    timestamp=0,
8    trace_id="trace",
9    span_id="model-1",
10    model="gpt-5.6",
11    inputs={"prompt": "hello"},
12    outputs={"text": "hi"},
13))
14run_id = recording.finalize()
15evaluation_id = recording.evaluate({"quality": 0.9}, evaluator="judge")
16recording.promote("production")

Event schema

TraceEvent supports seven kinds: model, tool, human, policy, approval, subagent, and error. Record failures as error events so partial executions remain inspectable. Parent and causal span references are qualified by trace ID; duplicates and cycles are refused.

Importers

import_trace.py

1from opentine import Recorder, Repo
2from opentine.trace import (
3    framework_events,
4    jsonl_events,
5    native_events,
6    otel_genai_events,
7)
8
9repo = Repo.open(".")
10events = jsonl_events("trace.jsonl")
11recording = Recorder.start(repo, ref="heads/imported", capture=False)
12recording.import_events(events)
13run_id = recording.finalize()
14
15# Other inputs:
16# native_events(run)
17# otel_genai_events(otlp_json)
18# framework_events(records, "langchain")

Importers accept native opentine runs, JSONL, OpenTelemetry GenAI spans or complete OTLP/JSON exports, and best-effort serialized records from LangChain, LlamaIndex, AutoGen, CrewAI, and OpenAI Agents. Malformed JSONL records are skipped per line; unresolved partial-trace boundaries remain explicit. CrewAI is post-hoc only in v0.5.

Import from the shell

Terminal

tine import trace.otlp.json --format otel-json --save imported.tine
tine import events.jsonl --format jsonl --repo . --ref heads/imported

tine import exposes those importers without a Python wrapper. It can write a portable v2 artifact, advance a ref in an existing v3 repository, or do both. The importing machine's code and environment are deliberately not captured as though they produced the original trace.

Export OpenTelemetry GenAI data

export_trace.py

1from opentine import Run, to_otel_genai, to_otel_genai_document
2
3run = Run.load("imported.tine")
4spans = to_otel_genai(run)
5document = to_otel_genai_document(run, service_name="agent")

The export functions accept loaded portable or repository runs and TraceEvent values. They return span dictionaries or an OTLP/JSON document; they do not write or transmit anything. See OpenTelemetry interoperability for supported content and round-trip limits.

Live framework capture

The optional LangChain and LangGraph callback handler records both frameworks through their shared callback protocol while a run is executing. Other named framework formats remain serialized-log imports.

Bounds and capture completeness

One stored Recorder run is limited to 3,000 events. Bulk import checks capacity before writing event data, preserves dependency order, and commits one final run snapshot. Git code capture has a 16 MiB ceiling; untracked paths are listed but their contents are not captured, so the code manifest is marked incomplete.

MCP boundary

Repository MCP tools expose bounded search, inspection, context, semantic diff, fork/resume, evaluation, and attestation. Fork and resume may write only experiments/*. Promotion is disabled by default and appears only when the host opts into allow_promotion=True; recorded run text is untrusted input and must not control a release gate.