# Livrabil LOT 1 — Sistem AI (DiDi / PNRR DIGI150)

Pachet de lucru pentru continuarea LOT 1 pe serverul cu **inferență GPU**. Conține
codul `ai_platform` (curățat), documentația de achiziție (caiet + ofertă) și
raportul de audit cod-vs-caiet-vs-ofertă.

> **Scop:** muți acest folder pe serverul cu inferență, configurezi modelele
> reale și finalizezi punctele rămase (vezi §5). Tot ce s-a putut face fără GPU
> e deja făcut și validat în Docker.

---

## 1. Structura pachetului

```
livrabil_lot1/
├── README_LIVRABIL.md          ← acest fișier (handoff)
├── ai_platform/                ← codul LOT 1 (curățat: fără node_modules/.git/runs/cache)
│   ├── modules/<modul>/        ← fiecare modul: src/ tests/ deploy/ README.md API.md
│   ├── CLAUDE.md INDEX.md       ← convenții + overview oficial
│   └── DEPLOYMENT.md bootstrap.sh
└── documentatie/
    ├── Caiet_de_sarcini.pdf
    ├── Propunere_tehnica.pdf / Lot1.pdf / LOT1_AI_Propunere_Tehnica.docx
    └── AUDIT_LOT1.md            ← audit complet pe module (citește-l pentru detalii)
```

`uv.lock` au fost excluse intenționat (se regenerează cu `uv sync`). `node_modules`
se regenerează cu `npm ci`.

---

## 2. Ce este LOT 1 — harta modulelor (logica)

Sistemul AI = servicii independente, containerizate, pe care backend-ul (LOT 2)
le consumă prin API. Fiecare modul are `deploy/deploy.sh`, `docker-compose.yml`,
`Dockerfile`, `.env.example`.

| Modul | Ce face | Stare |
|---|---|---|
| **llm-inference** | Gateway OpenAI-compatible peste 3 backend-uri (vLLM/llama.cpp/LiteLLM); rutare + fallback + metrici | 🟢 ~95% |
| **extractors** *(nou)* | Feature extraction *ușor*: metadata (EXIF/ELA/spectrogramă/integritate), sentiment/OCR (deleagă LLM), NER (GLiNER), detect (YOLO) | 🟢 ~95% |
| **video-analysis** | Deepfake video (BusterX/vLLM), verdict REAL/FAKE/UNCERTAIN + frames + evidence | 🟢 |
| **audio** | Transcriere (faster-whisper) | 🟢 |
| **web** | Web crawl & evidence (Playwright, multi-provider search) | 🟡 90% |
| **embeddings / rerank** | bge-m3 / bge-reranker-v2-m3, OpenAI-compatible | 🟢 85% |
| **didi_brain** | Cache rezultate (Postgres/pgvector) + RAG (Atomic) + fact-checking; consumat de backend | 🟢 |
| **dashboard** | Admin UI (React+FastAPI): monitorizare AI, catalog modele DB, config, RBAC | 🟡 ~78% |
| **catalog-api** | Agregator service-discovery (`/v1/info`), stateless | 🟢 |
| **gateway** | Reverse-proxy nginx (config-only) — punct de intrare AI | 🟢 |
| **forensic_features** | Detectoare forensice (rPPG/lip-sync/forgery heatmap/lighting) | 🟢 |
| **cloak** | Scraper SERP stealth (tier-3 fallback pt `web`) | 🟢 |

Detalii complete + procente per cerință: **`documentatie/AUDIT_LOT1.md`**.

---

## 3. Ce s-a remediat în această iterație (rezumat)

Toate validate rulând în container (mediul de build n-are python/GPU local).

- **Extractor ML — modul nou `extractors`** (39 teste): `/v1/metadata` (EXIF, codec/bitrate via ffprobe, spectrogramă numpy, ELA, integritate/C2PA), `/v1/sentiment` + `/v1/ocr` (deleagă la gateway-ul LLM), `/v1/ner` (GLiNER, validat pe RO), `/v1/detect` (YOLOv8, validat real).
- **video-analysis** — verdict aliniat: enum `UNCERTAIN`, `frames_analyzed` + `evidence[]`; reparat bug pyproject (virgulă lipsă → modul neinstalabil). 7 teste.
- **dashboard** — *AI Monitoring* (health agregat + cozi RabbitMQ + latențe Prometheus, fail-open), *Catalog modele/extractoare DB-backed* + CRUD, *RBAC* pe suprafața de citire + warning staging. 12 teste pe Postgres. Reparat 2 bug-uri reale (audit NOT NULL, Query default).
- **llm-inference** — model `qwen3.5` + alias, `/v1/completions`, **fallback cascadă** cross-backend, **metrici Prometheus** (latență/tokens/requests). 100 teste. Pin `fastapi<0.116`.
- **Cache** — reclasificat: acoperit la nivel de orchestrare (didi_brain + Redis backend), nu se construiește cache nou în LOT 1.

