docs/README.md

---
title: Assuntos Juridicos API
emoji: ⚖️
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
---

# ⚖️ Assuntos Jurídicos — FastAPI + Elasticsearch

API de busca full-text sobre **5.184 assuntos jurídicos** do STJ/TST em 22 ramos do Direito.

---

## 🚀 Dois modos de execução

### Modo 1 — HuggingFace Spaces (single container)
> ES + FastAPI **no mesmo container** — sem docker-compose

```bash
# HuggingFace usa apenas o Dockerfile automaticamente
# ES_HOST padrão = http://localhost:9200
```

O `entrypoint.sh` faz tudo:
1. Inicia Elasticsearch em background (porta 9200 local)
2. Baixa `bulk_assuntos.ndjson` do GitHub (~15 MB)
3. FastAPI indexa os dados no startup
4. API disponível em `:7860`

### Modo 2 — Desenvolvimento local (docker-compose)
```bash
git clone https://huggingface.co/spaces/SEU_USER/SEU_SPACE
cd SEU_SPACE

# Sobe ES separado + API (ES_HOST=http://elasticsearch:9200)
docker compose up --build

# Acesse
open http://localhost:7860/docs
```

---

## 📡 Endpoints

| Método | Rota | Descrição |
|--------|------|-----------|
| GET | `/` | Landing page |
| GET | `/health` | Status API + ES |
| GET | `/busca?q=...` | Full-text + filtros + facets |
| POST | `/busca` | Busca via JSON |
| GET | `/autocomplete?q=...` | Typeahead |
| GET | `/assuntos/{id}` | Detalhe por ID |
| GET | `/hierarquia` | Árvore de ramos/categorias |
| GET | `/grafo/filhos?ancestor=...` | Drill-down |
| POST | `/admin/reindex` | Re-indexa tudo |
| GET | `/docs` | Swagger UI |

---

## 🗂️ Estrutura

```
├── Dockerfile              ← single-container (ES + FastAPI)
├── docker-compose.yml      ← multi-container (dev local)
├── entrypoint.sh           ← inicia ES + download + uvicorn
├── app/
│   ├── main.py
│   ├── routes.py
│   ├── es_client.py
│   ├── schemas.py
│   ├── builders.py
│   └── config.py
├── data/
│   └── es_mapping.json     ← único arquivo de dados no repo
└── scripts/
    └── test_api.py
```

## ⚙️ Variáveis de Ambiente

| Variável | HF Spaces | Docker Compose |
|----------|-----------|----------------|
| `ES_HOST` | `http://localhost:9200` | `http://elasticsearch:9200` |
| `ES_INDEX` | `assuntos_juridicos` | `assuntos_juridicos` |
| `PORT` | `7860` | `7860` |
| `WORKERS` | `1` | `1` |
| `ES_JAVA_OPTS` | `-Xms512m -Xmx512m` | (gerenciado pelo ES container) |