Engineering Reference

Everything on this page is machinery that exists to keep one promise: the library stays zero-config, fast, offline-capable, and private, no matter who is committing. The workspace layout, the CI gates, the release gate, and the test isolation fixtures are all enforcement mechanisms for that promise.

Workspace layout: six packages, one shared version

graph TD
  somm["somm — client, router, CLI"] --> core["somm-core — records, SQLite, pricing, quotas"]
  service["somm-service — dashboard, proxy, workers"] --> core
  mcp["somm-mcp — agent tools over stdio"] --> somm
  mcp --> core
  lc["somm-langchain — chat-model adapter"] --> somm
  skill["somm-skill — agent onboarding docs, no dependencies"]
    

The whole workspace moves as one version. Releases bump every package together (RELEASING.md:8), and a standard-library-only script enforces it: scripts/check_release_gate.py loads every package's pyproject.toml, requires a single shared version, verifies that somm_core.VERSION matches, and checks that internal somm/somm-core dependency pins are exact (scripts/check_release_gate.py:23, scripts/check_release_gate.py:54, scripts/check_release_gate.py:71). Underneath it all sits the migration-backed database: schema v20 evolves the original workload/prompt/call ledger into decisions, workload revisions, datasets, evaluation receipts, campaigns, canonical model aliases, and serving SLOs (packages/somm-core/src/somm_core/version.py:7).

CI gates: lint, tests on 3.12/3.13, pip-audit, and the perf budget

The performance gate protects the hot path the whole project is built around. It measures clean import somm latency in fresh subprocesses, then exercises a warmed SommLLM.generate() path 500 times against a fake provider and a temporary repository — isolating somm's own overhead from network and provider latency (scripts/check_perf_budget.py:52, scripts/check_perf_budget.py:69, scripts/check_perf_budget.py:22).

Human process backs the automation: the PR template requires contributors to confirm tests, the blocklist guard, lint status, changelog handling, and coordinated versioning (.github/PULL_REQUEST_TEMPLATE.md:5), and CONTRIBUTING.md requires tests plus an Unreleased changelog entry with every change (CONTRIBUTING.md:28).

Release discipline: the version gate, trusted publishing, and rerunnable publishes

Two small decisions make multi-package publishing survivable. Each package builds into its own artifact directory, because workspace-member builds would otherwise all write into the root dist/ (.github/workflows/publish.yml:54). And skip-existing means a release that failed halfway through six packages can simply be rerun — already-published packages are skipped rather than erroring (.github/workflows/publish.yml:63).

Before any of that, the release gate runs — the same check_release_gate.py used in CI, written against only the standard library so it works before dependencies are even installed (scripts/check_release_gate.py:1). Beyond version consistency, releases with major version 1 or higher additionally require a committed approval marker (scripts/check_release_gate.py:82); RELEASING.md frames this as an explicit readiness file required before any 1.x publication (RELEASING.md:94). The release process also refreshes bundled pricing and plan data and updates agent-skill documentation (RELEASING.md:28).

Test strategy: isolated machine state, offline pricing, and the blocklist scanner

Configuration tests pin down zero-config behavior precisely: they clear the relevant environment variables, call somm_core.config.load(), and verify defaults plus precedence among explicit environment settings, pyproject.toml, an existing project-root .somm, the project registry, and a fresh local .somm directory (tests/test_config_load.py:44). Local project state wins over registry reuse, an explicit SOMM_DB_DIR wins over everything tested, and registry reuse is announced on stderr so telemetry is never silently shared (tests/test_config_load.py:78, tests/test_config_load.py:102, tests/test_config_load.py:135).

Pricing tests keep cost accounting honest offline. The packaged JSON snapshot — regenerated by scripts/update_pricing_bundle.py, which normalizes LiteLLM data to per-million-token prices and prunes it to routes somm supports (scripts/update_pricing_bundle.py:71) — must cover every paid routed provider and populate model intelligence with no network access (tests/test_pricing_bundle.py:38, tests/test_pricing_bundle.py:47). Bundle sync replaces stale seeded data but preserves manually entered prices, and a fingerprint skips repeat work (tests/test_pricing_bundle.py:66, tests/test_pricing_bundle.py:84). A missing price yields zero cost plus a once-per-provider/model warning for paid providers, while free providers stay silent (tests/test_pricing_safety.py:87, tests/test_pricing_safety.py:101, tests/test_pricing_safety.py:115).

CLI quick reference: generate, status, doctor, compare, serve

The somm CLI spans generation, status, workloads, prompts, evals, campaigns, plans, diagnostics, and service startup (README.md:330). These are the commands contributors and bug reporters reach for most:

Canonical errors: the SOMM_* catalog

The budget error is the catalog's clearest expression of the project's design philosophy: auxiliary intelligence — hooks, mirroring, learned overrides — fails open so it can never break live inference, but hard budgets deliberately fail closed before any provider is contacted (packages/somm/src/somm/hooks.py:246, packages/somm/src/somm/client.py:571).

Where to go next