# Del 9 – AAMOS-integration

AAMOS är er befintliga AI-plattform och nås **uteslutande via API** från appens
backend (beslut 2026-08-02). Mobilappen har aldrig direktkontakt och innehåller inga
AI-hemligheter (spec §31, §61.13).

## Kontraktet (`packages/ai-contracts`)

Appen definierar ett versionerat, Zod-validerat kontrakt per uppgiftstyp. Input
valideras FÖRE nätverksanropet, output valideras EFTER – ett svar som bryter kontraktet
behandlas som fel och når aldrig användardata. AAMOS kan därmed byta modeller,
prompts och leverantörer fritt bakom kontraktet ("Food API ska få stabila kontrakt
oavsett modell").

Antaget transport-API (justeras mot er AAMOS-dokumentation – endast
`HttpAamosClient` berörs):

```text
POST {AAMOS_API_URL}/v1/tasks      Authorization: Bearer {AAMOS_API_KEY}
  → AamosRequestEnvelope  { taskId, taskType, contractVersion, input, metadata }
  ← AamosResponseEnvelope { taskId, status: ok|uncertain|failed, output,
                            modelVersion, promptVersion, latencyMs, costUsd }
GET {AAMOS_API_URL}/v1/health
```

Metadata per anrop: `correlationId` (spårbarhet §58), `subjectRef`
(**pseudonymiserat** id – aldrig e-post/namn, §56), `priority`, samt
`consentFlags {personalization, anonymizedImprovement, imageTraining}` så att AAMOS
kan upprätthålla samtyckesreglerna på sin sida också.

**Behövs från er:** AAMOS bas-URL + API-nyckel per miljö, och er endpoint-/schema-
dokumentation. Avviker kuvertformatet mappas det i `HttpAamosClient` – kontrakten
utåt ändras inte.

## Uppgiftstyper (15)

Bild/OCR: `ANALYZE_FRIDGE_IMAGE`, `ANALYZE_PANTRY_IMAGE`, `ANALYZE_MEAL_IMAGE`
(kcal-INTERVALL, aldrig exakt påstående), `READ_RECEIPT`, `READ_NUTRITION_LABEL`
(värden från etiketten – inte modellens gissning), `READ_EXPIRY_DATE`.
Text/struktur: `NORMALIZE_PRODUCTS`, `DEDUPLICATE_INVENTORY`, `STRUCTURE_RECIPE_TEXT`,
`PARSE_CRAVING`, `MODERATE_RECIPE`.
Rådgivande: `GENERATE_RECIPE_OPTIONS` (granskas redaktionellt, §15), `RANK_RECIPES`
(får ordna om – aldrig lägga till), `GENERATE_WEEK_PLAN`, `UPDATE_USER_MEMORY`.

Alla outputs bär `confidence`, och "osäker/okänd" är förstklassiga svar
(`canonicalIngredientId: null`, `requiresConfirmation: true`) – spec §10/§61.4.

## Routing & specialister (spec §33)

Rekommenderad routing inne i AAMOS: specialistmodell först (vanliga livsmedel,
nordiska förpackningar, kvitto-OCR, datum-OCR, portionssegmentering) → hög confidence:
svara; låg: extern generalist (Haiku 4.5-klass för volym, Sonnet-klass för svåra fall);
fortsatt osäkert: `status: "uncertain"` → appen frågar användaren. Appen skickar
`modelVersion`/`promptVersion` vidare in i `scan_jobs` och `ai_corrections` så att
varje datapunkt är spårbar till modellversion (§9).

## Feedback → träning (spec §33)

Varje användarkorrigering i granska-flödet sparas som `ai_corrections`
(AI-utdata + korrigering + modell/promptversion + **samtyckessnapshot**).
Veckojobbet `BUILD_TRAINING_SAMPLE` exporterar endast rader där
`anonymized_improvement = granted` vid korrigeringstillfället; bilder kräver
separat `image_training`-samtycke. Personligt minne är aldrig träningsdata (§32).

## Memory (spec §32)

Appens DB är den användarsynliga sanningen (`memory_items`). Nattjobbet skickar
veckans domänhändelser + befintliga minnesnycklar till `UPDATE_USER_MEMORY`; AAMOS
returnerar förslag (kind/key/sammanfattning/confidence/expires) som skrivs in – men
poster som användaren verifierat eller pausat skrivs **aldrig** över. Användarens
rättelser blir `user_stated` med confidence 1 och vinner alltid (§30).

## Evals (spec §34)

`ai_eval_cases` (fast testbibliotek: kyl/frys/skafferi/tallrik/kvitton/etiketter/
allergifall/mörka bilder/överlapp/orimliga recept) + `ai_eval_runs` (precision, recall,
missade produkter, hallucinationer, allergifel, latens, kostnad, korrigeringsgrad).
Regel: **ingen modell- eller promptändring i AAMOS tas i produktion för appen utan
grön eval-körning**, synlig i adminpanelen (`/admin/v1/ai/eval-runs`). Corpus byggs
under beta ur anonymiserade, samtyckta exempel.

## Kostnadskontroll

`costUsd` per anrop loggas på scan_jobs → daglig kostnad per uppgiftstyp i admin;
larm vid spik (§58). Fair use-kvoterna (Del 10/13) begränsar exponeringen per användare.
Mock-läget (`AAMOS_MODE=mock`) finns för dev/test; produktion vägrar starta i mock.
