Initial commit (unpacked platform)

2026-08-05 19:21:11 +07:00
commit ac5340195a
314 changed files with 57584 additions and 0 deletions
@@ -0,0 +1,86 @@
+# 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.