# 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ă (8085 = portul host; containerul expune intern 8080)
curl http://localhost:8085/health
curl http://localhost:8085/api/forensic-modules

# Test end-to-end
curl -X POST http://localhost:8085/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 (418 linii, 6 endpoints — inclusiv /metrics)
├── 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.