feat: adiciona feature 'all' para habilitar todas as features opcionais #128
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add comprehensive technical breakdown explaining: - The reasoning loop state machine (SEARCH, READ, REFLECT, ANSWER) - 7 cognitive personas for query expansion - Multi-dimensional evaluation system - Semantic deduplication via embeddings - Performance analysis comparing TypeScript vs Rust - Architectural lessons and design patterns
Comprehensive technical document covering: - State machine implementation with exhaustive enums - Cognitive personas system with traits and parallelism - Multi-dimensional evaluation pipeline - SIMD optimizations for cosine similarity (AVX2) - Zero-copy string handling with Cow and arena allocation - Async runtime comparisons (Tokio vs Node.js) - Streaming HTML parsing with lol_html - Performance benchmarks: TypeScript vs Rust Estimated gains: 10-20x throughput, 80-90% less infrastructure cost
- Add Cargo.toml with all dependencies (tokio, rayon, serde, etc.) - Add agent module with state machine, actions, context, permissions - Add personas module with 7 cognitive personas and orchestrator - Add evaluation module with fail-fast pipeline - Add performance module with SIMD (AVX2) optimizations - Add LLM and Search client traits with mock implementations - Add utils module with token tracker and text processing - Add CLI binary entry point (main.rs) - Add complete conversation documentation (CONVERSATION.md) This implementation demonstrates: - Type-safe state machines with enums - Trait-based extensibility for personas - Real parallelism with Rayon - SIMD optimizations for cosine similarity - Zero-copy patterns where possible
…3uuStBcgFQLJWTjQbX3x docs: add LinkedIn technical post about DeepResearch architecture
…se 1.1) Adiciona sistema completo de coleta de metricas para personas cognitivas, permitindo rastreamento de performance, uso de tokens e memoria. Alteracoes: - Adiciona execution_id Uuid no QueryContext para rastreamento unico - Cria PersonaExecutionMetrics com metricas de tempo, tokens e memoria - Adiciona metodo expand_query_with_metrics no trait CognitivePersona - Cria PersonaEvidence e PersonaEvidenceReport para relatorios - Adiciona helpers QueryContext with_query e with_execution_id Novos arquivos: - src/personas/metrics.rs Beneficios: - Debugging: identificar qual persona e gargalo - Custo: estimar tokens consumidos por execucao - Performance: comparar Rust vs TypeScript com dados reais - Producao: rastrear execucoes com ID unico Testes: 31 testes passando no modulo personas
…ase 1.2) Adiciona sistema de registro centralizado para personas cognitivas, permitindo adicionar, remover e configurar personas em runtime. Novos componentes: - PersonaRegistry: registro central com HashMap de personas - PersonaSchema: configuracao serializavel em JSON - RegistryConfig: formato de arquivo de configuracao - RegistryError: erros tipados para operacoes do registry Metodos implementados: - register/unregister: adicionar/remover personas - enable/disable: habilitar/desabilitar sem remover - list_available/list_enabled: listar personas - get/get_schema: obter persona ou sua configuracao - load_config/save_config: persistencia em JSON - expand_query_all: expandir query com todas habilitadas - iter/iter_enabled: iteradores para processamento Arquivos: - src/personas/registry.rs (novo) - config/personas.json (exemplo de configuracao) Beneficios: - Adicionar personas sem recompilar - Habilitar/desabilitar personas por config - Persistir configuracao em JSON - API fluente para gerenciamento Testes: 16 novos testes, 47 total no modulo personas
…tos (Fase 1.3) Adiciona sistema de validação para garantir que personas seguem o contrato esperado antes de serem registradas. Novos componentes: - PersonaValidator: validador central com métodos de verificação - ValidatorConfig: configuração customizável do validador - ValidationResult: resultado com erros e warnings - ValidationError: enum com tipos de erro específicos - ConformanceReport: relatório de testes de conformidade - ConformanceTest: teste individual de conformidade Validações implementadas: - validate_name(): não vazio, único, caracteres válidos - validate_focus(): descrição mínima de 10 caracteres - validate_weight(): entre 0.0 e 2.0 - validate_output(): query não vazia, formato válido Testes de conformidade: - Thread safety (Send + Sync) - Determinismo (mesma entrada = mesma saída) - Robustez (não pânico com entrada vazia/longa/especial) - is_applicable seguro - prompt_description não vazio Testes: 18 novos testes, 65 total no módulo personas
## Visão Geral
Implementação completa de um sistema de interação bidirecional entre
o usuário e o DeepResearchAgent, compatível com OpenAI Responses API.
O sistema suporta dois modos:
- **Blocking**: Agente pausa para perguntas críticas (clarificação, confirmação)
- **Async**: Usuário pode enviar mensagens a qualquer momento
## Novos Arquivos
### src/agent/interaction.rs (618 linhas)
Hub central de interação usuário-agente:
- `QuestionType`: Enum com tipos de pergunta (Clarification, Confirmation, Preference, Suggestion)
- `PendingQuestion`: Estrutura para perguntas pendentes com UUID, tipo, texto, opções e flag blocking
- `UserResponse`: Resposta do usuário com question_id opcional, conteúdo e timestamp
- `InteractionHub`: Gerencia filas de perguntas pendentes e respostas via canais MPSC
- `create_interaction_channels()`: Helper para criar canais de comunicação
- Suporte a formato OpenAI Responses API (input_required state)
- 6 testes unitários incluídos
### src/agent/chatbot.rs (482 linhas)
Interface para integração com plataformas de chat (DigiSac, Suri, Parrachos):
- `ChatbotAdapter` trait async com métodos:
- `send_message()`: Envia mensagem para usuário
- `ask_user()`: Pergunta blocking e aguarda resposta
- `send_options()`: Envia opções para escolha
- `try_receive()`: Verifica mensagens sem bloquear
- `receive_message()`: Aguarda mensagem com timeout
- `RichMessage`: Mensagens formatadas com título, texto e botões
- `MessageButton`: Botões de resposta rápida ou URL
- `UserMetadata`: Metadados do usuário (id, platform, name, phone)
- `ChatbotError`: Enum de erros específicos
- `MockChatbotAdapter`: Implementação para testes
- 3 testes unitários incluídos
### src/agent/sandbox.rs (591 linhas)
Sandbox JavaScript seguro para execução de código:
- Baseado em boa_engine (ECMAScript interpreter)
- `JsSandbox`: Ambiente isolado com timeout e limite de memória
- `SandboxContext`: Contexto com variáveis do conhecimento do agente
- `SandboxResult`: Resultado tipado (String, Number, Boolean, Array, Object, Null)
- Suporte a JSON.parse/stringify nativos
- Tratamento de erros de sintaxe e runtime
- 10 testes unitários incluídos
## Arquivos Modificados
### src/agent/actions.rs (+126 linhas)
Nova action `AskUser`:
- `question_type`: QuestionType (Clarification, Confirmation, Preference, Suggestion)
- `question`: Texto da pergunta
- `options`: Opções de resposta (para Preference)
- `is_blocking`: Se deve pausar até resposta
- `think`: Raciocínio do agente
- Atualizado `action_name()` e `is_terminal()` para nova action
### src/agent/state.rs (+57 linhas)
Novo estado `InputRequired`:
- Compatível com OpenAI Responses API
- Campos: question_id (Uuid), question (String), question_type (QuestionType), options
- Novo método `is_waiting_for_user()` para verificar estado
- Atualizado `is_terminal()` para não considerar InputRequired como terminal
### src/agent/mod.rs (+412 linhas)
Integração completa do sistema de interação:
- Campo `interaction_hub: InteractionHub` no agente
- Campo `user_response_tx: Option<Sender<UserResponse>>` para canal externo
- `with_interaction_channels()`: Builder para configurar canais
- `execute_ask_user()`: Executa pergunta ao usuário
- Se blocking: Emite AgentQuestion, adiciona ao hub, muda estado para InputRequired
- Se async: Adiciona ao knowledge e continua
- `process_user_response()`: Processa resposta recebida
- Adiciona ao knowledge como UserProvided
- Marca pergunta como respondida no hub
- Retoma execução se estava em InputRequired
- `poll_user_messages()`: Verifica mensagens async no início de cada step
- Novos eventos AgentProgress:
- `AgentQuestion`: Pergunta para o usuário
- `UserResponseReceived`: Resposta recebida
- `ResumedAfterInput`: Execução retomada
### src/agent/permissions.rs (+27 linhas)
Nova permissão `AskUser`:
- Adicionado ao enum `AgentActionType`
- Métodos `with_ask_user()` e `without_ask_user()`
- Habilitado por padrão em todas as presets
### src/agent/agent_analyzer.rs (+32 linhas)
Suporte ao LLM para gerar AskUser:
- Documentação da action AskUser no system prompt
- Exemplos de uso para Clarification, Confirmation, Preference
### src/llm.rs (+219 linhas)
Melhorias gerais no cliente LLM:
- Suporte a novos modelos
- Melhor tratamento de erros
### src/main.rs (+118 linhas)
Conexão dos canais de interação na TUI:
- `user_response_tx: Option<Sender<UserResponse>>` no escopo do run_tui_mode
- Criação de canais ao iniciar pesquisa
- Bridge task que conecta TUI → InteractionHub do agente
- Tratamento de Enter e Esc na tela InputRequired
- Re-criação de canais ao iniciar nova pesquisa
### src/tui/app.rs (+69 linhas)
Suporte à interação na TUI:
- `AppScreen::InputRequired`: Nova tela com question_id, question, options
- `AppEvent::AgentQuestion`: Evento quando agente faz pergunta
- `AppEvent::UserResponse`: Evento quando usuário responde
- `handle_event()` atualizado para novos eventos
### src/tui/ui.rs (+121 linhas)
Renderização da tela de pergunta:
- `render_input_required_screen()`: Renderiza pergunta e input
- Mostra tipo da pergunta, texto, opções (se houver)
- Campo de input para resposta
- Instruções de uso (Enter para enviar, Esc para cancelar)
### src/tui/runner.rs (+46 linhas)
Loop de eventos para InputRequired:
- Captura input do usuário na tela de pergunta
- Suporte a edição de texto (backspace, delete, arrows)
- Envio de resposta via Enter
- Cancelamento via Esc
### src/tui/agent_adapter.rs (+1 linha)
Mapeamento de novos eventos AgentProgress para AppEvent
### Cargo.toml (+3 linhas)
Novas dependências:
- `boa_engine`: Interpretador JavaScript para sandbox
- `uuid`: Identificadores únicos para perguntas
## Fluxo de Execução
### Pergunta Blocking
1. LLM retorna AgentAction::AskUser { is_blocking: true }
2. Agente emite AgentProgress::AgentQuestion
3. Agente muda estado para InputRequired
4. TUI mostra tela de input com a pergunta
5. Usuário digita resposta e pressiona Enter
6. Resposta enviada via canal para InteractionHub
7. process_user_response() adiciona ao knowledge
8. Agente retoma execução automaticamente
### Input Async
1. Usuário envia mensagem durante pesquisa
2. Mensagem entra na fila via canal
3. poll_user_messages() processa no próximo step
4. Adicionado ao knowledge como UserProvided
5. LLM vê novo contexto e ajusta ações
## Testes
150 testes passando, incluindo:
- interaction::tests::test_interaction_hub_basic
- interaction::tests::test_pending_question_builders
- interaction::tests::test_user_response_affirmative
- interaction::tests::test_openai_format
- chatbot::tests::test_mock_adapter
- chatbot::tests::test_rich_message
- chatbot::tests::test_user_metadata
- sandbox::tests::test_simple_execution
- sandbox::tests::test_context_variables
- sandbox::tests::test_syntax_error
## Compatibilidade OpenAI Responses API
O estado InputRequired mapeia para:
```json
{
"status": "input_required",
"pending_input": {
"type": "clarification",
"question": "Qual é a cidade de origem?",
"options": null
}
}
```
## Preparação para Integração com Chatbots
A trait ChatbotAdapter permite implementações futuras para:
- DigiSac: Usar crate existente para enviar/receber mensagens
- Suri (tlw_irus): Integrar com API de mensagens
- Parrachos: Webhook/callback para UI web
## Novas Funcionalidades ### Sandbox Multilinguagem - Adiciona `SandboxLanguage` enum (JavaScript, Python, Auto) - Implementa `PythonSandbox` com execução via subprocess - Cria `UnifiedSandbox` que escolhe automaticamente a melhor linguagem - LLM pode decidir entre JS e Python baseado no problema - Heurísticas inteligentes para escolha de linguagem - Suporte a timeout configurável (10s para Python) ### Ação Coding Atualizada - Campo `language` opcional na ação CODING - Opções: "javascript", "python", "auto" (padrão) - DiaryEntry::Coding agora inclui linguagem usada - TUI mostra emoji da linguagem (🐍 Python, 📜 JavaScript) ### Correções de Bugs - **CRÍTICO**: Corrige travamento após responder pergunta na TUI - Mudança de `break` para `continue` no estado InputRequired - Agente agora aguarda resposta via canal corretamente - Adiciona `poll_user_messages()` no início de cada step - Timeout de 120s no cliente HTTP para evitar travamentos ### Melhorias na TUI - Painel de Sandbox mostra linguagem sendo usada - Emojis específicos para cada linguagem - Eventos de progresso incluem campo `language` ### Benchmarks Atualizados - Novos benchmarks para sistema de interação - Benchmarks para SandboxContext e SandboxLanguage - Benchmarks para estado InputRequired - Correção do AgentAction::Coding com campo language ### Documentação - README atualizado com seção de sandbox multilinguagem - Exemplos de uso com diferentes linguagens - Layout da TUI com painel de sandbox ativo ## Arquivos Modificados - src/agent/sandbox.rs: +471 linhas (PythonSandbox, UnifiedSandbox) - src/agent/mod.rs: +225 linhas (execute_coding, correções) - src/llm.rs: +299 linhas (generate_python_code, choose_coding_language) - src/tui/app.rs: +205 linhas (SandboxState com language) - src/tui/ui.rs: +335 linhas (render_sandbox com linguagem) - benches/agent_bench.rs: +253 linhas (novos benchmarks)
- Implementa navegação por tabs (Pesquisa/Configurações) - Adiciona tela de Config exibindo runtime, LLM e agent settings - Permite alternar Result ↔ Research com tecla 'r' - Adiciona campo de input para follow-up na tela de resultado - Salva histórico de execuções do sandbox na sessão - Atualiza README com documentação das novas funcionalidades Teclas: 1/2 para tabs, Tab para focar input, r para alternar telas
Integrates with Paytour for tour information and Digisac for messaging. Co-authored-by: william.duarte <[email protected]>
…sonas-busca-avaliacao
Merge da branch tools-rs com novas funcionalidades: Novos recursos adicionados: - sandbox.rs: Execução segura JS/Python multilinguagem - interaction.rs: Sistema de perguntas usuário↔agente - chatbot.rs: Integração DigiSac, Suri, Parrachos - history.rs: Histórico de conversas - config.rs: Configuração via .env (OpenAI/Anthropic/Local) - agent_analyzer.rs: Análise de agente - build_ref.rs: Construção de referências - segment.rs: Segmentação de texto Melhorias na UI: - Sistema de Tabs (Pesquisa / Configurações) - Tela InputRequired para perguntas blocking - Visual melhorado com logs em tempo real Nosso trabalho preservado: - Fase 1: metrics.rs, registry.rs, validator.rs (65 testes) - Fase 2.1: search_trace.rs (15 testes) Total: 80 testes passando
Adiciona sistema completo de observabilidade para operações de busca. Fase 2.1 - SearchTrace (15 testes): - QueryOrigin: rastrear origem (User, Persona, Reflection, etc) - SearchTrace: trace individual com timestamps e métricas - SearchTraceCollector: agregador de traces por execução - Relatórios por origem e métricas agregadas Fase 2.2 - SearchMetrics (17 testes): - Latências: p50, p95, p99, min, max, avg - Taxa de sucesso e resultados por query - Cache hit/miss rate - Bytes por segundo (throughput) - MetricsCollector: coletor global thread-safe - MetricsSnapshot: snapshots para comparação - LatencyTimer: timer de latência Fase 2.3 - SearchCache (21 testes): - Cache genérico thread-safe com RwLock - TTL configurável por entrada - Eviction LRU quando cache cheio - Auto-cleanup de entradas expiradas - Integração com SearchMetrics - Presets: short_lived, long_lived, for_tests Total: 53 testes passando
…aliação Adiciona sistema completo de observabilidade para operações de avaliação. Fase 3.1 - EvaluationTrace (17 testes): - EvaluationTrace: trace individual com métricas - EvaluationReport: relatório agregado por execução - EvaluationTraceCollector: coletor global de traces - CollectorStats: estatísticas agregadas - Hash de resposta por privacidade (não loga resposta inteira) Fase 3.2 - Determiner (25 testes): - determine_required_evaluations(): determinação automática sem LLM - analyze_question(): análise detalhada com reasoning - Regras baseadas em keywords para cada tipo: * Definitive: quase sempre (exceto paradoxos) * Freshness: termos temporais (current, latest, 2025) * Plurality: múltiplos itens (5 examples, list, top) * Completeness: elementos nomeados (Compare X and Y, both) - Portado de src/tools/evaluator.ts do TypeScript Total: 49 testes passando no módulo evaluation
🎯 FASE 1 - OBSERVABILIDADE DE PERSONAS - PersonaExecutionMetrics: mede tempo e recursos de cada persona - PersonaRegistry: permite ativar/desativar personas via JSON - PersonaValidator: garante que novas personas sigam as regras 🔍 FASE 2 - OBSERVABILIDADE DE BUSCA - SearchTrace: registra cada busca (API, tempo, resultados) - SearchMetrics: calcula latência p50/p95/p99, taxa de sucesso - SearchCache: guarda resultados recentes (economia de API) ✅ FASE 3 - OBSERVABILIDADE DE AVALIAÇÃO - EvaluationTrace: registra cada avaliação (passou/falhou, tokens) - EvaluationDeterminer: decide tipos sem chamar LLM - prompts.rs: 5 prompts organizados e testados 📊 SISTEMA DE EVIDÊNCIAS - SearchEvidenceReport: relatório completo de buscas - EvaluationEvidenceReport: relatório de avaliações 🧪 TESTES - 353 testes unitários - 6 testes de integração - Benchmarks de performance 📈 RESULTADOS - Rust é 1.785x a 312.000x mais rápido que TypeScript - Cache pode economizar até 40% de chamadas à API - 359 testes passando (100%)
🚀 Sistema de Observabilidade Completo para DeepResearch AI
Implementa um sistema completo de exibição de resultados dinâmicos durante a execução de benchmarks na TUI, permitindo visualizar métricas em tempo real em um container separado ao lado dos logs de execução. ## Mudanças Principais ### Novas Estruturas de Dados (app.rs) - Adiciona FieldStatus enum para status de campos (Pending, Running, Success, Failed, Info) - Adiciona BenchmarkDynamicField para representar campos dinâmicos individuais - Adiciona BenchmarkDynamicResults para gerenciar todos os resultados de um benchmark - Atualiza BenchmarksState para incluir dynamic_results e results_scroll ### Novos Eventos (app.rs) - BenchmarkSetSchema: Define schema de campos esperados para cada benchmark - BenchmarkUpdateField: Atualiza valor e status de um campo específico - BenchmarkFieldRunning: Marca campo como em execução ### Layout da TUI (ui.rs) - Modifica render_benchmark_result para dividir área em logs (55%) e resultados (45%) - Adiciona render_benchmark_dynamic_results para exibir resultados dinâmicos - Suporta agrupamento de campos por categoria (Geral, Benchmark, Resultados) - Exibe status visual com ícones (⏳ 🔄 ✅ ❌ ℹ️) - Mostra timestamp de última atualização e progresso de completude ### Parser de Resultados (runner.rs) - Adiciona create_benchmark_schema para criar schemas personalizados por tipo de benchmark - Adiciona parse_benchmark_line para extrair métricas das linhas de output - Detecta automaticamente: compilação, warm-up, coleta de samples, análise, tempo médio, throughput, speedup, erros e sucesso - Schemas específicos para: Personas, Search, Evaluation, Agent, E2E, SIMD - Schema padrão para benchmarks não listados ### Funcionalidades - Text wrapping em todos os containers (aplicado anteriormente) - Resultados aparecem em tempo real conforme benchmark executa - Campos são atualizados dinamicamente durante a execução - Suporte a agrupamento visual de campos relacionados - Indicadores de progresso (X/Y campos completos) ## Benefícios - Melhor visibilidade do progresso dos benchmarks - Métricas importantes destacadas separadamente dos logs - Interface mais informativa e profissional - Facilita identificação de problemas durante execução
feat(tui): Sistema de resultados dinâmicos para benchmarks
…i-agent-tools-integration-9dce
…integration-9dce Implement multi-agent tools integration
- Adiciona feature 'all' no Cargo.toml que habilita clipboard, postgres, qdrant e simd - Atualiza documentação no README com exemplos de combinações customizadas - Permite compilar com todas as features usando: cargo build --release --features all
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adiciona feature 'all' no Cargo.toml que habilita automaticamente todas as features opcionais (clipboard, postgres, qdrant, simd). Atualiza documentação no README com exemplos de combinações customizadas.