# System Design Document (SDD)
## ForgeAgent - Modo Agentic para ForgeLM

**Versão:** 1.0  
**Data:** 2025-04-02  
**Status:** Draft  

---

## 1. Visão Geral

### 1.1 Objetivo
Transformar respostas do modelo LLM de simples "bolhas de texto" em uma **experiência agentic visível**, onde o usuário acompanha em tempo real:
- O plano estruturado de execução
- Progresso passo a passo com checkmarks
- Sub-tarefas detalhadas
- Artefatos gerados (arquivos Markdown)

### 1.2 Motivação
Modelos pequenos (0.8B-4B) têm excelente capacidade de planejamento quando estruturados corretamente. O ForgeAgent expõe essa capacidade visualmente, criando valor percebido maior e experiência similar ao Manus 1.6 Lite.

### 1.3 Escopo
- **Incluído:** Frontend React/Tauri, backend Rust (structured output), prompts para modelo
- **Excluído (futuro):** Suporte a ZIP, visão/áudio, execução real de código

---

## 2. Arquitetura

### 2.1 High-Level Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Frontend (React/Tauri)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │ ChatView     │  │ ForgeAgent   │  │ Artifact     │        │
│  │              │  │ Plan Card    │  │ Viewer       │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
└────────────────────┬────────────────────────────────────────┘
                     │ Tauri Events
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                    Backend (Rust/Tauri)                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │ Trigger      │  │ Plan         │  │ Streaming    │        │
│  │ Detector     │  │ Generator    │  │ Emitter      │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                       LLM (llama.cpp)                        │
│              ForgeSteel 4B / ForgeIron 2B                    │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 Fluxo de Dados

```
1. Usuário envia mensagem
   ↓
2. Trigger Detector analisa: modo agentic necessário?
   ↓ Sim
3. Plan Generator envia prompt estruturado ao LLM
   ↓
4. LLM retorna JSON (AgentPlan)
   ↓
5. Streaming Emitter envia eventos Tauri progressivamente
   ↓
6. Frontend renderiza: Plano → Execução → Artefatos
```

---

## 3. Componentes

### 3.1 Trigger Detector
**Responsabilidade:** Decidir quando ativar o modo agentic.

**Critérios Automáticos:**
- Palavras-chave: "como fazer", "guia", "passo a passo", "tutorial", "exemplo completo", "projeto"
- Padrões regex: `/\b(como|guia|tutorial|passo a passo|exemplo completo|projeto)\b/i`

**Critérios Manuais:**
- Toggle "🛠️ Modo Agentic" ao lado do input de chat

**Saída:** Boolean (`shouldUseAgentic`)

### 3.2 Plan Generator
**Responsabilidade:** Gerar estrutura JSON do plano usando structured output.

**Schema (Rust):**
```rust
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct AgentPlan {
    pub title: String,
    pub overview: String,
    pub steps: Vec<Step>,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct Step {
    pub id: u32,
    pub title: String,
    pub description: String,
    pub status: StepStatus,
    pub sub_steps: Vec<SubStep>,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct SubStep {
    pub id: String,  // formato: "{step_id}.{sub_id}"
    pub description: String,
    pub status: StepStatus,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum StepStatus {
    Pending,
    Running,
    Completed,
    Error,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct Artifact {
    pub filename: String,
    pub content: String,
    pub language: Option<String>,  // "markdown", "javascript", etc.
}
```

### 3.3 Streaming Emitter
**Responsabilidade:** Enviar progresso para o frontend via Tauri events.

**Eventos:**
- `forgeagent:plan-started` - Início do plano
- `forgeagent:step-started` - Step N iniciado
- `forgeagent:step-completed` - Step N completado
- `forgeagent:step-error` - Step N falhou
- `forgeagent:artifact-ready` - Artefato disponível
- `forgeagent:plan-completed` - Plano finalizado

### 3.4 Frontend Components

#### 3.4.1 ForgeAgentBubble
Container especial para mensagens agentic. Diferente da bolha normal por:
- Avatar distinto (badge "ForgeAgent")
- Background sutilmente diferente
- Badge "Modo Agentic"

#### 3.4.2 PlanCard
Card expansível mostrando o plano completo:
- Header: Título + progresso (X de Y passos)
- Body: Lista de steps com checkmarks
- Accordion: Steps podem expandir para mostrar sub-steps
- Progress bar: Visualização linear do progresso

#### 3.4.3 StepItem
Item individual de uma tarefa:
- Ícone de status (⏳ pending, ⏯️ running, ✅ completed, ❌ error)
- Título da tarefa
- Descrição curta
- Sub-steps (se houver)

