Sous

Sous is Valio Aimo's front door for AI purchasing agents. A hotel's, hospital's or school's agent searches the catalog over MCP or REST, gets a quote signed by the gateway with live Valio price and availability, and orders under a mandate its buyer set. The customer stays in control, and autonomy is earned: plain code puts every order in one of four tiers (auto, auto + FYI, needs approval, refused), no language model ever approves an order or relaxes a rule, and the agent gets more freedom only when the buyer accepts it.

Built at Junction 2026 for Valio Aimo's challenge "Trusted Trade Agents".

The flow, in Valio's four steps:

1. Request. The agent states what the buyer needs (amount, unit, date, what it is for) under the buyer's signed mandate (valtakirja).

2. Lookup. Search over 17,546 products (fi/sv/en) on a local index, no API calls; live price and availability for a shortlist only, at most 2 batched Valio calls per quote.

3. Order. A signed quote (pack sizes, VAT, cut-offs, stock as ample/limited/short) is ordered once, at that price; the mandate engine decides the tier and names the rule.

4. Approval. A held order reaches the buyer's phone with an approve-by time (earliest cut-off minus 15 min); routine orders go through and are logged.

What keeps the buyer in control:

• Only an authenticated person of the buyer approves. Held orders are decided on the buyer side with the approver code or a passkey; agents get 403 (audited), the claude.ai connector refuses an approver token, and Valio staff see held orders read-only.

• No agent can become its own approver. Passkeys are enrolled only with the buyer's own credential, never by whoever opens a link first; a passkey approval signs this order at this total, including any "remember this" choice.

• Autonomy is earned and can be taken back. After 5+ unchanged approvals over 2+ weeks for one rule and product type, Sous proposes ask → notify with the evidence; the buyer accepts it as a re-signed mandate, and a later rejection proposes the revert. Never allergens or spend limits (PROTOCOL 7.2).

