hermes-trace/docs/architecture.md

2.1 KiB

hermes-trace Architecture

Overview

hermes-trace is a Hermes Agent plugin that captures every LLM API call (main session, background review forks, subagents) to a local SQLite store with a Granian-powered query frontend.

Data Flow

LLM API call happens (main, background_review, or subagent)
        │
        ▼
pre_api_request / post_api_request hooks in __init__.py
        │
        ▼
db.write_turn() / db.write_tool_call()
        │
        ▼
telemetry.db (SQLite: turns + tool_calls tables)
        │
        ▼
Granian → FastAPI → Jinja2 templates → HTMX + Alpine.js in browser
        │
        ▼
Flat turn timeline table
        │
        ▼ click a row
Right-side overlay detail panel

Components

Capture Layer (__init__.py)

  • Registers 3 Hermes plugin hooks: pre_api_request, post_api_request, post_tool_call
  • Spawns a Granian daemon thread for the frontend server
  • Spawns a cleanup daemon thread for periodic data retention

Data Layer (db.py)

  • SQLite schema with turns and tool_calls tables
  • Write helpers: write_turn(), write_tool_call()
  • Read helpers: get_sessions(), get_turns_for_session(), get_turns_with_tool_calls(), get_turn_detail()
  • Cleanup: clean_expired_turns() with ON DELETE CASCADE for tool_calls

Frontend Server (app.py)

  • FastAPI application served by Granian (--interface asgi), launched as a subprocess from a daemon thread (Granian requires the main thread for signal.signal())
  • 6 routes (incl. focus_tc variant): session list, flat-table session view, turn detail overlay (with focus_tc), payload lazy-load, and a legacy waterfall fragment
  • The waterfall route and template are legacy code with no live navigation path in the UI; they may be removed in a future cleanup
  • Custom Jinja2 filters: commas (thousands separator for token counts), utc8 (UTC → UTC+8 datetime formatting)
  • Pretty-print helper: _pretty_json() with optional \n → newline replacement

Templates (templates/)

See docs/frontend.md for detailed frontend architecture.