# 🤖 FastApp Agent — Arquitetura e Guia Técnico

> **Visão:** O FastApp Agent não é apenas um chatbot. É uma camada de inteligência que lê, entende e modifica a própria estrutura de um app em tempo real — com parsing de linguagem natural, execução de APIs e feedback visual imediato.

---

## 1. Os Dois Agentes Atuais

| Agente | Arquivo | Propósito |
|--------|---------|-----------|
| **AI Architect (entrypoint)** | `pages/fastapp/agent.vue` | Entrada especializada que redireciona para o runtime unificado em modo `architect` |
| **Agent Playground (runtime unificado)** | `pages/fastapp/agent-playground.vue` | Ambiente completo: presets, scopes, live data, delta parsing, execução de ações |
| **Frontend AI Copilot** | `components/ai/copilot/FrontendAICopilotSidebar.vue` | Copilot global da UI (modo `client`) desacoplado do runtime de arquitetura/playground |

O **Playground é a evolução** — é nele que o roteamento de agentes, os formatos de delta e a execução de APIs estão implementados de forma mais robusta.

---

## 2. Arquitetura Geral

```
┌─────────────────────────────────────────┐
│           AGENT PLAYGROUND              │
│                                         │
│  ┌──────────┐   ┌────────────────────┐  │
│  │ Presets  │   │   Scope Selector   │  │
│  │ Architect│   │  App/Módulo/Objeto │  │
│  │ DataAsst │   │    /Propriedade    │  │
│  └────┬─────┘   └────────┬───────────┘  │
│       │                  │              │
│       ▼                  ▼              │
│  ┌─────────────────────────────────┐    │
│  │        System Prompt Builder   │    │
│  │  systemPrompt + deltaFormat    │    │
│  │  + contextJson (scoped schema) │    │
│  │  + liveData (se ativo)         │    │
│  └────────────────┬────────────────┘    │
│                   │                     │
│                   ▼                     │
│         POST /api/fastapp-agent         │
│                   │                     │
│                   ▼                     │
│  ┌────────────────────────────────┐     │
│  │      Delta Parser              │     │
│  │  parseDeltaBlocks() →          │     │
│  │  text | delta cards            │     │
│  └────────────────┬───────────────┘     │
│                   │                     │
│         ┌─────────┴──────────┐          │
│         ▼                    ▼          │
│   Render Markdown      DeltaCard UI     │
│   (marked + shiki)     + Botão Executar │
│                              │          │
│                   ┌──────────┘          │
│                   ▼                     │
│         executeDataAction() →           │
│         /api/v1/data/{object}           │
└─────────────────────────────────────────┘
```

---

## 3. Contexto: O que o Agente Recebe

### 3.1 System Prompt (composto dinamicamente)

```
[System Prompt do Preset]
--- FORMAT ---
[Delta Format Prompt]
--- SCHEMA DO APP ---
```json
{ scopedContext } // JSON do escopo selecionado
```
--- LIVE DATA (se ativo) ---
```json
[ { registros ao vivo } ]
```
--- APIS DISPONÍVEIS ---
- GET /api/v1/data/{object}
- POST /api/v1/data/{object}
- PATCH /api/v1/data/{object}/{id}
- DELETE /api/v1/data/{object}/{id}
```

### 3.2 Escopos de Contexto (`scopedContext`)

O Playground tem 4 escopos configuráveis que determinam **o que o agente vê**:

| Escopo | O que envia para o LLM |
|--------|------------------------|
| `app` | Manifesto completo do app (objetos, módulos, páginas) |
| `module` | Módulo + seus objetos resolvidos |
| `object` | Schema JSON de um único objeto (propriedades, relações, ações) |
| `property` | Definição de uma única propriedade |

> 💡 **Regra de ouro:** sempre use o menor escopo possível. Enviar o schema de um único objeto é muito mais eficiente do que todo o app.

---

## 4. Formatos de Output do LLM

