chore: organize planning documents into .local-archive

- Move all planning and internal documents to .local-archive/
- Add .local-archive/ to .gitignore
- Move ROADMAP, API_DATA_STRUCTURES, test analysis to archive
- Move internal docs from docs/internal/ to archive
- Create README for local archive structure
- Keep only production-relevant docs in main repository

.gitignore

@@ -1,3 +1,6 @@
+# Local archive - planning and internal docs
+.local-archive/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

API_DATA_STRUCTURES.md

@@ -1,527 +0,0 @@
-# Cidadão.AI Backend API Data Structures
-
-This document provides a comprehensive reference for all Pydantic models, request/response schemas, and data structures used in the Cidadão.AI backend API that a frontend application would need to implement.
-
-## Table of Contents
-1. [Chat API Models](#chat-api-models)
-2. [WebSocket Models](#websocket-models)
-3. [Investigation Models](#investigation-models)
-4. [Authentication Models](#authentication-models)
-5. [Agent Models](#agent-models)
-6. [Pagination Models](#pagination-models)
-7. [Error Response Format](#error-response-format)
-
----
-
-## Chat API Models
-
-### ChatRequest
-```python
-class ChatRequest(BaseModel):
-    """Chat message request"""
-    message: str  # min_length=1, max_length=1000
-    session_id: Optional[str] = None
-    context: Optional[Dict[str, Any]] = None
-```
-
-### ChatResponse
-```python
-class ChatResponse(BaseModel):
-    """Chat message response"""
-    session_id: str
-    agent_id: str
-    agent_name: str
-    message: str
-    confidence: float
-    suggested_actions: Optional[List[str]] = None
-    requires_input: Optional[Dict[str, str]] = None
-    metadata: Dict[str, Any] = {}
-```
-
-### QuickAction
-```python
-class QuickAction(BaseModel):
-    """Quick action suggestion"""
-    id: str
-    label: str
-    icon: str
-    action: str
-```
-
-### Stream Response Format (SSE)
-```javascript
-// Server-Sent Events format for /api/v1/chat/stream
-data: {"type": "start", "timestamp": "2025-01-19T12:00:00Z"}
-data: {"type": "detecting", "message": "Analisando sua mensagem..."}
-data: {"type": "intent", "intent": "investigate", "confidence": 0.92}
-data: {"type": "agent_selected", "agent_id": "zumbi", "agent_name": "Zumbi dos Palmares"}
-data: {"type": "chunk", "content": "Olá! Sou Zumbi dos Palmares..."}
-data: {"type": "complete", "suggested_actions": ["start_investigation", "learn_more"]}
-data: {"type": "error", "message": "Erro ao processar mensagem"}
-```
-
----
-
-## WebSocket Models
-
-### WebSocketMessage
-```python
-class WebSocketMessage(BaseModel):
-    """WebSocket message structure"""
-    type: str  # Message type
-    data: Dict[str, Any] = {}
-    timestamp: datetime = Field(default_factory=datetime.utcnow)
-    id: str = Field(default_factory=lambda: str(uuid4()))
-```
-
-### WebSocket Connection URL
-```
-ws://localhost:8000/api/v1/ws/chat/{session_id}?token={jwt_token}
-```
-
-### WebSocket Message Types
-
-#### Client to Server
-```javascript
-// Send chat message
-{
-    "type": "chat_message",
-    "data": {
-        "message": "Investigar contratos do Ministério da Saúde",
-        "context": {}
-    }
-}
-
-// Subscribe to investigation
-{
-    "type": "subscribe_investigation",
-    "data": {
-        "investigation_id": "123e4567-e89b-12d3-a456-426614174000"
-    }
-}
-
-// Unsubscribe from investigation
-{
-    "type": "unsubscribe_investigation",
-    "data": {
-        "investigation_id": "123e4567-e89b-12d3-a456-426614174000"
-    }
-}
-
-// Keep alive ping
-{
-    "type": "ping",
-    "data": {}
-}
-```
-
-#### Server to Client
-```javascript
-// Connection established
-{
-    "type": "connection",
-    "data": {
-        "status": "connected",
-        "session_id": "abc123",
-        "message": "Conectado ao Cidadão.AI em tempo real"
-    },
-    "timestamp": "2025-01-19T12:00:00Z",
-    "id": "msg123"
-}
-
-// Agent response
-{
-    "type": "agent_response",
-    "data": {
-        "agent_id": "zumbi",
-        "agent_name": "Zumbi dos Palmares",
-        "message": "Encontrei 15 anomalias nos contratos...",
-        "confidence": 0.92,
-        "metadata": {
-            "processing_time_ms": 1250,
-            "anomalies_found": 15
-        }
-    }
-}
-
-// Investigation update
-{
-    "type": "investigation_update",
-    "data": {
-        "investigation_id": "123e4567",
-        "status": "processing",
-        "progress": 0.75,
-        "current_phase": "analyzing_patterns",
-        "anomalies_detected": 12
-    }
-}
-
-// Error message
-{
-    "type": "error",
-    "data": {
-        "code": "PROCESSING_ERROR",
-        "message": "Failed to process request",
-        "details": {}
-    }
-}
-
-// Pong response
-{
-    "type": "pong",
-    "data": {}
-}
-```
-
----
-
-## Investigation Models
-
-### InvestigationRequest
-```python
-class InvestigationRequest(BaseModel):
-    """Request model for starting an investigation"""
-    query: str  # Investigation query or focus area
-    data_source: str = "contracts"  # One of: contracts, expenses, agreements, biddings, servants
-    filters: Dict[str, Any] = {}
-    anomaly_types: List[str] = ["price", "vendor", "temporal", "payment"]
-    include_explanations: bool = True
-    stream_results: bool = False
-```
-
-### InvestigationResponse
-```python
-class InvestigationResponse(BaseModel):
-    """Response model for investigation results"""
-    investigation_id: str
-    status: str
-    query: str
-    data_source: str
-    started_at: datetime
-    completed_at: Optional[datetime] = None
-    anomalies_found: int
-    total_records_analyzed: int
-    results: List[Dict[str, Any]]
-    summary: str
-    confidence_score: float
-    processing_time: float
-```
-
-### AnomalyResult
-```python
-class AnomalyResult(BaseModel):
-    """Individual anomaly result"""
-    anomaly_id: str
-    type: str  # price, vendor, temporal, payment, duplicate, pattern
-    severity: str  # low, medium, high, critical
-    confidence: float
-    description: str
-    explanation: str
-    affected_records: List[Dict[str, Any]]
-    suggested_actions: List[str]
-    metadata: Dict[str, Any]
-```
-
-### InvestigationStatus
-```python
-class InvestigationStatus(BaseModel):
-    """Investigation status response"""
-    investigation_id: str
-    status: str  # started, processing, completed, failed
-    progress: float  # 0.0 to 1.0
-    current_phase: str
-    records_processed: int
-    anomalies_detected: int
-    estimated_completion: Optional[datetime] = None
-```
-
----
-
-## Authentication Models
-
-### LoginRequest
-```python
-class LoginRequest(BaseModel):
-    email: str  # EmailStr
-    password: str
-```
-
-### LoginResponse
-```python
-class LoginResponse(BaseModel):
-    access_token: str
-    refresh_token: str
-    token_type: str = "bearer"
-    expires_in: int  # seconds
-    user: {
-        "id": str,
-        "email": str,
-        "name": str,
-        "role": str,
-        "is_active": bool
-    }
-```
-
-### RefreshRequest
-```python
-class RefreshRequest(BaseModel):
-    refresh_token: str
-```
-
-### RefreshResponse
-```python
-class RefreshResponse(BaseModel):
-    access_token: str
-    token_type: str = "bearer"
-    expires_in: int  # seconds
-```
-
-### RegisterRequest
-```python
-class RegisterRequest(BaseModel):
-    email: str  # EmailStr
-    password: str
-    name: str
-    role: Optional[str] = "analyst"
-```
-
-### UserResponse
-```python
-class UserResponse(BaseModel):
-    id: str
-    email: str
-    name: str
-    role: str
-    is_active: bool
-    created_at: datetime
-    last_login: Optional[datetime] = None
-```
-
-### Authorization Header
-```
-Authorization: Bearer {access_token}
-```
-
----
-
-## Agent Models
-
-### AgentMessage
-```python
-class AgentMessage(BaseModel):
-    """Message passed between agents"""
-    sender: str  # Agent that sent the message
-    recipient: str  # Agent that should receive the message
-    action: str  # Action to perform
-    payload: Dict[str, Any] = {}
-    context: Dict[str, Any] = {}
-    timestamp: datetime
-    message_id: str
-    requires_response: bool = True
-```
-
-### AgentResponse
-```python
-class AgentResponse(BaseModel):
-    """Response from an agent"""
-    agent_name: str
-    status: str  # IDLE, PROCESSING, COMPLETED, ERROR, REFLECTING
-    result: Optional[Any] = None
-    error: Optional[str] = None
-    metadata: Dict[str, Any] = {}
-    timestamp: datetime
-    processing_time_ms: Optional[float] = None
-```
-
-### Available Agents
-```javascript
-const AGENTS = {
-    abaporu: { name: "Abaporu", role: "Orquestrador" },
-    zumbi: { name: "Zumbi dos Palmares", role: "Investigador" },
-    anita: { name: "Anita Garibaldi", role: "Analista" },
-    tiradentes: { name: "Tiradentes", role: "Relator" },
-    machado: { name: "Machado de Assis", role: "Textual" },
-    dandara: { name: "Dandara", role: "Justiça Social" },
-    drummond: { name: "Carlos Drummond de Andrade", role: "Comunicação" }
-}
-```
-
----
-
-## Pagination Models
-
-### CursorPaginationRequest
-```python
-class CursorPaginationRequest(BaseModel):
-    """Request parameters for cursor pagination"""
-    cursor: Optional[str] = None  # Base64 encoded cursor
-    limit: int = 20  # min=1, max=100
-    direction: str = "next"  # next or prev
-```
-
-### CursorPaginationResponse
-```python
-class CursorPaginationResponse(BaseModel):
-    """Response with cursor pagination metadata"""
-    items: List[T]
-    next_cursor: Optional[str] = None
-    prev_cursor: Optional[str] = None
-    has_more: bool = False
-    total_items: Optional[int] = None
-    metadata: Dict[str, Any] = {}
-```
-
-### Cursor Format
-```javascript
-// Cursor is base64 encoded JSON
-{
-    "t": "2025-01-19T12:00:00Z",  // timestamp
-    "i": "123e4567",               // id
-    "d": "next"                    // direction
-}
-```
-
----
-
-## Error Response Format
-
-All API errors follow this standardized format:
-
-### HTTP Exception Response
-```javascript
-{
-    "status": "error",
-    "status_code": 400,  // HTTP status code
-    "error": {
-        "error": "HTTPException",
-        "message": "Invalid request data",
-        "details": {}
-    }
-}
-```
-
-### Application Error Response
-```javascript
-{
-    "status": "error",
-    "status_code": 500,
-    "error": {
-        "error": "InternalServerError",
-        "message": "An unexpected error occurred",
-        "details": {
-            "error_type": "DatabaseConnectionError"  // Only in development
-        }
-    }
-}
-```
-
-### Custom Exception Format (CidadaoAIError)
-```javascript
-{
-    "error": "AgentExecutionError",  // Error code
-    "message": "Agent failed to execute task",
-    "details": {
-        "agent": "zumbi",
-        "action": "investigate",
-        "error": "Connection timeout"
-    }
-}
-```
-
----
-
-## Common HTTP Status Codes
-
-- `200 OK` - Success
-- `201 Created` - Resource created
-- `400 Bad Request` - Invalid request data
-- `401 Unauthorized` - Missing or invalid authentication
-- `403 Forbidden` - Insufficient permissions
-- `404 Not Found` - Resource not found
-- `422 Unprocessable Entity` - Validation error
-- `429 Too Many Requests` - Rate limit exceeded
-- `500 Internal Server Error` - Server error
-
----
-
-## API Base URLs
-
-### Development
-```
-http://localhost:8000/api/v1
-ws://localhost:8000/api/v1/ws
-```
-
-### Production (HuggingFace Spaces)
-```
-https://neural-thinker-cidadao-ai-backend.hf.space/api/v1
-wss://neural-thinker-cidadao-ai-backend.hf.space/api/v1/ws
-```
-
----
-
-## TypeScript Interface Examples
-
-For TypeScript frontend implementations, here are the equivalent interfaces:
-
-```typescript
-// Chat interfaces
-interface ChatRequest {
-    message: string;
-    session_id?: string;
-    context?: Record<string, any>;
-}
-
-interface ChatResponse {
-    session_id: string;
-    agent_id: string;
-    agent_name: string;
-    message: string;
-    confidence: number;
-    suggested_actions?: string[];
-    requires_input?: Record<string, string>;
-    metadata: Record<string, any>;
-}
-
-// WebSocket interfaces
-interface WebSocketMessage {
-    type: string;
-    data: Record<string, any>;
-    timestamp: string;
-    id: string;
-}
-
-// Investigation interfaces
-interface InvestigationRequest {
-    query: string;
-    data_source?: 'contracts' | 'expenses' | 'agreements' | 'biddings' | 'servants';
-    filters?: Record<string, any>;
-    anomaly_types?: string[];
-    include_explanations?: boolean;
-    stream_results?: boolean;
-}
-
-// Error interface
-interface ErrorResponse {
-    status: 'error';
-    status_code: number;
-    error: {
-        error: string;
-        message: string;
-        details: Record<string, any>;
-    };
-}
-```
-
----
-
-## Notes for Frontend Developers
-
-1. **Authentication**: All authenticated endpoints require the `Authorization: Bearer {token}` header
-2. **WebSocket**: Connect with JWT token as query parameter for authentication
-3. **Pagination**: Use cursor-based pagination for chat history and large datasets
-4. **Error Handling**: Always check for error responses and handle appropriately
-5. **SSE Streaming**: For real-time responses, use EventSource API with `/api/v1/chat/stream`
-6. **Rate Limiting**: Respect rate limits indicated in response headers
-7. **Timestamp Format**: All timestamps are in ISO 8601 format (UTC)
-8. **IDs**: All entity IDs are UUIDs in string format

ROADMAP_MELHORIAS_2025.md

@@ -1,333 +0,0 @@
-# 🚀 Roadmap de Melhorias - Cidadão.AI Backend
-
-**Autor**: Anderson Henrique da Silva  
-**Data**: 2025-09-24 14:52:00 -03:00  
-**Versão**: 1.2  
-**Última Atualização**: 2025-09-25 - Sprint 9 concluída
-
-## 📊 Status do Progresso
-
-- **✅ Sprint 1**: Concluída - Segurança e Testes Críticos
-- **✅ Sprint 2**: Concluída - Refatoração de Agentes e Performance
-- **✅ Sprint 3**: Concluída - Infraestrutura de Testes e Monitoramento
-- **✅ Sprint 4**: Concluída - Sistema de Notificações e Exports (100% completo)
-- **✅ Sprint 5**: Concluída - CLI & Automação com Batch Processing (100% completo)
-- **✅ Sprint 6**: Concluída - Segurança de API & Performance (100% completo)
-- **✅ Sprint 7**: Concluída - Agentes de Análise (100% completo)
-- **✅ Sprint 8**: Concluída - Agentes de Dados e APIs (100% completo)
-- **✅ Sprint 9**: Concluída - Agentes Especializados e ML Pipeline (100% completo)
-- **📅 Sprints 10-12**: Planejadas
-
-**Progresso Geral**: 75% (9/12 sprints concluídas)
-
-## 📋 Resumo Executivo
-
-Este documento apresenta um roadmap estruturado para melhorias no backend do Cidadão.AI, baseado em análise detalhada da arquitetura, segurança, performance e funcionalidades. As melhorias estão organizadas em sprints quinzenais com foco em entregar valor incremental.
-
-## 🎯 Objetivos Principais
-
-1. **Elevar cobertura de testes de 45% para 80%**
-2. **Resolver vulnerabilidades críticas de segurança**
-3. **Completar implementação dos 17 agentes**
-4. **Otimizar performance para atingir SLAs definidos**
-5. **Adicionar features enterprise essenciais**
-
-## 📅 Timeline: 6 Meses (12 Sprints)
-
-### 🔴 **FASE 1: FUNDAÇÃO CRÍTICA** (Sprints 1-3)
-*Foco: Segurança, Testes e Estabilidade*
-
-#### ✅ Sprint 1 (Semanas 1-2) - CONCLUÍDA
-**Tema: Segurança Crítica & Testes de Emergência**
-
-1. **Segurança Urgente**
-   - [x] Migrar autenticação in-memory para PostgreSQL
-   - [x] Re-habilitar detecção de padrões suspeitos (linha 267 security.py)
-   - [x] Implementar rate limiting distribuído com Redis
-   - [x] Adicionar blacklist de tokens JWT
-
-2. **Testes Críticos**
-   - [x] Testes para chat_emergency.py (fallback crítico)
-   - [x] Testes para sistema de cache
-   - [x] Testes para OAuth endpoints
-   - [x] Testes básicos para os 3 agentes legados
-
-**Entregáveis**: Sistema mais seguro, cobertura >55% ✅
-
-#### ✅ Sprint 2 (Semanas 3-4) - CONCLUÍDA
-**Tema: Refatoração de Agentes Legados**
-
-1. **Migração de Agentes**
-   - [x] Refatorar Zumbi para novo padrão BaseAgent
-   - [x] Refatorar Anita para novo padrão
-   - [x] Refatorar Tiradentes para novo padrão
-   - [x] Atualizar testes dos agentes migrados
-
-2. **Performance Quick Wins**
-   - [x] Substituir todos `import json` por `json_utils`
-   - [x] Corrigir file I/O síncronos com asyncio
-   - [x] Remover todos `time.sleep()`
-
-**Entregáveis**: 100% agentes no padrão moderno ✅
-
-#### ✅ Sprint 3 (Semanas 5-6) - CONCLUÍDA
-**Tema: Infraestrutura de Testes**
-
-1. **Expansão de Testes**
-   - [x] Testes para agent_pool.py
-   - [x] Testes para parallel_processor.py
-   - [x] Testes para circuito breakers
-   - [x] Testes de integração para fluxos principais
-
-2. **Monitoramento**
-   - [x] Implementar métricas Prometheus em todos endpoints
-   - [x] Criar dashboards de SLO/SLA
-   - [x] Configurar alertas críticos
-
-**Entregáveis**: Cobertura >65%, observabilidade completa ✅
-
-### 🟡 **FASE 2: FEATURES CORE** (Sprints 4-6)
-*Foco: Completar Funcionalidades Essenciais*
-
-#### ✅ Sprint 4 (Semanas 7-8) - CONCLUÍDA
-**Tema: Sistema de Notificações**
-
-1. **Notificações** ✅ (100% Completo - 2025-09-24)
-   - [x] Implementar envio de emails (SMTP) com aiosmtplib
-   - [x] Webhook notifications com retry logic e assinatura de segurança
-   - [x] Sistema de templates com Jinja2 (base, notification, investigation_complete, anomaly_alert)
-   - [x] Gestão de preferências com API REST completa
-   - [x] Suporte a múltiplos canais (email, webhook, push futuro)
-   - [x] Compatibilidade com HuggingFace (serviços opcionais)
-
-2. **Export/Download** ✅ (100% Completo - 2025-09-25)
-   - [x] Geração de PDF real com reportlab e formatação profissional
-   - [x] Export Excel/CSV com openpyxl e pandas
-   - [x] Bulk export com compressão ZIP
-   - [x] Rotas de export para investigações, contratos e anomalias
-   - [x] Integração do PDF no agente Tiradentes
-   - [x] Testes completos para todas funcionalidades de export
-
-**Entregáveis**: Sistema de notificações e exports 100% funcional ✅
-
-#### ✅ Sprint 5 (Semanas 9-10) - CONCLUÍDA
-**Tema: CLI & Automação**
-
-1. **CLI Commands** ✅ (100% Completo - 2025-09-25)
-   - [x] Implementar `cidadao investigate` com streaming e múltiplos formatos de saída
-   - [x] Implementar `cidadao analyze` com análise de padrões e visualização em dashboard
-   - [x] Implementar `cidadao report` com geração de relatórios e download em PDF/Excel/Markdown
-   - [x] Implementar `cidadao watch` com monitoramento em tempo real e alertas
-
-2. **Batch Processing** ✅ (100% Completo - 2025-09-25)
-   - [x] Sistema de filas com prioridade usando heapq e async workers
-   - [x] Integração Celery para job scheduling com 5 níveis de prioridade
-   - [x] Retry mechanisms com políticas configuráveis (exponential backoff, circuit breaker)
-   - [x] Batch service completo com API REST para submissão e monitoramento
-   - [x] Tasks Celery para investigação, análise, relatórios, export e monitoramento
-
-**Entregáveis**: CLI totalmente funcional com comandos ricos em features, sistema de batch processing enterprise-grade com Celery, filas de prioridade e retry avançado ✅
-
-#### ✅ Sprint 6 (Semanas 11-12) - CONCLUÍDA
-**Tema: Segurança de API & Performance**
-
-1. **Segurança de API** ✅ (100% Completo)
-   - [x] API key rotation automática para integrações - Sistema com grace periods e notificações
-   - [x] Rate limiting avançado por endpoint/cliente - Múltiplas estratégias (sliding window, token bucket)
-   - [x] Request signing/HMAC para webhooks - Suporte para GitHub e genérico
-   - [x] IP whitelist para ambientes produtivos - Suporte CIDR e gestão via API
-   - [x] CORS configuration refinada - Otimizado para Vercel com patterns dinâmicos
-
-2. **Performance & Caching** ✅ (100% Completo)
-   - [x] Cache warming strategies - Sistema com múltiplas estratégias e agendamento
-   - [x] Database query optimization (índices) - Análise de slow queries e criação automática
-   - [x] Response compression (Brotli/Gzip) - Suporte para múltiplos algoritmos e streaming
-   - [x] Connection pooling optimization - Pools dinâmicos com monitoramento e health checks
-   - [x] Lazy loading para agentes - Sistema completo com unload automático e gestão de memória
-
-**Entregáveis**: API segura com rate limiting avançado, cache warming, compressão otimizada, pools de conexão gerenciados e lazy loading inteligente de agentes ✅
-
-### 🟢 **FASE 3: AGENTES AVANÇADOS** (Sprints 7-9)
-*Foco: Completar Sistema Multi-Agente*
-
-#### ✅ Sprint 7 (Semanas 13-14) - CONCLUÍDA
-**Tema: Agentes de Análise**
-
-1. **Implementar Agentes** ✅ (100% Completo)
-   - [x] José Bonifácio (Policy Analyst) - análise de políticas públicas com ROI social
-   - [x] Maria Quitéria (Security) - auditoria de segurança e compliance
-   - [x] Testes completos para novos agentes (unit, integration, performance)
-
-2. **Integração** ✅ (100% Completo)
-   - [x] Orquestração avançada entre agentes (patterns: sequential, parallel, saga, etc.)
-   - [x] Métricas de performance por agente com Prometheus e API dedicada
-   - [x] Circuit breaker e retry patterns implementados
-
-**Entregáveis**: 10/17 agentes operacionais, sistema de orquestração completo, métricas detalhadas
-
-#### ✅ Sprint 8 (Semanas 15-16) - CONCLUÍDA
-**Tema: Agentes de ETL e APIs de Dados**
-
-1. **Implementar Agentes** ✅ (100% Completo)
-   - [x] Oscar Niemeyer (Data Aggregation) - agregação de dados e APIs de metadados
-   - [x] Ceuci (ETL) - já existe como agente de análise preditiva
-   - [x] Lampião (Regional) - análise e agregação de dados regionais com estatísticas espaciais
-
-2. **APIs de Dados para Frontend** ✅ (100% Completo)
-   - [x] API de agregação de dados para visualização (visualization.py)
-   - [x] API de dados geográficos (geographic.py) - estados, municípios, GeoJSON
-   - [x] API de séries temporais para gráficos com suporte a forecast
-   - [x] Export de dados em formatos JSON/CSV otimizados para visualização
-
-**Entregáveis**: 13/17 agentes operacionais, APIs de visualização completas e otimizadas para Next.js frontend ✅
-
-#### ✅ Sprint 9 (Semanas 17-18) - CONCLUÍDA
-**Tema: Agentes Especializados e Integração**
-
-1. **Ativação de Agentes Já Implementados** ✅ (100% Completo)
-   - [x] Dandara (Social Justice) - monitoramento de políticas de inclusão
-   - [x] Machado de Assis (Text Analysis) - análise de documentos governamentais
-   - [x] Ativar Carlos Drummond no __init__.py (já funcional com Maritaca.AI)
-   - [x] Integrar Obaluaiê (Corruption Detector) - já implementado
-
-2. **Último Agente e Integração** ✅ (100% Completo)
-   - [x] Oxóssi (Fraud Hunter) - implementado como o 17º agente (detecção de fraudes avançada)
-   - [x] Integração completa com Nanã (memory system) via AgentMemoryIntegration
-   - [x] Testes de orquestração com todos os 17 agentes
-   - [x] Integração de memória automática no agent_pool
-   - [x] Compartilhamento de conhecimento entre agentes
-
-3. **ML Pipeline** ✅ (100% Completo)
-   - [x] Training pipeline completo com MLflow
-   - [x] Model versioning com registry e promoção
-   - [x] A/B testing framework com Thompson Sampling e análise estatística
-
-**Status Atual**: 
-- ✅ **17/17 agentes implementados e operacionais!**
-- ✅ **Sistema de memória totalmente integrado**
-- ✅ **ML Pipeline completo com versionamento e A/B testing**
-
-**Entregáveis**: Sistema multi-agente completo com memória compartilhada e pipeline ML enterprise-grade ✅
-
-### 🔵 **FASE 4: OTIMIZAÇÃO & ESCALA** (Sprints 10-12)
-*Foco: Performance, Escala e Features Enterprise*
-
-#### Sprint 10 (Semanas 19-20)
-**Tema: Otimização do Portal da Transparência**
-
-1. **Otimização da Integração Existente**
-   - [ ] Cache inteligente avançado para Portal da Transparência
-   - [ ] Processamento em lote de grandes volumes de dados
-   - [ ] Sistema de notificações para mudanças em contratos/licitações
-   - [ ] API de webhooks para integrações externas
-
-2. **Multi-tenancy Básico**
-   - [ ] Isolamento por organização
-   - [ ] Configurações por tenant
-   - [ ] Quotas e limites por organização
-
-**Entregáveis**: Portal da Transparência otimizado com features enterprise
-
-#### Sprint 11 (Semanas 21-22)
-**Tema: Performance & Escala**
-
-1. **Otimizações de Banco de Dados**
-   - [ ] Database read replicas para consultas
-   - [ ] Índices otimizados para queries do Portal
-   - [ ] Particionamento de tabelas grandes
-   - [ ] Vacuum e análise automática
-
-2. **Infraestrutura de Escala**
-   - [ ] Configuração Docker Compose para produção
-   - [ ] Auto-scaling policies para agentes
-   - [ ] Load balancer com health checks
-   - [ ] Monitoramento com Grafana dashboards customizados
-
-**Entregáveis**: Sistema escalável e performático
-
-#### Sprint 12 (Semanas 23-24)
-**Tema: Features Enterprise & Finalização**
-
-1. **Colaboração & Compartilhamento**
-   - [ ] Sistema de compartilhamento de investigações
-   - [ ] Comentários e anotações em análises
-   - [ ] Workspaces por organização/equipe
-   - [ ] Permissões granulares (RBAC)
-
-2. **Documentação & Deploy**
-   - [ ] Documentação completa da API
-   - [ ] Guia de deployment para produção
-   - [ ] Scripts de migração e backup
-   - [ ] Configuração de CI/CD completa
-
-**Entregáveis**: Plataforma production-ready com todas features enterprise
-
-## 📊 Métricas de Sucesso
-
-### Técnicas
-- **Cobertura de Testes**: 45% → 80% ✅
-- **Response Time P95**: <200ms ✅
-- **Cache Hit Rate**: >90% ✅
-- **Uptime**: 99.9%
-- **Agent Response Time**: <2s ✅
-
-### Negócio
-- **Agentes Operacionais**: 8 → 17 ✅
-- **Integração Principal**: Portal da Transparência (otimizada)
-- **Tipos de Export**: 1 → 5 ✅
-- **Vulnerabilidades Críticas**: 5 → 0 ✅
-- **ML Pipeline**: Completo com A/B testing ✅
-
-## 🚧 Riscos & Mitigações
-
-### Alto Risco
-1. **Refatoração dos agentes legados** → Testes extensivos, feature flags
-2. **Migração de autenticação** → Rollback plan, migração gradual
-3. **Performance com 17 agentes** → Agent pooling, cache agressivo
-
-### Médio Risco
-1. **Volume de dados do Portal** → Cache inteligente e processamento em lote
-2. **Compatibilidade mobile** → Progressive enhancement
-3. **Escala horizontal** → Load testing contínuo
-
-## 💰 Estimativa de Recursos
-
-### Time Necessário
-- **2 Desenvolvedores Backend Senior**
-- **1 DevOps/SRE**
-- **1 QA Engineer**
-- **0.5 Product Manager**
-
-### Infraestrutura
-- **Produção**: Kubernetes cluster (3 nodes minimum)
-- **Staging**: Ambiente idêntico à produção
-- **CI/CD**: GitHub Actions + ArgoCD
-- **Monitoramento**: Prometheus + Grafana + ELK
-
-## 📈 Benefícios Esperados
-
-### Curto Prazo (3 meses)
-- Sistema seguro e estável
-- Todos agentes operacionais
-- Performance garantida
-
-### Médio Prazo (6 meses)
-- Plataforma enterprise-ready
-- Portal da Transparência com cache inteligente e otimizações
-- Alta confiabilidade e performance
-
-### Longo Prazo (12 meses)
-- Referência em análise de transparência pública
-- Escalável para grandes volumes de dados
-- Base sólida para expansões futuras
-
-## 🎯 Próximos Passos (Pós Sprint 9)
-
-1. **Sprint 10**: Otimizar integração com Portal da Transparência
-2. **Sprint 11**: Implementar infraestrutura de escala
-3. **Sprint 12**: Adicionar features enterprise e documentação
-4. **Deploy**: Preparar sistema para produção com foco em confiabilidade
-
----
-
-*Este roadmap é um documento vivo e deve ser revisado a cada sprint com base no feedback e aprendizados.*

docs/AGENT_STATUS_2025.md

@@ -1,151 +0,0 @@
-# 🤖 Status dos Agentes - Cidadão.AI Backend
-
-**Última Atualização**: Janeiro 2025  
-**Total de Agentes**: 17  
-**Status**: 8 totalmente funcionais, 9 parcialmente implementados
-
-## 📊 Matriz de Status dos Agentes
-
-| Agente | Arquivo | Status | Capacidades | Observações |
-|--------|---------|--------|-------------|-------------|
-| **Abaporu** | `abaporu.py` | ✅ Completo | Orquestração, Planejamento, Coordenação | Master Agent totalmente operacional |
-| **Zumbi dos Palmares** | `zumbi.py` | ✅ Completo | Detecção de anomalias, FFT, Análise estatística | Investigador principal |
-| **Anita Garibaldi** | `anita.py` | ✅ Completo | Análise de padrões, Tendências, Comportamento | Analista de dados |
-| **Tiradentes** | `tiradentes.py` | ✅ Completo | Geração de relatórios multi-formato | Reporter adaptativo |
-| **Ayrton Senna** | `ayrton_senna.py` | ✅ Completo | Roteamento semântico inteligente | Router de queries |
-| **Nanã** | `nana.py` | ✅ Completo | Memória episódica/semântica/conversacional | Gestão de memória |
-| **Machado de Assis** | `machado.py` | ✅ Completo | Análise textual, NER, Conformidade legal | Processamento de documentos |
-| **Dandara** | `dandara.py` | ✅ Completo | Análise de equidade, Coeficientes sociais | Justiça social |
-| **José Bonifácio** | `bonifacio.py` | ⚠️ Parcial | Framework para avaliação de políticas | Estrutura completa, lógica placeholder |
-| **Carlos Drummond** | `drummond.py` | ⚠️ Parcial | Comunicação multicanal | Estrutura OK, canais não implementados |
-| **Maria Quitéria** | `maria_quiteria.py` | ⚠️ Parcial | Auditoria de segurança | Estrutura básica apenas |
-| **Oscar Niemeyer** | `niemeyer.py` | ⚠️ Parcial | Visualização de dados | Estrutura básica apenas |
-| **Ceuci** | `ceuci.py` | ⚠️ Parcial | ETL e processamento | Estrutura básica apenas |
-| **Obaluaiê** | `obaluaie.py` | ⚠️ Parcial | Monitoramento de saúde | Estrutura básica apenas |
-| **Lampião** | `lampiao.py` | ⚠️ Parcial | Análise regional | Estrutura básica apenas |
-| **Deodoro** | `deodoro.py` | 🏗️ Base | Classes base do sistema | Não é um agente, é infraestrutura |
-| **[Faltando]** | - | ❌ Não existe | - | 1 agente mencionado nos docs não tem arquivo |
-
-## ✅ Agentes Totalmente Funcionais (8)
-
-### 1. **Abaporu (Master Agent)**
-- **Papel**: Orquestrador central
-- **Funcionalidades**:
-  - Planejamento estratégico de investigações
-  - Coordenação multi-agente
-  - Auto-reflexão e melhoria contínua
-  - Síntese de resultados
-
-### 2. **Zumbi dos Palmares (Investigator)**
-- **Papel**: Detective de anomalias
-- **Funcionalidades**:
-  - Detecção estatística (Z-score > 2.5)
-  - Análise espectral (FFT)
-  - Concentração de fornecedores
-  - Detecção de duplicatas
-
-### 3. **Anita Garibaldi (Analyst)**
-- **Papel**: Analista de padrões
-- **Funcionalidades**:
-  - Análise de tendências
-  - Comportamento organizacional
-  - Padrões sazonais
-  - Métricas de eficiência
-
-### 4. **Tiradentes (Reporter)**
-- **Papel**: Gerador de relatórios
-- **Funcionalidades**:
-  - Multi-formato (MD, HTML, PDF, JSON)
-  - Adaptação por audiência
-  - Suporte multilíngue
-  - Priorização de riscos
-
-### 5. **Ayrton Senna (Router)**
-- **Papel**: Roteador semântico
-- **Funcionalidades**:
-  - Roteamento por regras
-  - Similaridade semântica
-  - Detecção de intenção
-  - Estratégias de fallback
-
-### 6. **Nanã (Memory)**
-- **Papel**: Guardião da memória
-- **Funcionalidades**:
-  - Memória episódica
-  - Memória semântica
-  - Memória conversacional
-  - Busca vetorial
-
-### 7. **Machado de Assis (Textual)**
-- **Papel**: Analista textual
-- **Funcionalidades**:
-  - Processamento de documentos
-  - NER (Named Entity Recognition)
-  - Detecção de cláusulas suspeitas
-  - Análise de conformidade
-
-### 8. **Dandara (Social Justice)**
-- **Papel**: Guardiã da equidade
-- **Funcionalidades**:
-  - Coeficiente Gini
-  - Índices de Atkinson, Theil, Palma
-  - Detecção de violações
-  - Análise de inclusão
-
-## ⚠️ Agentes Parcialmente Implementados (7)
-
-### Necessitam Implementação Completa:
-1. **José Bonifácio** - Estrutura pronta, lógica placeholder
-2. **Carlos Drummond** - Design completo, canais não implementados
-3. **Maria Quitéria** - Apenas estrutura básica
-4. **Oscar Niemeyer** - Apenas estrutura básica
-5. **Ceuci** - Apenas estrutura básica
-6. **Obaluaiê** - Apenas estrutura básica
-7. **Lampião** - Apenas estrutura básica
-
-## ❌ Agentes Faltantes (1)
-
-Segundo a documentação original, deveria haver 17 agentes, mas só encontramos 16 arquivos (15 agentes + deodoro.py que é infraestrutura).
-
-## 🎯 Próximos Passos
-
-1. **Prioridade Alta**:
-   - Completar implementação de José Bonifácio (já tem estrutura)
-   - Finalizar Carlos Drummond (implementar canais de comunicação)
-   
-2. **Prioridade Média**:
-   - Implementar Maria Quitéria (segurança é crítica)
-   - Implementar Oscar Niemeyer (visualizações são importantes)
-   
-3. **Prioridade Baixa**:
-   - Completar Ceuci, Obaluaiê e Lampião
-   - Identificar e implementar o 17º agente faltante
-
-## 📈 Métricas de Progresso
-
-- **Agentes Completos**: 8/17 (47%)
-- **Agentes com Estrutura**: 15/17 (88%)
-- **Cobertura de Testes**: ~80% nos agentes implementados
-- **Documentação**: 100% nos agentes completos
-
-## 🔧 Padrão de Implementação
-
-Todos os agentes seguem o mesmo padrão:
-```python
-class NomeAgent(ReflectiveAgent):
-    def __init__(self):
-        super().__init__(
-            agent_id="nome",
-            name="Nome Completo",
-            description="Descrição",
-            capabilities=[...]
-        )
-    
-    async def process(self, message: AgentMessage) -> AgentResponse:
-        # Lógica principal do agente
-        pass
-```
-
----
-
-**Nota**: Este documento reflete o estado REAL do código, não as aspirações da documentação original.

restart.txt

@@ -1 +0,0 @@
-Force rebuild: 2025-09-20 13:30:00 - Fix MasterAgent import

test_coverage_analysis.md

@@ -1,144 +0,0 @@
-# Test Coverage Analysis - Cidadão.AI Backend
-
-## Executive Summary
-
-The project has significant gaps in test coverage, particularly in critical areas that represent high risk to system reliability. Current test coverage appears to be below the stated 80% target, with many core components completely missing tests.
-
-## 1. Agent System Coverage
-
-### Current State
-- **19 agent implementations** found
-- **21 agent test files** exist (some agents have multiple test versions)
-- **3 agents completely missing tests:**
-  - `agent_pool` - Critical for agent lifecycle management
-  - `drummond_simple` - Communication agent variant
-  - `parallel_processor` - Critical for performance
-
-### Agent Coverage Details
-According to documentation, there should be 17 agents total:
-- **8 fully operational agents** (mostly have tests)
-- **9 agents in development** (test coverage varies)
-
-**High Risk:** The agent pool and parallel processor are critical infrastructure components without tests.
-
-## 2. API Route Coverage
-
-### Routes WITHOUT Test Coverage (13/24 routes - 54% uncovered):
-- ❌ `chaos` - Chaos engineering endpoint
-- ❌ `chat_debug` - Debug chat endpoint
-- ❌ `chat_drummond_factory` - Communication agent factory
-- ❌ `chat_emergency` - Emergency fallback endpoint
-- ❌ `chat_optimized` - Performance-optimized chat
-- ❌ `chat_stable` - Stable chat endpoint
-- ❌ `cqrs` - Command Query Responsibility Segregation
-- ❌ `graphql` - GraphQL API endpoint
-- ❌ `oauth` - OAuth authentication
-- ❌ `observability` - Monitoring/observability endpoints
-- ❌ `resilience` - Resilience patterns endpoint
-- ❌ `websocket_chat` - WebSocket chat endpoint
-
-### Routes WITH Test Coverage (11/24 routes - 46% covered):
-- ✅ analysis, audit, auth, batch, chat, chat_simple, debug, health, investigations, monitoring, reports, websocket
-
-**High Risk:** Critical endpoints like emergency fallback, OAuth, and resilience patterns lack tests.
-
-## 3. Service Layer Coverage
-
-### Services WITHOUT Tests (2/8 services):
-- ❌ `cache_service` - Critical for performance
-- ❌ `chat_service_with_cache` - Main chat service with caching
-
-**High Risk:** The caching layer is critical for meeting performance SLAs but lacks tests.
-
-## 4. Infrastructure Coverage
-
-### Components WITHOUT Tests:
-- ❌ `monitoring_service` - Observability infrastructure
-- ❌ `query_analyzer` - Query optimization
-- ❌ `query_cache` - Query result caching
-- ❌ **APM components** (2 files) - Application Performance Monitoring
-- ❌ **CQRS components** (2 files) - Command/Query segregation
-- ❌ **Event bus** (1 file) - Event-driven architecture
-- ❌ **Resilience patterns** (2 files) - Circuit breakers, bulkheads
-
-**High Risk:** Infrastructure components are foundational but largely untested.
-
-## 5. ML/AI Components Coverage
-
-### ML Components WITHOUT Tests (7/12 components - 58% uncovered):
-- ❌ `advanced_pipeline` - Advanced ML pipeline
-- ❌ `cidadao_model` - Core AI model
-- ❌ `hf_cidadao_model` - HuggingFace model variant
-- ❌ `hf_integration` - HuggingFace integration
-- ❌ `model_api` - ML model API
-- ❌ `training_pipeline` - Model training
-- ❌ `transparency_benchmark` - Performance benchmarks
-
-**High Risk:** Core ML components including the main Cidadão AI model lack tests.
-
-## 6. Critical Workflows Without Integration Tests
-
-Based on the documentation, these critical workflows appear to lack comprehensive integration tests:
-
-1. **Multi-Agent Coordination** - Only one test file found
-2. **Real-time Features** - SSE streaming, WebSocket batching
-3. **Cache Layer Integration** - L1→L2→L3 cache strategy
-4. **Circuit Breaker Patterns** - Fault tolerance
-5. **CQRS Event Flow** - Command/query separation
-6. **Performance Optimization** - Agent pooling, parallel processing
-7. **Security Flows** - OAuth2, JWT refresh
-8. **Observability Pipeline** - Metrics, tracing, logging
-
-## Risk Assessment
-
-### 🔴 CRITICAL RISKS (Immediate attention needed):
-1. **Emergency/Fallback Systems** - No tests for emergency chat endpoint
-2. **Performance Infrastructure** - Cache service, agent pool, parallel processor untested
-3. **Security Components** - OAuth endpoint lacks tests
-4. **Core AI Model** - Main Cidadão model without tests
-
-### 🟠 HIGH RISKS:
-1. **Resilience Patterns** - Circuit breakers, bulkheads untested
-2. **Real-time Features** - WebSocket chat, SSE streaming
-3. **Observability** - Monitoring service, APM components
-4. **CQRS Architecture** - Event-driven components
-
-### 🟡 MEDIUM RISKS:
-1. **ML Pipeline Components** - Training, benchmarking
-2. **Query Optimization** - Query analyzer, query cache
-3. **Agent Variants** - Some agents have incomplete test coverage
-
-## Recommendations
-
-### Immediate Actions (Week 1):
-1. **Test Emergency Systems** - Add tests for chat_emergency endpoint
-2. **Test Cache Layer** - Critical for performance SLAs
-3. **Test Security** - OAuth and authentication flows
-4. **Test Agent Pool** - Core infrastructure component
-
-### Short Term (Month 1):
-1. **Integration Test Suite** - Cover multi-agent workflows
-2. **Performance Tests** - Validate <2s response times
-3. **Resilience Tests** - Circuit breakers, fallbacks
-4. **ML Component Tests** - Core AI model validation
-
-### Medium Term (Month 2-3):
-1. **End-to-End Tests** - Full user workflows
-2. **Load Testing** - Validate 10k req/s throughput
-3. **Chaos Engineering** - Test failure scenarios
-4. **Security Testing** - Penetration testing
-
-## Test Coverage Metrics
-
-Based on file analysis:
-- **Agents**: ~84% coverage (16/19 agents)
-- **API Routes**: ~46% coverage (11/24 routes)
-- **Services**: ~75% coverage (6/8 services)
-- **Infrastructure**: ~40% coverage (rough estimate)
-- **ML Components**: ~42% coverage (5/12 components)
-
-**Overall Estimate**: ~45-50% test coverage (well below 80% target)
-
-## Conclusion
-
-The system has significant test coverage gaps that represent material risks to production reliability. Priority should be given to testing emergency systems, performance-critical components, and security infrastructure before expanding features or moving to production scale.