ForgeLM/tauri-app/docs/MULTI_AGENT_ARCHITECTURE.md

# Arquitetura: Multi-Agentes Especialistas para ForgeLM

## Visão Geral

Sistema de especialistas que analisam e refinam iterativamente as respostas do assistente, utilizando a infraestrutura ForgeAgent existente.

## 1. Fluxo Conceitual

```
Usuário → ChatView → API Local → Resposta Inicial
                                    ↓
                    ┌───────────────┼───────────────┐
                    ↓               ↓               ↓
            [Especialista 1] [Especialista 2] [Especialista 3]
            CodeReviewer      StyleEditor      FactChecker
                    ↓               ↓               ↓
                    └───────────────┴───────────────┘
                                    ↓
                          Resposta Refinada
                                    ↓
                              ChatView UI
```

## 2. Estrutura de Dados

### SpecialistDefinition (Configuração)
```typescript
interface SpecialistDefinition {
  id: string;                    // "code-reviewer", "style-editor"
  name: string;                  // "Code Reviewer"
  title: string;                 // "Revisor de Código"
  systemPrompt: string;          // Prompt específico do especialista
  activationRules: ActivationRule[];  // Quando ativar
  modelTier: "fast" | "quality"; // Qual modelo usar
  maxTokens: number;
  temperature: number;
}

type ActivationRule = 
  | { type: "always" }
  | { type: "contains-code"; languages?: string[] }
  | { type: "length-threshold"; minChars: number }
  | { type: "content-pattern"; regex: string }
  | { type: "manual-toggle"; toggleId: string };
```

### ReviewCycle (Execução)
```typescript
interface ReviewCycle {
  id: string;                    // UUID da revisão
  originalMessageId: number;     // ID da mensagem original
  originalContent: string;       // Resposta inicial do assistente
  specialists: SpecialistReview[];
  finalContent: string;          // Resposta após todas as revisões
  status: "running" | "completed" | "error";
  startedAt: number;
  completedAt?: number;
}

interface SpecialistReview {
  specialistId: string;
  status: "pending" | "thinking" | "completed" | "error";
  thinking?: string;             // Chain of thought
  suggestions: Suggestion[];
  applied: boolean;              // Se as sugestões foram aplicadas
}

interface Suggestion {
  type: "improvement" | "correction" | "addition" | "deletion";
  original?: string;             // Texto original
  replacement?: string;          // Texto sugerido
  explanation: string;           // Por que mudar
  confidence: number;            // 0.0 - 1.0
}
```

## 3. Componentes Principais

### A. SpecialistRegistry (src/lib/specialist-registry.ts)
Registro central de especialistas disponíveis.

```typescript
class SpecialistRegistry {
  private specialists: Map<string, SpecialistDefinition> = new Map();
  
  register(def: SpecialistDefinition): void;
  unregister(id: string): void;
  getActiveForContent(content: string, context: Context): SpecialistDefinition[];
  getAll(): SpecialistDefinition[];
}
```

### B. ReviewOrchestrator (src/lib/review-orchestrator.ts)
Orquestra o ciclo de revisão.

```typescript
class ReviewOrchestrator {
  async startReview(
    messageId: number,
    content: string,
    context: MessageContext
  ): Promise<ReviewCycle>;
  
  private async runSpecialist(
    cycle: ReviewCycle,
    specialist: SpecialistDefinition,
    currentContent: string
  ): Promise<SpecialistReview>;
  
  private applySuggestions(content: string, review: SpecialistReview): string;
  
  onProgress(callback: (cycle: ReviewCycle) => void): void;
  onComplete(callback: (cycle: ReviewCycle) => void): void;
}
```

### C. SpecialistService (Backend/Tauri)
Comandos Rust para executar revisões sem bloquear a UI.

```rust
#[tauri::command]
async fn run_specialist_review(
    specialist_id: String,
    content: String,
    context: MessageContext,
    server: String,
    model: String,
) -> Result<SpecialistReview, String>;
```

## 4. Integração ao ChatView

### Modo Síncrono vs Assíncrono

**Opção A: Assíncrono (Recomendado)**
- Resposta inicial aparece imediatamente
- Especialistas processam em background
- Badge/indicator mostra "Melhorando..."
- Quando completo, mensagem é atualizada com versão refinada
- Toggle "Agentic" controla se ativa especialistas

**Opção B: Síncrono**
- Aguarda todos os especialistas antes de mostrar
- Mais lento mas garante qualidade máxima
- Mostra progresso em tempo real (SpecialistCards)

### Proposta: Híbrido com Streaming

