Livrare LOT 1 - Didi

ai_platform/modules/extractors/README.md

@@ -0,0 +1,57 @@
+# extractors
+
+Consolidated **lightweight feature-extraction** service for the DiDi AI platform
+(LOT 1, Modul 2 — Extractoare ML). Hosts the CPU-only / LLM-delegating feature
+extractors that do **not** warrant a dedicated GPU model server.
+
+> Heavy model services stay separate: **deepfake/BusterX** → `video-analysis`,
+> **speech-to-text/Whisper** → `audio`. They require GPU at runtime and are not
+> folded in here.
+
+## Capabilities
+
+| Endpoint | Status | Type | Notes |
+|----------|--------|------|-------|
+| `POST /v1/metadata` | ✅ implemented | CPU, deterministic | EXIF, video metadata (ffprobe), spectrogram, ELA, integrity/signature |
+| `POST /v1/sentiment` | ✅ implemented | LLM-delegated | LLM gateway + Romanian-aware prompt (irony/sarcasm) |
+| `POST /v1/ocr` | ✅ implemented | LLM vision | verbatim text from images via the vision model |
+| `POST /v1/ner` | ✅ implemented | model (`.[ml]`) | GLiNER multilingual, configurable entity types, GPU-capable |
+| `POST /v1/detect` | ✅ implemented | model (`.[ml]`) | YOLO object detection (COCO), boxes+conf, GPU-capable |
+
+The metadata extractors are selected automatically from the detected media type
+(image / video / audio).
+
+## Prerequisites
+
+- Python 3.10+
+- **ffmpeg/ffprobe** on PATH (provided by the container image) — required for
+  video metadata and non-WAV audio decoding. Image extractors (EXIF/ELA/
+  integrity) work without it.
+
+## Run (local)
+
+```bash
+uv sync
+uv run uvicorn extractors.app:app --port 54400
+```
+
+## Test
+
+```bash
+uv run pytest                      # local (needs deps)
+./deploy/deploy.sh test            # or build the wheel in Docker
+```
+
+In the container image, ffmpeg-dependent paths run for real; the unit tests are
+fixture-driven so they pass without the binaries.
+
+## Deploy
+
+```bash
+cp .env.example .env               # set EXTRACTORS_TAG / PORT / MAX_UPLOAD_MB
+./deploy/deploy.sh up
+```
+
+Ports follow the datacenter convention: `54400` (dev), `14400` (prod).
+
+See `API.md` for the full request/response contract.