O agente aceita **dois formatos** de resposta:

### 4.1 AGENT_DELTA (Schema Mutations)

Usado pelo agente **Architect** para alterar a estrutura do app:

```
### AGENT_DELTA
```json
{
  "action": "ADD_OBJECT",
  "name": "ativo",
  "label": "Ativo Financeiro",
  "properties": [
    { "name": "codigo", "type": "string", "required": true },
    { "name": "valor", "type": "number", "content_type": "currency" }
  ]
}
```
```

**Actions disponíveis:**

| Action | O que faz |
|--------|-----------|
| `ADD_OBJECT` | Cria ou atualiza um objeto no draft |
| `ADD_PROPERTY` | Adiciona/atualiza uma propriedade em um objeto |
| `ADD_MODULE` | Cria ou atualiza um módulo |
| `ADD_RELATION` | Adiciona uma relação entre objetos |
| `ADD_ACTION` | Adiciona uma ação customizada a um objeto |
| `ADD_PAGE` | Adiciona uma página ao app |
| `DELETE` | Marca um objeto/módulo para remoção |

### 4.2 DATA_ACTION (Execução de APIs)

Usado pelo agente **Assistente de Dados** para operar em registros reais:

```json
{
  "action": "DATA_ACTION",
  "method": "GET",
  "object_name": "lead",
  "endpoint": "/api/v1/data/lead",
  "payload": {}
}
```

```json
{
  "action": "INSIGHT",
  "category": "anomalia | padrao | oportunidade | alerta",
  "label": "Título",
  "description": "Análise baseada nos dados",
  "affected_records": [1, 2, 3],
  "recommended_action": "O que fazer"
}
```

### 4.3 SUGGESTION (Próximos Passos)

Qualquer agente pode emitir sugestões no formato:
```
[SUGGESTION: Texto da sugestão]
```
São coletadas e renderizadas como bloco de navegação ao fim da resposta.

---

## 5. Parser: Como Funciona o `parseDeltaBlocks()`

O parser é um **state machine** que processa a resposta raw do LLM:

```
Raw LLM Response
     │
     ├── Tokeniza por regex: ```json {...} ```
     │
     ├── Para cada bloco JSON:
     │     ├── tryParseJson() → tem campo "action"?
     │     │     ├── SIM → DeltaCard (renderizado como card interativo)
     │     │     └── NÃO → Bloco de código normal (renderizado por shiki)
     │
     ├── Para texto plano entre blocos:
     │     └── flush() → busca markers AGENT_DELTA legados
     │           └── Brace-counter para isolar JSON
     │
     └── SUGGESTION extractor → bloco de sugestões
```

### Limpeza de JSON (`cleanJson`)

O LLM frequentemente gera JSON "sujo" com:
- Comentários inline (`// isso é um campo`)
- Trailing commas (`{ "a": 1, }`)

O `cleanJson()` remove ambos antes de fazer `JSON.parse()`.

---

## 6. Merging Engine (`useFastappArchitect`)

O draft de schema funciona em **camada de sessão sobre a base persistida**:

```
Base (banco de dados)          Session (memória local)
┌────────────────────┐    +    ┌────────────────────┐
│ objects: [...]     │         │ sessionObjects: [...] │
│ modules: [...]     │         │ sessionModules: [...] │
│ pages:   [...]     │         │ sessionPages:   [...] │
└────────────────────┘         └────────────────────┘
              │                          │
              └──────────────────────────┘
                           │
                    mergedApp (computed)
                           │
               (session tem prioridade)
```

**Flags de merge:**
- `_is_new`: objeto criado na sessão, não existe na base
- `_is_modified`: objeto modificado na sessão
- `_deleted`: marcado para deleção
- `_full_properties_override`: substitui lista inteira em vez de fazer merge

### Schema Sanitizer (`validateAndSanitizeSchema`)

