From 4f0dfbadfd23d62732c63de1f968ed3a067de77b Mon Sep 17 00:00:00 2001 From: "william.dias" Date: Wed, 21 Jan 2026 14:18:04 -0300 Subject: [PATCH] fix: Add type ignore comment for aiofiles import in file_handler and metadata_repository --- docs/proposta-arquitetura-agno.md | 115 ++++++++++++++++++ .../persistence/file_handler.py | 2 +- .../persistence/metadata_repository.py | 2 +- 3 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 docs/proposta-arquitetura-agno.md diff --git a/docs/proposta-arquitetura-agno.md b/docs/proposta-arquitetura-agno.md new file mode 100644 index 0000000..bf7cfae --- /dev/null +++ b/docs/proposta-arquitetura-agno.md @@ -0,0 +1,115 @@ +# Proposta de Arquitetura Agnóstica de LLM (Agno) para Otimização de SQL + +## 1) Resumo executivo + +Esta proposta apresenta uma arquitetura moderna baseada em Agno para construção de agentes especializados em performance e refatoração de queries SQL Server e Oracle, com governança, observabilidade e segurança de dados. O objetivo é acelerar a melhoria de desempenho, reduzir custos operacionais e habilitar automações confiáveis em múltiplos setores. + +## 2) Objetivo do projeto + +- Criar um time de agentes especializados em SQL (explicação, otimização, revisão de qualidade e análise conservadora). +- Reaproveitar e evoluir a base existente de prompts e conhecimento. +- Garantir segurança, rastreabilidade e controle de custo/latência. +- Viabilizar RAG corporativo para respostas alinhadas ao conhecimento interno. + +## 3) Escopo funcional + +- Otimização de queries SQL para Oracle e SQL Server. +- Revisão por agente de qualidade com diff e riscos. +- Análise conservadora para cenários sensíveis. +- Execução assistida (manual ou semi-automática) com trilha de auditoria. + +## 4) Benefícios para a diretoria + +- **Eficiência operacional**: redução de tempo gasto por equipes na análise manual de queries. +- **Ganho de performance**: otimizações padronizadas e repetíveis. +- **Escalabilidade**: capacidade de atender múltiplas áreas com o mesmo núcleo de agentes. +- **Governança e compliance**: rastreabilidade, métricas, custos e decisões auditáveis. +- **Redução de risco**: revisão automática e análise conservadora antes de mudanças. + +## 5) Novas possibilidades de automação + +- **Catálogo de otimizações** por área (financeiro, seguros, operações, BI). +- **Rotina diária de otimização** de top N queries críticas. +- **Apoio ao refactoring** em migrações e reengenharias. +- **Assistente de engenharia** para padrões corporativos de SQL. +- **RAG corporativo** para políticas internas, padrões de modelagem e convenções. + +## 6) Arquitetura proposta (Agno-first) + +- **Orquestração Agno**: times e agentes especializados, com histórico e memória controlada. +- **Core de negócio exposto como ferramentas**: casos de uso (ex: otimizar, explicar, comparar) invocados via tools. +- **Módulos únicos sob sql_optimizer_team**: todos os componentes centralizados no mesmo namespace. +- **Integrações corporativas**: bancos, repositórios de conhecimento, logs e custos. + +## 7) Observabilidade (obrigatório) + +Recomendação de ferramentas de mercado: + +- **OpenTelemetry** para traces e métricas. +- **Langfuse** ou **Phoenix** para rastreio de prompts, custos e latência. +- **Grafana/Prometheus** para dashboards executivos. + +Métricas mínimas: + +- Tokens por request e por área. +- Custo estimado mensal por time/serviço. +- Latência média e p95. +- Taxa de retrabalho/recusa. + +## 8) Segurança da informação + +- **RAG isolado**: o modelo opera prioritariamente sobre base interna. +- **Bloqueio de Deep Search na web** por padrão; uso somente com autorização. +- **Mascaramento de dados sensíveis** antes do envio ao LLM. +- **Políticas de retenção** e segregação de dados por área. + +## 9) RAG corporativo + +- Base de conhecimento interna versionada. +- Ingestão de documentação técnica, padrões, e decisões arquiteturais. +- Recuperação com filtros por área e confidencialidade. + +## 10) Frameworks considerados + +### A) Agno (foco recomendado) + +- **Pontos fortes**: orquestração de agentes, memória, tools, execução local, integração rápida. +- **Ideal para**: time de agentes especializados e integração customizada. + +### B) Langflow + +- **Pontos fortes**: low-code visual, facilita protótipos e POCs. +- **Ideal para**: validação rápida de fluxos e PoCs de RAG. + +### C) Dify + +- **Pontos fortes**: plataforma pronta para apps com RAG, autenticação e gestão. +- **Ideal para**: portal de uso corporativo com usuários finais. + +## 11) Recomendações de escolha + +- **Agno** para o core e a arquitetura principal. +- **Langflow** para protótipos e desenho de fluxos. +- **Dify** para distribuição ampla (se desejarem um portal corporativo pronto). + +## 12) Roadmap proposto + +1. **Fase 1**: validação técnica (agentes + prompts + RAG inicial). +2. **Fase 2**: observabilidade + segurança + governança. +3. **Fase 3**: escala para áreas e processos internos. + +## 13) Riscos e mitigação + +- **Qualidade do output**: mitigado com revisão automática + validação conservadora. +- **Custo**: mitigado com observabilidade e limites de uso. +- **Vazamento de dados**: mitigado com RAG isolado e mascaramento. + +## 14) Próximos passos + +- Alinhamento técnico com @Rodrigo Bittencourt De Macedo. +- Definição do escopo mínimo viável (Oracle + SQL Server). +- Aprovação do framework prioritário e das ferramentas de observabilidade. + +--- + +Documento preparado para apresentação executiva, com foco em resultados, governança e segurança. diff --git a/src/sql_optimizer_team/infrastructure/persistence/file_handler.py b/src/sql_optimizer_team/infrastructure/persistence/file_handler.py index 0e4eb61..080e37e 100644 --- a/src/sql_optimizer_team/infrastructure/persistence/file_handler.py +++ b/src/sql_optimizer_team/infrastructure/persistence/file_handler.py @@ -8,7 +8,7 @@ import json from pathlib import Path from typing import Any -import aiofiles +import aiofiles # type: ignore[import-untyped] from sql_optimizer_team.application.ports.storage_port import FileStoragePort from sql_optimizer_team.infrastructure.config.logger import get_logger diff --git a/src/sql_optimizer_team/infrastructure/persistence/metadata_repository.py b/src/sql_optimizer_team/infrastructure/persistence/metadata_repository.py index 6a4c006..2b99fb4 100644 --- a/src/sql_optimizer_team/infrastructure/persistence/metadata_repository.py +++ b/src/sql_optimizer_team/infrastructure/persistence/metadata_repository.py @@ -7,7 +7,7 @@ a JSON file as the storage backend. import json from pathlib import Path -import aiofiles +import aiofiles # type: ignore[import-untyped] from sql_optimizer_team.application.ports.storage_port import MetadataRepositoryPort from sql_optimizer_team.domain.domain.entities.optimization import OptimizationMetadata