---

## 4. Cum se validează (fără a instala nimic local) — reț. Docker

Mediul de dezvoltare n-are python/uv/ffmpeg/GPU. Tot se rulează în container:

```bash
# Teste unui modul Python (în containerul lui de build):
cd ai_platform/modules/<modul>
docker run --rm -v "$PWD":/app -w /app python:3.11-slim \
  bash -c "pip install -e '.[dev]' && pytest -q"

# Module cu model greu (extractors NER/YOLO): instalează extra-ul ml
#   pip install -e '.[ml]'   (trage torch — imagine mai mare)

# dashboard (are nevoie de Postgres): Postgres efemer în Docker
docker run -d --name pg --network <net> -e POSTGRES_PASSWORD=test -e POSTGRES_DB=test postgres:16-alpine
docker run --rm --network <net> -v "$PWD":/app -w /app \
  -e TEST_DATABASE_URL="postgresql+asyncpg://postgres:test@pg:5432/test" \
  python:3.11-slim bash -c "pip install -e '.[dev]' && pytest -q"

# frontend dashboard (Vite 7 cere Node 20+):
cd ai_platform/modules/dashboard/web
docker run --rm -v "$PWD":/app -w /app node:20-slim bash -c "npm ci && npx tsc -b --noEmit"
```

---

## 5. Ce mai e de făcut pe serverul cu inferență

### 5.1 Configurări obligatorii la mutare (altfel serviciile nu „văd" modelele)
- **llm-inference**: pornește vLLM cu `--served-model-name qwen3.5` (sau setează
  `LLM_MODEL_ALIASES`), `VLLM_MODEL=Qwen/Qwen3.5-35B-A3B`. Vezi `.env.example`.
- **extractors**: `EXTRACTORS_LLM_GATEWAY_URL=http://<llm-gateway>:14011` (pt sentiment/OCR).
- **video-analysis / audio / embeddings / rerank**: setează URL-urile vLLM/model în `.env`.
- **dashboard**: pentru a aprinde panourile noi —
  `DASHBOARD_PROMETHEUS_URL=http://<prometheus>:9090`,
  `DASHBOARD_RABBITMQ_MGMT_URL=http://<rabbitmq>:15672` (+ user/parolă).
  RBAC se activează automat când e setat `DASHBOARD_KEYCLOAK_URL`; **scoate
  `DASHBOARD_STAGING_MODE` în producție** (bypassează auth).

### 5.2 Cod rămas (validabil pe server cu modelele reale)
- **llm-inference — load/unload model** (Task 4): vLLM **nu** suportă hot-swap
  nativ (un model/proces). Decizie: (a) implementezi „register/route" — load =
  asiguri că un backend servește modelul X; sau (b) marchezi „nesuportat de vLLM"
  în ofertă/recepție. *(singurul punct deschis la inferență)*
- **web** (ofertă): `robots.txt`, rate-limit per-domeniu, jurnal audit persistent.
- **embeddings/rerank**: failover automat între backend-uri + teste API.
- **RAG**: wrapper de contract `/v1/query`/`/v1/index` peste `/v1/gather` din
  didi_brain (sau acceptat în forma livrată).
- **CI/CD**: non-root pe 5 Dockerfile, rollback + publish imagini AI în registry.

### 5.3 Infra (manifeste de scris; validare reală doar cu cluster/GPU)
- **Orchestrare / scalare automată** (caiet 747-766) — k8s/Helm + HPA. *Singurul
  gap mare de caiet rămas.*
- **dashboard GPU/VRAM** — exporter dcgm pe host-ul GPU + panou (codul de panou se
  cablează ca latențele, prin Prometheus).
- **dashboard control rute** — gateway-ul AI e nginx static; control real = view +
  enable/disable prin regenerare config + reload (NU Kong, care e LOT 2).

---

## 6. Pornire rapidă (per modul)

```bash
cd ai_platform/modules/<modul>/deploy
cp ../.env.example .env      # completează variabilele (fail-fast, fără defaults)
./deploy.sh up               # sau: docker compose up -d --build
```

Convenție porturi: `1xxxx` producție / `5xxxx` dev (vezi `ai_platform/CLAUDE.md`).
Bootstrap pentru host CPU-only: `ai_platform/bootstrap.sh` + `DEPLOYMENT.md`.

---

## 7. Pointere
- **Audit complet pe cerințe** (procente, file:line, ce lipsește): `documentatie/AUDIT_LOT1.md`
- Convenții cod + porturi: `ai_platform/CLAUDE.md`
- Overview module: `ai_platform/INDEX.md`
- Fiecare modul: `README.md` + `API.md` + `INDEX.md` propriu.