docs/README.md

metadata

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

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

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)