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

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:

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 atual cria tabelas e executa seed por meio de:

• app/db/init_db.py

Esse bootstrap e usado no container e pode ser executado manualmente antes do servico principal.

Execucao Local

Sem Docker

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

python -m app.db.init_db

3. Inicie o satelite do Telegram:

python -m app.integrations.telegram_satellite_service

Com Docker Compose

O compose atual sobe:

• mysql
• redis
• telegram

Subida completa:

docker compose up --build

Somente infraestrutura:

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 hoje sobe o servico principal do projeto:

python -m app.db.init_db && python -m app.integrations.telegram_satellite_service

Isso deixa o container alinhado com o uso atual do sistema, sem assumir FastAPI como interface principal.

Testes

Suite automatizada atual:

python -m unittest discover -s tests -v

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

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

Arquivos Uteis

• TEST_CASES.md
• DEPLOY_SERVIDOR.md
• .env.example

Proximos Passos Naturais

Os proximos ganhos mais valiosos para o projeto sao:

• persistir trilha de conversa e decisoes
• desacoplar bootstrap de banco do startup da aplicacao
• aumentar observabilidade por turno e por tool
• reduzir o tamanho do OrquestradorService
• consolidar documentacao operacional Telegram-first