orquestrador/README.md

# AI Orquestrador

Orquestrador conversacional para concessionaria, focado em combinar:
- interpretacao semantica via Vertex AI
- execucao deterministica de tools de negocio
- normalizacao tecnica na aplicacao
- atendimento pelo Telegram como canal principal

## Proposta

A ideia central do sistema e:
- o usuario conversa em linguagem natural
- o modelo entende intencao, contexto e proximo passo
- a aplicacao normaliza dados, protege regras e executa tools
- a resposta final volta para o usuario pelo canal de atendimento

Hoje o projeto esta mais proximo de um orquestrador conversacional do que de uma API tradicional. O FastAPI continua no repositorio como apoio legado/bootstrap, mas o fluxo operacional principal e o satelite do Telegram.

## Estado Atual

O dominio atual cobre dois grupos principais:
- vendas
- revisao e pos-venda

Capacidades ja implementadas:
- consultar estoque de veiculos
- validar cliente para compra
- avaliar veiculo para troca
- criar pedido
- listar pedidos
- cancelar pedido
- agendar revisao
- listar revisoes
- cancelar revisao
- remarcar revisao

Capacidades conversacionais ja tratadas:
- multiplos pedidos na mesma mensagem
- fila de pedidos
- troca de contexto entre dominios
- coleta incremental de campos
- reaproveitamento de contexto temporario
- confirmacao antes de mudar de assunto
- sugestao de horario alternativo em conflito de agenda

## Arquitetura Atual

| Componente | Tecnologia | Papel atual |
| --- | --- | --- |
| LLM | Vertex AI / Gemini | interpretacao e apoio a decisao |
| Orquestracao | Python | coordena contexto, fluxo e tools |
| Metadados de tools | MySQL | catalogo das tools disponiveis |
| Dados mock de negocio | MySQL | veiculos, clientes, usuarios, pedidos e revisoes |
| Estado conversacional | Redis ou memoria | rascunhos, fila e contexto temporario |
| Canal | Telegram Bot API | atendimento principal via long polling |
| Containerizacao | Docker Compose | ambiente local e deploy simples |

## Fluxo Principal

Fluxo principal do atendimento pelo Telegram:

1. O usuario envia uma mensagem ao bot.
2. O `TelegramSatelliteService` identifica ou cria o usuario interno.
3. O `OrquestradorService` recupera o contexto conversacional.
4. O `MessagePlanner` e o Vertex ajudam a estruturar a intencao do turno.
5. A aplicacao continua fluxos abertos ou decide a proxima tool.
6. A tool e executada com validacoes e normalizacoes deterministicas.
7. O sistema devolve a resposta ao usuario no Telegram.

Importante:
- o historico completo da conversa ainda nao e persistido como trilha audivel;
- o estado de trabalho pode ficar em memoria ou Redis;
- em producao, Redis e o backend recomendado para continuidade real.

## Estrutura do Projeto

```text
app/
  main.py
  api/
    schemas.py
  core/
    settings.py
  db/
    database.py
    mock_database.py
    init_db.py
    tool_seed.py
    mock_seed.py
    models/
      tool.py
  integrations/
    telegram_satellite_service.py
  models/
    tool_model.py
  repositories/
    tool_repository.py
    user_repository.py
  services/
    ai/
      llm_service.py
    domain/
      credit_service.py
      inventory_service.py
      order_service.py
      review_service.py
    flows/
      order_flow.py
      review_flow.py
    orchestration/
      conversation_policy.py
      conversation_state_repository.py
      conversation_state_store.py
      entity_normalizer.py
      message_planner.py
      orquestrador_service.py
      prompt_builders.py
      redis_state_repository.py
      response_formatter.py
      tool_executor.py
      turn_decision.py
    tools/
      handlers.py
      tool_registry.py
    user/
      mock_customer_service.py
      user_service.py
tests/
  ...
```

## Tools Disponiveis

As definicoes padrao ficam em [app/db/tool_seed.py](/d:/vitor/Pessoal/PJ/Orquestrador/app/db/tool_seed.py):

