@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

package/stacks/blazor-azure/.morph/examples/multi-agent/spec.md

@@ -1,479 +0,0 @@
-# Multi-Agent System - Especificação
-
-## 1. Visão Geral
-
-Sistema de agentes de IA cooperativos usando Microsoft Semantic Kernel para resolver tarefas complexas através de decomposição e especialização.
-
-### 1.1 Objetivos
-
-- Criar sistema escalável de agentes cooperativos
-- Implementar orquestração inteligente de tarefas
-- Fornecer extensibilidade para novos agentes e plugins
-- Manter custos controlados com uso eficiente de tokens
-
-### 1.2 Use Cases
-
-| Use Case | Agentes Envolvidos |
-|----------|-------------------|
-| Pesquisa de mercado | Orchestrator → Research → Analysis → Writing |
-| Análise de documentos | Orchestrator → Research → Analysis |
-| Geração de relatórios | Orchestrator → Research → Writing |
-| Q&A com base de conhecimento | Orchestrator → Research |
-
-## 2. Arquitetura
-
-### 2.1 Componentes Principais
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        API Layer                                 │
-│  ┌─────────────────┐  ┌─────────────────┐                       │
-│  │  ChatEndpoints  │  │  AgentEndpoints │                       │
-│  └─────────────────┘  └─────────────────┘                       │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                    Orchestration Layer                           │
-│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
-│  │ TaskDecomposer  │  │  AgentRouter    │  │ ResultAggregator│ │
-│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                      Agent Layer                                 │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
-│  │ Research     │  │ Analysis     │  │ Writing              │  │
-│  │ Agent        │  │ Agent        │  │ Agent                │  │
-│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                      Plugin Layer                                │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
-│  │ WebSearch   │  │ Document    │  │ DataAnalysis│             │
-│  │ Plugin      │  │ Plugin      │  │ Plugin      │             │
-│  └─────────────┘  └─────────────┘  └─────────────┘             │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                    Infrastructure Layer                          │
-│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
-│  │  Azure OpenAI   │  │  Vector Store   │  │  Memory Store   │ │
-│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### 2.2 Fluxo de Dados
-
-```
-User Request
-    │
-    ▼
-┌─────────────────────────────────────────┐
-│           Task Decomposition            │
-│  "Compare cloud providers" →            │
-│  [Research AWS, Research Azure,         │
-│   Research GCP, Compare, Write Report]  │
-└─────────────────────────────────────────┘
-    │
-    ▼
-┌─────────────────────────────────────────┐
-│           Agent Execution               │
-│  Research Agent → findings[]            │
-│  Analysis Agent → insights              │
-│  Writing Agent → report                 │
-└─────────────────────────────────────────┘
-    │
-    ▼
-┌─────────────────────────────────────────┐
-│         Result Aggregation              │
-│  Combine outputs, format, validate      │
-└─────────────────────────────────────────┘
-    │
-    ▼
-Final Response
-```
-
-## 3. Requisitos Funcionais
-
-### 3.1 API
-
-| ID | Requisito |
-|----|-----------|
-| API-001 | Endpoint de chat para interação com usuário |
-| API-002 | Endpoint para consultar status de processamento |
-| API-003 | Endpoint para listar agentes disponíveis |
-| API-004 | Streaming de respostas (SSE) |
-| API-005 | Autenticação via API Key |
-
-### 3.2 Orchestrator
-
-| ID | Requisito |
-|----|-----------|
-| ORCH-001 | Análise de intenção do usuário |
-| ORCH-002 | Decomposição de tarefas complexas |
-| ORCH-003 | Roteamento para agentes especialistas |
-| ORCH-004 | Agregação de resultados |
-| ORCH-005 | Retry automático em falhas |
-| ORCH-006 | Timeout por subtarefa |
-
-### 3.3 Agentes
-
-| ID | Requisito |
-|----|-----------|
-| AGT-001 | Research Agent com acesso a web search |
-| AGT-002 | Research Agent com RAG (vector search) |
-| AGT-003 | Analysis Agent para comparações |
-| AGT-004 | Analysis Agent para insights |
-| AGT-005 | Writing Agent para relatórios |
-| AGT-006 | Writing Agent para sumários |
-
-### 3.4 Plugins
-
-| ID | Requisito |
-|----|-----------|
-| PLG-001 | WebSearch via Bing API |
-| PLG-002 | Document retrieval via vector store |
-| PLG-003 | Calculator para análises numéricas |
-| PLG-004 | Date/Time utilities |
-
-### 3.5 Memória
-
-| ID | Requisito |
-|----|-----------|
-| MEM-001 | Conversation memory por sessão |
-| MEM-002 | Semantic memory para contexto relevante |
-| MEM-003 | Persistência opcional em Cosmos DB |
-
-## 4. Requisitos Não-Funcionais
-
-### 4.1 Performance
-
-| ID | Requisito |
-|----|-----------|
-| PERF-001 | Response streaming para UX fluida |
-| PERF-002 | Timeout máximo de 60s por request |
-| PERF-003 | Execução paralela de subtarefas independentes |
-
-### 4.2 Custo
-
-| ID | Requisito |
-|----|-----------|
-| COST-001 | Limite de tokens por request configurável |
-| COST-002 | Uso de modelos menores para subtarefas simples |
-| COST-003 | Cache de resultados de pesquisa |
-| COST-004 | Tracking de uso de tokens |
-
-### 4.3 Segurança
-
-| ID | Requisito |
-|----|-----------|
-| SEC-001 | API Key authentication |
-| SEC-002 | Rate limiting por API key |
-| SEC-003 | Input sanitization |
-| SEC-004 | Output filtering (PII, harmful content) |
-
-## 5. Agentes em Detalhe
-
-### 5.1 Orchestrator Agent
-
-**System Prompt**:
-```
-You are an orchestrator agent responsible for coordinating other specialized agents.
-
-When you receive a user request:
-1. Analyze the intent and complexity
-2. Decompose into subtasks if needed
-3. Delegate to appropriate specialist agents
-4. Aggregate and format the final response
-
-Available agents:
-- research: For information gathering, web search, document retrieval
-- analysis: For data analysis, comparisons, insight generation
-- writing: For text generation, summaries, reports
-
-Respond with a plan in JSON format:
-{
-  "understanding": "Brief summary of user's request",
-  "subtasks": [
-    {"agent": "research", "task": "specific task description"},
-    {"agent": "analysis", "task": "specific task description"},
-    {"agent": "writing", "task": "specific task description"}
-  ]
-}
-```
-
-### 5.2 Research Agent
-
-**System Prompt**:
-```
-You are a research specialist agent. Your capabilities include:
-- Searching the web for current information
-- Retrieving relevant documents from the knowledge base
-- Summarizing and extracting key information
-
-When researching:
-1. Use web_search for current/recent information
-2. Use document_search for internal knowledge
-3. Synthesize findings into structured data
-
-Always cite your sources and indicate confidence level.
-```
-
-**Plugins**:
-- `web_search(query, max_results)`
-- `document_search(query, limit)`
-
-### 5.3 Analysis Agent
-
-**System Prompt**:
-```
-You are an analysis specialist agent. Your capabilities include:
-- Analyzing data and identifying patterns
-- Comparing options and alternatives
-- Generating insights and recommendations
-
-When analyzing:
-1. Structure the data clearly
-2. Apply appropriate analytical frameworks
-3. Provide evidence-based conclusions
-
-Be objective and highlight trade-offs.
-```
-
-**Plugins**:
-- `calculate(expression)`
-- `compare(items, criteria)`
-
-### 5.4 Writing Agent
-
-**System Prompt**:
-```
-You are a writing specialist agent. Your capabilities include:
-- Generating clear, well-structured text
-- Creating summaries and reports
-- Adapting tone and style for the audience
-
-When writing:
-1. Start with a clear structure
-2. Use appropriate formatting
-3. Be concise but comprehensive
-
-Match the requested format (report, summary, email, etc.).
-```
-
-## 6. Plugins em Detalhe
-
-### 6.1 WebSearchPlugin
-
-```csharp
-public class WebSearchPlugin
-{
-    private readonly BingSearchService _searchService;
-
-    [KernelFunction("web_search")]
-    [Description("Search the web for information on a topic")]
-    public async Task<SearchResults> SearchAsync(
-        [Description("The search query")] string query,
-        [Description("Maximum results to return")] int maxResults = 5)
-    {
-        var results = await _searchService.SearchAsync(query, maxResults);
-        return new SearchResults
-        {
-            Query = query,
-            Items = results.Select(r => new SearchResult
-            {
-                Title = r.Title,
-                Snippet = r.Snippet,
-                Url = r.Url
-            }).ToList()
-        };
-    }
-}
-```
-
-### 6.2 DocumentPlugin
-
-```csharp
-public class DocumentPlugin
-{
-    private readonly IVectorStore _vectorStore;
-    private readonly IEmbeddingService _embeddingService;
-
-    [KernelFunction("document_search")]
-    [Description("Search internal documents using semantic similarity")]
-    public async Task<IEnumerable<DocumentResult>> SearchDocumentsAsync(
-        [Description("The search query")] string query,
-        [Description("Maximum documents")] int limit = 3)
-    {
-        var embedding = await _embeddingService.GetEmbeddingAsync(query);
-        var documents = await _vectorStore.SearchAsync(embedding, limit);
-
-        return documents.Select(d => new DocumentResult
-        {
-            Title = d.Title,
-            Content = d.Content,
-            Score = d.Score,
-            Source = d.Source
-        });
-    }
-}
-```
-
-## 7. APIs
-
-### 7.1 Chat Endpoint
-
-```
-POST /api/chat
-Content-Type: application/json
-
-{
-  "message": "Compare AWS, Azure and GCP for a SaaS startup",
-  "sessionId": "optional-session-id",
-  "stream": true
-}
-
-Response (streaming):
-data: {"type": "thinking", "content": "Analyzing request..."}
-data: {"type": "agent", "agent": "research", "status": "started"}
-data: {"type": "agent", "agent": "research", "status": "completed"}
-data: {"type": "content", "content": "Based on my analysis..."}
-data: {"type": "done", "usage": {"tokens": 1234}}
-```
-
-### 7.2 Agents Endpoint
-
-```
-GET /api/agents
-
-Response:
-{
-  "agents": [
-    {
-      "id": "orchestrator",
-      "name": "Orchestrator Agent",
-      "description": "Coordinates other agents",
-      "capabilities": ["task_decomposition", "routing", "aggregation"]
-    },
-    {
-      "id": "research",
-      "name": "Research Agent",
-      "description": "Information gathering specialist",
-      "capabilities": ["web_search", "document_retrieval", "summarization"]
-    }
-  ]
-}
-```
-
-## 8. Modelo de Dados
-
-### 8.1 Conversation
-
-```csharp
-public class Conversation
-{
-    public string Id { get; set; }
-    public string UserId { get; set; }
-    public List<Message> Messages { get; set; }
-    public DateTime CreatedAt { get; set; }
-    public DateTime UpdatedAt { get; set; }
-}
-
-public class Message
-{
-    public string Id { get; set; }
-    public MessageRole Role { get; set; } // User, Assistant, System
-    public string Content { get; set; }
-    public AgentMetadata? AgentMetadata { get; set; }
-    public TokenUsage? Usage { get; set; }
-    public DateTime Timestamp { get; set; }
-}
-
-public class AgentMetadata
-{
-    public string AgentId { get; set; }
-    public List<string> PluginsUsed { get; set; }
-    public Dictionary<string, object> Metadata { get; set; }
-}
-```
-
-### 8.2 Agent Task
-
-```csharp
-public class AgentTask
-{
-    public string Id { get; set; }
-    public string AgentId { get; set; }
-    public string Description { get; set; }
-    public TaskStatus Status { get; set; }
-    public string? Input { get; set; }
-    public string? Output { get; set; }
-    public string? Error { get; set; }
-    public TimeSpan Duration { get; set; }
-    public TokenUsage Usage { get; set; }
-}
-
-public enum TaskStatus
-{
-    Pending,
-    Running,
-    Completed,
-    Failed
-}
-```
-
-## 9. Configuração
-
-### 9.1 Azure OpenAI
-
-```json
-{
-  "AzureOpenAI": {
-    "Endpoint": "https://{resource}.openai.azure.com/",
-    "ApiKey": "{key}",
-    "Deployments": {
-      "Chat": "gpt-4",
-      "ChatFast": "gpt-35-turbo",
-      "Embedding": "text-embedding-ada-002"
-    }
-  }
-}
-```
-
-### 9.2 Agent Configuration
-
-```json
-{
-  "Agents": {
-    "Orchestrator": {
-      "Model": "gpt-4",
-      "MaxTokens": 2000,
-      "Temperature": 0.3
-    },
-    "Research": {
-      "Model": "gpt-35-turbo",
-      "MaxTokens": 1500,
-      "Temperature": 0.5
-    },
-    "Analysis": {
-      "Model": "gpt-35-turbo",
-      "MaxTokens": 1500,
-      "Temperature": 0.3
-    },
-    "Writing": {
-      "Model": "gpt-4",
-      "MaxTokens": 3000,
-      "Temperature": 0.7
-    }
-  }
-}
-```
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/stacks/blazor-azure/.morph/examples/multi-agent/tasks.md

