From a588db11a7b9d95aa19a608ae92a236712e0d205 Mon Sep 17 00:00:00 2001 From: Lukas Babaliauskas Date: Thu, 1 Oct 2026 15:52:40 +0200 Subject: [PATCH] docs(traces): imported traces stay local; fix the docstrings that said otherwise The UtcTimestamp docstring in traces/models.py claimed imported-trace timestamps "are copied into the bundle verbatim by ... from_agent_trace". False: evalshift traces import writes them to .evalshift/runs//traces.jsonl, read only by evaluate, report.json and diff/inspect/replay case. from_agent_trace has no production caller; bundle.py only calls from_tool_trace, fed by the replay's own tool-call traces. Fixed that docstring and the from_agent_trace docstring and module docstring in hosted/trace_events.py to say so. Comments/docstrings only, no behaviour change. Co-Authored-By: Claude Opus 5.5 (1M context) --- src/evalshift_cli/hosted/trace_events.py | 14 +++++++++++++- src/evalshift_cli/traces/models.py | 11 +++++++---- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/src/evalshift_cli/hosted/trace_events.py b/src/evalshift_cli/hosted/trace_events.py index eb42b32..e21fd3c 100644 --- a/src/evalshift_cli/hosted/trace_events.py +++ b/src/evalshift_cli/hosted/trace_events.py @@ -12,6 +12,11 @@ Both map here onto one wire shape so the server, the database and the client speak a single language. Neither internal model changes. + +Only :func:`from_tool_trace` has a production caller (``hosted/bundle.py``): a run +bundle's ``examples[].traces`` come from the replay's own tool-call traces. +:func:`from_agent_trace` converts imported agent traces to the same wire shape but is +not wired into bundling today — those traces stay local. """ from __future__ import annotations @@ -170,7 +175,14 @@ def from_tool_trace(trace: ToolTrace | None, *, side: str) -> dict[str, Any] | N def from_agent_trace(trace: AgentTrace) -> dict[str, Any] | None: - """Wire stream for one imported bring-your-own-agent trace. + """Convert an imported agent trace to bundle wire events. + + Not called by ``bundle.py`` today: imported traces (``evalshift traces import``) + stay local in ``.evalshift/runs//traces.jsonl`` and are read only by + ``evaluate``, ``report.json`` and the ``diff``/``inspect``/``replay case`` + commands. A run bundle's ``examples[].traces`` come solely from the replay's own + tool-call traces via :func:`from_tool_trace`. This function exists for a future + caller that would include imported traces in the bundle. A round begins at each ``model_call``. The counter increments on every ``model_call`` after the first, so events preceding any model call stay in diff --git a/src/evalshift_cli/traces/models.py b/src/evalshift_cli/traces/models.py index fade868..06c0a22 100644 --- a/src/evalshift_cli/traces/models.py +++ b/src/evalshift_cli/traces/models.py @@ -25,10 +25,13 @@ def _to_utc(value: datetime) -> datetime: UtcTimestamp = Annotated[AwareDatetime, AfterValidator(_to_utc)] """An event timestamp, offset-aware and stored in UTC. -The bundle contract requires a zero offset (`BUNDLE_SPEC.md` §Validation, enforced by -`app/runs/bundle.py`), and these events are copied into the bundle verbatim by -`evalshift_cli.hosted.trace_events.from_agent_trace`. So the two cases are settled here, where -the error can still name the capture file and line: +Imported agent traces stay local: `evalshift traces import` writes them to +`.evalshift/runs//traces.jsonl`, and only `evaluate`, `report.json` and the +`diff`/`inspect`/`replay case` commands read them back. They are never copied into a +hosted run bundle — `evalshift_cli.hosted.trace_events.from_agent_trace` exists for that +purpose but has no production caller today; `bundle.py` only calls `from_tool_trace` for +the replay's own tool-call traces. So the two cases below are settled here, for internal +consistency and so the error can still name the capture file and line: * an offset timestamp is unambiguous and is converted; * a naive one is refused, because assuming UTC would silently relabel a trace recorded