Agents and Integrations

flowchart LR
    subgraph adopt["Existing code plugs in"]
        shim["OpenAI shim
openai_chat_completions()"]
        compat["GenericLLMCompat
legacy-wrapper drop-in"]
        lc["SommChatModel
LangChain / LangGraph"]
    end
    subgraph agents["Coding agents plug in"]
        mcp["somm-mcp
14 stdio tools"]
        skill["somm-skill
SKILL.md + SOMMELIER.md"]
    end
    gen["SommLLM.generate()
routing / budgets / hooks"]
    db[("project SQLite
calls / evals / decisions")]
    global[("global cross-project
decision repository")]
    shim --> gen
    compat --> gen
    lc --> gen
    mcp -->|"compare / replay"| gen
    skill -. "teaches agents to call" .-> gen
    gen --> db
    mcp <--> db
    mcp -. "best-effort mirror" .-> global
    

Drop-in adoption: the OpenAI shim and legacy-wrapper compat layer

The examples/ area exists to prove a claim: adding somm to an existing Python application should take minimal code changes (examples/README.md:3). It demonstrates two adoption paths, one for codebases with their own LLM wrapper class and one for codebases written against the OpenAI SDK shape.

The OpenAI shim, openai_chat_completions(...), accepts chat-completion arguments and preserves the access pattern existing code depends on — resp.choices[0].message.content still works (examples/openai_swap_in.py:21, examples/openai_swap_in.py:24). Somm-specific metadata is exposed as optional extra attributes on the response, so nothing downstream has to change to ignore it (examples/openai_swap_in.py:36).

The third example shows the privacy machinery working through a shim-shaped call site. A sensitive workload is registered once with PrivacyClass.PRIVATE; every subsequent call using that workload is restricted to local providers (examples/private_workload.py:18, examples/private_workload.py:27).

Once a shim is in place, the accumulated record is inspectable immediately: somm status and somm tail read the telemetry, and somm serve brings up the dashboard (examples/README.md:70, examples/README.md:78).

SommChatModel: LangChain and LangGraph without leaving somm

The translation is bidirectional and careful about tool calling. Going in, assistant tool calls become tool_use blocks and tool results become user-side tool_result blocks, with system prompts passed separately (packages/somm-langchain/src/somm_langchain/chat_model.py:173). Coming back, the somm result becomes an AIMessage inside a ChatGeneration, carrying tool calls, provider/model provenance, latency, cost, outcome, and token usage (packages/somm-langchain/src/somm_langchain/chat_model.py:118). bind_tools() accepts LangChain-compatible tool definitions, normalizes them through OpenAI's common schema, and unwraps them to somm's neutral schema immediately before generation (packages/somm-langchain/src/somm_langchain/chat_model.py:152).

Several small decisions reward attention:

• Failures raise by default, so LangChain retry or circuit-breaker middleware can react; callers can instead request an empty message carrying failure metadata (packages/somm-langchain/src/somm_langchain/chat_model.py:63).
• Pins are optional. Model and provider overrides exist, but absent them, routing stays with somm (packages/somm-langchain/src/somm_langchain/chat_model.py:57).
• Reasoning content is preserved across tool-calling turns, because some thinking-model providers reject subsequent requests without it (packages/somm-langchain/src/somm_langchain/chat_model.py:122).
• Text-only assistant turns collapse to plain strings for interoperability, while mixed text/tool turns keep structured blocks (packages/somm-langchain/src/somm_langchain/chat_model.py:236). Unknown LangChain message subclasses are forwarded as user text on a best-effort basis rather than rejected (packages/somm-langchain/src/somm_langchain/chat_model.py:210).

somm-mcp: telemetry, advice, compare, and replay over stdio

The intelligence-facing tools are layered on evidence, not vibes: somm_recommend combines open recommendations with model rankings from shadow evaluations, and when no evaluation data exists it falls back to model-intelligence candidates and prior decisions (packages/somm-mcp/src/somm_mcp/server.py:117). The execution tools instantiate a real SommLLM with explicit providers, record normal telemetry, and always close the client; replay additionally requires captured samples and refuses private workloads outright (packages/somm-mcp/src/somm_mcp/server.py:663).

Decision memory: record a model choice once, recall it across projects

Most telemetry in somm is per-project. Decision memory is the deliberate exception: when an agent (or a person driving one) commits to a model choice, somm_record_decision writes that judgment locally and best-effort mirrors it to a global cross-project repository, where somm_search_decisions can recall it from any other project on the machine (packages/somm-mcp/src/somm_mcp/server.py:360, packages/somm-mcp/src/somm_mcp/server.py:310).

sequenceDiagram
    participant A as Coding agent
    participant M as somm-mcp
    participant L as Project repository
    participant G as Global repository
    A->>M: somm_search_decisions — recall related prior choices
    A->>M: somm_advise — rank live candidates under constraints
    M->>L: model intelligence + shadow-eval evidence
    A->>M: somm_record_decision — committed choice + rationale
    M->>L: write decision
    M--)G: best-effort mirror (cross-project recall)
  

The three-step sequence — recall, advise, record — is codified as the model-selection lifecycle in SOMMELIER.md: first recall related cross-project decisions, then request ranked live candidates through somm_advise, then record the user's committed choice along with its rationale (packages/somm-skill/src/somm_skill/SOMMELIER.md:17, packages/somm-skill/src/somm_skill/SOMMELIER.md:40, packages/somm-skill/src/somm_skill/SOMMELIER.md:110).

Past model decisions inform recommendations but are deliberately non-authoritative — model intelligence changes. — design note, packages/somm-skill/src/somm_skill/SOMMELIER.md:36

That stance matters. A decision recorded in April against last quarter's pricing and capability data should shape, not dictate, a choice made in July. The recall step surfaces precedent; the advise step re-ranks against current evidence; only then is a new decision recorded.

somm-skill: teaching coding agents to instrument their own calls

SKILL.md is the operating manual: create a client with somm.llm(), tag every generation with a stable workload, register that workload with privacy and budget controls, and mark results with typed outcomes (packages/somm-skill/src/somm_skill/SKILL.md:24, packages/somm-skill/src/somm_skill/SKILL.md:44, packages/somm-skill/src/somm_skill/SKILL.md:103). It encodes operational judgment too — CLI subscription seats are pinned-only, preserving scarce quota for grading and low-volume work rather than exposing it to hot-loop routing (packages/somm-skill/src/somm_skill/SKILL.md:124). Because it ships as plain package resources, the same guidance travels to Claude, Codex, Cursor, Windsurf, and other agent packaging formats (packages/somm-skill/README.md:34).

Together, the skill and the MCP server close a loop the earlier pages set up: agents write instrumented calls (skill), those calls accumulate into evidence (substrate), workers turn evidence into recommendations (intelligence loop), and the same agents read the recommendations back and record their choices (MCP). Each surface is separable; none is required for the one before it to work.

Where to go next