poc-v1/README.md

SQL Optimizer Team (Agno)

POC de um time de agentes usando o framework Agno para reproduzir o fluxo do projeto oracle-sql-query-optimizer.

Objetivo

• Receber uma SQL e o banco alvo (oracle/sqlserver/postgresql/mysql/sqlite).
• Gerar explicação detalhada (SQL → linguagem natural).
• Gerar SQL otimizada (linguagem natural → SQL), preservando 100% da lógica de negócio.
• (Opcional) Gerar análise conservadora (sem reescrever a query).

As prompts são mantidas idênticas às do projeto oracle-sql-query-optimizer.

Estrutura

src/
  sql_optimizer_team/
    team_app.py
    agents/
    tools/

Configuração rápida

1. Crie o ambiente e instale dependências:
   • pip install -r requirements.txt
2. Configure variáveis de ambiente (exemplo em sample.env ou .env).
3. Execute o servidor (UI + backend):

• ./scripts/start.sh

Acesse:

• http://localhost:7777/docs (Swagger UI)
• http://localhost:7777 (informações básicas da API)

UI local (Agent UI)

Use o Agent UI (agno-agi/agent-ui) como front local.

• O ./scripts/start.sh já faz tudo automaticamente: clona o Agent UI em ../agent-ui, instala dependências e inicia a UI.
• Abra http://localhost:3000 (o endpoint padrão já é http://localhost:7777).
• Para trocar a porta do backend, use SQL_OPT_TEAM_PORT e ajuste o endpoint na UI.

Manual (se quiser rodar a UI separadamente):

1. npx create-agent-ui@latest
2. pnpm dev

Opcional: se o AgentOS usar autenticação, configure NEXT_PUBLIC_OS_SECURITY_KEY na UI (conforme README do Agent UI).

Fluxo do time

1. Gestor recebe a requisição e valida o contexto (banco + SQL).
2. SQL Analyst gera a explicação detalhada usando a prompt original.
3. SQL Optimizer gera a query otimizada preservando toda a lógica.
4. SQL Quality Reviewer valida fidelidade e checklist.
5. Conservative Analyst (se solicitado) gera análise sem reescrever a query.
6. Gestor consolida e entrega.

RAG (KB interna)

• Coloque documentos em kb/ (md/txt/sql/pdf).
• O RAG local usa Chroma + SentenceTransformers.
• Variáveis principais:
  • SQL_OPT_KB_PATH, SQL_OPT_KB_CHROMA_PATH, SQL_OPT_KB_DB_FILE
  • SQL_OPT_KB_EMBEDDER_ID
  • SQL_OPT_BLOCK_EXTERNAL_TOOLS=true bloqueia ferramentas externas.

Observabilidade de tokens/custos

• Ative com LLM_LOG_USAGE=true.
• Defina preços (USD por 1K tokens) com:
  • LLM_COST_INPUT_PER_1K
  • LLM_COST_OUTPUT_PER_1K

Observações

• Use o provedor configurado em .env (ex.: OpenAI, Gemini, Groq, Mistral ou Ollama local).
• O time é colaborativo e mantém histórico em SQLite (configurável via env).