#### 3.4.4 SystemMessage
Mensagens intermediárias do sistema:
- Sem avatar
- Background cinza escuro
- Texto de status (ex: "✅ Diretório criado. Próximo passo...")

#### 3.4.5 ArtifactViewer
Visualizador de artefatos Markdown:
- Preview do conteúdo
- Botão "Download"
- Syntax highlight para blocos de código

---

## 4. Interface do Usuário

### 4.1 Layout da Tela de Chat

```
┌────────────────────────────────────────────────────────────┐
│  💬 Chat                                                  │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  ┌────────────────────────────────────────────────────┐   │
│  │ 👤 Usuário: como criar uma api em nodejs?          │   │
│  └────────────────────────────────────────────────────┘   │
│                                                            │
│  ┌────────────────────────────────────────────────────┐   │
│  │ 🤖 ForgeAgent [Modo Agentic]                       │   │
│  │                                                    │   │
│  │ Vou criar um guia completo para você!            │   │
│  │                                                    │   │
│  │ ┌──────────────────────────────────────────────┐  │   │
│  │ │ 📋 Plano de Execução (4 passos)     [░░░░]   │  │   │
│  │ │                                              │  │   │
│  │ │ ✅ 1. Configurar ambiente                     │  │   │
│  │ │    ├── Instalar Node.js                      │  │   │
│  │ │    └── Verificar versão                      │  │   │
│  │ │                                                │  │   │
│  │ │ ⏯️ 2. Inicializar projeto (executando...)     │  │   │
│  │ │                                                │  │   │
│  │ │ ⏳ 3. Instalar dependências                   │  │   │
│  │ │                                                │  │   │
│  │ │ ⏳ 4. Criar endpoints                         │  │   │
│  │ └──────────────────────────────────────────────┘  │   │
│  │                                                    │   │
│  │ ✅ Projeto inicializado com sucesso!             │   │
│  │                                                    │   │
│  │ 📄 api-nodejs-guide.md                    [⬇️]   │   │
│  └────────────────────────────────────────────────────┘   │
│                                                            │
│  ┌────────────────────────────────────────────────────┐   │
│  │ [🛠️ Modo Agentic] [                    ] [➤]     │   │
│  └────────────────────────────────────────────────────┘   │
│                                                            │
└────────────────────────────────────────────────────────────┘
```

### 4.2 Estados Visuais

#### Step - Pending
```
⏳ Título da tarefa
   Descrição curta
```

#### Step - Running
```
⏯️ Título da tarefa
   [==========>    ] 60%
   Descrição curta
```

#### Step - Completed
```
✅ Título da tarefa
   Descrição curta
   └── Sub-step 1
   └── Sub-step 2
```

#### Step - Error
```
❌ Título da tarefa
   ⚠️ Erro: mensagem de erro
```

---

## 5. Prompt Engineering

### 5.1 System Prompt

```markdown
Você é o ForgeAgent, um assistente especializado em criar planos estruturados e executáveis.

SUA TAREFA:
1. Analisar a solicitação do usuário
2. Criar um plano passo a passo detalhado
3. Retornar APENAS um objeto JSON válido no formato especificado

REGRAS:
- NUNCA adicione texto fora do JSON
- Sempre divida tarefas complexas em passos claros
- Cada passo deve ter 2-5 sub-passos quando aplicável
- Use linguagem clara e direta
- O overview deve ter no máximo 2 frases

FORMATO JSON OBRIGATÓRIO:
{
  "title": "Título do plano (máx 50 caracteres)",
  "overview": "Breve descrição do que será feito",
  "steps": [
    {
      "id": 1,
      "title": "Título do passo",
      "description": "Descrição detalhada",
      "status": "pending",
      "sub_steps": [
        {
          "id": "1.1",
          "description": "Sub-tarefa específica",
          "status": "pending"
        }
      ]
    }
  ]
}
```

### 5.2 Few-Shot Example

**Input:** "como fazer uma api em nodejs"

