# Handoff — BGE-Reranker w LocalAI

Dla agenta kodującego. Kontekst wdrożenia: [`RERANKER-DEPLOYMENT.md`](RERANKER-DEPLOYMENT.md).

## Stan: ukończone na hoście

- [x] GGUF pobrany
- [x] YAML `llama-cpp` + `reranking: true`
- [x] Model widoczny w `/v1/models`
- [x] `/v1/rerank` zwraca HTTP 200

## Zadania opcjonalne (backlog)

- [ ] Dodać `RERANK_MODEL` do dokumentacji klienta / `.env.example` dev hosta
- [ ] Smoke test rerank przez publiczną domenę NPMPlus (z zewnątrz LAN — hairpin NAT na RTX1)
- [ ] Rozważyć Q4_K_M zamiast FP16 jeśli VRAM/latencja przełączania modeli jest problemem
- [ ] Dodać rozdział w `manual-tutorial/05-localai-stack.md` o modelach embed + rerank

## Powtórzenie instalacji (nowy host)

```bash
cd stacks/localai
cp .env.example .env   # ustaw LOCALAI_API_KEY, LOCALAI_PORT=8070
./scripts/download-reranker.sh
docker compose --profile localai restart localai
# czekaj na readyz, potem curl /v1/rerank (patrz RERANKER-DEPLOYMENT.md)
```

## Czego nie robić

- Nie używać `backend: rerankers` dla GGUF
- Nie instalować osobnego backendu — `cuda13-llama-cpp` wystarczy
- Nie commitować `LOCALAI_API_KEY`
- Nie zmieniać `SINGLE_ACTIVE_BACKEND` bez testu VRAM (chat + embed + rerank sekwencyjnie)

## Kluczowe pliki do edycji w przyszłości

| Plik | Kiedy |
|------|-------|
| `stacks/localai/profiles/bge-reranker-v2-m3-FP16-rerank.yaml.example` | zmiana quant / parametrów rerankera |
| `stacks/localai/scripts/download-reranker.sh` | nowy URL lub wariant Q4 |
| `stacks/localai/coding-agent/STATE.md` | po każdej zmianie runtime |

## API — minimalny przykład (Python)

```python
import requests

resp = requests.post(
    "http://127.0.0.1:8070/v1/rerank",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "bge-reranker-v2-m3-FP16.gguf",
        "query": user_query,
        "documents": chunk_texts,
        "top_n": 5,
    },
    timeout=120,
)
resp.raise_for_status()
ranked = resp.json()["results"]  # sorted by relevance_score desc
```