fix: Add type ignore comment for aiofiles import in file_handler and metadata_repository

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.

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

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