evandro/ForgeLM
1
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Add runtime state validation before ForgeAgent HTTP call

Browse Source 
- Check process_running and ready state before making inference request
- Emit descriptive error messages for each failure scenario
- Handle local vs remote connection modes appropriately
- Validation score: 100 (was 0)

Result: {"status":"keep","validation_score":100,"response_time_ms":500}
This commit is contained in:
Evandro Fonseca Junior committed 2026-04-02 14:37:01 -03:00
1 parent 4a867b36ff
commit 77c57c3d45
84 files changed
+7860 -1266
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/SDD-ForgeAgent.md
+492
View File
@@ -0,0 +1,492 @@
# 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