Skip to content

ARQUITETURA.md

Latest commit

 

History

History
270 lines (204 loc) · 5.81 KB

ARQUITETURA.md

File metadata and controls

270 lines (204 loc) · 5.81 KB

Arquitetura do DiaryMCP v2

Sistema federado de diary de desenvolvimento com análise LLM e busca semântica.

🎯 Visão Geral

DiaryMCP captura automaticamente o contexto de desenvolvimento, analisa com LLMs e permite busca semântica local.

Filosofia: "Install and forget" - zero manutenção após instalação.

📐 Componentes Principais

1. Agente Local (local/)

Roda no projeto do desenvolvedor. Responsável por captura e indexação.

local/
├── agent/          # Coleta, anonimização, upload
├── daemon/         # Monitoramento de arquivos
├── search/         # Busca semântica local
├── hooks/          # Git hooks automáticos
└── scripts/        # CLI (capture, search, daemon)

Fluxo de Captura:

Git Event/File Change
  ↓
Hook/Daemon Trigger
  ↓
ContextCollector: Coleta git, arquivos, TODOs, processos
  ↓
DataAnonymizer: Remove dados sensíveis
  ↓
LocalStorage: Salva em .diary/data/entries/
  ↓
AutoIndexer: Indexa para busca (FAISS + SQLite)
  ↓
CloudUploader: Envia ao orquestrador (opcional)

2. Orquestrador Cloud (cloud/)

Servidor FastAPI que processa capturas com múltiplos agentes LLM.

cloud/
├── orchestrator/   # API, queue, dispatcher, consensus
├── agents/         # Agentes especializados com LLM
├── storage/        # Repositório e vector store
├── telegram/       # Bot (opcional)
└── llm/            # Cliente LLM (OpenAI/OpenRouter)

Fluxo de Processamento:

POST /api/v1/capture
  ↓
QueueManager: Enfileira job
  ↓
AgentDispatcher: Distribui para agentes
  ↓
Agentes Paralelos:
  - CodeReviewerAgent: Code smells, bugs
  - StorytellerAgent: Narrativas
  - ArchitectAgent: Decisões arquiteturais
  - ConnectorAgent: Conexões com histórico
  ↓
ByzantineConsensus: Agrega resultados
  ↓
Repository: Armazena + indexa em Pinecone
  ↓
TelegramBot: Notifica (opcional)

3. Busca Semântica Local

Embeddings locais com sentence-transformers, sem API calls.

Capture → EntryIndexer
            ↓
         FAISS Index (vetores)
         SQLite DB (metadados)
            ↓
Query → EntrySearcher
            ↓
         Top-K Results

Modelo: all-MiniLM-L6-v2 (80MB, multilíngue, rápido)

🔄 Modos de Operação

Modo 1: 100% Local (Sem Cloud)

  • ✅ Auto-capture via git hooks
  • ✅ Busca semântica local
  • ✅ Armazenamento local
  • ❌ Sem análise LLM
  • ❌ Sem Telegram

Uso: Desenvolvedor individual, offline-first

Modo 2: Híbrido (Local + Cloud)

  • ✅ Auto-capture via git hooks
  • ✅ Busca semântica local
  • ✅ Análise LLM no cloud
  • ✅ Telegram opcional

Uso: Desenvolvedor com LLM API

Modo 3: Federado Completo (Time)

  • ✅ Múltiplos desenvolvedores
  • ✅ Orquestrador centralizado
  • ✅ Consenso entre agentes
  • ✅ Busca federada (Pinecone)
  • ✅ Telegram como hub

Uso: Times com servidor compartilhado

🧩 Tecnologias

Local

  • Python 3.11+: Core
  • GitPython: Integração Git
  • psutil: Monitoramento processos
  • watchdog: File system events
  • sentence-transformers: Embeddings locais
  • FAISS: Busca vetorial
  • SQLite: Metadados

Cloud

  • FastAPI: API REST
  • Uvicorn: ASGI server
  • OpenAI SDK: LLM client
  • Pinecone: Vector store (opcional)
  • python-telegram-bot: Bot (opcional)
  • Tenacity: Retry logic

📊 Dados e Privacidade

O que é Capturado

Git:

  • Branch, commit hash, mensagem
  • Diff recente (anonimizado)
  • Arquivos modificados

Código:

  • TODOs/FIXMEs
  • Imports modificados
  • Estrutura (não conteúdo completo)

Sistema:

  • Processos relevantes (python, node, docker)
  • Timestamp

NÃO Capturado:

  • Conteúdo completo de arquivos
  • Credenciais (via .diaryprivate)
  • Arquivos hidden (por padrão)

Anonimização

Aplicada automaticamente em DataAnonymizer:

  • Remove emails, IPs, paths absolutos
  • Redação de secrets (.env, .pem)
  • Respeita .diaryprivate
  • Configurable via manifest.yaml

Onde os Dados Ficam

Local:

  • .diary/data/entries/ - Capturas JSON
  • .diary/search/ - Índice FAISS + SQLite
  • .diary/cache/ - Cache temporário

Cloud (se configurado):

  • Orquestrador: SQLite ou PostgreSQL
  • Vector store: Pinecone (opcional)

🔐 Segurança

  • API keys em credentials.yaml (gitignored)
  • Signing keys para criptografia
  • API authentication com X-API-Key header
  • Dados anonimizados antes de upload
  • HTTPS recomendado para orquestrador

🚀 Deploy

Local (Dev Machine)

./local/install.sh  # Uma vez por projeto

Cloud (Servidor)

Docker Compose:

cd cloud
docker-compose up -d

Manual:

cd cloud
uvicorn orchestrator.api:app --host 0.0.0.0 --port 8000

🔧 Extensibilidade

Criar Novo Agente

from cloud.agents.base_agent import BaseAgent

class MyAgent(BaseAgent):
    name = "my_agent"

    def _heuristic_analyze(self, context):
        # Análise sem LLM
        return {"analysis": {...}, "confidence": 0.7}

    def _prepare_context_for_llm(self, context):
        # Preparar para LLM
        return f"Analyze: {context}"

    def _calculate_llm_confidence(self, response):
        # Calcular confiança
        return 0.9

Adicionar Modelo de Busca

from local.search.indexer import EntryIndexer

indexer = EntryIndexer(
    diary_dir=".diary",
    model_name="custom-model-name"  # Hugging Face
)

📈 Performance

Auto-Capture

  • Git hooks: ~0-2s (background)
  • Daemon: ~50MB RAM, <1% CPU

Busca Semântica

  • Indexação: ~100ms/entry
  • Busca: ~100-200ms/query
  • Armazenamento: ~2KB/entry

LLM (Cloud)

  • Latência: ~1-3s/captura
  • Custo: ~$0.18/mês (gpt-4o-mini, 10 capturas/dia)

📚 Referências

  • Código: /root/DiaryMCP/
  • Guias: docs/AUTO_CAPTURE.md, docs/BUSCA_SEMANTICA.md
  • Config: docs/CONFIGURACAO.md