PolyHedra / src /polyhedra /core /trace_logger.py
yf176
fix: preserve failed agent token usage in trace
44d82a2
Raw History Blame Contribute Delete
4.9 kB
"""TraceLogger — structured per-run trace for every agent invocation.
Writes append-only JSONL entries to ``~/.polyhedra/sessions/<id>/trace.jsonl``.
This is the authoritative source for token usage in V4.4+ (replaces
``QuantState.token_log`` for new code paths).
STRUCT-3 (V4.4) — FR-S3.1 through FR-S3.4.
"""
from __future__ import annotations
import hashlib
import json
import logging
import time
import uuid
from datetime import datetime, timezone
from pathlib import Path
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from polyhedra.agents.base import AgentResponse
logger = logging.getLogger(__name__)
_TRACE_FILENAME = "trace.jsonl"
class TraceLogger:
"""Logs each agent invocation to a session-scoped ``trace.jsonl`` file.
Usage::
trace = TraceLogger(session_dir)
run_id = trace.start_run("trendanalyst")
response = await agent.handle(...)
trace.end_run(run_id, response, prompt_tokens=843, completion_tokens=412, cache_hit=False)
"""
def __init__(self, session_dir: Path) -> None:
self._path = session_dir / _TRACE_FILENAME
self._in_flight: dict[str, dict[str, Any]] = {} # run_id -> partial entry
# ------------------------------------------------------------------ #
# Public API (FR-S3.1)
# ------------------------------------------------------------------ #
def start_run(self, agent_role: str, *, prompt: str = "", session_id: str = "") -> str:
"""Begin tracing an agent run. Returns a ``run_id`` (UUID4)."""
run_id = str(uuid.uuid4())
self._in_flight[run_id] = {
"run_id": run_id,
"session_id": session_id,
"agent_role": agent_role,
"timestamp_start": datetime.now(tz=timezone.utc).isoformat(),
"_start_mono": time.monotonic(),
"input_hash": _sha256_prefix(prompt) if prompt else "",
}
return run_id
def end_run(
self,
run_id: str,
response: "AgentResponse",
*,
prompt_tokens: int = 0,
completion_tokens: int = 0,
cache_hit: bool = False,
estimated_cost_usd: float | None = 0.0,
) -> None:
"""Finish tracing and append the completed entry to ``trace.jsonl``."""
partial = self._in_flight.pop(run_id, None)
if partial is None:
logger.warning("TraceLogger.end_run: unknown run_id %s", run_id)
return
start_mono: float = partial.pop("_start_mono", time.monotonic())
latency_ms = int((time.monotonic() - start_mono) * 1000)
next_role = response.mentions[0] if response.mentions else None
entry: dict[str, Any] = {
**partial,
"timestamp_end": datetime.now(tz=timezone.utc).isoformat(),
"latency_ms": latency_ms,
"output_hash": _sha256_prefix(response.content),
"prompt_tokens": prompt_tokens,
"completion_tokens": completion_tokens,
"estimated_cost_usd": (
round(estimated_cost_usd, 6) if estimated_cost_usd is not None else None
),
"cache_hit": cache_hit,
"artifact_written": response.artifact_path or "",
"next_role": next_role,
"routing_reason": "",
"error": response.error,
}
self._append(entry)
def read_trace(self, last_n: int | None = None) -> list[dict[str, Any]]:
"""Read the trace file and return entries, optionally limited to *last_n*."""
if not self._path.exists():
return []
entries: list[dict[str, Any]] = []
try:
with self._path.open("r", encoding="utf-8") as fh:
for line in fh:
line = line.strip()
if line:
try:
entries.append(json.loads(line))
except json.JSONDecodeError:
pass
except OSError as exc:
logger.error("TraceLogger: failed to read %s: %s", self._path, exc)
if last_n is not None:
entries = entries[-last_n:]
return entries
# ------------------------------------------------------------------ #
# Internal helpers
# ------------------------------------------------------------------ #
def _append(self, entry: dict[str, Any]) -> None:
try:
self._path.parent.mkdir(parents=True, exist_ok=True)
with self._path.open("a", encoding="utf-8") as fh:
fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
except OSError as exc:
logger.error("TraceLogger: failed to write trace entry: %s", exc)
def _sha256_prefix(text: str, length: int = 16) -> str:
return hashlib.sha256(text.encode("utf-8", errors="replace")).hexdigest()[:length]