somm-skill 0.6.1__tar.gz

somm_skill-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_skill-0.6.1/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: somm-skill
+Version: 0.6.1
+Summary: somm onboarding skill templates for coding agents (Claude, Codex, Cursor, Windsurf)
+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-skill
+
+Onboarding guidance for coding agents working in projects that use `somm`.
+
+`SKILL.md` is the canonical content — a Claude Code skill. Agent-specific
+variants (Codex, Cursor, Windsurf, …) live under `templates/` and are derived
+from the same core guidance.
+
+## Installation
+
+For Claude Code:
+
+```bash
+mkdir -p ~/.claude/skills/somm
+cp packages/somm-skill/SKILL.md ~/.claude/skills/somm/SKILL.md
+```
+
+Or, once `somm mcp install --client=claude-code` lands in D2:
+
+```bash
+somm mcp install --client=claude-code   # installs MCP + skill in one step
+```
+
+For other agents:
+
+- **Cursor:** copy `templates/cursor.md` into `.cursor/rules/` in your project.
+- **Windsurf:** copy `templates/windsurf.md` into `.windsurf/rules/`.
+- **Codex:** copy `templates/codex.md` into your project's Codex config.
+
+(Agent-specific templates ship in D2+; v0.1 has only the canonical `SKILL.md`.)

somm_skill-0.6.1/README.md

@@ -0,0 +1,30 @@
+# somm-skill
+
+Onboarding guidance for coding agents working in projects that use `somm`.
+
+`SKILL.md` is the canonical content — a Claude Code skill. Agent-specific
+variants (Codex, Cursor, Windsurf, …) live under `templates/` and are derived
+from the same core guidance.
+
+## Installation
+
+For Claude Code:
+
+```bash
+mkdir -p ~/.claude/skills/somm
+cp packages/somm-skill/SKILL.md ~/.claude/skills/somm/SKILL.md
+```
+
+Or, once `somm mcp install --client=claude-code` lands in D2:
+
+```bash
+somm mcp install --client=claude-code   # installs MCP + skill in one step
+```
+
+For other agents:
+
+- **Cursor:** copy `templates/cursor.md` into `.cursor/rules/` in your project.
+- **Windsurf:** copy `templates/windsurf.md` into `.windsurf/rules/`.
+- **Codex:** copy `templates/codex.md` into your project's Codex config.
+
+(Agent-specific templates ship in D2+; v0.1 has only the canonical `SKILL.md`.)

somm_skill-0.6.1/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "somm-skill"
+version = "0.6.1"
+description = "somm onboarding skill templates for coding agents (Claude, Codex, Cursor, Windsurf)"
+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_skill"]

