Overview

What somm is: telemetry, routing, and an intelligence loop

Everything else is layered on that substrate. Calls, workloads, optional samples, evaluations, model intelligence, provider health, and recommendations all share one SQLite data model (docs/BLUEPRINT.md:118). When the optional somm serve service is running, scheduled workers grade sampled calls, refresh model metadata, and produce recommendations; the MCP server and web dashboard read the same local state (notes/PLAN.md:69). Services consume calls to produce evaluations and recommendations without ever rewriting the original telemetry (docs/BLUEPRINT.md:171).

flowchart LR
  A["somm.llm(project=...)"] --> C["SommLLM client"]
  C --> R["Router"]
  R --> P["Provider adapters"]
  C --> DB[("project-local SQLite\n.somm/calls.sqlite")]
  subgraph serve ["Optional: somm serve"]
    W["Background workers\n(model intel, shadow eval, agent)"]
    UI["Web dashboard"]
  end
  W --> DB
  UI --> DB
  W --> REC["Recommendations"]
  MCP["somm-mcp\n(coding-agent tools)"] --> DB

The core bet: local-first, privacy-first, zero-config

Local-first means the database is user-owned. Constructing a repository creates a permission-restricted SQLite file, applies migrations automatically, and configures WAL for continuous local writes with concurrent readers (packages/somm-core/src/somm_core/repository.py:177). Cost tracking works offline from a bundled pricing snapshot shipped inside the wheel (packages/somm-core/src/somm_core/pricing.py:108), and paid intelligence sources stay off the default path (ROADMAP.md:237). CI enforces the speed of this bet mechanically: a performance gate measures clean import latency and a 500-call warmed hot path against a fake provider, failing when medians exceed budget (scripts/check_perf_budget.py:96).

Privacy-first is structural, not aspirational. Prompt and response bodies are stored only through opt-in sampling; databases use owner-only permissions (packages/somm-core/src/somm_core/repository.py:185). Privacy is enforced independently in routing, workers, SQL views, file permissions, and localhost service defaults (docs/threat-model.md:44). A workload registered as private is restricted to local providers — and if none are available, the call fails rather than sending data upstream (examples/private_workload.py:27).

Telemetry is append-only. Intelligence is advisory. Budgets are law. — the design stance, per docs/BLUEPRINT.md:56, packages/somm-core/src/somm_core/pricing.py:240, and docs/errors/SOMM_BUDGET_EXCEEDED.md:23

Workloads, not providers, as the stable identity

This is what makes the intelligence loop possible. The router filters explicitly incapable provider/model pairs before any network access, applies quota pacing, skips cooled-down providers, and falls through transient failures (packages/somm/src/somm/routing.py:158) — but because every one of those decisions is recorded against a workload, the system can later answer "which model actually serves this task best?" with evidence instead of vibes. Recommendations expose their supporting evidence and require the user to apply them; nothing rolls out automatically (docs/BLUEPRINT.md:255).

The six packages at a glance

A uv workspace separates the system into six independently published packages (README.md:528, pyproject.toml:7), each with its own PyPI trusted-publishing environment (.github/workflows/publish.yml:28):

The dependency shape is deliberate: somm-core has no dependencies at all (packages/somm-core/README.md:3), the client keeps the hot path self-hosted, and everything above — service, MCP, LangChain, skill — is optional. Provider dispatch never leaks into the foundation.

By the numbers

How to read this site

The pages follow the data. Start with a single call and follow it outward — through the substrate it lands in, the loop that learns from it, the agents that consume it, and the engineering that keeps it honest.