Metadata-Version: 2.4
Name: hermes-usage-insights
Version: 0.1.0b3
Summary: Track, analyze, and visualize Hermes token usage over time.
Project-URL: Homepage, https://clawlter.mehalter.page/hermes-usage-insights/
Project-URL: Documentation, https://clawlter.mehalter.page/hermes-usage-insights/
Project-URL: Source, https://code.mehalter.com/clawlter/hermes-usage-insights
Project-URL: Issues, https://code.mehalter.com/clawlter/hermes-usage-insights/issues
Project-URL: Changelog, https://code.mehalter.com/clawlter/hermes-usage-insights/src/branch/main/CHANGELOG.md
Author: Hermes Agent
License: MIT
License-File: LICENSE
Keywords: analytics,hermes,reporting,tokens,usage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: matplotlib<4,>=3.10
Description-Content-Type: text/markdown

# Hermes Usage Insights

Hermes Usage Insights is a small Python package for collecting, storing, and inspecting Hermes usage telemetry.

It gives you a local SQLite database plus a CLI for:

- importing Hermes session artifacts without changing Hermes source
- ingesting structured JSONL usage events
- generating summary and breakdown reports
- filtering reports, search, exports, and plots to a date window
- searching stored events
- exporting CSV
- rendering daily token plots

## When to use it

Use this project when you want to answer practical questions about Hermes usage over time without manually spelunking raw session artifacts.

Typical use cases:

- backfill a running Hermes deployment into a local analysis database
- keep a no-source-change collector loop running against Hermes artifacts
- ingest richer JSONL telemetry from an upstream emitter
- inspect usage by session, model, skill, tool, or day
- inspect usage by provider or event source
- export results into a spreadsheet or another analysis workflow

## Choose a collection path

| Path            | Best when                                                      | Requires Hermes source changes | Continuous        | Session totals | Per-tool token attribution |
| --------------- | -------------------------------------------------------------- | ------------------------------ | ----------------- | -------------- | -------------------------- |
| `demo-data`     | You want a fast local proof first                              | No                             | No                | Demo only      | Demo only                  |
| `import-hermes` | You want a one-shot no-source-change backfill                  | No                             | No                | Yes            | No                         |
| `watch-hermes`  | You want a continuous no-source-change collector               | No                             | Yes               | Yes            | No                         |
| `ingest-jsonl`  | You already emit structured events and want richer attribution | Usually yes upstream           | Depends on caller | Yes if emitted | Yes if emitted             |

Rule of thumb:

- start with `demo-data` to prove the package locally
- use `import-hermes` or `watch-hermes` for the no-source-change Hermes path
- use `ingest-jsonl` when you need exact event-level attribution

## Installation

### From source

```bash
git clone https://code.mehalter.com/clawlter/hermes-usage-insights.git
cd hermes-usage-insights
uv sync
```

### From the Forgejo PyPI registry

```bash
pip install \
  --index-url https://<username>:<token>@code.mehalter.com/api/packages/clawlter/pypi/simple \
  --no-deps \
  hermes-usage-insights==0.1.0b2
```

Notes:

- Use a Forgejo personal access token when authentication is required.
- Prefer `--index-url` over `--extra-index-url` to avoid dependency-confusion risk.
- `0.1.0b2` is the current beta release and should be treated as pre-1.0 software.

## Quick start

The fastest local proof uses deterministic demo data.

```bash
uv sync
uv run hui --db usage.db demo-data
uv run hui --db usage.db report summary
uv run hui --db usage.db report breakdown --by tool
uv run hui --db usage.db report breakdown --by provider --since 2026-04-09 --until 2026-04-10
uv run hui --db usage.db plot daily-tokens --output artifacts/daily.png
```

## No-source-change Hermes import

If you already have a Hermes home directory, the simplest real collector path is:

```bash
uv run hui \
  --db artifacts/hermes-usage.db \
  import-hermes \
  --hermes-home /path/to/hermes-home
```

For a continuous collector loop:

```bash
uv run hui \
  --db artifacts/hermes-usage.db \
  watch-hermes \
  --hermes-home /path/to/hermes-home \
  --interval-seconds 60
```

Important limitation:

- collector mode gives accurate session-level totals and tool-call counts
- it does not provide exact per-tool token attribution unless that telemetry is emitted upstream

## JSONL ingestion

If you already emit structured usage events, ingest them directly:

```bash
uv run hui --db usage.db ingest-jsonl path/to/events.jsonl
```

## Common commands

```bash
uv run hui --db usage.db init
uv run hui --db usage.db report summary
uv run hui --db usage.db report breakdown --by model
uv run hui --db usage.db report breakdown --by source
uv run hui --db usage.db search "browser_navigate" --limit 10
uv run hui --db usage.db search "browser_navigate" --since 2026-04-09 --until 2026-04-10
uv run hui --db usage.db export csv --output artifacts/usage.csv
uv run hui --db usage.db export csv --since 2026-04-09 --output artifacts/usage.csv
uv run hui --db usage.db plot daily-tokens --output artifacts/daily.png
```

## Documentation

Public documentation site:

- https://clawlter.mehalter.page/hermes-usage-insights/

Key pages:

- `docs/overview.md` — project overview and operator framing
- `docs/getting-started.md` — shortest path to a working first run
- `docs/collection-paths.md` — importer vs JSONL decision guide
- `docs/integration.md` — Hermes collector-mode and emitter-mode details
- `docs/cli-reference.md` — command reference
- `docs/schema.md` — event schema and collector-generated event semantics
- `docs/troubleshooting.md` — common operational issues

## Development

Install dependencies:

```bash
uv sync
```

Run validation:

```bash
uv run black --check src tests
uv run isort --check-only src tests
uv run pyright
uv run pytest -q
uv run python -m build
uv run mkdocs build --strict
uv run pytest -q tests/test_docs_site.py
```

Build distributions:

```bash
uv run python -m build
uv run twine check dist/*
```

Build the documentation site locally:

```bash
uv run mkdocs build --strict
```

This writes a static site into `site-build/` using MkDocs Material.
