Download src/polyhedra/core/trace_logger.py from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 4.9 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/src/polyhedra/core/trace_logger.py
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/src/polyhedra/core/trace_logger.py
-
curl -L -o trace_logger.py https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/src/polyhedra/core/trace_logger.py
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] | |