52 lines
2.1 KiB
Markdown
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.
|