**Output:**
```json
{
  "title": "Criar API Node.js",
  "overview": "Vamos criar uma API REST completa usando Express.js com estrutura profissional.",
  "steps": [
    {
      "id": 1,
      "title": "Configurar ambiente",
      "description": "Preparar o ambiente de desenvolvimento",
      "status": "pending",
      "sub_steps": [
        {"id": "1.1", "description": "Verificar instalação do Node.js", "status": "pending"},
        {"id": "1.2", "description": "Instalar npm/yarn", "status": "pending"}
      ]
    },
    {
      "id": 2,
      "title": "Inicializar projeto",
      "description": "Criar estrutura base do projeto",
      "status": "pending",
      "sub_steps": [
        {"id": "2.1", "description": "Criar diretório do projeto", "status": "pending"},
        {"id": "2.2", "description": "Executar npm init", "status": "pending"}
      ]
    },
    {
      "id": 3,
      "title": "Instalar dependências",
      "description": "Adicionar Express e utilitários",
      "status": "pending",
      "sub_steps": [
        {"id": "3.1", "description": "Instalar express", "status": "pending"},
        {"id": "3.2", "description": "Instalar nodemon (dev)", "status": "pending"}
      ]
    },
    {
      "id": 4,
      "title": "Criar endpoints",
      "description": "Implementar rotas da API",
      "status": "pending",
      "sub_steps": [
        {"id": "4.1", "description": "Criar servidor Express", "status": "pending"},
        {"id": "4.2", "description": "Adicionar rota GET /", "status": "pending"},
        {"id": "4.3", "description": "Adicionar rota POST /api/data", "status": "pending"}
      ]
    }
  ]
}
```

---

## 6. API & Eventos

### 6.1 Commands (Tauri)

```rust
#[tauri::command]
async fn generate_agent_plan(
    request: AgentPlanRequest,
) -> Result<AgentPlan, String> {
    // Implementation
}

#[tauri::command]
async fn execute_plan_step(
    plan_id: String,
    step_id: u32,
) -> Result<StepResult, String> {
    // Implementation
}
```

### 6.2 Events (Tauri)

```typescript
// Frontend listening
listen('forgeagent:plan-started', (event) => {
  const { plan_id, title, total_steps } = event.payload;
  // Update UI
});

listen('forgeagent:step-started', (event) => {
  const { plan_id, step_id, title } = event.payload;
  // Update step status to "running"
});

listen('forgeagent:step-completed', (event) => {
  const { plan_id, step_id, message } = event.payload;
  // Update step status to "completed"
  // Insert system message
});

listen('forgeagent:artifact-ready', (event) => {
  const { plan_id, artifact } = event.payload;
  // Show artifact viewer
});
```

---

## 7. Estados e Transições

```
                    ┌─────────────┐
                    │    IDLE     │
                    └──────┬──────┘
                           │ trigger detected
                           ▼
                    ┌─────────────┐
         ┌──────────│   PLANNING  │◄─────────┐
         │          └──────┬──────┘          │
         │                 │ plan generated  │
         │                 ▼                 │
         │          ┌─────────────┐          │
         │          │  EXECUTING  │──────────┘
         │          └──────┬──────┘ (next step)
         │                 │
         │                 ▼
         │          ┌─────────────┐
         └──────────│  COMPLETED  │
    (all steps done) └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  ARTIFACT   │
                    │   READY     │
                    └─────────────┘
```

---

## 8. Considerações de Performance

### 8.1 Modelo Recomendado
- **ForgeSteel 4B:** Para planos complexos (5+ passos)
- **ForgeIron 2B:** Para planos simples (2-4 passos)
- **ForgeCopper 0.8B:** Não recomendado para geração de planos

### 8.2 Tempos Esperados
- Geração do plano: 2-5 segundos
- Cada step (simulado): 500ms-2s
- Total para plano de 5 steps: 5-15 segundos

### 8.3 Otimizações
- Streaming progressivo (não esperar plano completo)
- Cache de planos similares
- Debounce em palavras-chave

---

## 9. Testes

### 9.1 Testes Unitários
- Parse de JSON válido/inválido
- Detecção de triggers
- Cálculo de progresso

### 9.2 Testes de Integração
- Fluxo completo: input → plano → execução → artefato
- Eventos Tauri
- Error handling

### 9.3 Testes Manuais
- Planos complexos (10+ steps)
- Caracteres especiais
- Timeout de modelo

---

## 10. Referências

- [Manus 1.6 Lite UI Reference](manus-reference.png)
- [Structured Output - llama.cpp](https://github.com/ggerganov/llama.cpp/blob/master/examples/main/README.md#grammar)
- [Tauri Events](https://tauri.app/v1/guides/features/events/)

---

## Histórico de Revisões

| Versão | Data | Autor | Mudanças |
|--------|------|-------|----------|
| 1.0 | 2025-04-02 | ForgeLM Team | Versão inicial |

---

## Aprovações

- [ ] Tech Lead
- [ ] Product Manager
- [ ] QA Lead