# 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.