hermes-trace/docs/architecture.md

52 lines
2.1 KiB
Markdown

# 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.