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