somm_skill-0.6.1/src/somm_skill/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: somm
+description: Use when writing or modifying LLM-calling code in a Python project. Guides you to `somm.llm()` instead of raw provider SDKs, keeps telemetry and provenance consistent across projects, and surfaces model recommendations grounded in real local telemetry.
+---
+
+# somm — LLM call guidance for coding agents
+
+You are working in a Python project that uses **somm**, a self-hosted LLM
+telemetry + routing layer. This skill ensures the code you write records
+useful telemetry and benefits from somm's intelligence loop.
+
+## When this applies
+
+Trigger when you are about to:
+- Call an LLM (chat completion, embedding, structured output, streaming).
+- Add a new LLM-using feature or endpoint.
+- Refactor an existing LLM wrapper in the project.
+- Choose between models or providers.
+- Tune a prompt.
+
+## Rules
+
+### 1. Use `somm.llm()` — not raw provider SDKs
+
+```python
+import somm
+
+llm = somm.llm(project="my-project")
+result = llm.generate(
+    prompt="Extract contacts from the text below...",
+    workload="contact_extract",        # required — tags telemetry
+    max_tokens=256,
+)
+print(result.text)
+```
+
+Do **not** reach for `anthropic.Anthropic()`, `openai.OpenAI()`, raw `httpx`,
+or provider-specific SDKs directly in project code. somm wraps them with
+telemetry, routing, cost tracking, and provenance for free.
+
+### 2. Tag every call with a `workload`
+
+A workload is the *task*, not the call. "extract_contacts_from_article" is a
+workload; "call_anthropic" is not. Use snake_case, lowercase, stable across
+time.
+
+Register workloads before use (outside the hot path):
+
+```python
+# run once per workload, at app startup or in a migration
+somm.llm().repo.register_workload(
+    name="contact_extract",
+    project="my-project",
+    description="Pull person names + emails from unstructured text",
+    privacy_class=somm.PrivacyClass.INTERNAL,
+)
+```
+
+In `observe` mode (default) somm auto-registers unknown workloads and warns.
+In `strict` mode it raises `SommStrictMode`.
+
+### 3. Stamp provenance on stored data
+
+When an LLM result lands in your project's DB, stamp the provenance on the
+row:
+
+```python
+row["llm_provenance"] = {
+    "call_id": result.call_id,
+    "provider": result.provider,
+    "model": result.model,
+    "workload": "contact_extract",
+}
+```
+
+This lets you later answer "which model generated this row" without guessing.
+
+### 4. Check outcomes
+
+`somm.Outcome` is a typed enum. Use `result.mark()` to tag quality signals:
+
+```python
+data = somm.extract_json(result.text)
+if data is None:
+    result.mark(somm.Outcome.BAD_JSON)
+elif not data.get("contacts"):
+    result.mark(somm.Outcome.OFF_TASK)
+else:
+    result.mark(somm.Outcome.OK)
+```
+
+### 5. Before choosing a model, ask somm
+
+When `somm_recommend` or `somm_advise` is available, call one of them
+before hand-picking a model. somm has telemetry from your real
+workloads + pricing/capability intel from the provider APIs — it knows
+more than your training data does. Do not default to "Claude because
+that's what the user asked for." Ask which model fits the workload's
+cost/quality profile *as of today*.
+
+For free-form model advice ("what vision model should I use?",
+"cheapest option for long context?"), the dedicated [sommelier
+skill](./SOMMELIER.md) covers the full recall → advise → record loop
+with cross-project decision memory. Load it when the conversation
+shifts from coding to model choice.
+
+### 6. Streaming and structured output
+
+- `llm.stream(prompt, workload=...)` for streamed responses.
+- `llm.extract_structured(prompt, workload=...)` returns `dict | list`,
+  handling markdown fences, brace extraction, and provider quirks.
+
+Do **not** implement your own JSON repair loop. somm already has one.
+
+### 7. Never ship these patterns
+
+- **Raw provider SDK imports** (`from anthropic import ...`) in project code.
+- **Hardcoded model names** outside config — route via workload + provider preference.
+- **Inline retry loops** — routing handles cooldowns and fallback.
+- **Prompt concatenation as strings** for long-lived prompts — use
+  `somm.prompt(workload, version="latest")` (D2+) so versions are tracked.
+- **API keys in code or logs** — somm's adapters strip auth headers before
+  any telemetry write. Keep it that way.
+
+## When somm-service is running
+
+If `somm serve` is running (usually `localhost:7878`), you can link to it in
+PR descriptions or error messages: the dashboard shows the current call's
+place in the workload's rollup. The service is optional — the library works
+without it.
+
+## When the MCP is connected
+
+If the user has configured `somm-mcp` in this agent, you can call:
+- `somm_stats` — telemetry roll-up for the current project.
+- `somm_recommend` — model recommendations grounded in local shadow-eval
+  data, with cold-start sommelier fallback when data is sparse.
+- `somm_advise` — free-form candidate ranking over `model_intel` +
+  capability filters + past decisions. See [SOMMELIER.md](./SOMMELIER.md).
+- `somm_record_decision` / `somm_search_decisions` — cross-project
+  advisory memory for model choices.
+- `somm_compare` — run a prompt through N models side-by-side.
+- `somm_replay` — replay a past call against a different model.
+
+Call these *before* deciding on a model for new LLM code.
+
+## If you can't use somm
+
+If the project intentionally doesn't use somm (e.g., a pre-existing integration
+test harness with its own LLM stub), don't force it. But:
+- Note this in a PR comment so the user can decide later.
+- Still stamp `somm.provenance()`-shaped metadata on stored rows if feasible
+  — the schema is self-documenting.