• The right product for its use. Skimmed milk for a dessert or coffee cream for whipping is held with a fitting alternative; a substitute is judged by use (another brand of whipping cream for a dessert asks, coffee cream for coffee doesn't).

• Needs change mid-contract. A ward goes nut-free: standing, held and upcoming orders and remembered approvals are re-checked and conflicts held.

• Buyer controls. Four-eyes (the requester can't approve), a cap on a substitute's price premium, and doubts the agent declares always reach a human (PROTOCOL 7.3).

• A record both sides can check. Every rule at /rules (en/fi), signed quotes and receipts (Ed25519 JWS; the order card inside Claude checks the signature itself, see /ui/cards.html), a hash-chained audit log plus MariaDB system versioning: what the mandate said when each order was decided.

Try it: watch agents order live at sous.saarikko.dev · try it in the browser in 5 minutes, nothing to install or paste: /ui/try.html (one click makes your sandbox; the agent orders, you approve, you check the log; your own Claude connects from the same page) · the same by curl: docs/pitch/try-it.md · approve as the buyer: /ui/buyer.html · try six attacks: /ui/break.html · in claude.ai add the connector https://sous.saarikko.dev/connect/mcp and press "Create a demo sandbox and connect" (on staging now, https://staging.sous.saarikko.dev/connect/mcp, until production is redeployed; you get the approver token, the assistant only the agent token; other clients: docs/CONNECT.md) · honest numbers, held-out set included: docs/STATUS.md.

Download a verification bundle from an order in the reference buyer, then verify it with independently trusted public keys (Node 22+, no dependencies):

node scripts/verify_buyer_bundle.mjs order-proof.json trusted-jwks.json
node scripts/verify_buyer_bundle.mjs --tamper order-proof.json trusted-jwks.json

The second command demonstrates rejection of an altered receipt and preserves the saved proof.

Judge path in 5 minutes

The demo server is production, https://sous.saarikko.dev, set as SOUS below (the earlier 135-181-8-209.sslip.io and staging.135-181-63-134.sslip.io names still work). It is redeployed from main until the Sun 15.11 08:00 Helsinki freeze. Staging, https://staging.sous.saarikko.dev, is the fallback if production is ever down and usually runs newer code (on Sat 14.11 14:11Z /health showed prod at cdb7670, staging at ede8518); docs/STATUS.md says what runs where. Needs curl and jq.

Dates: Valio's mock gives Stock products a cut-off of Sun 15.11 17:00 for Monday delivery. After that the quickstart's Monday date is refused (availability.cutoff_passed) unless the server runs the disclosed demo clock (SOUS_DEMO_NOW, PROTOCOL.md section 21; shown in /health as clock.mode) or you ask for a later date.

1. Get a private sandbox: copies of the hotel, hospital and school mandates, valid 24 h, 15 live Valio lookups. The two tokens in the response are shown once.

   export SOUS=https://sous.saarikko.dev
   curl -s -X POST $SOUS/sandbox | tee sandbox.json | jq '{sandbox, mandates: [.mandates[] | {mandate_id, rules}]}'

2. Run the quickstart: the response's quickstart.curl_quote gets a signed quote for 100 L of lactose-free milk for the hotel, and quickstart.curl_order orders it.

   Q=$(jq -r .quickstart.curl_quote sandbox.json | sh | jq -r .quote.id)
   jq -r .quickstart.curl_order sandbox.json | sed "s/<quote.id>/$Q/g" | sh | jq 'if .error then . else {id, status, tier: .decision.outcome, rules: [.decision.findings[].rule]} end'

   Within the hotel's limits it is ordered, tier silent (auto), rule mandate.ok. Every finding carries a rule_url. The idempotency key is your sandbox id plus the quote id: run the order line again and you get the same order back, not a second one. Keys are scoped per agent, so no two judges clash.

3. Approve a held order as the human: every new sandbox is seeded with a hotel standing order (four weeks of simulated history, milk creeping up) and this week's renewal already held for approval by the drift rules (standing.quantity_creep, standing.quantity_trend, standing.cost_drift); seeded in the response names it. It is priced from reference prices stored in the gateway, not a live Valio quote, and says so on the order; creating the sandbox makes no Valio call. Open the seller inbox, paste approver_token when it asks for the approver code, and approve or reject. The token works only on your sandbox's orders.

   jq '.seeded | {held_order_id, why, reasons}' sandbox.json
   jq -r .quickstart.seller_ui sandbox.json     # $SOUS/ui/?sandbox=SBX-....#/inbox

4. Check the rules and the audit chain:

   curl -s $SOUS/rules | jq '.tiers, .count'                 # every rule: id, owner, tiers, plain text
   curl -s $SOUS/audit/verify | jq                           # recomputes the hash chain: "ok": true, events, head
   curl -s "$SOUS/audit?sandbox=$(jq -r .sandbox.id sandbox.json)&limit=5" \
     -H "Authorization: Bearer $(jq -r .agent_token sandbox.json)" | jq '.events[] | {seq, event, hash, prev_hash}'

5. Connect an MCP client to $SOUS/mcp with the agent token, then paste one of the four prompts. Prices and stock are live, so products and totals vary; each prompt's expect says which tier and rule to look for: hotel milk (usually ordered with an FYI, spend.notify), hospital substitute (held for a human, substitution), past the cut-off (refused after the cut-off, availability.cutoff_passed), school over budget (refused above €1,500, spend.hard_limit).

   jq -r .quickstart.claude_code sandbox.json | sh   # claude mcp add --transport http sous $SOUS/mcp --header "Authorization: Bearer <agent_token>"
   jq -r '.prompts[] | .title, .prompt, ""' sandbox.json

   From claude.ai, Claude Desktop or ChatGPT instead: add a custom connector with URL $SOUS/connect/mcp, press Connect and paste the agent_token on the Sous sign-in page (OAuth; never the approver token). Cursor, VS Code and the details: docs/CONNECT.md.

Evaluation, as docs/STATUS.md states it. Held-out (LLM_EVAL.md, CI 43620135327): 15 buyer requests written blind before reading the code, Gemini 4 Hydrogen + Sous agent, 3 runs each: 0 false auto-approvals, 9/9 unsafe requests stopped (all by the gateway, the agent placed every one), but only 3/36 should-order runs matched the need (one item per request, headcounts read as pack counts). After the fixes, held-out set 2 (LLM_EVAL.md, CI 43628767992, 20 new blind requests x 3 runs, run once): again 0 false auto-approvals, 12/12 should-hold held or refused; wrong dates 12 -> 0, expected lines at the right amount 10/96 -> 73/167, dishes cookable 0/9 -> 5/9; whole requests matched with no correction still 3/48 (stock on hand read as an order, long Finnish lists merged, counts as cartons), but 27 of those runs waited for a human instead of shipping a guess and 3 went through alone (a starch as thickener, findings). The rest are our own cases. From one full CI run on CRACI, 43587725624 on f31967b: scripted cases (no LLM, live Valio prices) 60/60, 43/43 unsafe actions blocked or escalated; LLM buyer agent on 48 one-sentence cases: Kimi K3.1 Pro (Verda Inference) 47/48, Gemini 4 Hydrogen 46/48, Nemotron 3.5 Super VL 30/48, with 0 mandate violations auto-ordered by any of them (unsafe requests blocked or escalated 34/34, 34/34, 33/34); mandate drafting by Gemini 23/23. Conformance kit 17/17 on staging (CONFORMANCE.md); check-the-checker catches 47/47 planted violations (EVAL_INTEGRITY.md); Monday rush, 60 agents on 400 units of stock: 0 over-allocated (ROBUSTNESS.md). Recipe planner, 7 menus (CI 43595658113, after the R05 crash fix): recipe table 7/7, Gemini 5/7, Kimi 5/7, every miss a quantity outside our 35 % bar. Red team on a Verda GPU (REDTEAM.md, 01480fd): 2,000 generated requests through a self-hosted Qwen3-30B-A3B (vLLM), 976/997 unsafe held or refused; it found 3 order-slicing misses in the gateway (demo mandates had the split window off), fixed with a 60-minute split window (ad366ce; Gemma 4 re-run on 100 slicing requests: 0 gateway violations). Spend so far: $56.01 known (COSTS.md).

Related MCP server: AchPay

Valio's brief → where it is in Sous

Where to read more

• docs/pitch/try-it.md: the sandbox walk-through as a one-page handout.

• docs/STATUS.md: what works, what is deployed where, evaluation with run ids, assumptions, open questions.

• docs/PROTOCOL.md: the full protocol. Start with 6. Tiers and rules, 12. Audit log and 18. Judge sandbox.

• docs/DECISIONS.md: technical choices and the path to production.

• docs/INTEGRATION.md: how Sous plugs into Valio Aimo's systems: orders to SAP (ORDERS05 outbox, stub today), customer accounts (credit limit, payment block, delivery days), contract prices, routes, a phased plan, and what we don't know.

• docs/CONFORMANCE.md: one command (scripts/conformance.py --base <url>) runs 17 black-box checks (signatures, tampering, idempotency, self-approval, private reads, hard limit, prompt injection, audit, stock exposure) against any Sous gateway; 17/17 on staging, run output included.

• docs/STANDARDS.md: mapping to AP2, ACP, A2A, MCP server cards, schema.org, W3C VC 2.0, JOSE, and Peppol BIS Ordering 3.0 (UBL Order and Order Response per order).

• docs/EVAL_INTEGRITY.md: checking the checker, 47 planted violations the evals and verifiers must catch.

• docs/ROBUSTNESS.md: the Monday rush, 60 agents on one short product, stock reservations and fair share.

• docs/CAPACITY.md: measured capacity of one gateway process (4 CPUs, MariaDB, Valio replayed): ~23 req/s, ~3 orders/s; the bottleneck and the scale-out plan.

• docs/CRACI.md: CI on CRACI runners, deny-by-default egress per job and the signed egress evidence.

• docs/COSTS.md: every paid model run and running service.

• docs/LLM_EVAL.md (per-model LLM eval, case by case), docs/CI.md, docs/VERDA.md, docs/GEMINI.md, docs/NEMOTRON.md, docs/AIVEN.md, docs/demo-runbook.md.

• The rest of this README: features, API table, local setup, configuration, architecture.

What it does

• Search 17,546 products in Finnish, Swedish and English, with filters for claims, allergens, labels, temperature and country of origin. Search uses a local index and costs no Valio API calls. Type-aware ranking (9eb15ec): 'laktoositon maito' ranks plain lactose-free milk above coffee milk; precision@3 90.5 % → 99.3 % on our own 49 tuning queries.

• Signed quotes with live price and availability for a shortlist only: 2 batched Valio API calls per uncached quote, 2 more when an item is short and substitutes are priced for the options (1.0 on average with the cache in evals/results.json). Pack and lot sizes, VAT, cut-offs, stock vs Terminal, delivery reliability, CO₂ estimate, splits when stock is short.

• Mandate engine in plain code. Every order lands in one tier: silent, notify, ask or block, with the rule that fired.

• What always needs a human in the demo mandates: a substitute for what was asked, a product the buyer has never bought before, a unit price more than 20 % off the last price paid, and anything past the daily or weekly budget or that several small orders add up to past the auto-approve limit. Valio Aimo can pause all agent ordering (every buyer or one buyer) with one call; nothing is ordered or approved until it resumes.

• Autonomy levels, capped by Valio Aimo: a mandate lets its agent advise only, reorder the buyer's usual products, or order; Valio can cap any buyer (or all) lower with one call, and held orders name Valio's reason.

• Order cards in the chat (MCP Apps): in Claude (web, desktop, phone) every quote, order, substitute and renewal arrives as a card under the tool call, served by the gateway (ui://sous/card.html): lines, totals, the mandate's decision rule by rule, the approval link for the buyer's person, and the gateway's Ed25519 signature checked inside the chat. Without Claude: /ui/cards.html draws real demo orders with the same card.

• Lost demand, Valio's view (/stats/lost-demand, stats page): the value of orders Valio couldn't supply vs ones the buyer's rules refused or a human declined, quantities no product covered, and why products were passed over (cut-off, stock, holds).

• Peppol BIS Ordering 3.0: every order as a UBL Order and Valio's Order Response (accepted / held / rejected) at /orders/{id}/peppol/order.xml and /order-response.xml, for buyers' ERP and e-procurement systems. Validated against the official UBL 2.1 XSD and OpenPeppol BIS schematron in CI (9e5ed51).

• Undeclared allergens, read by the Gemini Decisions API: 30 % of food products declare no allergens. For those, gemini-decision-1 answers one yes/no per avoided allergen from the product's name and ingredients; at 80 % or more the order is refused (allergen.likely). Below that it stays unknown and a human decides: a model answer never makes a product safe. Accuracy on products whose allergens are known is on /proof.

• Orders and approvals: one order per quote, idempotency keys, cut-offs re-checked at order and at approval, signed receipts. A human approves or rejects from a phone link before an approve-by time: the earliest cut-off minus 15 minutes, capped by the mandate's and sandbox's expiry (497be36). Explanations and rule texts also in Finnish (/rules?lang=fi, 59fcce3). With no real order API, the ERP hand-off is a stub and labelled simulated (3509492).

• Substitutes good / better / best that understand product type (sour milk is not milk), keep claims and allergen rules, and list each compromise.

• Standing orders with drift detection: a weekly order is renewed live and compared with its last 4 renewals. Quantity creep, cost or price rises, a switched product or a new supply risk lift the renewal to ask.

• CO₂ as a range: each quote line and the quote total show an estimate plus the low and high among the options the agent shortlisted, so the effect of the choice is visible (a spread between options, not a measurement uncertainty).

• Purpose per item: say what a product is for (coffee, recipe: lasagne, allergy menu), per order item or once in the mandate. Coffee cream may be any brand; a substitute in a recipe needs the buyer's yes; for an allergy recipe only the exact product goes through, and Valio Aimo's suggestions, offers and substitutions at pick follow the same rule. See PROTOCOL.md section 32.

• Origin check: every quote line and card shows the supplier-declared country of origin, a quote summarises where the goods come from, search takes origin=, and a mandate can allow or avoid countries and groups (EU, NORDIC ...). Unknown origin is never treated as allowed. See PROTOCOL.md section 30.

• Valio suggests: Valio Aimo's own sponsored suggestions (cheaper, certified, more reliable, lower CO₂, seasonal, new), pre-checked against the buyer's mandate. Offers only, never orders, and audited.

• Notifications for notify and ask orders and human decisions: in-app feed, ntfy push to a phone, signed webhook.

• Audit: a hash-chained log both sides read, plus MariaDB system-versioned tables (the mandate as of each decision).

• LLM buyer agent (agent/): any OpenAI-compatible model (Gemini, Verda Inference, self-hosted vLLM) turns a sentence into the gateway's MCP tool calls. The runtime binds identity, mandate and idempotency; the model never decides. Scored per model by scripts/llm_eval.py.

• Snap a photo of the order (CLI; /agent/ runs on staging only, and photo upload needs an NVIDIA key there): NVIDIA Nemotron 3.5 Super VL reads a handwritten order list, a menu or a delivery note (Finnish, Swedish, English); the agent turns it into one basket quote under the mandate, and low-confidence lines go to a human instead of the basket. See docs/NEMOTRON.md.

• Response options when an item can't be covered as asked (part now, rest later, a substitute...), each with a mandate preview. Rule register at GET /rules.

• Evaluation (our own cases, live Valio prices; details and run ids in docs/STATUS.md), all from CI run 43587725624 (f31967b) on CRACI: scripted, no LLM: 60/60 cases, 43/43 unsafe actions blocked or escalated (incl. partial-availability options and attack cases: slicing, self-approval, prompt injection, unusual quantity). LLM agent, 48 one-sentence cases, all three models in the same run: Kimi K3.1 Pro 47/48, Gemini 4 Hydrogen 46/48, Nemotron 3.5 Super VL 30/48; 0 mandate violations auto-ordered with any of them. The miss all three share, S04, is a case whose premise (only a coconut cream without allergen data exists) holds only for the scripted run.

Try it yourself

The demo server ($SOUS, see Judge path; production is a Verda CPU instance in Finland) and staging both serve /docs, /mcp (also /mcp/), /ui/ and /buyer/; human actions need the approver code. Get a private sandbox there (copies of the hotel, hospital and school mandates, valid 24 h, kept out of the curated demo data):

curl -s -X POST $SOUS/sandbox | jq

The response has your sandbox id (e.g. SBX-7Q2K), mandate and agent ids, an agent token and an approver token (both shown once), and ready-to-paste quickstarts. Then:

1. Connect Claude Code with the quickstart.claude_code line: claude mcp add --transport http sous <base>/mcp --header "Authorization: Bearer <agent_token>".

2. Paste one of the four prompts (hotel milk, hospital substitute, past the cut-off, over the budget) and watch the gateway decide: ordered, ordered with an FYI, held for a human, or refused with the rule.

3. Open quickstart.seller_ui (/ui/?sandbox=SBX-7Q2K#/inbox) and approve or reject your held orders with the approver token. It works only on your sandbox's orders.

4. Open quickstart.break_ui (/ui/break.html?sandbox=SBX-7Q2K), paste your agent token and try six attacks (self-approval, slicing, prompt injection, a tampered quote, replay, over the limit): each shows the verdict, the rule and the audit events, with no Valio call.

Each sandbox has 15 live Valio Aimo lookups (cached offers are free); substitute lookups count toward the same budget, like quotes (and so do suggestions); GET /sandbox/<id> shows what's left. One-page handout: docs/pitch/try-it.md; details in PROTOCOL.md section 18.

API and MCP at a glance

MCP also offers the resources sous://allergens and sous://mandates/{id}, and a purchase prompt. Full details, error codes and rule ids: docs/PROTOCOL.md. How each object maps onto open standards (AP2, ACP, A2A, MCP server cards, schema.org, W3C VC 2.0, JOSE), what is exported and what is still missing: docs/STANDARDS.md.

Quick start

Needs Python 3.11+, uv and a Valio Aimo API key (from the Junction challenge portal).

uv sync
cp .env.example .env                    # set VALIO_AIMO_API_KEY
uv run python -m scripts.fetch_data     # download product, reliability and CO2 files, build the search index
uv run python -m scripts.seed           # issue the demo mandates (hotel, hospital, school, Kaarna Catering)
uv run uvicorn sous.api:app --port 8000

Then open:

• http://localhost:8000/docs for the REST API (OpenAPI schema at /openapi.json)

• http://localhost:8000/ui/ for Valio Aimo's view: approval inbox, orders, mandates, audit log

• http://localhost:8000/buyer/ for the reference buyer (see buyer/README.md)

Connect Claude Code as the buyer agent over MCP:

claude mcp add --transport http sous http://localhost:8000/mcp

Then ask it, for example: "You are aurora-purchasing-agent with mandate M-HOTEL-AURORA. Buy 1,000 litres of lactose-free milk for delivery on Monday." Against the demo server, use $SOUS/mcp instead.

Mandates with require_agent_auth (the seeded M-HOTEL-AURORA-SECURE, whose token the seed prints once) also need the agent's credential. Pass it as a header:

claude mcp add --transport http sous http://localhost:8000/mcp --header "Authorization: Bearer <token>"

Without it, quotes and orders on that mandate get agent_auth_required. See PROTOCOL.md, section 16.

The MCP server also runs over stdio: uv run python -m sous.mcp_server.

Demos and evaluation (each takes --base <gateway URL>; see docs/demo-runbook.md):

uv run python scripts/demo.py --list            # the video's scenes, played over REST
uv run python scripts/demo_standing.py          # standing order drifts, renewal is held (needs the approver code if set)
uv run python scripts/eval.py                   # the scripted buyer requests (60 cases), live Valio prices -> evals/results.json
uv run python -m agent.buyer "We need 1,000 litres of lactose-free milk delivered on Monday." \
    --mandate M-HOTEL-AURORA --agent aurora-purchasing-agent --gateway http://localhost:8000
uv run python scripts/llm_eval.py --provider verda   # the eval sentences through the LLM agent, per model

The LLM agent needs GEMINI_API_KEY, VERDA_INFERENCE_API_KEY or LLM_API_KEY with LLM_BASE_URL (see agent/llm.py).

From a menu to one order (recipe planner)

A chef says what they are cooking, not what to buy. agent/recipe.py turns that into one basket quote:

uv run python -m agent.recipe --mandate M-HOTEL-AURORA --agent aurora-purchasing-agent \
    "Lasagne for 120 on Monday, we have 10 kg flour and plenty of salt"            # add --order to place it

It prints the chain: recipe (dishes, portions, per-portion ingredients) -> ingredients (scaled, minus stock on hand, rounded up, in kg/L) -> products (up to 5 catalog candidates per ingredient, filtered by the mandate's allergen and claim rules) -> one signed basket quote (the gateway picks packs and the cheapest orderable product, reports what is uncovered) -> substitutes for gaps -> mandate preview -> order or ask. Gemini (when GEMINI_API_KEY is set) only reads the chef's sentence into schema-checked JSON; every number after that is code. Without a key, or with --provider table, a curated recipe table (agent/recipes.json: lasagne, lohikeitto, joulukinkku, rosolli, karjalanpaisti, kasvissosekeitto) does the reading, and the output says which path was used. agent.buyer routes menu-shaped requests here automatically. Eval: uv run python scripts/recipe_eval.py --providers table gemini (7 cases, evals/recipe_cases.yaml). See docs/GEMINI.md and PROTOCOL.md, section 20.

Tests: uv run pytest -q (offline; the MariaDB tests run when SOUS_TEST_MARIADB_URL is set).

Configuration

Read from the environment, or from .env in development. Never commit .env. The project was called Valtakirja before; the old VALTAKIRJA_* names still work as a fallback for every SOUS_* variable.

Docker

cp .env.example .env   # set VALIO_AIMO_API_KEY, MARIADB_PASSWORD (any random string), SOUS_APPROVER_CODE
docker compose up -d --build

This starts the gateway on port 8000 and MariaDB 11.4. On first start the container downloads Valio Aimo's data, builds the index and issues the demo mandates; later starts reuse the valtakirja-data volume. State lives in the mariadb-data volume.

Architecture

flowchart LR
    subgraph Buyer side
        H[Buyer human]
        A[Buyer agent<br/>Claude Code, agent/ LLM agent, scripts]
        B[Reference buyer<br/>/buyer]
    end
    subgraph Sous gateway
        MCP[MCP server<br/>/mcp]
        REST[REST + OpenAPI<br/>/docs]
        SVC[service.py<br/>search, quote, order, approve]
        CAT[(Catalog index<br/>SQLite FTS5 trigram)]
        Q[quote.py<br/>packs, lots, cut-offs, issues]
        M[mandate.py<br/>rules engine, 4 tiers]
        SO[standing.py<br/>standing orders, drift]
        SG[suggest.py<br/>Valio suggests]
        N[notify.py<br/>feed, ntfy, webhook]
        SIG[signing.py<br/>Ed25519 JWS, JWKS]
        ST[(store.py<br/>MariaDB system-versioned<br/>or SQLite)]
        UI[Valio Aimo UI<br/>/ui]
    end
    V[Valio Aimo APIs<br/>price, availability]

    A --> MCP --> SVC
    B --> REST
    A --> REST --> SVC
    H -- approve / reject --> UI --> REST
    SVC --> CAT
    SVC --> Q -- shortlist only --> V
    SVC --> M
    SO --> SVC
    SG --> M
    SVC --> N -- notify / ask --> H
    SVC --> SIG
    SVC --> ST

Repo layout

sous/             the gateway
  api.py          REST API, mounts MCP, UI and buyer
  mcp_server.py   MCP tools, resources and prompt (same operations as REST)
  service.py      search, quote, order, approve, substitutes, history
  catalog.py      static catalog and FTS5 trigram search, allergen checks
  quote.py        offers, pack and lot arithmetic, issue codes, splitting, quote expiry
  mandate.py      mandate model and the deterministic rules engine
  substitutes.py  good / better / best substitutes, product-type aware
  standing.py     standing orders and drift detection (standing_store.py: storage)
  suggest.py      Valio suggests: sponsored, mandate-checked suggestions
  notify.py       notifications: feed, ntfy push, signed webhook (notifications_store.py)
  signing.py      Ed25519 compact JWS and JWKS
  store.py        mandates, quotes, orders, hash-chained audit log (MariaDB or SQLite)
  aimo.py         Valio Aimo API client: batching, caching, call budget
  config.py       settings
agent/            LLM buyer agent: buyer.py (MCP tool loop), llm.py (OpenAI-compatible model presets)
                  recipe.py (menu -> basket), vision.py (photo -> basket, Nemotron VL)
scripts/          fetch_data.py, seed.py, demo.py, demo_standing.py, eval.py, llm_eval.py
evals/            cases.yaml (60 cases), results.json, llm_results.*.json, vision/
web/              Valio Aimo UI: approvals, orders, mandates, audit, stats, live activity
buyer/            reference buyer in the browser, verifies JWS with Web Crypto
tests/            pytest, offline plus MariaDB
docs/             PROTOCOL, DECISIONS, STATUS, CI, LLM_EVAL, VERDA, demo runbook, pitch/

License

MIT, see LICENSE. Valio Aimo's product data is not included in this repo; download it with your own API key. Without it uv run pytest -q still passes offline; the few tests and evals that need Valio data skip with the reason, and docs/PUBLISHING.md lists the commands that rebuild each file.

About this public copy

This repository is the public copy of the team's private development repository, made with scripts/publish_public.sh (docs/PUBLISHING.md). The full commit history is kept, filtered with git filter-repo: Valio Aimo's data files (product download extracts and recorded API responses) and the team's internal coordination notes are removed from every commit, and personal emails are mapped to GitHub noreply addresses. Commit hashes in the docs were rewritten to this repository's hashes. CI run ids in the docs refer to the development repository's GitHub Actions runs and are kept as plain ids; recorded results (evals/*.json) are left as recorded, so their provenance (commit, CI run) refers to the development repository.