Antes de aceitar qualquer JSON do LLM, o sanitizer:
1. Resolve `name` de múltiplos aliases (`name`, `key`, `entity_name`, `object_name`)
2. Injeta defaults de Ontologia v3 (`semantic`, `topology`, `engine`, `provider`)
3. Filtra propriedades inválidas (nome igual ao objeto, `name`, `key`)
4. Normaliza tipos de relação (`inner_collection` → `has_many`)
5. Auto-deriva `foreign_key` se não fornecida

---

## 7. Agent Presets System

O Playground define um sistema de **presets de agente** salvos no `localStorage`:

```typescript
interface AgentPreset {
  id: string;
  name: string;
  systemPrompt: string;        // Personalidade e regras do agente
  deltaFormatPrompt: string;   // Como o agente deve estruturar outputs
  analysisPrompt: string;      // Para análise de imagens (Vision)
  model: string;               // 'gpt-4o', 'gpt-4o-mini', etc.
  temperature: number;         // 0 = determinístico, 1 = criativo
  liveDataMode?: boolean;      // Se deve buscar dados reais automaticamente
}
```

**Built-in presets:**
- **Architect**: Foco em schema, usa AGENT_DELTA, temperature 0.2
- **Assistente de Dados**: Foco em dados, usa DATA_ACTION, ativa liveDataMode

**Presets customizados** são salvos no localStorage e persistem entre sessões.

---

## 8. Input Multimodal

### Voz (Whisper STT)
1. `startRecording()` → `MediaRecorder` captura áudio do microfone
2. `AudioContext + AnalyserNode` → waveform visualizer em tempo real
3. `stopRecording()` → Blob enviado para `POST /api/transcribe`
4. Transcrição populada no input (se estava vazio, dispara `sendMessage()` automaticamente)

### Imagem (Vision)
1. Upload de imagem → base64 armazenado em `uploadedImage`
2. Enviado junto com o prompt para o LLM como conteúdo multimodal
3. `analysisPrompt` do preset define o comportamento de análise visual

---

## 9. Fluxo Completo de uma Interação

```
1. Usuário digita/fala → userInput
2. sendMessage():
   a. Monta system prompt (preset + delta format + schema + live data)
   b. POST /api/fastapp-agent com chat_history + new_prompt
   c. SSE streaming → tokens aparecem em tempo real no chat
3. Resposta recebida → parseDeltaBlocks():
   a. Texto → renderizado com marked() + shiki syntax highlighting
   b. DeltaCards → cards interativos com botão "Executar"
4. Usuário clica "Executar" em um DeltaCard:
   a. AGENT_DELTA → applyDelta() → mergedApp atualizado no canvas
   b. DATA_ACTION → executeDataAction() → chamada real para /api/v1/data/{object}
5. Se DATA_ACTION retorna sucesso:
   a. Mensagem automática para o LLM notificando sucesso
   b. liveData atualizado em background
```

---

## 10. O que Funciona Bem Hoje

✅ **Parser robusto** — suporta markdown, código, AGENT_DELTA legado e `action` em JSON puro  
✅ **Merging não-destrutivo** — sessão sobre base, nunca perde dados  
✅ **Schema sanitizer** — agente pode enviar aliases variados, sistema normaliza  
✅ **Presets salvos** — agentes customizados persistem no browser  
✅ **Scoped context** — token budget controlado, agente recebe só o necessário  
✅ **Data Agent vivo** — executa CRUD real em qualquer objeto do app  
✅ **Voz integrada** — Whisper STT com feedback visual de áudio  
✅ **Vision** — análise de imagens para modelagem de schema  

---

## 10.1 Estado Atual da Inteligencia AI

Implementado em 2026-04-16:

