Livrare LOT 1 - Didi

2026-06-25 14:13:25 -07:00 · 2026-06-25 14:13:25 -07:00 · 5380c3fc63
commit 5380c3fc63
990 changed files with 133308 additions and 0 deletions
--- a/ai_platform/modules/forensic_features/README.md
+++ b/ai_platform/modules/forensic_features/README.md
@ -0,0 +1,134 @@
+# Forensic Features API
+
+**Microserviciu REST care extrage măsurători forensice obiective din
+video/imagini și le împachetează într-un format consumabil de un LLM extern
+multimodal (Qwen Vision, GPT-4V, Claude Sonnet, etc.).**
+
+> Acest serviciu **NU** face clasificare end-to-end. Nu spune "FAKE" sau "REAL".
+> Produce **numere și hărți vizuale** pe care LLM-ul tău (cel care face deja
+> vision/OCR/tipologii) le folosește ca semnal suplimentar peste analiza lui
+> vizuală.
+
+## Ce face concret
+
+Pentru fiecare video/imagine primit la `POST /api/forensic-evidence`, rulează
+**5 detectoare forensice** care produc semnale **pe care un LLM nu le poate
+calcula din imagine**:
+
+| Modul | Ce extrage | De ce e util pentru LLM |
+|-------|------------|--------------------------|
+| **m25 Physiology** | Puls cardiac (rPPG POS), rata clipitului, asimetrie ochi L/R | LLM nu poate „număra" pulsul din variația subtilă de culoare facială |
+| **m26 Audio Forensics** | Drift lip-sync (ms), F0 std, varianță spectrală centroidă, voice/silence ratio | LLM nu poate cuantifica sincronicitatea audio-video sau caracteristici TTS |
+| **m27 AI Detector** | NPR cross-scale + JPEG-recon error (opțional HF model) | LLM nu poate face FFT / inferință neurală pe textura imaginii |
+| **m28 Forgery Heatmap** | Hartă vizuală localizare blending boundary (Face X-ray-like) | LLM primește o **imagine PNG** care arată EXACT unde să se uite |
+| **m29 Lighting 3D** | Direcție lumină față vs scenă (azimuth+elevation), catchlight consistency | LLM nu poate fitta un model de iluminare 3D |
+
+Output: text formatat + 12-15 imagini PNG base64 + scoruri raw structurate.
+
+## Arhitectură (5 secunde)
+
+```
+┌────────────────┐                              ┌─────────────────────┐
+│  Aplicația ta  │  POST video.mp4              │ Forensic Features   │
+│  (existentă)   │ ───────────────────────────► │ API (acest serviciu)│
+│                │                              │                     │
+│  + Qwen/GPT-4V │  ◄────────────────────────── │  - extrage features │
+│  + tipologii   │  evidence_text + PNG-uri     │  - generează PNG    │
+│  + OCR         │  + raw scores                │  - formatează prompt│
+└────────────────┘                              └─────────────────────┘
+       │
+       │ inserează evidence_text în prompt LLM
+       │ atașează imagini PNG la apel multimodal
+       ▼
+┌────────────────┐
+│  LLM extern    │  vede:
+│  (Qwen/GPT-4V) │   - imaginile originale uploadate
+│                │   - tipologiile tale
+│                │   + evidence_text de la noi
+│                │   + heatmap-uri PNG de la noi
+│                │  → produce verdict cu signal mult mai bogat
+└────────────────┘
+```
+
+## Quick start
+
+```bash
+# Build și pornește container
+docker compose up -d
+
+# Verifică
+curl http://localhost:8080/health
+curl http://localhost:8080/api/forensic-modules
+
+# Test end-to-end
+curl -X POST http://localhost:8080/api/forensic-evidence \
+     -F "video=@test_video.mp4" \
+     -F "encode_images=1"
+```
+
+Răspunsul conține `evidence_text` (de inserat în promptul LLM-ului tău) plus
+o listă de imagini PNG base64 (de atașat la apelul multimodal).
+
+## Cerințe sistem
+
+| Resursă | Minim | Recomandat |
+|---------|-------|------------|
+| RAM     | 2 GB  | 4 GB       |
+| CPU     | 2 cores | 4 cores  |
+| Disk    | 2 GB liberi | 5 GB (date temporare) |
+| OS      | Linux (Docker), Windows/Mac (Docker Desktop) | Linux |
+
+Per request: ~2-3 GB RAM peak, 5-90 secunde procesare (depinde de durata
+video — videoclipuri >30s pot lua minute pe CPU).
+
+## Structura proiectului
+
+```
+forensic_features/
+├── README.md                    # Acest fișier
+├── docs/                        # Documentație tehnică în adâncime
+│   ├── ARCHITECTURE.md          # Cum funcționează fiecare strat
+│   ├── API.md                   # Reference complet endpoint-uri
+│   ├── CONTRACT.md              # Schema completă de output
+│   ├── MODULES.md               # Deep dive m25-m29 cu algoritmi
+│   └── INTEGRATION.md           # Cum integrezi în aplicația ta LLM
+│
+├── Dockerfile                   # Multi-stage, ~1.5 GB final
+├── docker-compose.yml           # Healthcheck + volumes + limits
+├── .dockerignore
+├── .env.example
+├── requirements.txt             # Lean: numpy, scipy, opencv, mediapipe, aiohttp
+│
+├── api.py                       # REST API (270 linii, doar 5 endpoints)
+├── preprocessing.py             # Frame extraction prin ffmpeg
+├── face_landmarker.task         # MediaPipe model (~3.6 MB)
+│
+├── forensic/                    # Glue layer (orchestrare + fuziune + formatare)
+│   ├── __init__.py
+│   ├── orchestrator.py          # Rulează modulele cu input corect, captează erori
+│   ├── scoring.py               # Fuziune Dempster-Shafer-inspired a scorurilor
+│   └── prompt_builder.py        # Formatare evidence_text + base64 imagini
+│
+└── tools/                       # Cele 5 detectoare forensice
+    ├── _contract.py             # Helper make_response() pentru schema unificată
+    ├── m25_physiology/          # rPPG POS + blink dynamics
+    ├── m26_audio/               # Lip-sync + voice clone heuristic
+    ├── m27_ai_detector/         # NPR cross-scale + JPEG-recon
+    ├── m28_forgery_heatmap/     # Face X-ray-inspired blending detection
+    └── m29_lighting/            # Lambertian SfS + catchlight consistency
+```
+
+## Documentație suplimentară
+
+Pentru detalii tehnice profunde, vezi [docs/](docs/):
+
+- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — cum se leagă straturile
+- **[docs/API.md](docs/API.md)** — reference complet endpoint-uri
+- **[docs/CONTRACT.md](docs/CONTRACT.md)** — schema returnată
+- **[docs/MODULES.md](docs/MODULES.md)** — algoritmii fiecărui modul, line by line
+- **[docs/INTEGRATION.md](docs/INTEGRATION.md)** — cum apelezi din aplicația ta
+
+## License & contact
+
+Cod custom pentru pipeline de augmentare LLM cu signal forensic.
+Toate dependențele third-party sunt MIT/BSD/Apache 2.0 compatible.