| Tool | Finalidade |
| --- | --- |
| `consultar_estoque` | consulta veiculos por preco, categoria e ordenacao |
| `validar_cliente_venda` | valida elegibilidade de compra por CPF e valor |
| `avaliar_veiculo_troca` | estima valor de troca do veiculo do cliente |
| `agendar_revisao` | agenda revisao com calculo de valor |
| `listar_agendamentos_revisao` | lista revisoes do usuario |
| `cancelar_agendamento_revisao` | cancela revisao por protocolo |
| `editar_data_revisao` | remarca revisao existente |
| `realizar_pedido` | cria pedido de compra |
| `listar_pedidos` | lista pedidos do usuario |
| `cancelar_pedido` | cancela pedido existente |
| `limpar_contexto_conversa` | zera contexto e fila |
| `continuar_proximo_pedido` | retoma o proximo item da fila |
| `descartar_pedidos_pendentes` | limpa apenas a fila pendente |
| `cancelar_fluxo_atual` | encerra apenas o fluxo atual |

## Banco e Bootstrap

O projeto usa duas conexoes MySQL:
- banco de tools
- banco mock de negocio

O bootstrap agora e uma rotina dedicada e explicita:
- [app/db/bootstrap.py](/d:/vitor/Pessoal/PJ/Orquestrador/app/db/bootstrap.py)
- [app/db/init_db.py](/d:/vitor/Pessoal/PJ/Orquestrador/app/db/init_db.py) como alias legado de compatibilidade

Importante:
- o container principal nao executa bootstrap automaticamente;
- o app HTTP legado nao executa bootstrap no startup;
- a preparacao de schema e seed deve ser rodada de forma explicita antes do servico principal quando necessario.

## Execucao Local

### Sem Docker

1. Configure as variaveis de ambiente com base em `.env.example`.
2. Inicialize banco e seed com a rotina dedicada:

```bash
python -m app.db.bootstrap
```

Alias legado ainda aceito:

```bash
python -m app.db.init_db
```

3. Inicie o satelite do Telegram:

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

### Com Docker Compose

O compose atual sobe:
- `mysql`
- `redis`
- `telegram`
- `bootstrap` como rotina opcional e dedicada via profile

Preparar banco e seed:

```bash
docker compose --profile bootstrap run --rm bootstrap
```

Subida completa do atendimento:

```bash
docker compose up --build
```

Somente infraestrutura:

```bash
docker compose up mysql redis
```

## Variaveis de Ambiente

Principais variaveis:

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

### Estado conversacional

- `CONVERSATION_STATE_BACKEND` (`memory` ou `redis`)
- `CONVERSATION_STATE_TTL_MINUTES`
- `REDIS_URL`
- `REDIS_KEY_PREFIX`
- `REDIS_SOCKET_TIMEOUT_SECONDS`

### Ambiente

- `ENVIRONMENT`
- `DEBUG`

Observacao:
- para producao com Telegram, prefira `CONVERSATION_STATE_BACKEND=redis`;
- evite valores nao booleanos em `DEBUG`.

## Docker

O [Dockerfile](/d:/vitor/Pessoal/PJ/Orquestrador/Dockerfile) agora sobe apenas o servico principal do projeto:

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

O bootstrap fica separado e pode ser executado quando necessario com:

```bash
python -m app.db.bootstrap
```

Isso evita que um restart do container recrie schema ou rode seed de forma implicita.

## Testes

Suite automatizada atual:

```bash
python -m unittest discover -s tests -v
```

Se o ambiente local tiver `DEBUG` com valor invalido, force antes da execucao:

```bash
DEBUG=false python -m unittest discover -s tests -v
```

## Arquivos Uteis

- [TEST_CASES.md](/d:/vitor/Pessoal/PJ/Orquestrador/TEST_CASES.md)
- [DEPLOY_SERVIDOR.md](/d:/vitor/Pessoal/PJ/Orquestrador/DEPLOY_SERVIDOR.md)
- [.env.example](/d:/vitor/Pessoal/PJ/Orquestrador/.env.example)

## Proximos Passos Naturais

Os proximos ganhos mais valiosos para o projeto sao:
- persistir trilha de conversa e decisoes
- consolidar observabilidade por turno e por tool com baixo acoplamento operacional
- aumentar observabilidade por turno e por tool
- reduzir o tamanho do `OrquestradorService`
- consolidar documentacao operacional Telegram-first