```typescript
// No ChatView
const [reviewCycle, setReviewCycle] = useState<ReviewCycle | null>(null);

// Após receber resposta completa
if (agenticMode) {
  const cycle = await reviewOrchestrator.startReview(
    messageId, 
    responseContent,
    { chatId, previousMessages }
  );
  setReviewCycle(cycle);
  
  // Mostra mensagem inicial imediatamente
  // Atualiza quando especialistas completam
  cycle.onProgress((updated) => {
    setReviewCycle({ ...updated });
  });
}
```

### UI Components

1. **ReviewProgressIndicator** - Badge mostrando "3/5 especialistas completos"
2. **ReviewDiffViewer** - Mostra diff entre original e refinado
3. **SpecialistSidebar** - Panel mostrando thinking de cada especialista
4. **SuggestionAcceptReject** - Controles para aceitar/rejeitar sugestões

## 5. Especialistas Padrão

### 1. CodeReviewer
```typescript
{
  id: "code-reviewer",
  name: "Code Reviewer",
  title: "Revisor de Código",
  activationRules: [{ type: "contains-code" }],
  systemPrompt: `Você é um revisor de código sênior. Analise o código fornecido e sugira melhorias em:
- Eficiência e performance
- Legibilidade e clareza
- Boas práticas e padrões
- Possíveis bugs ou edge cases

Formato de resposta (JSON):
{
  "thinking": "sua análise passo a passo",
  "suggestions": [
    {
      "type": "improvement",
      "original": "código original",
      "replacement": "código melhorado",
      "explanation": "por que melhorar",
      "confidence": 0.95
    }
  ]
}`
}
```

### 2. StyleEditor
```typescript
{
  id: "style-editor",
  name: "Style Editor", 
  title: "Editor de Estilo",
  activationRules: [{ type: "length-threshold", minChars: 200 }],
  systemPrompt: `Você é um editor de texto profissional. Melhore a clareza e fluidez do texto mantendo o significado original.

Foque em:
- Clareza e concisão
- Fluxo e coesão entre frases
- Tom apropriado ao contexto
- Eliminação de redundâncias

Formato de resposta (JSON):
{
  "thinking": "análise do estilo",
  "suggestions": [...]
}`
}
```

### 3. FactChecker
```typescript
{
  id: "fact-checker",
  name: "Fact Checker",
  title: "Verificador de Fatos",
  activationRules: [{ type: "content-pattern", regex: "\b(sabe|sabia|fato|verdade|estudo|pesquisa|dado|estatística)\b" }],
  systemPrompt: `Você é um verificador de fatos. Identifique afirmações factuais no texto e avalie:
- Se são factualmente corretas (conhecimento até 2024)
- Se precisam de citação ou fonte
- Se há nuances ou contexto faltante

NÃO invente informações. Marque como "não verificável" se incerto.

Formato de resposta (JSON):
{
  "thinking": "análise factual",
  "suggestions": [
    {
      "type": "correction",
      "original": "afirmação incorreta",
      "replacement": "versão corrigida ou com ressalvas",
      "explanation": "por que precisa correção",
      "confidence": 0.85
    }
  ]
}`
}
```

### 4. ToneAdapter
```typescript
{
  id: "tone-adapter",
  name: "Tone Adapter",
  title: "Adaptador de Tom",
  activationRules: [{ type: "always" }],
  systemPrompt: `Você adapta o tom da resposta ao contexto da conversa.

Analise o histórico recente e ajuste:
- Formalidade (técnico vs casual)
- Entusiasmo (neutro vs animado)
- Detalhamento (resumo vs aprofundado)
- Personalização (menção a fatos do usuário)

Formato de resposta (JSON):
{
  "thinking": "análise do contexto e tom adequado",
  "suggestions": [...]
}`
}
```

## 6. Fluxo de Execução

```typescript
// 1. Usuário envia mensagem
// 2. Recebe resposta do assistente
// 3. Se agenticMode ativo:

async function processWithSpecialists(messageId: number, content: string) {
  // Determina quais especialistas ativar
  const activeSpecialists = specialistRegistry.getActiveForContent(content, context);
  
  // Cria ciclo de revisão
  const cycle: ReviewCycle = {
    id: generateUUID(),
    originalMessageId: messageId,
    originalContent: content,
    specialists: activeSpecialists.map(s => ({
      specialistId: s.id,
      status: "pending",
      suggestions: [],
      applied: false
    })),
    finalContent: content, // Começa com original
    status: "running",
    startedAt: Date.now()
  };
  
  // Executa sequencialmente (para builds contextuais)
  let currentContent = content;
  for (const specialist of activeSpecialists) {
    updateSpecialistStatus(cycle, specialist.id, "thinking");
    
    const review = await runSpecialist(specialist, currentContent, context);
    
    updateSpecialistStatus(cycle, specialist.id, "completed", review);
    
    // Aplica sugestões automaticamente (pode ser manual no futuro)
    currentContent = applySuggestions(currentContent, review);
    cycle.finalContent = currentContent;
    
    notifyProgress(cycle);
  }
  
  cycle.status = "completed";
  cycle.completedAt = Date.now();
  
  // Atualiza mensagem no DB com versão refinada
  await updateMessage(messageId, cycle.finalContent, cycle);
  
  return cycle;
}
```

