docs/API.md

# API reference (FastAPI)

Base URL (local): `http://localhost:8000`  
Interactive docs: `/docs` (Swagger), `/redoc` (ReDoc)

Implementation: [`src/api/main.py`](../src/api/main.py)  
Inference: [`src/service/model_service.py`](../src/service/model_service.py)

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/` | Health check and active model name |
| `GET` | `/model-info` | Metadata for the loaded model |
| `GET` | `/models` | List available models and active one |
| `PUT` | `/model/{model_name}` | Switch active model (lazy load on next predict) |
| `POST` | `/predict` | Classify one comment |
| `POST` | `/predict-batch` | Classify up to 100 comments |
| `POST` | `/predict-video` | Fetch YouTube comments and classify (needs API key or demo fallback) |

---

## `POST /predict`

**Request body**

```json
{
  "text": "Comment text here",
  "threshold": 0.5
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | yes | 1–5000 characters, non-empty after trim |
| `threshold` | float | no | Toxic if `probability >= threshold` (**0.381** production, **0.5** LR baseline, **0.12** frozen BERT baseline) |

**Response**

```json
{
  "text": "Comment text here",
  "is_toxic": false,
  "probability": 0.0821,
  "labels": [],
  "model_used": "Meta-Feature Stacking (Production)",
  "latency_ms": 15.2
}
```

| Field | Description |
|-------|-------------|
| `is_toxic` | `true` = **Toxic**, `false` = **Safe** |
| `probability` | P(toxic), 0.0–1.0 |
| `labels` | Optional category hints when toxic (keyword/heuristic or HF labels) |
| `model_used` | Active model id from `ModelService` |

**curl**

```bash
curl -s -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks for the tutorial!", "threshold": 0.5}'
```

**Toxic example**

```bash
curl -s -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"text": "You are worthless garbage", "threshold": 0.5}'
```

---

## `POST /predict-batch`

```json
{
  "texts": ["Safe comment", "Another line"],
  "threshold": 0.5
}
```

Response includes `results` (list of predict objects), `total`, `toxic_count`, `latency_ms`.

```bash
curl -s -X POST http://localhost:8000/predict-batch \
  -H "Content-Type: application/json" \
  -d '{"texts": ["Nice video", "I hate you"], "threshold": 0.5}'
```

---

## `POST /predict-video`

```json
{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "max_comments": 50,
  "threshold": 0.5
}
```

Set `YOUTUBE_API_KEY` in `.env` for live comment fetch. Without a key, the API may use a limited fallback scraper or demo data (see implementation in `main.py`).

---

## `GET /models` and model switch

Demo models from [`configs/model_catalog.yaml`](../configs/model_catalog.yaml):

| Name | Type | Artifact / weights |
|------|------|-------------------|
| `Meta-Feature Stacking (Production)` | meta_stack | `models/production_final/meta_stack_final.joblib` |
| `LR + TF-IDF (Baseline)` | local | `models/baseline/lr_tfidf.joblib` |
| `Frozen Toxic-BERT (Baseline)` | hf_remote | Hugging Face `unitary/toxic-bert` |

```bash
curl -s http://localhost:8000/models/status

curl -s -X POST http://localhost:8000/models/select \
  -H "Content-Type: application/json" \
  -d '{"model_name": "LR + TF-IDF (Baseline)"}'
```

Default at startup: `Meta-Feature Stacking (Production)` (`MODEL_NAME` in `.env`).

---

## Environment variables

| Variable | Used by | Description |
|----------|---------|-------------|
| `MODEL_NAME` | API startup | Initial model from `AVAILABLE_MODELS` |
| `YOUTUBE_API_KEY` | `/predict-video` | YouTube Data API v3 |
| `ENV` | logging / behavior | `development` or `production` |

Copy from [`.env.example`](../.env.example).

---

## Errors

| Status | When |
|--------|------|
| `422` | Invalid body (e.g. empty `text`) |
| `503` | Model not loaded yet |
| `500` | Prediction failure |