@@ -1,185 +0,0 @@
-# Multi-Agent System - Tasks
-
-## Fase 1: Setup do Projeto
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T001 | Criar solution e projetos | - | S |
-| T002 | Configurar packages (Semantic Kernel, etc) | T001 | S |
-| T003 | Configurar appsettings.json | T001 | S |
-| T004 | Criar estrutura de pastas | T001 | S |
-
-## Fase 2: Infrastructure Layer
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T005 | Implementar AzureOpenAIService | T002 | M |
-| T006 | Implementar EmbeddingService | T005 | M |
-| T007 | Implementar InMemoryVectorStore | T006 | M |
-| T008 | Implementar ConversationStore (in-memory) | T002 | M |
-
-## Fase 3: Plugin Layer
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T009 | Criar WebSearchPlugin | T005 | M |
-| T010 | Configurar Bing Search API | T009 | S |
-| T011 | Criar DocumentPlugin | T007 | M |
-| T012 | Criar CalculatorPlugin | T005 | S |
-| T013 | Criar DateTimePlugin | T005 | S |
-
-## Fase 4: Agent Layer - Base
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T014 | Criar BaseAgent abstract class | T005 | M |
-| T015 | Implementar AgentFactory | T014 | M |
-| T016 | Criar AgentContext (DI scope) | T015 | M |
-
-## Fase 5: Agent Layer - Agents
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T017 | Implementar ResearchAgent | T014, T009, T011 | L |
-| T018 | Implementar AnalysisAgent | T014, T012 | M |
-| T019 | Implementar WritingAgent | T014 | M |
-| T020 | Implementar OrchestratorAgent | T017-T019 | L |
-
-## Fase 6: Orchestration Layer
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T021 | Implementar TaskDecomposer | T020 | M |
-| T022 | Implementar AgentRouter | T015, T021 | M |
-| T023 | Implementar ResultAggregator | T020 | M |
-| T024 | Implementar Orchestrator | T021-T023 | L |
-
-## Fase 7: Memory Layer
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T025 | Implementar ConversationMemory | T008 | M |
-| T026 | Implementar SemanticMemory | T007 | M |
-| T027 | Integrar memória com Orchestrator | T024-T026 | M |
-
-## Fase 8: API Layer
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T028 | Configurar Program.cs base | T001 | M |
-| T029 | Criar ChatEndpoints | T024, T027 | M |
-| T030 | Implementar streaming (SSE) | T029 | M |
-| T031 | Criar AgentEndpoints | T015 | S |
-| T032 | Criar HealthEndpoints | T028 | S |
-| T033 | Configurar API Key auth | T028 | S |
-
-## Fase 9: Error Handling & Resilience
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T034 | Implementar retry policies | T024 | M |
-| T035 | Implementar circuit breaker | T034 | M |
-| T036 | Implementar timeout handling | T024 | M |
-| T037 | Criar error logging middleware | T028 | S |
-
-## Fase 10: Monitoring & Metrics
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T038 | Implementar token tracking | T005 | M |
-| T039 | Implementar usage metrics | T038 | M |
-| T040 | Criar cost estimation | T039 | S |
-| T041 | Integrar com App Insights | T028 | M |
-
-## Fase 11: Infrastructure (IaC)
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T042 | Criar main.bicep | - | M |
-| T043 | Configurar Container App | T042 | M |
-| T044 | Configurar Azure OpenAI (manual) | - | M |
-| T045 | Configurar Key Vault | T042 | S |
-| T046 | Configurar App Insights | T042 | S |
-
-## Fase 12: Testes
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T047 | Criar testes unitários - Plugins | T009-T013 | M |
-| T048 | Criar testes unitários - Agents | T017-T020 | M |
-| T049 | Criar testes integração - Orchestrator | T024 | L |
-| T050 | Criar testes E2E - API | T029-T032 | L |
-
-## Fase 13: Documentação
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T051 | Documentar APIs (OpenAPI) | T029-T032 | M |
-| T052 | Criar guia de extensibilidade | T014-T020 | M |
-| T053 | Criar exemplos de uso | T029 | M |
-
-## Checkpoints
-
-| Checkpoint | Após Tasks | Validação |
-|------------|------------|-----------|
-| CP1 | T004 | Projeto compila |
-| CP2 | T008 | Infrastructure funcionando |
-| CP3 | T013 | Plugins funcionando |
-| CP4 | T020 | Agents funcionando |
-| CP5 | T024 | Orchestrator funcionando |
-| CP6 | T027 | Memória integrada |
-| CP7 | T033 | API completa |
-| CP8 | T037 | Error handling completo |
-| CP9 | T041 | Monitoring ativo |
-| CP10 | T046 | IaC pronto |
-| CP11 | T053 | Projeto completo |
-
-## Legenda
-
-- **S** = Small (< 1h)
-- **M** = Medium (1-3h)
-- **L** = Large (3-8h)
-
-## Dependências Críticas
-
-```
-Azure OpenAI Setup (T044) - BLOQUEANTE para todos os testes reais
-
-T005 (LLM Service) → T014 (BaseAgent) → T017-T020 (Agents) → T024 (Orchestrator)
-           ↓
-       T006 (Embedding) → T007 (VectorStore) → T011 (DocumentPlugin)
-           ↓
-       T009 (WebSearch) → T017 (ResearchAgent)
-```
-
-## Ordem de Execução Recomendada
-
-### Fase Paralela 1 (Setup)
-- T001-T004 (Setup)
-- T042 (IaC base)
-
-### Fase Paralela 2 (Foundation)
-- T005-T008 (Infrastructure)
-- T044 (Azure OpenAI manual)
-
-### Fase Paralela 3 (Building Blocks)
-- T009-T013 (Plugins)
-- T014-T016 (Agent base)
-
-### Fase Sequencial 4 (Core)
-- T017-T020 (Agents)
-- T021-T024 (Orchestration)
-- T025-T027 (Memory)
-
-### Fase Paralela 5 (API + Supporting)
-- T028-T033 (API)
-- T034-T037 (Resilience)
-- T038-T041 (Monitoring)
-
-### Fase Final
-- T043-T046 (IaC complete)
-- T047-T053 (Tests + Docs)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*