orquestrador/README.md

# AI Orquestrador

Backend conversacional para concessionária, focado em orquestrar ferramentas de negócio com apoio de LLM.

A proposta do sistema é:
- receber uma mensagem em linguagem natural
- deixar o modelo interpretar a intenção do usuário
- usar ferramentas do sistema quando precisar consultar dados ou executar ações
- devolver uma resposta objetiva ao usuário

Hoje o projeto já implementa esse fluxo, mas ainda inclui camadas de suporte ao modelo, como extração estruturada, memória temporária por usuário, coleta incremental de dados e fallback determinístico de resposta.

## Visão Geral

O domínio atual do projeto cobre dois fluxos principais:
- vendas
- revisão/pós-venda

O sistema consegue:
- consultar estoque de veículos
- validar cliente para compra
- avaliar veículo para troca
- criar pedido de compra
- cancelar pedido
- agendar revisão
- listar revisões agendadas
- cancelar revisão
- remarcar revisão

Além do roteamento por tool, o orquestrador também trata cenários conversacionais como:
- mensagens com mais de um pedido na mesma entrada
- coleta de parâmetros em múltiplas mensagens
- reaproveitamento de contexto temporário
- confirmação antes de trocar de assunto
- sugestão de próximo horário quando uma revisão entra em conflito

## Stack Atual

| Componente | Tecnologia | Observação |
| --- | --- | --- |
| Backend | FastAPI | API principal |
| LLM | Google Vertex AI | Modelos Gemini |
| Banco de tools | MySQL | Metadados das ferramentas |
| Banco mock de negócio | MySQL | Veículos, clientes, usuários, pedidos e revisões |
| ORM | SQLAlchemy | Acesso aos dois bancos |
| Runtime | Python 3.11+ | Aplicação principal |
| Integração de canal | Telegram Bot API | Long polling via serviço satélite |
| Containerização | Docker | Ambiente local e deploy |

## Como o Sistema Funciona

Fluxo principal do `/chat`:

1. O usuário envia uma mensagem.
2. O `OrquestradorService` inicializa ou atualiza o contexto temporário do usuário.
3. O sistema tenta separar múltiplos pedidos contidos na mesma mensagem.
4. O LLM ajuda a extrair intenções e entidades estruturadas.
5. Se houver fluxo em aberto, o orquestrador continua a coleta dos dados faltantes.
6. Quando necessário, o modelo escolhe uma tool.
7. A tool é executada pelos handlers do sistema.
8. O resultado é devolvido ao usuário, usando resposta do modelo ou fallback determinístico.

Importante:
- a memória de conversa atual é volátil e fica em memória do processo
- o sistema ainda não persiste histórico conversacional entre reinícios
- o `response_formatter` responde direto ao usuário; ele não devolve o resultado para o modelo

## Estrutura do Projeto

```text
app/
  main.py
  api/
    routes/
      chat.py
      mock.py
      tools.py
      dependencies.py
    schemas.py
  core/
    settings.py
  db/
    database.py
    mock_database.py
    init_db.py
    tool_seed.py
    mock_seed.py
    models/
      tool.py
  repositories/
    tool_repository.py
    user_repository.py
  integrations/
    telegram_satellite_service.py
  services/
    ai/
      llm_service.py
    flows/
      order_flow.py
      review_flow.py
    orchestration/
      orquestrador_service.py
      orchestrator_config.py
      conversation_state_store.py
      prompt_builders.py
      response_formatter.py
    tools/
      handlers.py
      tool_registry.py
    user/
      user_service.py
```

## Organização das Camadas

### `services/orchestration`

Núcleo do orquestrador:
- coordenação do fluxo conversacional
- controle de contexto ativo
- fila de pedidos
- construção de prompts
- fallback de resposta

### `services/flows`

Fluxos incrementais de negócio:
- criação e cancelamento de pedido
- agendamento, listagem, cancelamento e remarcação de revisão

### `services/ai`

Integração com Vertex AI e Gemini.

### `services/tools`

Registro das tools e implementação dos handlers que executam as ações reais.

### `services/user`

Serviços ligados à identificação e persistência de usuários de canal, como Telegram.

## Ferramentas Disponíveis

As tools padrão são semeadas a partir de [app/db/tool_seed.py](app/db/tool_seed.py):

