trace-sdk 0.1.1__py3-none-any.whl

trace_sdk/__init__.py

@@ -0,0 +1,13 @@
+from .capture import decision, span, wrap, wrap_tools
+from .context import TraceError, track
+from .store import load_config
+
+__all__ = [
+    "TraceError",
+    "decision",
+    "load_config",
+    "span",
+    "track",
+    "wrap",
+    "wrap_tools",
+]

trace_sdk/capture.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import functools
+import hashlib
+import inspect
+from contextlib import contextmanager
+from typing import Any, Callable
+
+from .context import append_step, normalize_config, push_span
+
+
+def summarize(value: Any, max_string: int = 120) -> Any:
+    try:
+        if value is None or isinstance(value, (bool, int, float)):
+            return value
+        if isinstance(value, str):
+            digest = hashlib.sha256(value.encode("utf-8")).hexdigest()[:10]
+            return {"type": "str", "len": len(value), "hash": digest, "preview": value[:max_string]}
+        if isinstance(value, (list, tuple, set)):
+            items = list(value)
+            return {"type": type(value).__name__, "count": len(items), "sample": [summarize(item) for item in items[:3]]}
+        if isinstance(value, dict):
+            notable = {}
+            for key in ("status", "id", "name", "model", "prompt_id", "strategy", "selected", "count", "minimum_viable", "activities", "days", "total", "budget"):
+                if key in value:
+                    notable[key] = summarize(value[key])
+            return {"type": "dict", "keys": sorted(map(str, value.keys())), **notable}
+        if hasattr(value, "model_dump"):
+            return summarize(value.model_dump())
+        if hasattr(value, "__dict__"):
+            public = {k: v for k, v in vars(value).items() if not k.startswith("_")}
+            if public:
+                return {"type": type(value).__name__, **summarize(public)}
+        text = repr(value)
+        return summarize(text, max_string=max_string)
+    except Exception:
+        return {"type": type(value).__name__}
+
+
+def decision(label: str, **meta: Any) -> None:
+    try:
+        append_step("decision", label, meta={key: summarize(value) for key, value in meta.items()})
+    except Exception:
+        return
+
+
+@contextmanager
+def span(name: str):
+    with push_span(name):
+        yield
+
+
+def wrap_tools(tools_dict: dict[str, Callable]) -> dict[str, Callable]:
+    wrapped = {}
+    for name, func in tools_dict.items():
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_tool(*args, __func=func, __name=name, **kwargs):
+                result = await __func(*args, **kwargs)
+                append_step("tool_call", __name, input=summarize({"args": args, "kwargs": kwargs}), output=summarize(result))
+                return result
+
+            wrapped[name] = async_tool
+        else:
+
+            @functools.wraps(func)
+            def sync_tool(*args, __func=func, __name=name, **kwargs):
+                result = __func(*args, **kwargs)
+                append_step("tool_call", __name, input=summarize({"args": args, "kwargs": kwargs}), output=summarize(result))
+                return result
+
+            wrapped[name] = sync_tool
+    return wrapped
+
+
+class ClientProxy:
+    def __init__(self, client: Any):
+        self._trace_client = client
+
+    def __getattr__(self, attr: str) -> Any:
+        target = getattr(self._trace_client, attr)
+        if not callable(target):
+            return target
+        if inspect.iscoroutinefunction(target):
+
+            @functools.wraps(target)
+            async def async_call(*args, **kwargs):
+                result = await target(*args, **kwargs)
+                append_step("model_call", _model_name(self._trace_client, attr), input=summarize({"args": args, "kwargs": kwargs}), output=summarize(result))
+                return result
+
+            return async_call
+
+        @functools.wraps(target)
+        def sync_call(*args, **kwargs):
+            result = target(*args, **kwargs)
+            append_step("model_call", _model_name(self._trace_client, attr), input=summarize({"args": args, "kwargs": kwargs}), output=summarize(result))
+            return result
+
+        return sync_call
+
+    def __call__(self, *args, **kwargs):
+        result = self._trace_client(*args, **kwargs)
+        append_step("model_call", _model_name(self._trace_client, "__call__"), input=summarize({"args": args, "kwargs": kwargs}), output=summarize(result))
+        return result
+
+
+def _model_name(client: Any, method: str) -> str:
+    for attr in ("model", "model_name", "name"):
+        value = getattr(client, attr, None)
+        if value:
+            return str(value)
+    return f"{type(client).__name__}.{method}"
+
+
+def wrap(client: Any) -> Any:
+    return ClientProxy(client)

