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/extractors/API.md
+++ b/ai_platform/modules/extractors/API.md
@ -0,0 +1,133 @@
+# Extractors API
+
+## Base URL
+
+```
+{BASE_URL}
+```
+
+- **Local development:** `http://localhost:54400`
+- **Docker (internal):** `http://extractors:54400`
+- **Production:** use your configured hostname (port `14400`)
+
+## Authentication
+
+None at the service level — access is mediated by the platform API gateway
+(Bearer token at the perimeter). Do not expose this service directly.
+
+## Endpoints
+
+### GET /health
+
+Liveness probe.
+
+```json
+{ "status": "ok", "version": "0.1.0" }
+```
+
+### GET /ready
+
+Readiness + optional tooling availability (informational; the service degrades
+gracefully if ffprobe/ffmpeg are absent).
+
+```json
+{ "status": "ready", "ffprobe": true, "ffmpeg": true }
+```
+
+### POST /v1/metadata
+
+Extract deterministic media metadata & integrity features. The applicable
+extractors are chosen automatically from the detected media type.
+
+**Request** — `multipart/form-data`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `file` | file | Image, video or audio file |
+
+```bash
+curl -X POST http://localhost:54400/v1/metadata \
+  -F "file=@photo.jpg"
+```
+
+**Response** `200 OK`
+
+```json
+{
+  "filename": "photo.jpg",
+  "media_type": "image",
+  "sha256": "9f86d081884c7d65...",
+  "size_bytes": 84211,
+  "analyses": {
+    "integrity": {
+      "tool_id": "integrity",
+      "name": "Integrity & signature",
+      "ok": true,
+      "results": { "container": "JPEG", "sha256": "9f86...", "size_bytes": 84211 },
+      "evidence": ["Container: JPEG.", "SHA-256: 9f86d081884c7d65…"],
+      "anomalies": [],
+      "confidence": 1.0
+    },
+    "exif": {
+      "tool_id": "exif",
+      "name": "EXIF metadata",
+      "ok": true,
+      "results": {
+        "format": "JPEG", "dimensions": [4032, 3024],
+        "make": "Apple", "model": "iPhone 13",
+        "datetimeoriginal": "2024:06:15 14:30:00",
+        "gps": { "latitude": 44.426, "longitude": 26.102 },
+        "software": "Adobe Photoshop 25.0"
+      },
+      "evidence": ["Captured with Apple iPhone 13.", "GPS location present: 44.426, 26.102."],
+      "anomalies": ["Editing/generation software detected in EXIF: Adobe Photoshop 25.0."],
+      "confidence": 0.95
+    },
+    "ela": {
+      "tool_id": "ela", "name": "Error Level Analysis", "ok": true,
+      "results": { "quality": 90, "mean_error": 6.1, "max_error": 211.0, "p99_error": 38.0, "hot_pixel_fraction": 0.031 },
+      "evidence": ["ELA mean error 6.1, p99 38.0 (quality=90)."],
+      "anomalies": ["Localized high-error region(s) detected — possible splice/edit (3.1% of pixels)."],
+      "confidence": 0.6
+    }
+  },
+  "evidence": ["..."],
+  "anomalies": ["..."],
+  "execution_time_ms": 42.7
+}
+```
+
+For **video** inputs the `analyses` block contains `integrity`, `video_metadata`
+(codec/width/height/fps/bitrate/encoder) and `spectrogram`. For **audio**:
+`integrity` + `spectrogram`.
+
+Each extractor returns a uniform `FeatureResult`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tool_id` | string | Stable extractor id |
+| `name` | string | Human-readable name |
+| `ok` | bool | Ran without error |
+| `results` | object | Structured extracted data |
+| `evidence` | string[] | Neutral findings (LLM-readable) |
+| `anomalies` | string[] | Tampering/edit hints |
+| `confidence` | number\|null | 0..1 (extraction confidence, not a verdict) |
+| `error` | string\|null | Set when `ok` is false |
+
+## Error Responses
+
+| Status | Meaning |
+|--------|---------|
+| 400 | Empty file |
+| 413 | File exceeds `EXTRACTORS_MAX_UPLOAD_MB` |
+| 422 | Missing `file` field |
+
+```json
+{ "detail": "empty file" }
+```
+
+## Request Headers
+
+| Header | Required | Notes |
+|--------|----------|-------|
+| `Content-Type` | yes | `multipart/form-data` (set by the client) |