| Tool | Finalidade |
| --- | --- |
| `consultar_estoque` | Consulta veículos por preço, categoria e ordenação |
| `validar_cliente_venda` | Valida elegibilidade de compra por CPF e valor |
| `avaliar_veiculo_troca` | Estima valor de troca do veículo do cliente |
| `agendar_revisao` | Agenda revisão com cálculo de valor |
| `listar_agendamentos_revisao` | Lista revisões do usuário |
| `cancelar_agendamento_revisao` | Cancela uma revisão por protocolo |
| `editar_data_revisao` | Remarca revisão existente |
| `realizar_pedido` | Cria pedido de compra |
| `cancelar_pedido` | Cancela pedido existente |

## Bancos e Seeds

O projeto usa duas conexões distintas:

### Banco de tools

Responsável por armazenar:
- nome da tool
- descrição
- schema de parâmetros

Arquivos principais:
- `app/db/database.py`
- `app/db/models/tool.py`
- `app/db/tool_seed.py`

### Banco mock de negócio

Responsável por armazenar dados fictícios de:
- veículos
- clientes
- usuários
- pedidos
- agendamentos de revisão

Arquivos principais:
- `app/db/mock_database.py`
- `app/db/mock_models.py`
- `app/db/mock_seed.py`

No startup, a aplicação tenta:
- criar as tabelas dos dois bancos
- popular tools
- popular dados mock
- fazer warmup do LLM

## Endpoints

### Chat

- `POST /chat`
  - entrada principal do orquestrador

### Tools

- `GET /tools/`
- `POST /tools/`
- `GET /tools/{tool_id}`
- `DELETE /tools/{tool_id}`

### Mock

Endpoints diretos para depuração e testes manuais dos handlers:

- `POST /mock/consultar-estoque`
- `POST /mock/validar-cliente-venda`
- `POST /mock/avaliar-veiculo-troca`
- `POST /mock/agendar-revisao`
- `POST /mock/listar-agendamentos-revisao`
- `POST /mock/cancelar-agendamento-revisao`
- `POST /mock/editar-data-revisao`
- `POST /mock/realizar-pedido`
- `POST /mock/cancelar-pedido`

Documentação interativa:
- `GET /docs`

## Execução Local

### Sem Docker

```bash
uvicorn app.main:app --reload
```

### Com Docker Compose

```bash
docker-compose up
```

Arquivos úteis:
- `TEST_CASES.md`
- `DEPLOY_SERVIDOR.md`
- `.env.example`

## Variáveis de Ambiente

Principais variáveis:

### Vertex AI

- `GOOGLE_PROJECT_ID`
- `GOOGLE_LOCATION`
- `VERTEX_MODEL_NAME`

### Banco de tools

- `DB_HOST`
- `DB_PORT`
- `DB_USER`
- `DB_PASSWORD`
- `DB_NAME`
- `DB_CLOUD_SQL_CONNECTION_NAME`

### Banco mock

- `MOCK_DB_HOST`
- `MOCK_DB_PORT`
- `MOCK_DB_USER`
- `MOCK_DB_PASSWORD`
- `MOCK_DB_NAME`
- `MOCK_DB_CLOUD_SQL_CONNECTION_NAME`
- `MOCK_SEED_ENABLED`
- `AUTO_SEED_TOOLS`
- `AUTO_SEED_MOCK`

### Telegram

- `TELEGRAM_BOT_TOKEN`
- `TELEGRAM_POLLING_TIMEOUT`
- `TELEGRAM_REQUEST_TIMEOUT`

## Telegram Satellite Service

Existe um serviço satélite para atendimento via Telegram em long polling.

Arquivo principal:
- `app/integrations/telegram_satellite_service.py`

Execução:

```bash
python -m app.integrations.telegram_satellite_service
```

Esse serviço:
- consome mensagens do Telegram
- cria ou recupera o usuário interno
- encaminha a mensagem para o `OrquestradorService`
- envia a resposta de volta ao chat

## Estado Atual do Projeto

O sistema já está além de um MVP simples de tool calling. Hoje ele combina:
- decisão assistida por modelo
- execução determinística de tools
- memória volátil por usuário
- fluxos multi-etapas
- múltiplos pedidos na mesma conversa

Pontos que ainda permanecem em aberto:
- persistência real de histórico conversacional
- suíte automatizada de testes
- evolução da autonomia do modelo
- alinhamento contínuo entre prompts, fluxo e regras de negócio