didi-lot1-ai/ai_platform/modules/forensic_features

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

# 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/ARCHITECTURE.md — cum se leagă straturile
• docs/API.md — reference complet endpoint-uri
• docs/CONTRACT.md — schema returnată
• docs/MODULES.md — algoritmii fiecărui modul, line by line
• 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.