Initial commit

docs/api-reference.md

@@ -0,0 +1,88 @@
+# Referência da API
+
+A API REST é servida pelo FastAPI na porta `8000`, implementada em [app/api.py](../code/app/api.py) e orquestrada por [app/backend/orquestrador.py](../code/app/backend/orquestrador.py).
+
+## Endpoints
+
+### `GET /`
+
+Health check da aplicação.
+
+**Resposta:**
+
+```json
+{
+  "status": "ok"
+}
+```
+
+---
+
+### `POST /agent`
+
+Executa uma consulta no agente analítico.
+
+**Request Body (`QueryRequest`):**
+
+| Campo | Tipo | Obrigatório | Descrição |
+|-------|------|-------------|-----------|
+| `query` | `string` | Sim | Pergunta do usuário em português |
+| `history` | `string` | Não | Histórico de mensagens anteriores (serializado) |
+| `model` | `string` | Não | ID do modelo LLM (padrão: Claude Haiku) |
+| `base` | `string` | Não | Nome do dashboard/base de dados |
+
+**Response Body (`QueryResponse`):**
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `response` | `string` | Resposta do agente em português |
+| `input_tokens` | `int` | Total de tokens de entrada consumidos |
+| `output_tokens` | `int` | Total de tokens de saída gerados |
+| `total_tokens` | `int` | Total de tokens (input + output) |
+
+**Exemplo — cURL:**
+
+```bash
+curl -X POST http://localhost:8000/agent \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "Qual foi meu NPS?",
+    "history": "",
+    "model": "anthropic.claude-haiku-4-5-20251001-v1:0",
+    "base": "nome_do_dashboard"
+  }'
+```
+
+**Exemplo — Resposta:**
+
+```json
+{
+  "response": "O NPS foi...",
+  "input_tokens": 1250,
+  "output_tokens": 340,
+  "total_tokens": 1590
+}
+```
+
+## Modelos Disponíveis
+
+| ID do Modelo | Provider |
+|-------------|----------|
+| `anthropic.claude-haiku-4-5-20251001-v1:0` | Anthropic |
+| `anthropic.claude-sonnet-4-5-20250929-v1:0` | Anthropic |
+| `meta.llama4-maverick-17b-instruct-v1:0` | Meta |
+| `meta.llama4-scout-17b-instruct-v1:0` | Meta |
+| `amazon.nova-lite-v1:0` | Amazon |
+| `amazon.nova-pro-v1:0` | Amazon |
+| `amazon.nova-2-lite-v1:0` | Amazon |
+
+## Bases Disponíveis
+
+As bases são carregadas dinamicamente do DynamoDB (tabela `TABLE`, index `item_type_index`, `item_type = "contexto"`). O formato do nome segue o padrão `{cliente}_{dashboard}`.
+
+## Documentação Interativa
+
+Com a aplicação rodando:
+
+- **Swagger UI:** `http://localhost:8000/docs`
+- **ReDoc:** `http://localhost:8000/redoc`