## 7. Persistência

### Tabela: specialist_reviews
```sql
CREATE TABLE specialist_reviews (
  id TEXT PRIMARY KEY,
  message_id INTEGER NOT NULL,
  original_content TEXT NOT NULL,
  final_content TEXT NOT NULL,
  specialists_json TEXT NOT NULL,  -- SpecialistReview[]
  status TEXT NOT NULL,
  created_at INTEGER NOT NULL,
  completed_at INTEGER
);
```

### Tabela: specialist_definitions (configuração do usuário)
```sql
CREATE TABLE specialist_definitions (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  title TEXT NOT NULL,
  system_prompt TEXT NOT NULL,
  activation_rules_json TEXT NOT NULL,
  is_enabled BOOLEAN DEFAULT 1,
  sort_order INTEGER DEFAULT 0
);
```

## 8. Configuração do Usuário

### Settings UI
- Lista de especialistas (drag-drop para reordenar)
- Toggle individual para cada especialista
- Editor de system prompts customizados
- Regras de ativação configuráveis

### Padrões do Sistema
```typescript
const DEFAULT_SPECIALISTS: SpecialistDefinition[] = [
  toneAdapter,      // Sempre ativo
  codeReviewer,     // Só com código
  styleEditor,      // Textos longos
  factChecker,      // Quando detecta factualidade
];
```

## 9. Otimizações de Performance

1. **Caching**: Especialistas memorizam contexto entre mensagens
2. **Lazy Loading**: Só carrega especialistas quando necessário
3. **Parallel where safe**: Especialistas independentes rodam em paralelo
4. **Early Exit**: Se confiança < threshold, pula para o próximo
5. **Model Tier**: Especialistas usam modelos menores/fasters quando possível

## 10. Considerações de UX

### Quando Mostrar
- ✅ Sempre mostrar resultado original primeiro
- ✅ Mostrar progresso discreto (badge, não modal)
- ✅ Permitir ver thinking de cada especialista (expansível)
- ✅ Permitir toggle on/off global (já existe AgenticToggle)
- ✅ Permitir ver diff original vs refinado

### Quando NÃO Usar
- ❌ Não bloquear a UI esperando especialistas
- ❌ Não mostrar erros de especialista ao usuário (fail silently)
- ❌ Não processar mensagens muito curtas (< 50 chars)
- ❌ Não processar se modelo indisponível

## 11. MVP - Fase 1

Implementação mínima viável:

1. **2 especialistas hardcoded**: ToneAdapter (sempre) + CodeReviewer (se código)
2. **Execução sequencial síncrona** (simplifica UI)
3. **Aplicação automática** de sugestões
4. **UI mínima**: Badge "Melhorando..." → "Melhorado ✓" + SpecialistCard expansível
5. **Sem persistência** de review cycles (só resultado final)

### Arquivos a Criar (Fase 1)
```
src/
  lib/
    specialist-definitions.ts       # Especialistas padrão
    review-orchestrator.ts          # Lógica de orquestração
  components/
    forgeagent/
      ReviewProgress.tsx            # Badge de progresso
      ReviewDiffViewer.tsx          # Diff original vs refinado
  hooks/
    useSpecialistReview.ts          # Hook para gerenciar ciclo
```

### Arquivos a Modificar
```
src/components/ChatView.tsx       # Integrar ao fluxo de resposta
src/components/MessageBubble.tsx  # Mostrar badge de revisão
src/prompts/specialists/          # Prompts de cada especialista
```

## 12. Próximos Passos

1. ✅ Validar arquitetura com o usuário
2. Implementar Fase 1 (MVP)
3. Testar com diferentes modelos (Qwen3 0.8B, 2B, 4B)
4. Ajustar prompts baseado em resultados
5. Adicionar especialistas adicionais
6. Implementar modo paralelo assíncrono
7. Adicionar configuração via UI Settings