Metadata-Version: 2.4
Name: hermitcrab
Version: 0.1.1
Summary: Track and analyze LLM token usage across providers with local billing ledger and OpenAI-compatible routing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1.0.0,>=0.115.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: pydantic<3.0.0,>=2.8.0
Requires-Dist: pydantic-settings<3.0.0,>=2.3.0
Requires-Dist: uvicorn<1.0.0,>=0.30.0

# hermitcrab

OpenAI-compatible LLM proxy with local token accounting. Every request is logged to SQLite so you can reconcile your usage against provider invoices.

```bash
pip install hermitcrab
hermitcrab serve        # start proxy on 127.0.0.1:14415
hermitcrab tui          # terminal management UI
```

## Features

- OpenAI-compatible `POST /v1/chat/completions`, `POST /v1/embeddings`, `GET /v1/models`
- SQLite token ledger — prompt / completion / total tokens per request
- Analytics endpoints and CLI reports for billing reconciliation
- Server-side model enforcement via active profile; hot-switch without restart
- 18+ supported providers (see below)
- Curses TUI: guided profile setup, live stats, systemd service management
- systemd user-service install/uninstall via CLI or TUI (no sudo required)

## Quick start

```bash
hermitcrab serve                        # proxy starts on 127.0.0.1:14415
hermitcrab tui                          # open TUI — press 'a' to add first profile
```

Point any OpenAI-compatible client at `http://127.0.0.1:14415/v1`.

## Token reports

```bash
hermitcrab usage                                         # total up/down tokens
hermitcrab report --view summary                         # one-line totals + avg latency
hermitcrab report --view by-model                        # aggregate by provider/model
hermitcrab report --view recent --requests-limit 20      # last N requests
hermitcrab report --view timeseries --bucket day --since 2026-04-01T00:00:00
```

## Profiles (CLI)

```bash
hermitcrab profiles list
hermitcrab profiles current

hermitcrab profiles add \
  --name openrouter-gemma \
  --provider openrouter \
  --model google/gemma-3-27b-it:free \
  --api-key YOUR_KEY \
  --activate

hermitcrab profiles activate openrouter-gemma   # hot-switch, no restart
hermitcrab profiles delete 2
```

## Supported providers

`openai`, `openrouter`, `anthropic`, `deepseek`, `ollama`, `vllm`, `lmstudio`,
`google-gemini`, `xai-grok`, `alibaba-qwen`, `minimax`, `glm`,
`github-models`, `github-copilot`, `copilot-proxy`,
`xiaomi`, `amazon-bedrock`, `nvidia`, `huggingface`, `openai-compatible`

## systemd service

```bash
hermitcrab service install --user     # install + enable user-level service
hermitcrab service restart --user
hermitcrab service status --user
hermitcrab service uninstall --user
```

## Configuration

| Variable | Default |
|---|---|
| `HERMIT_DATABASE_URL` | `sqlite:///$HOME/.hermitcrab/hermit.db` |
| `HERMIT_DEFAULT_PROVIDER` | `ollama` |
| `HERMIT_DEFAULT_MODEL` | `deepseek-r1:32b` |
| `HERMIT_REQUEST_TIMEOUT_SECONDS` | `120` |

Config and database are stored in `~/.hermitcrab/` by default.

## HTTP API

```
GET  /health
POST /v1/chat/completions
POST /v1/embeddings
GET  /v1/models
GET  /analytics/summary
GET  /analytics/by-model
GET  /analytics/timeseries?bucket=hour&since=2026-04-01T00:00:00
GET  /analytics/requests?limit=100
GET  /profiles
POST /profiles
POST /profiles/{id}/activate
PUT  /profiles/{id}
DELETE /profiles/{id}
```
