Skip to content
Python
8.6 KB
Raw Blame
"""Build an ATIF (Agent Trajectory Interchange Format) trajectory from an OpenWorker
conversation, so a headless run's record can be read by tools that consume that format.

Written against ATIF-v1.7:

- steps are numbered from 1, sequentially;
- `source` is "user", "agent", or "system"; model_name / tool_calls / metrics only on
  agent steps;
- an observation result's `source_call_id` must name a tool call in the SAME step;
- an agent step with llm_call_count == 0 may not carry metrics.

OpenWorker persists one message per model round-trip (role "assistant", with
`tool_calls` in OpenAI form and a `usage` sidecar) followed by one "tool" message per
tool call, so the mapping is: assistant message -> agent step, following tool messages ->
that step's observation.
"""

from __future__ import annotations

import json
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Optional

from .pricing import estimate_cost

SCHEMA_VERSION = "ATIF-v1.7"


def _iso(ts: Any) -> Optional[str]:
    try:
        return datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat()
    except (TypeError, ValueError, OverflowError, OSError):
        return None


def _text(content: Any) -> str:
    if content is None:
        return ""
    if isinstance(content, str):
        return content
    try:
        from ..attachments import content_to_text

        return content_to_text(content)
    except Exception:  # noqa: BLE001 - never fail the trajectory over a content part
        return json.dumps(content, default=str)


def _parse_args(raw: Any) -> dict[str, Any]:
    if isinstance(raw, dict):
        return raw
    try:
        parsed = json.loads(raw or "{}")
    except (TypeError, ValueError):
        return {"_raw": str(raw)}
    return parsed if isinstance(parsed, dict) else {"_value": parsed}


def build_trajectory(
    messages: list[dict[str, Any]],
    *,
    agent_name: str,
    agent_version: str,
    model_name: str,
    session_id: str,
    outcome: str,
    prices: Optional[dict] = None,
    agent_extra: Optional[dict[str, Any]] = None,
    reasoning_effort: Optional[str] = None,
) -> dict[str, Any]:
    steps: list[dict[str, Any]] = []
    pending: Optional[dict[str, Any]] = None  # the last agent step, for observations
    totals = {"prompt": 0, "completion": 0, "cached": 0}
    cost_total = 0.0
    cost_known = False
    cost_unknown = False

    for msg in messages:
        role = msg.get("role")
        ts = _iso(msg.get("ts"))

        if role == "user":
            pending = None
            steps.append({"source": "user", "message": _text(msg.get("content")), "timestamp": ts})
            continue

        if role == "assistant":
            step: dict[str, Any] = {
                "source": "agent",
                "message": _text(msg.get("content")),
                "timestamp": ts,
                "llm_call_count": 1,
            }
            usage = msg.get("usage") or {}
            step["model_name"] = str(usage.get("model") or model_name)
            if reasoning_effort:
                step["reasoning_effort"] = reasoning_effort  # ATIF: agent steps only
            if msg.get("reasoning"):
                step["reasoning_content"] = str(msg["reasoning"])
            calls = msg.get("tool_calls") or []
            if calls:
                step["tool_calls"] = [
                    {
                        "tool_call_id": str(tc.get("id")),
                        "function_name": str((tc.get("function") or {}).get("name", "")),
                        "arguments": _parse_args((tc.get("function") or {}).get("arguments")),
                    }
                    for tc in calls
                ]
            if usage:
                prompt = (
                    int(usage.get("input", 0) or 0)
                    + int(usage.get("cache_read", 0) or 0)
                    + int(usage.get("cache_write", 0) or 0)
                )
                completion = int(usage.get("output", 0) or 0)
                cached = int(usage.get("cache_read", 0) or 0)
                metrics: dict[str, Any] = {
                    "prompt_tokens": prompt,
                    "completion_tokens": completion,
                    "cached_tokens": cached,
                }
                # The four raw counts and the serving host travel too, so a consumer can
                # price the call itself (cache reads and writes are billed differently,
                # and a router's upstream host decides which rate applies).
                extra = {
                    k: int(usage.get(k, 0) or 0)
                    for k in ("input", "output", "cache_read", "cache_write")
                }
                if msg.get("served_by"):
                    extra["served_by"] = str(msg["served_by"])
                metrics["extra"] = extra
                cost = estimate_cost(step["model_name"], usage, prices)
                if cost is not None:
                    metrics["cost_usd"] = cost
                    cost_total += cost
                    cost_known = True
                else:
                    cost_unknown = True
                step["metrics"] = metrics
                totals["prompt"] += prompt
                totals["completion"] += completion
                totals["cached"] += cached
            else:
                cost_unknown = True
            steps.append(step)
            pending = step
            continue

        if role == "tool":
            result = {"content": _text(msg.get("content"))}
            call_id = msg.get("tool_call_id")
            if pending is not None and any(
                tc["tool_call_id"] == call_id for tc in pending.get("tool_calls") or []
            ):
                result["source_call_id"] = str(call_id)
                pending.setdefault("observation", {"results": []})["results"].append(result)
            else:
                # Orphan tool output (should not happen); keep it as a system step.
                steps.append({"source": "system", "message": result["content"], "timestamp": ts})
            continue

        # Notices, system prompts, and anything else become system steps. Engine notices
        # carry their wording in `text` (not `content`); a compacted notice also carries
        # the compaction record, so the trajectory shows what the model's memory was
        # replaced with, not just that it was.
        text = (
            _text(msg.get("content"))
            or str(msg.get("text") or "")
            or str(msg.get("kind") or role or "")
        )
        compaction = msg.get("compaction") if role == "notice" else None
        if isinstance(compaction, dict):
            summary = str(compaction.get("summary_text") or "")
            working = str(compaction.get("working_state") or "")
            parts = [text]
            if compaction.get("trimmed"):
                # The trim path stores a placeholder sentence as its summary; say what
                # happened instead of quoting it as if it were a summary.
                parts.append("[compaction: oldest turns trimmed; no summary was produced]")
            elif summary:
                parts.append("[compaction summary]\n" + summary)
            if working:
                parts.append("[working state]\n" + working)
            text = "\n\n".join(x for x in parts if x)
        if text:
            steps.append({"source": "system", "message": text, "timestamp": ts})

    for i, step in enumerate(steps, start=1):
        step["step_id"] = i
        if step.get("timestamp") is None:
            step.pop("timestamp", None)

    final_metrics: dict[str, Any] = {
        "total_prompt_tokens": totals["prompt"],
        "total_completion_tokens": totals["completion"],
        "total_cached_tokens": totals["cached"],
        "total_steps": len(steps),
        "extra": {"outcome": outcome},
    }
    if cost_known:
        # The priced part of the run. When a call could not be priced (unknown model,
        # or no usage block) the total is a lower bound, and `cost_complete` says so.
        final_metrics["total_cost_usd"] = round(cost_total, 6)
        final_metrics["extra"]["cost_complete"] = not cost_unknown

    return {
        "schema_version": SCHEMA_VERSION,
        "session_id": session_id,
        "agent": {
            "name": agent_name,
            "version": agent_version,
            "model_name": model_name,
            **({"extra": agent_extra} if agent_extra else {}),
        },
        "steps": steps,
        "final_metrics": final_metrics,
    }


def write_trajectory(path: str | Path, trajectory: dict[str, Any]) -> None:
    p = Path(path)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(json.dumps(trajectory, indent=1, default=str), encoding="utf-8")