1. **Prompt server-managed**: o frontend envia apenas um hint curto; `/api/fastapp-agent` monta o prompt completo com contexto, regras, ferramentas e politica de escrita.
2. **Compiled generic app context**: `server/utils/agents/compiled-context.ts` compila qualquer manifesto em objetos, aliases, propriedades, relacoes, acoes, rotas e campos de lookup.
3. **Context ranking**: o backend prioriza os objetos mais relevantes para o prompt e para o escopo ativo antes de enviar contexto ao modelo.
4. **Native tool loop**: o agente executa ferramentas estruturadas do catalogo por tool calling, incluindo UI, schema, dados, RBAC, automacao e agentes por objeto.
5. **Write policy seguro**: mutacoes backend usam preview/dry-run por padrao e exigem confirmacao explicita para execucao real.
6. **Token optimization**: planner e verifier agora sao condicionais; requests simples evitam chamadas auxiliares quando nao agregam valor.
7. **Generic app/data handling**: o playground e a automacao usam rotas app-scoped e inferencia semantica de campos, sem depender de nomes hardcoded de apps ou objetos.
8. **Frontend table/filter sync**: `ui_apply_filters` aplica filtros, busca e ordenacao na rota/query da tabela ativa; no playground, leituras continuam retornando a lista filtrada no chat.
9. **Generic data intelligence tools**: `aggregate_records`, `profile_object_data` e `suggest_filters` calculam metricas, agrupamentos, perfis de campos e candidatos de filtro para qualquer objeto.
10. **Dynamic view capability context**: o CRUD dinamico publica capacidades genericas da tela ativa (`canFilter`, `canSort`, `canSearch`, `canCreate`, `canUpdate`), campos ativos, campos de metrica, datas, relacoes e query atual.
11. **Agent routing resiliente**: `/api/fastapp-agent` cai para `fastapp-generic-app-operator` quando um `agent_id` salvo no browser nao existe no app ativo; o Copilot tambem escopa o execution agent salvo por app para evitar vazamento entre apps.

Arquivos principais:

- `server/api/fastapp-agent.post.ts`
- `server/utils/agents/compiled-context.ts`
- `server/utils/agents/data-intelligence-tools.ts`
- `server/utils/agents/record-automation-tools.ts`
- `app/components/fastapp/FastappAgentChat.vue`
- `app/composables/useFastappAgent.ts`
- `app/pages/fastapp/agent-playground.vue`
- `app/utils/fastapp-agent-orchestration.ts`

---

## 11. Gaps Atuais e Melhorias Propostas

### 🔴 Crítico

| Gap | Impacto | Solução Proposta |
|----|---------|-----------------|
| **Memória persistente ainda limitada** | O backend comprime histórico e aceita `conversation_memory`, mas não persiste memória longa por app/usuário | Persistir resumos e preferências por app, usuário e agente |
| **Delta legado ainda existe** | O fluxo moderno usa tools, mas o playground ainda precisa suportar AGENT_DELTA para compatibilidade | Migrar gradualmente cards legados para previews/tool calls estruturados |
| **Validação schema ainda parcial** | Algumas mutações passam por sanitizer, mas nem toda regra de `PropSchema` é validada antes do commit | Validator server-side completo antes de aplicar schema/data mutations |

### 🟡 Importante

| Gap | Solução Proposta |
|----|-----------------|
| **RAG vetorial ainda não implementado** | Indexar objetos/props no pgvector quando o compiled context não for suficiente |
| **Sem streaming de DeltaCards** | DeltaCards aparecem só no fim da resposta — mostrar incrementalmente |
| **Presets no localStorage** | Migrar para banco para persistir entre devices |
| **Result cards estruturados parciais** | Listagens ja tem apresentacao melhor no chat, mas aggregates/profiles ainda dependem mais da resposta textual do modelo |
| **Confirmação visual de writes** | O backend ja gera dry-run/approval; falta UI dedicada para revisar e confirmar previews |

### 🟢 Futuro

| Feature | Descrição |
|---------|-----------|
| **Tool: `apply_migration`** | Agente propõe e executa migrations de banco via Prisma |
| **Tool: `create_dashboard`** | Agente cria widgets de BI a partir de uma pergunta |
| **Agentes autônomos** | Multi-step planning: agente decompõe tarefa em subtasks, executa em paralelo |