trace_sdk/cli.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import typer
+
+from .diff import diff_runs, render_diff
+from .store import clear_runs, list_runs, read_run, write_config_for_run
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.command()
+def log() -> None:
+    """List captured runs."""
+    typer.echo(f"{'ID':<8} {'AGENT':<16} {'TIME':<20} {'MODEL':<18} {'STATUS':<8} STEPS")
+    for run in list_runs():
+        model = run.config.model or run.config.extra.get("model") or run.config.extra.get("pipeline") or "-"
+        time = run.timestamp.strftime("%Y-%m-%d %H:%M:%S")
+        typer.echo(f"{run.id:<8} {(run.agent or '-'):<16} {time:<20} {str(model):<18} {run.status:<8} {len(run.steps)}")
+
+
+@app.command()
+def show(run_id: str) -> None:
+    """Pretty-print a run."""
+    run = read_run(run_id)
+    typer.echo(f"Run {run.id} agent={run.agent} status={run.status}")
+    typer.echo(f"started={run.started_at} ended={run.ended_at}")
+    current = object()
+    for step in run.steps:
+        span = step.span or "root"
+        if span != current:
+            typer.echo(f"span {span}")
+            current = span
+        detail = step.output if step.output is not None else step.meta
+        typer.echo(f"  {step.index:02d} {step.type:<10} {step.name:<28} {detail}")
+    typer.echo(f"output: {run.output}")
+
+
+@app.command()
+def diff(run_a: str, run_b: str, json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON.")) -> None:
+    """Diff two runs behaviorally."""
+    result = diff_runs(read_run(run_a), read_run(run_b))
+    if json_output:
+        typer.echo(json.dumps(result, indent=2, sort_keys=True, default=str))
+    else:
+        typer.echo(render_diff(result))
+
+
+@app.command()
+def revert(run_id: str, agent: Optional[str] = typer.Option(None, "--agent", help="Restore only one logical agent.")) -> None:
+    """Restore config from a run."""
+    run = read_run(run_id)
+    try:
+        restored = write_config_for_run(run, agent=agent)
+    except KeyError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    names = ", ".join(restored)
+    typer.echo(f"Restored configuration for {names} from run {run.id}.")
+    typer.echo(
+        f"Restored the configuration (model + prompt + tools) for `{names}` from run `{run.id}`. "
+        "This restores the setup that produced that behavior - it does not guarantee identical behavior "
+        "if the model provider or tool data has changed upstream."
+    )
+
+
+@app.command()
+def clear() -> None:
+    """Wipe captured runs."""
+    clear_runs()
+    typer.echo("Cleared .trace/runs.")
+
+
+@app.command()
+def serve(host: str = "127.0.0.1", port: int = 7000) -> None:
+    """Launch TraceHub."""
+    import uvicorn
+
+    uvicorn.run("trace_sdk.web.server:app", host=host, port=port, reload=False)

trace_sdk/context.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import contextvars
+import functools
+import hashlib
+import inspect
+import json
+import uuid
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional, Union
+
+from .schema import Config, Run, Step
+from .store import write_head, write_run
+
+
+class TraceError(RuntimeError):
+    pass
+
+
+@dataclass
+class AgentRegistration:
+    config_fingerprint: str
+    call_site: str
+    count: int = 0
+
+
+@dataclass
+class RunState:
+    run: Run
+    agent_registry: dict[str, AgentRegistration] = field(default_factory=dict)
+
+
+_current_state: contextvars.ContextVar[Optional[RunState]] = contextvars.ContextVar("trace_state", default=None)
+_span_stack: contextvars.ContextVar[tuple[str, ...]] = contextvars.ContextVar("trace_span_stack", default=())
+
+
+def current_state() -> Optional[RunState]:
+    return _current_state.get()
+
+
+def current_span() -> Optional[str]:
+    stack = _span_stack.get()
+    return "/".join(stack) if stack else None
+
+
+def normalize_config(config: Optional[Union[dict[str, Any], Config]]) -> Config:
+    if isinstance(config, Config):
+        return config
+    if config is None:
+        return Config()
+    known = {key: config[key] for key in ("model", "prompt_id", "tools") if key in config}
+    extra = {key: value for key, value in config.items() if key not in known}
+    if "extra" in config and isinstance(config["extra"], dict):
+        extra.update(config["extra"])
+    return Config(**known, extra=extra)
+
+
+def _fingerprint(config: Config) -> str:
+    payload = json.dumps(config.model_dump(mode="json"), sort_keys=True, default=str)
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def register_agent(name: str, config: Config, call_site: str) -> str:
+    state = current_state()
+    if state is None:
+        return name
+    fingerprint = _fingerprint(config)
+    existing = state.agent_registry.get(name)
+    if existing is not None:
+        if existing.config_fingerprint != fingerprint or existing.call_site != call_site:
+            raise TraceError(
+                f'duplicate agent name "{name}": two different agents share it. '
+                "Agent names must be unique within a run so revert can target them. "
+                f'Rename one (e.g. "{name}_a" / "{name}_b").'
+            )
+        existing.count += 1
+        return f"{name}#{existing.count}"
+
+    state.agent_registry[name] = AgentRegistration(fingerprint, call_site, count=1)
+    state.run.span_configs.setdefault(name, config)
+    return f"{name}#1"
+
+
+def append_step(step_type: str, name: str, input: Any = None, output: Any = None, meta: Optional[dict[str, Any]] = None) -> None:
+    state = current_state()
+    if state is None:
+        return
+    try:
+        span = current_span()
+        step = Step(
+            index=len(state.run.steps),
+            type=step_type,
+            name=name,
+            input=input,
+            output=output,
+            span=span,
+            meta=meta or {},
+        )
+        state.run.steps.append(step)
+        write_run(state.run)
+    except Exception:
+        return
+
+
+@contextmanager
+def push_span(name: str, config: Optional[Config] = None, call_site: Optional[str] = None):
+    token = None
+    try:
+        span_name = name
+        if config is not None:
+            span_name = register_agent(name, config, call_site or name)
+        stack = _span_stack.get()
+        token = _span_stack.set((*stack, span_name))
+        yield
+    finally:
+        if token is not None:
+            _span_stack.reset(token)
+
+
+def _new_run(agent: Optional[str], config: Config, input_value: Any) -> Run:
+    now = datetime.now(timezone.utc)
+    return Run(
+        id=uuid.uuid4().hex[:6],
+        timestamp=now,
+        agent=agent,
+        config=config,
+        input=input_value,
+        started_at=now,
+    )
+
+
+def track(agent: Optional[str] = None, config: Optional[Union[dict[str, Any], Config, Callable[..., Any]]] = None):
+
+    def decorator(fn: Callable):
+        call_site = f"{fn.__module__}.{fn.__qualname__}"
+
+        def summarize_call(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+            from .capture import summarize
+
+            return summarize({"args": args, "kwargs": kwargs})
+
+        def resolve_config(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Config:
+            if callable(config):
+                return normalize_config(config(*args, **kwargs))
+            return normalize_config(config)
+
+        async def run_async(*args, **kwargs):
+            config_model = resolve_config(args, kwargs)
+            state = current_state()
+            if state is not None:
+                name = agent or fn.__qualname__
+                with push_span(name, config_model, call_site):
+                    return await fn(*args, **kwargs)
+
+            run = _new_run(agent, config_model, summarize_call(args, kwargs))
+            state = RunState(run=run)
+            state.agent_registry[run.agent or "orchestrator"] = AgentRegistration(_fingerprint(config_model), call_site, 1)
+            state_token = _current_state.set(state)
+            span_token = _span_stack.set(())
+            try:
+                write_run(run)
+                result = await fn(*args, **kwargs)
+                from .capture import summarize
+
+                run.output = summarize(result)
+                run.status = "success"
+                return result
+            except Exception as exc:
+                run.status = "error"
+                run.error = str(exc)
+                raise
+            finally:
+                run.ended_at = datetime.now(timezone.utc)
+                write_run(run)
+                write_head(run.id)
+                _span_stack.reset(span_token)
+                _current_state.reset(state_token)
+
+        def run_sync(*args, **kwargs):
+            config_model = resolve_config(args, kwargs)
+            state = current_state()
+            if state is not None:
+                name = agent or fn.__qualname__
+                with push_span(name, config_model, call_site):
+                    return fn(*args, **kwargs)
+
+            run = _new_run(agent, config_model, summarize_call(args, kwargs))
+            state = RunState(run=run)
+            state.agent_registry[run.agent or "orchestrator"] = AgentRegistration(_fingerprint(config_model), call_site, 1)
+            state_token = _current_state.set(state)
+            span_token = _span_stack.set(())
+            try:
+                write_run(run)
+                result = fn(*args, **kwargs)
+                from .capture import summarize
+
+                run.output = summarize(result)
+                run.status = "success"
+                return result
+            except Exception as exc:
+                run.status = "error"
+                run.error = str(exc)
+                raise
+            finally:
+                run.ended_at = datetime.now(timezone.utc)
+                write_run(run)
+                write_head(run.id)
+                _span_stack.reset(span_token)
+                _current_state.reset(state_token)
+
+        if inspect.iscoroutinefunction(fn):
+            return functools.wraps(fn)(run_async)
+        return functools.wraps(fn)(run_sync)
+
+    return decorator

trace_sdk/diff.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from difflib import SequenceMatcher
+from typing import Any, Optional
+
+from .schema import Config, Run, Step
+
+
+def diff_runs(a: Run, b: Run) -> dict[str, Any]:
+    config_changes = _diff_configs(a, b)
+    span_diffs = _diff_spans(a, b)
+    outcome = _diff_outcome(a, b)
+    root = _root_cause(span_diffs)
+    return {
+        "a": a.id,
+        "b": b.id,
+        "config": config_changes,
+        "spans": span_diffs,
+        "outcome": outcome,
+        "root_cause": root,
+    }
+
+
+def render_diff(diff: dict[str, Any]) -> str:
+    lines = [f"diff {diff['a']} -> {diff['b']}"]
+    lines.append("config:")
+    if diff["config"]:
+        for item in diff["config"]:
+            lines.append(f"  ~ {item['path']} {item['a']} -> {item['b']}")
+    else:
+        lines.append("  = unchanged")
+
+    lines.append("behavior:")
+    if diff["spans"]:
+        for span in diff["spans"]:
+            lines.append(f"  span {span['span']}:")
+            if span["changes"]:
+                for change in span["changes"]:
+                    lines.append(f"    {change['kind']} {change['detail']}")
+            else:
+                lines.append("    = control flow unchanged")
+    else:
+        lines.append("  = unchanged")
+
+    lines.append("outcome:")
+    if diff["outcome"]:
+        for item in diff["outcome"]:
+            lines.append(f"  ~ {item['path']} {item['a']} -> {item['b']}")
+    else:
+        lines.append("  = unchanged")
+    if diff.get("root_cause"):
+        lines.append(f"root cause: {diff['root_cause']}")
+    return "\n".join(lines)
+
+
+def _config_dump(config: Config) -> dict[str, Any]:
+    return config.model_dump(mode="json")
+
+
+def _diff_configs(a: Run, b: Run) -> list[dict[str, Any]]:
+    changes = []
+    names = sorted({a.agent or "orchestrator", b.agent or "orchestrator", *a.span_configs, *b.span_configs})
+    configs_a = {a.agent or "orchestrator": a.config, **a.span_configs}
+    configs_b = {b.agent or "orchestrator": b.config, **b.span_configs}
+    for name in names:
+        ca = _config_dump(configs_a.get(name, Config()))
+        cb = _config_dump(configs_b.get(name, Config()))
+        for key in ("model", "prompt_id", "tools", "extra"):
+            if ca.get(key) != cb.get(key):
+                changes.append({"path": f"{name}.{key}", "a": ca.get(key), "b": cb.get(key)})
+    return changes
+
+
+def _logical_span(span: Optional[str]) -> str:
+    if not span:
+        return "root"
+    parts = []
+    for part in span.split("/"):
+        parts.append(part.split("#", 1)[0])
+    return "/".join(parts)
+
+
+def _by_span(steps: list[Step]) -> dict[str, list[Step]]:
+    grouped: dict[str, list[Step]] = defaultdict(list)
+    for step in steps:
+        grouped[_logical_span(step.span)].append(step)
+    return grouped
+
+
+def _token(step: Step) -> str:
+    return f"{step.type}:{step.name}"
+
+
+def _diff_spans(a: Run, b: Run) -> list[dict[str, Any]]:
+    grouped_a = _by_span(a.steps)
+    grouped_b = _by_span(b.steps)
+    spans = sorted(set(grouped_a) | set(grouped_b), key=lambda name: _first_index(name, grouped_a, grouped_b))
+    result = []
+    for span in spans:
+        steps_a = grouped_a.get(span, [])
+        steps_b = grouped_b.get(span, [])
+        tokens_a = [_token(step) for step in steps_a]
+        tokens_b = [_token(step) for step in steps_b]
+        changes = []
+
+        counts_a = Counter(tokens_a)
+        counts_b = Counter(tokens_b)
+        for token in sorted(set(counts_a) | set(counts_b)):
+            if counts_a[token] != counts_b[token]:
+                changes.append({"kind": "~", "detail": f"{token} count {counts_a[token]} -> {counts_b[token]}"})
+
+        matcher = SequenceMatcher(a=tokens_a, b=tokens_b)
+        for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+            if tag == "equal":
+                continue
+            if tag == "delete":
+                changes.append({"kind": "-", "detail": ", ".join(tokens_a[i1:i2])})
+            elif tag == "insert":
+                changes.append({"kind": "+", "detail": ", ".join(tokens_b[j1:j2])})
+            else:
+                changes.append({"kind": "~", "detail": f"{tokens_a[i1:i2]} -> {tokens_b[j1:j2]}"})
+
+        for left, right in zip(steps_a, steps_b):
+            if _token(left) == _token(right) and left.output != right.output:
+                changes.append({"kind": "~", "detail": f"{_token(left)} output {left.output} -> {right.output}"})
+            if left.type == "decision" and right.type == "decision" and left.meta != right.meta:
+                changes.append({"kind": "~", "detail": f"decision:{left.name} meta {left.meta} -> {right.meta}"})
+
+        if changes:
+            result.append({"span": span, "changes": _dedupe(changes), "input_changed": _span_input(steps_a) != _span_input(steps_b)})
+    return result
+
+
+def _first_index(name: str, grouped_a: dict[str, list[Step]], grouped_b: dict[str, list[Step]]) -> int:
+    indexes = [steps[0].index for steps in (grouped_a.get(name, []), grouped_b.get(name, [])) if steps]
+    return min(indexes) if indexes else 10**9
+
+
+def _span_input(steps: list[Step]) -> Any:
+    return steps[0].input if steps else None
+
+
+def _dedupe(changes: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    seen = set()
+    result = []
+    for change in changes:
+        key = (change["kind"], str(change["detail"]))
+        if key not in seen:
+            seen.add(key)
+            result.append(change)
+    return result
+
+
+def _diff_outcome(a: Run, b: Run) -> list[dict[str, Any]]:
+    changes = []
+    if a.status != b.status:
+        changes.append({"path": "status", "a": a.status, "b": b.status})
+    if a.output != b.output:
+        changes.append({"path": "output", "a": a.output, "b": b.output})
+    return changes
+
+
+def _root_cause(span_diffs: list[dict[str, Any]]) -> Optional[str]:
+    for item in span_diffs:
+        if not item.get("input_changed"):
+            return item["span"]
+    return span_diffs[0]["span"] if span_diffs else None

trace_sdk/schema.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Step(BaseModel):
+    index: int
+    type: Literal["model_call", "tool_call", "decision"]
+    name: str
+    input: Any = None
+    output: Any = None
+    span: Optional[str] = None
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class Config(BaseModel):
+    model: Optional[str] = None
+    prompt_id: Optional[str] = None
+    tools: list[str] = Field(default_factory=list)
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+class Run(BaseModel):
+    id: str
+    timestamp: datetime
+    agent: Optional[str] = None
+    config: Config
+    span_configs: dict[str, Config] = Field(default_factory=dict)
+    input: Any = None
+    steps: list[Step] = Field(default_factory=list)
+    output: Any = None
+    status: Literal["success", "error", "running"] = "running"
+    error: Optional[str] = None
+    started_at: Optional[datetime] = None
+    ended_at: Optional[datetime] = None

trace_sdk/store.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any, Optional
+
+from .schema import Config, Run
+
+
+def trace_root() -> Path:
+    return Path.cwd() / ".trace"
+
+
+def runs_dir() -> Path:
+    return trace_root() / "runs"
+
+
+def ensure_trace_dirs() -> None:
+    runs_dir().mkdir(parents=True, exist_ok=True)
+
+
+def run_path(run_id: str) -> Path:
+    return runs_dir() / f"{run_id}.json"
+
+
+def write_run(run: Run) -> None:
+    ensure_trace_dirs()
+    payload = run.model_dump(mode="json")
+    run_path(run.id).write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def write_head(run_id: str) -> None:
+    ensure_trace_dirs()
+    (trace_root() / "HEAD").write_text(run_id, encoding="utf-8")
+
+
+def read_run(run_id: str) -> Run:
+    path = run_path(run_id)
+    if not path.exists():
+        matches = list(runs_dir().glob(f"{run_id}*.json")) if runs_dir().exists() else []
+        if len(matches) == 1:
+            path = matches[0]
+    return Run.model_validate_json(path.read_text(encoding="utf-8"))
+
+
+def list_runs() -> list[Run]:
+    if not runs_dir().exists():
+        return []
+    runs: list[Run] = []
+    for path in runs_dir().glob("*.json"):
+        try:
+            runs.append(Run.model_validate_json(path.read_text(encoding="utf-8")))
+        except Exception:
+            continue
+    return sorted(runs, key=lambda run: run.timestamp, reverse=True)
+
+
+def config_path() -> Path:
+    return trace_root() / "config.json"
+
+
+def _config_to_block(config: Config) -> dict[str, Any]:
+    block = config.model_dump(mode="json", exclude_none=True)
+    if not block.get("tools"):
+        block.pop("tools", None)
+    if not block.get("extra"):
+        block.pop("extra", None)
+    return block
+
+
+def write_config_for_run(run: Run, agent: Optional[str] = None) -> list[str]:
+    ensure_trace_dirs()
+    existing = load_config() if config_path().exists() else {}
+    if not isinstance(existing, dict):
+        existing = {}
+
+    orchestrator_name = run.agent or "orchestrator"
+    available = {orchestrator_name: run.config, **run.span_configs}
+
+    if agent is not None:
+        if agent not in available:
+            names = ", ".join(sorted(available))
+            raise KeyError(f'unknown agent "{agent}". Available agents: {names}')
+        existing[agent] = _config_to_block(available[agent])
+        restored = [agent]
+    else:
+        existing[orchestrator_name] = _config_to_block(run.config)
+        for name, config in run.span_configs.items():
+            existing[name] = _config_to_block(config)
+        restored = [orchestrator_name, *sorted(run.span_configs)]
+
+    config_path().write_text(json.dumps(existing, indent=2, sort_keys=True), encoding="utf-8")
+    return restored
+
+
+def load_config(span: Optional[str] = None) -> Any:
+    path = config_path()
+    if not path.exists():
+        return {} if span is None else {}
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if span is None:
+        return data
+    return data.get(span, {})
+
+
+def clear_runs() -> None:
+    if runs_dir().exists():
+        shutil.rmtree(runs_dir())
+    runs_dir().mkdir(parents=True, exist_ok=True)
+    head = trace_root() / "HEAD"
+    if head.exists():
+        head.unlink()

trace_sdk/web/__init__.py

@@ -0,0 +1 @@
+

trace_sdk/web/server.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import AsyncIterator
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import HTMLResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+from watchfiles import awatch
+
+from trace_sdk.diff import diff_runs
+from trace_sdk.store import list_runs, read_run, runs_dir
+
+app = FastAPI(title="TraceHub", version="0.1.0")
+
+DIST = Path(__file__).resolve().parents[2] / "tracehub" / "dist"
+if DIST.exists():
+    app.mount("/assets", StaticFiles(directory=DIST / "assets"), name="assets")
+
+
+def _summary(run):
+    duration = None
+    if run.started_at and run.ended_at:
+        duration = (run.ended_at - run.started_at).total_seconds()
+    spans = []
+    for step in run.steps:
+        if step.span and step.span not in spans:
+            spans.append(step.span)
+    return {
+        "id": run.id,
+        "agent": run.agent,
+        "status": run.status,
+        "started_at": run.started_at.isoformat() if run.started_at else None,
+        "ended_at": run.ended_at.isoformat() if run.ended_at else None,
+        "duration": duration,
+        "steps": len(run.steps),
+        "spans": spans,
+    }
+
+
+@app.get("/runs")
+def runs():
+    return [_summary(run) for run in list_runs()]
+
+
+@app.get("/runs/{run_id}")
+def run_detail(run_id: str):
+    try:
+        return read_run(run_id).model_dump(mode="json")
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+
+
+@app.get("/diff")
+def diff(a: str, b: str):
+    return diff_runs(read_run(a), read_run(b))
+
+
+@app.get("/stream")
+async def stream():
+    async def events() -> AsyncIterator[str]:
+        yield f"data: {json.dumps({'event': 'ready'})}\n\n"
+        runs_dir().mkdir(parents=True, exist_ok=True)
+        async for changes in awatch(runs_dir()):
+            for _, path in changes:
+                if str(path).endswith(".json"):
+                    run_id = Path(path).stem
+                    yield f"data: {json.dumps({'event': 'run_updated', 'id': run_id})}\n\n"
+            await asyncio.sleep(0)
+
+    return StreamingResponse(events(), media_type="text/event-stream")
+
+
+@app.get("/", response_class=HTMLResponse)
+def index():
+    index_path = DIST / "index.html"
+    if index_path.exists():
+        return index_path.read_text(encoding="utf-8")
+    return """
+    <!doctype html>
+    <html>
+      <head><title>TraceHub</title><style>body{font-family:system-ui;background:#101114;color:#f5f5f5;padding:32px}a{color:#7dd3fc}</style></head>
+      <body>
+        <h1>TraceHub</h1>
+        <p>React assets are not built yet. Run <code>cd tracehub && npm install && npm run build</code>, then restart <code>trace serve</code>.</p>
+        <p>API docs are available at <a href="/docs">/docs</a>.</p>
+      </body>
+    </html>
+    """

trace_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: trace-sdk
+Version: 0.1.1
+Summary: Local version control for AI agent behavior.
+Requires-Python: >=3.9
+Requires-Dist: fastapi>=0.111
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: watchfiles>=0.22
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Trace
+
+Trace is local version control for AI agent behavior. It captures structured agent runs, compares behavior across runs, and restores the configuration that produced a trusted run.
+
+```python
+import trace_sdk as trace
+
+@trace.track(agent="planner", config={"model": "mock-v1"})
+def run_agent(request):
+    tools = trace.wrap_tools({"lookup": lookup})
+    result = tools["lookup"](request)
+    trace.decision("lookup_done", status=result["status"])
+    return result
+```
+
+## Commands
+
+```bash
+trace log
+trace show <id>
+trace diff <id_a> <id_b>
+trace diff <id_a> <id_b> --json
+trace revert <id>
+trace revert <id> --agent budget_agent
+trace serve
+trace clear
+```
+
+Runs are stored in `.trace/runs/`. Config restored by `trace revert` is stored in `.trace/config.json`.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run python examples/demo_agent.py --variant stable
+uv run python examples/demo_agent.py --variant drift
+uv run trace log
+```
+
+TraceHub lives in `tracehub/`. Build it with `npm install && npm run build`; `trace serve` serves the built assets from `tracehub/dist`.

trace_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+trace_sdk/__init__.py,sha256=AHlejOU8gRqid0h4scIp_CGPhCF8pLB3k23YHWb7aO8,247
+trace_sdk/capture.py,sha256=6zUQk7sylIQNRsQMvefsNbXwKXrGezQN8tE5POlFvjk,4417
+trace_sdk/cli.py,sha256=bB6V--noxK3Mtyk5rL02po9Pvb4OeKwgmlK4qU__RiQ,2805
+trace_sdk/context.py,sha256=-RzPYqAvZ0Ao3bx8sNoLvI7QBKU5VURy_1wCXco_Pd0,7293
+trace_sdk/diff.py,sha256=cOp7YZWJYFZyrnMRj5ylte0X9Lw-aKkPDEODAKiUv-Y,5999
+trace_sdk/schema.py,sha256=-t_ouETVmMhPouWvzXIen8GJW2T7R3G_-_FO3sAn9Vc,1042
+trace_sdk/store.py,sha256=Ns06WPICg_cruxpw2Y3JAMyJXa-szTayo2IZnkACq7Q,3255
+trace_sdk/web/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+trace_sdk/web/server.py,sha256=DFhnu2LSjp2KIJLdvig1Gg7s-oh1LmD0MLRW7ateeVU,2873
+trace_sdk-0.1.1.dist-info/METADATA,sha256=2K06wIPZGZ9P2axmNWpVFYmgop0s5XnJkok6oW3yvZU,1574
+trace_sdk-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+trace_sdk-0.1.1.dist-info/entry_points.txt,sha256=w5OQp6MVJqm_Jjp3bEpVjjznElw9atmqV06ylDQyyXI,44
+trace_sdk-0.1.1.dist-info/RECORD,,

trace_sdk-0.1.1.dist-info/WHEEL

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

trace_sdk-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+trace = trace_sdk.cli:app