somm-core 0.6.1__tar.gz

somm_core-0.6.1/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+dist/
+
+# Environments
+.venv/
+.env
+.env.*
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Local Claude session id log (per-machine, not source of truth)
+sessions.txt
+
+# Local data (never commit telemetry)
+.somm/
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+
+# Author-local notes not for open source
+notes/
+.claude/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+
+# Archived internal design/process docs (see docs/BLUEPRINT.md for the public design doc)

somm_core-0.6.1/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: somm-core
+Version: 0.6.1
+Summary: somm shared core — schema, repository, config, parse, version
+Project-URL: Homepage, https://github.com/lavallee/somm
+Project-URL: Repository, https://github.com/lavallee/somm
+Project-URL: Issues, https://github.com/lavallee/somm/issues
+Project-URL: Changelog, https://github.com/lavallee/somm/blob/main/CHANGELOG.md
+Author: Marc Lavallee
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# somm-core
+
+Shared foundation for [somm](https://github.com/lavallee/somm) — the
+self-hosted LLM telemetry, routing, and intelligence loop.
+
+Contains the SQLite schema + migrations, the repository layer, config
+loading, parse helpers (multimodal content blocks, capability
+inference, JSON extraction), pricing (including the bundled offline
+pricing snapshot), and the version constants every somm package
+imports.
+
+You usually want to install [`somm`](https://pypi.org/project/somm/)
+(which depends on this package) rather than somm-core directly.

somm_core-0.6.1/README.md

@@ -0,0 +1,13 @@
+# somm-core
+
+Shared foundation for [somm](https://github.com/lavallee/somm) — the
+self-hosted LLM telemetry, routing, and intelligence loop.
+
+Contains the SQLite schema + migrations, the repository layer, config
+loading, parse helpers (multimodal content blocks, capability
+inference, JSON extraction), pricing (including the bundled offline
+pricing snapshot), and the version constants every somm package
+imports.
+
+You usually want to install [`somm`](https://pypi.org/project/somm/)
+(which depends on this package) rather than somm-core directly.

somm_core-0.6.1/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "somm-core"
+version = "0.6.1"
+description = "somm shared core — schema, repository, config, parse, version"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+readme = "README.md"
+authors = [{ name = "Marc Lavallee" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/lavallee/somm"
+Repository = "https://github.com/lavallee/somm"
+Issues = "https://github.com/lavallee/somm/issues"
+Changelog = "https://github.com/lavallee/somm/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/somm_core"]
+# hatchling includes non-Python package data (migrations/*.sql,
+# data/pricing_bundle.json, py.typed) from the package dir by default.

somm_core-0.6.1/src/somm_core/__init__.py

@@ -0,0 +1,82 @@
+"""somm-core — shared schema, repository, config, parse, version across all somm packages."""
+
+from somm_core.models import (
+    Call,
+    CallOutcome,
+    Decision,
+    EmbedResult,
+    FailureClass,
+    Outcome,
+    PrivacyClass,
+    Prompt,
+    SommResult,
+    ToolCall,
+    Workload,
+)
+from somm_core.plans import (
+    BurnRate,
+    CatalogEntry,
+    LimitStatus,
+    ObservedCeiling,
+    Plan,
+    PlanLimit,
+    limit_statuses,
+    load_catalog,
+    load_plans,
+    observed_ceilings,
+    payg_burn_rates,
+    plan_for,
+    recent_ok_calls,
+)
+from somm_core.pricing import (
+    cost_for_call,
+    list_intel,
+    merge_intel_capabilities,
+    seed_known_pricing,
+    sync_bundled_pricing,
+    write_intel,
+)
+from somm_core.registry import fleet_db_paths, register_project
+from somm_core.repository import Repository
+from somm_core.schema import current_schema_version, ensure_schema
+from somm_core.version import SCHEMA_VERSION, VERSION
+
+__all__ = [
+    "VERSION",
+    "SCHEMA_VERSION",
+    "Repository",
+    "ensure_schema",
+    "current_schema_version",
+    "Call",
+    "CallOutcome",
+    "Decision",
+    "EmbedResult",
+    "FailureClass",
+    "Outcome",
+    "PrivacyClass",
+    "Prompt",
+    "SommResult",
+    "ToolCall",
+    "Workload",
+    "cost_for_call",
+    "list_intel",
+    "merge_intel_capabilities",
+    "seed_known_pricing",
+    "sync_bundled_pricing",
+    "write_intel",
+    "Plan",
+    "PlanLimit",
+    "LimitStatus",
+    "CatalogEntry",
+    "ObservedCeiling",
+    "load_plans",
+    "load_catalog",
+    "plan_for",
+    "limit_statuses",
+    "observed_ceilings",
+    "BurnRate",
+    "payg_burn_rates",
+    "recent_ok_calls",
+    "register_project",
+    "fleet_db_paths",
+]

somm_core-0.6.1/src/somm_core/config.py

@@ -0,0 +1,145 @@
+"""Config loading: env > pyproject.toml > runtime override > defaults.
+
+Minimal v0.1 surface. Expands as features demand.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class Config:
+    project: str = "default"
+    mode: str = "observe"  # "observe" | "strict"
+    db_dir: Path = field(default_factory=lambda: Path("./.somm"))
+    spool_dir: Path = field(default_factory=lambda: Path("./.somm/spool"))
+    ollama_url: str = "http://localhost:11434"
+    ollama_model: str = "gemma4:e4b"
+    ollama_think: bool = False  # Set "think": true on ollama requests (reasoning models)
+    ollama_keep_alive: str = "30m"  # Model residency window; "0" to opt out
+    openrouter_api_key: str | None = None
+    openrouter_roster: list[str] | None = None
+    anthropic_api_key: str | None = None
+    anthropic_model: str = "claude-haiku-4-5-20251001"
+    openai_api_key: str | None = None
+    openai_model: str = "gpt-4o-mini"
+    openai_base_url: str = "https://api.openai.com/v1"
+    minimax_api_key: str | None = None
+    minimax_model: str = "MiniMax-M2.7"
+    deepseek_api_key: str | None = None
+    deepseek_model: str = "deepseek-chat"
+    gemini_api_key: str | None = None
+    gemini_model: str = "gemini-2.5-pro"
+    perplexity_api_key: str | None = None
+    perplexity_model: str = "sonar"  # search-grounded; only used when pinned
+    http_timeout: float = 180.0  # seconds; used by openai-compat providers
+    provider_order: list[str] | None = None  # e.g. ["openrouter", "minimax", "ollama"]
+    busy_timeout_ms: int = 5000
+    cross_project_enabled: bool = False
+    cross_project_path: Path | None = None  # defaults to ~/.somm/global.sqlite
+    budget_fail_closed: bool = False  # hard pre-request gate: block calls once a workload's daily cap is reached
+    budget_default_cap_usd_daily: float | None = None  # daily cap for workloads with no explicit budget_cap_usd_daily (when fail_closed)
+    inprocess_workers: bool = False  # run the somm-service scheduler inside the library process (SOMM_INPROCESS_WORKERS=1)
+
+    @property
+    def db_path(self) -> Path:
+        return self.db_dir / "calls.sqlite"
+
+    @property
+    def global_db_path(self) -> Path:
+        if self.cross_project_path is not None:
+            return Path(self.cross_project_path)
+        return Path.home() / ".somm" / "global.sqlite"
+
+
+def load(project: str | None = None, cwd: Path | None = None) -> Config:
+    """Load config from env + ./pyproject.toml [tool.somm] + defaults.
+
+    Order: defaults < pyproject [tool.somm] < env (SOMM_*) < explicit args.
+    """
+    cwd = cwd or Path.cwd()
+    cfg = Config()
+
+    pyproject = cwd / "pyproject.toml"
+    if pyproject.exists():
+        with pyproject.open("rb") as f:
+            data = tomllib.load(f)
+        somm_cfg = data.get("tool", {}).get("somm", {})
+        for key in ("project", "mode", "ollama_url", "ollama_model"):
+            if key in somm_cfg:
+                setattr(cfg, key, somm_cfg[key])
+
+    env_map = {
+        "SOMM_PROJECT": "project",
+        "SOMM_MODE": "mode",
+        "SOMM_OLLAMA_URL": "ollama_url",
+        "SOMM_OLLAMA_MODEL": "ollama_model",
+    }
+    for env_var, attr in env_map.items():
+        if env_var in os.environ:
+            setattr(cfg, attr, os.environ[env_var])
+    if "OPENROUTER_API_KEY" in os.environ:
+        cfg.openrouter_api_key = os.environ["OPENROUTER_API_KEY"]
+    if "SOMM_OPENROUTER_ROSTER" in os.environ:
+        cfg.openrouter_roster = [
+            m.strip() for m in os.environ["SOMM_OPENROUTER_ROSTER"].split(",") if m.strip()
+        ]
+    if "SOMM_OLLAMA_THINK" in os.environ:
+        val = os.environ["SOMM_OLLAMA_THINK"].strip().lower()
+        cfg.ollama_think = val in ("1", "true", "yes", "on")
+    if "SOMM_OLLAMA_KEEP_ALIVE" in os.environ:
+        cfg.ollama_keep_alive = os.environ["SOMM_OLLAMA_KEEP_ALIVE"].strip()
+    if "SOMM_CROSS_PROJECT" in os.environ:
+        val = os.environ["SOMM_CROSS_PROJECT"].strip().lower()
+        cfg.cross_project_enabled = val in ("1", "true", "yes", "on")
+    if "SOMM_BUDGET_FAIL_CLOSED" in os.environ:
+        val = os.environ["SOMM_BUDGET_FAIL_CLOSED"].strip().lower()
+        cfg.budget_fail_closed = val in ("1", "true", "yes", "on")
+    if "SOMM_INPROCESS_WORKERS" in os.environ:
+        val = os.environ["SOMM_INPROCESS_WORKERS"].strip().lower()
+        cfg.inprocess_workers = val in ("1", "true", "yes", "on")
+    if "SOMM_BUDGET_DEFAULT_CAP_USD_DAILY" in os.environ:
+        with contextlib.suppress(ValueError):
+            cfg.budget_default_cap_usd_daily = float(os.environ["SOMM_BUDGET_DEFAULT_CAP_USD_DAILY"])
+    if "SOMM_GLOBAL_PATH" in os.environ:
+        cfg.cross_project_path = Path(os.environ["SOMM_GLOBAL_PATH"])
+    if "SOMM_PROVIDER_ORDER" in os.environ:
+        cfg.provider_order = [
+            p.strip() for p in os.environ["SOMM_PROVIDER_ORDER"].split(",") if p.strip()
+        ]
+    for env_var, attr in (
+        ("ANTHROPIC_API_KEY", "anthropic_api_key"),
+        ("SOMM_ANTHROPIC_MODEL", "anthropic_model"),
+        ("OPENAI_API_KEY", "openai_api_key"),
+        ("SOMM_OPENAI_MODEL", "openai_model"),
+        ("SOMM_OPENAI_BASE_URL", "openai_base_url"),
+        ("MINIMAX_API_KEY", "minimax_api_key"),
+        ("SOMM_MINIMAX_MODEL", "minimax_model"),
+        ("DEEPSEEK_API_KEY", "deepseek_api_key"),
+        ("SOMM_DEEPSEEK_MODEL", "deepseek_model"),
+        ("GEMINI_API_KEY", "gemini_api_key"),
+        ("SOMM_GEMINI_MODEL", "gemini_model"),
+        ("PERPLEXITY_API_KEY", "perplexity_api_key"),
+        ("SOMM_PERPLEXITY_MODEL", "perplexity_model"),
+    ):
+        if env_var in os.environ:
+            setattr(cfg, attr, os.environ[env_var])
+    if "SOMM_HTTP_TIMEOUT" in os.environ:
+        with contextlib.suppress(ValueError):
+            cfg.http_timeout = float(os.environ["SOMM_HTTP_TIMEOUT"])
+
+    if project is not None:
+        cfg.project = project
+
+    # Resolve paths relative to cwd; caller may also pass explicit paths.
+    cfg.db_dir = (
+        Path(cfg.db_dir).resolve() if cfg.db_dir.is_absolute() else (cwd / cfg.db_dir).resolve()
+    )
+    cfg.spool_dir = cfg.db_dir / "spool"
+
+    return cfg

somm_core-0.6.1/src/somm_core/data/plan_catalog.toml

@@ -0,0 +1,98 @@
+# somm plan catalog — known commercial metered plans and their limits.
+#
+# Plan limits are vendor marketing copy, not an API: as of mid-2026 no
+# major vendor publishes a complete, dated, numeric limits table
+# (MiniMax describes quotas as "agent counts", Anthropic as multipliers,
+# OpenAI hides its weekly cap). Every entry below therefore carries a
+# `source` URL, a `last_verified` date (when a human last checked), and
+# `notes` on provenance. Observed change cadence across vendors is
+# roughly MONTHLY — `somm plans` warns when a referenced entry is >90
+# days old, and RELEASING.md requires re-verification before releases.
+#
+# Where numbers are estimates, notes say so. The most reliable quota
+# signal is your own telemetry: `somm plans` also reports "observed
+# ceilings" — trailing-window usage at the moment of your own
+# quota-429s.
+#
+# Reference an entry from ~/.somm/plans.toml:
+#   [minimax]
+#   mode = "metered"
+#   catalog = "token-plan-max"
+
+[minimax.token-plan-plus]
+display = "MiniMax Token Plan Plus ($20/mo)"
+source = "https://platform.minimax.io/docs/guides/pricing-token-plan"
+last_verified = "2026-07-02"
+notes = "Rebranded from Coding Plan Q1 2026; vendor now describes quota qualitatively ('3-4 agents'). Monthly token figure below was published on the pricing page ~Jun 1-9 2026 then removed — treat as estimate. A 5h window also applies (size undisclosed; EN docs say rolling, CN docs say fixed). Unused quota does not carry over."
+[[minimax.token-plan-plus.limits]]
+window = "month"
+quota = 1633000000
+unit = "tokens_total"
+
+[minimax.token-plan-max]
+display = "MiniMax Token Plan Max ($50/mo)"
+source = "https://platform.minimax.io/docs/guides/pricing-token-plan"
+last_verified = "2026-07-02"
+notes = "'4-5 agents'. Monthly token figure published ~Jun 1-9 2026 then removed — treat as estimate. Undisclosed 5h window also applies."
+[[minimax.token-plan-max.limits]]
+window = "month"
+quota = 5053000000
+unit = "tokens_total"
+
+[minimax.token-plan-ultra]
+display = "MiniMax Token Plan Ultra ($120/mo)"
+source = "https://platform.minimax.io/docs/guides/pricing-token-plan"
+last_verified = "2026-07-02"
+notes = "'6-7 agents'. Monthly token figure published ~Jun 1-9 2026 then removed — treat as estimate. Undisclosed 5h window also applies."
+[[minimax.token-plan-ultra.limits]]
+window = "month"
+quota = 9796000000
+unit = "tokens_total"
+
+[claude-cli.pro]
+display = "Claude Pro ($20/mo)"
+source = "https://support.claude.com/en/articles/11647753"
+last_verified = "2026-07-02"
+notes = "Anthropic publishes NO absolute numbers — limits are 5h rolling sessions plus weekly caps, described only relatively; pool is shared across claude.ai/Desktop/Claude Code. 5h limits doubled May 2026; +50% weekly boost expires 2026-07-13. No limits encoded here: rely on observed ceilings from your own 429s, or set your own from Settings > Usage."
+
+[claude-cli.max-5x]
+display = "Claude Max 5x ($100/mo)"
+source = "https://support.claude.com/en/articles/11049741"
+last_verified = "2026-07-02"
+notes = "'5x Pro'; otherwise identical structure to Pro (see claude-cli/pro). The 'monthly spend limit' 429 message corresponds to the OPT-IN usage-credits cap you set at claude.ai/settings/usage, or was a mid-2026 labeling bug — not a published plan cap."
+
+[claude-cli.max-20x]
+display = "Claude Max 20x ($200/mo)"
+source = "https://support.claude.com/en/articles/11049741"
+last_verified = "2026-07-02"
+notes = "'20x Pro'; see claude-cli/pro and claude-cli/max-5x notes."
+
+[codex-cli.chatgpt-plus]
+display = "ChatGPT Plus ($20/mo) — Codex"
+source = "https://developers.openai.com/codex/pricing"
+last_verified = "2026-07-02"
+notes = "Official ranges per 5h rolling window: GPT-5.5 15-80, GPT-5.4 20-100, mini 60-350 'local messages' (cloud tasks + reviews share the pool). Underlying meter is token credits since Apr 2026. Quota below = GPT-5.5 range midpoint — a coarse approximation. An UNPUBLISHED weekly cap also applies."
+[[codex-cli.chatgpt-plus.limits]]
+window = "5h"
+quota = 48
+unit = "requests"
+
+[codex-cli.chatgpt-pro-5x]
+display = "ChatGPT Pro 5x ($100/mo) — Codex"
+source = "https://developers.openai.com/codex/pricing"
+last_verified = "2026-07-02"
+notes = "GPT-5.5 75-400 per 5h; quota = range midpoint. Unpublished weekly cap also applies."
+[[codex-cli.chatgpt-pro-5x.limits]]
+window = "5h"
+quota = 238
+unit = "requests"
+
+[codex-cli.chatgpt-pro-20x]
+display = "ChatGPT Pro 20x ($200/mo) — Codex"
+source = "https://developers.openai.com/codex/pricing"
+last_verified = "2026-07-02"
+notes = "GPT-5.5 300-1600 per 5h; quota = range midpoint. Unpublished weekly cap also applies. The $200 price is corroborated by secondary sources only; official table shows 'From $100/month'."
+[[codex-cli.chatgpt-pro-20x.limits]]
+window = "5h"
+quota = 950
+unit = "requests"