somm_skill-0.6.1/src/somm_skill/SOMMELIER.md

@@ -0,0 +1,170 @@
+---
+name: somm-sommelier
+description: Use when the user asks for model advice ("what should I use for X", "good vision models", "cheapest option for long-context") or is choosing between providers/models for an LLM workload. Consults somm's local model intel + prior cross-project decisions, presents ranked options with reasoning, and records the outcome so future sessions can build on it.
+---
+
+# somm sommelier — model advisor for coding agents
+
+You are helping the user pick a model for a specific use case. somm has
+local model-intel and a cross-project memory of past decisions — use them
+instead of guessing from your training data.
+
+This skill assumes `somm-mcp` is configured as an MCP server in this
+agent. The relevant tools are `somm_advise`, `somm_record_decision`,
+`somm_search_decisions`, plus the existing `somm_recommend`,
+`somm_compare`, and `somm_stats`.
+
+## The loop
+
+Three phases: **recall → advise → record**.
+
+### 1. Recall
+
+Before recommending anything, call `somm_search_decisions` with the
+user's question. If somm already has a decision for a substantively
+similar question — from any project — surface it first. The user may
+want to reuse, revisit, or supersede it.
+
+```
+somm_search_decisions(
+    question="good free vision models on openrouter",
+    scope="global",            # decisions mirror globally by default
+    limit=5,
+)
+```
+
+Do not treat past decisions as authoritative — model intel changes. But
+*do* acknowledge them: "Last time in `captionapp` (2026-04-10) we picked
+`openrouter/gemma-3-27b-it:free` because … — still relevant?"
+
+### 2. Advise
+
+Call `somm_advise` with the user's constraints extracted from the
+conversation:
+
+```
+somm_advise(
+    question="good free vision models on openrouter",
+    capabilities=["vision"],
+    providers=["openrouter"],
+    required_output_modalities=["text"],   # for captioning — excludes audio-gen
+    free_only=True,
+    workload="critique_visual",    # optional — boosts ranking with shadow-eval scores
+    limit=8,
+)
+```
+
+The response carries ranked candidates with `reasons` — a list of
+human-readable factors the sommelier weighed. Present them verbatim
+rather than restating in your own words; the reasons are
+tokenisation-light and calibrated.
+
+**0.2.2 constraint knobs (all optional):**
+
+- `required_output_modalities` — drop candidates whose output modality
+  isn't in this set. Pass `["text"]` for captioning / QA workloads to
+  exclude audio-gen or image-gen models that happen to accept image
+  inputs. `["image"]` for generation.
+- `exclude_models` — fnmatch-style patterns against
+  `"<provider>/<model>"`. Inline blocklist when you hit a bad candidate
+  without waiting for a release.
+- `include_meta_routers` — off by default. Router meta-models
+  (`openrouter/auto`, `openrouter/free`) pick a backend at inference
+  time, so they're non-deterministic and inherit capability claims from
+  whatever they route to. Opt in only when you specifically want one.
+- `unknown_capability_penalty` — `0.9` by default. Models with
+  confirmed capabilities outrank models where we can't confirm. Set to
+  `1.0` to preserve pre-0.2.2 behavior (unknown == known-yes).
+
+**Guidelines for turning the response into a conversation:**
+
+- Show the top 3 with their reasons, not all 8.
+- When shadow-eval data exists (`shadow_score` is not null), lead with
+  that — it's the only candidate-level quality signal somm has.
+- If `prior_decisions` came back, cite them alongside the live
+  candidates: "Candidate X matches what we picked in project Y." Note
+  that as of 0.2.2 the sommelier also *weighs* matching priors into the
+  score — you'll see `prior(<project> <date>): chose — ×1.10` or
+  `flagged — ×0.50` in the reasons list. Weight decays with age
+  (half-life ~90 days).
+- If `candidates` is empty, read `note` — 0.2.2 returns a filter
+  breakdown like "Filtered out: 3 wrong output modality, 2 meta-router"
+  that tells you exactly which constraint to loosen.
+
+### 3. Record
+
+When the user commits to a choice ("let's go with X", "do that"), call
+`somm_record_decision` immediately. Do NOT wait for the end of the
+session; decisions are the advisory memory other sessions inherit.
+
+```
+somm_record_decision(
+    question="good free vision models on openrouter",
+    rationale="Picked gemma-3-27b because it has the biggest context
+               window among free vision models and matches the
+               chart-critique workload profile",
+    candidates=<candidates list from somm_advise, verbatim>,
+    chosen_provider="openrouter",
+    chosen_model="google/gemma-3-27b-it:free",
+    workload="critique_visual",
+    constraints=<constraints dict from somm_advise response>,
+    agent="claude-code",
+)
+```
+
+Rationale is the single most valuable field. Keep it short (≤ 3
+sentences) and capture the *reason* (not just the summary — "picked X
+because Y beats Z on …"). Future sessions read this.
+
+## When NOT to use sommelier
+
+- **Hard user intent.** If the user says "use Claude Haiku", don't
+  pop up a candidate list. Just record a decision with rationale
+  "user-specified" if it's a new choice worth remembering.
+- **Inside a hot loop.** Sommelier is for choices, not for every call.
+  Once a workload has a chosen model, put it in the workload's default
+  and move on.
+- **Private workloads.** Decisions themselves don't leak prompt bodies,
+  but if the *question text* contains sensitive info, phrase the
+  question abstractly ("pick a model for sensitive-workload-X") rather
+  than verbatim.
+
+## Retrospectives
+
+If the user reports back later ("the gemma-3 pick wasn't great — kept
+missing colour contrasts"), search for the original decision and call
+`mark_decision_outcome` (surfaced via `somm_record_decision` with
+`supersedes=<id>` once that lands, or via the repository directly in
+the interim). A retrospective note on a decision is how the memory
+self-corrects.
+
+## Example conversation shape
+
+> **User:** I need to add chart screenshots to the critique flow. What
+> vision model should I use? Free would be ideal.
+>
+> **Agent:** *(calls `somm_search_decisions(question="vision model for
+> chart critique", scope="global")`)* — no prior decisions found.
+>
+> *(calls `somm_advise(question="...", capabilities=["vision"], free_only=True)`)*
+>
+> Here are the three strongest candidates somm knows about right now:
+>
+> - `openrouter/google/gemma-3-27b-it:free` — free, 128k ctx, vision✓, seen today
+> - `openrouter/meta-llama/llama-3.2-11b-vision-instruct:free` — free,
+>   128k ctx, vision✓
+> - `ollama/llava:13b` — free (local), vision✓
+>
+> The gemma option has the widest context window, which helps if the
+> chart comes with a lot of surrounding text. The ollama option keeps
+> the data on your machine — which matters if the workload might end up
+> `privacy_class=PRIVATE`. Which trade-off fits?
+>
+> **User:** Let's try gemma-3 first.
+>
+> **Agent:** *(calls `somm_record_decision(...)` with rationale "picked
+> gemma-3-27b for chart critique — biggest free vision context; keep
+> llava as fallback if privacy constraints tighten")*
+>
+> Recorded. Decision id: `<uuid>`. This will surface next time
+> anyone — in this project or another — asks a similar question.

somm_skill-0.6.1/src/somm_skill/__init__.py

@@ -0,0 +1 @@
+"""somm-skill — onboarding skill content + templates for coding agents."""