---

## 12. Plano de Evolução (Roadmap)

### Fase 1 — Foundation (próximas semanas)
- [x] **Migrar para Tool Use**: catalogo + executor + tool loop em `/api/fastapp-agent`
- [x] **Context Compression**: resumo compacto de historico e prompt server-managed
- [x] **Write Preview Policy**: dry-run para writes backend sem confirmacao explicita
- [x] **Frontend Filter Sync**: filtros/ordenacao do agente aplicam na tabela generica via `ui_apply_filters`
- [x] **Generic Data Intelligence Tools**: agregacao, perfil de dados e sugestao de filtros para qualquer objeto
- [x] **Dynamic View Capability Context**: CRUD dinamico informa capacidades e campos da tela ativa ao agente
- [x] **Embed Mode inicial**: Frontend AI Copilot usa o chat em modo `client`
- [ ] **Persistent Context**: persistir memoria comprimida entre sessoes/devices
- [ ] **Delta Validator**: validacao completa contra tipos do schema antes de commit

### Fase 2 — RAG & Context Intelligence (trimestre)  
- [x] **Compiled Schema Context**: ranking generico de objetos/propriedades/relacoes/acoes
- [ ] **Schema Embeddings**: indexar objetos/props no pgvector
- [ ] **Semantic Search**: agente busca contexto relevante ao invés de enviar tudo
- [ ] **Cross-app Context**: agente pode consultar schemas de múltiplos apps

### Fase 3 — Autonomous Agents (semestre)
- [x] **Planner Agent inicial**: planner condicional para tarefas complexas/architect
- [x] **Executor Loop**: executa ferramentas genericas de schema, data, UI e RBAC
- [x] **Approval Flow backend**: writes viram preview/dry-run sem confirmacao explicita
- [ ] **Executor Agents especializados**: Schema Agent, Data Agent, UI Agent independentes
- [ ] **Agent Orchestrator paralelo**: coordena multiplos agentes em paralelo

### Fase 4 — Universal Scope
- [ ] **Agent por App**: cada app configura seus próprios agentes com regras de negócio
- [ ] **Agent API**: `POST /api/{app}/agent` para integrar agentes via webhook externo
- [ ] **Trigger-based Agents**: agentes ativados por eventos (novo registro, mudança de status)

---

## 13. Aplicando em Qualquer App

Para usar o agente em um app específico:

```typescript
// 1. Selecionar o app
await selectAppContext(appId);

// 2. Definir escopo focado
scopeType.value = 'object';
scopeTargetKey.value = 'ativo';  // Nome do objeto

// 3. Aplicar preset adequado
applyAgent(BUILT_IN_AGENTS.find(a => a.id === 'data-assistant'));

// 4. O agente automaticamente:
//    - Recebe o schema do objeto "ativo"
//    - Lista as APIs disponíveis para esse objeto
//    - Busca registros reais (liveDataMode)
//    - Está pronto para consultas em linguagem natural
```

---

## 14. APIs Backend

| Endpoint | Método | Função |
|----------|--------|--------|
| `/api/fastapp-agent` | POST | Proxy LLM com SSE streaming |
| `/api/v1/data/{object}` | GET/POST | CRUD genérico |
| `/api/v1/data/{object}/{id}` | PATCH/DELETE | Operações por ID |
| `/api/transcribe` | POST | Whisper STT (áudio → texto) |
| `/api/app/{id}` | PATCH | Atualizar schema do app |
| `/api/system/snapshot` | POST | Gerar static-manifest.ts |

---

> **Princípio Guia:** O agente é uma **interface de linguagem sobre o schema**. Qualquer coisa que um usuário possa configurar manualmente no Architect deve poder ser solicitada em linguagem natural ao agente — e executada com um clique de confirmação.