@polymorphism-tech/morph-spec 2.2.0 → 2.4.0

package/content/.morph/templates/agent.cs

@@ -1,172 +1,163 @@
-// ============================================================
-// MS AGENT FRAMEWORK TEMPLATE
-// Generated by MORPH Framework
-// ============================================================
-
-using Microsoft.Extensions.Logging;
-using Microsoft.SemanticKernel;
-using System.Text.Json;
-
-namespace MyProject.Agents.{Feature}Analyzer;
-
-/// <summary>
-/// AI Agent for analyzing {Feature} data.
-/// Uses Semantic Kernel with Azure OpenAI (gpt-4o-mini by default).
-/// </summary>
-public class {Feature}AnalyzerAgent(
-    Kernel kernel,
-    ILogger<{Feature}AnalyzerAgent> logger) : I{Feature}AnalyzerAgent
-{
-    private const int MaxRetries = 3;
-    private static readonly TimeSpan[] RetryDelays =
-    {
-        TimeSpan.FromSeconds(1),
-        TimeSpan.FromSeconds(2),
-        TimeSpan.FromSeconds(4)
-    };
-
-    /// <inheritdoc />
-    public async Task<{Feature}AnalysisResult> AnalyzeAsync(
-        {Feature}Data data,
-        CancellationToken cancellationToken = default)
-    {
-        logger.LogInformation("Starting {Feature} analysis for: {Content}",
-            data.Content.Length > 100 ? data.Content[..100] + "..." : data.Content);
-
-        var prompt = BuildPrompt(data);
-
-        for (int attempt = 0; attempt < MaxRetries; attempt++)
-        {
-            try
-            {
-                var response = await kernel.InvokePromptAsync(
-                    prompt,
-                    cancellationToken: cancellationToken);
-
-                var result = ParseResponse(response.ToString());
-
-                logger.LogInformation(
-                    "Analysis completed. Confidence: {Confidence:P0}",
-                    result.ConfidenceScore);
-
-                return result;
-            }
-            catch (Exception ex) when (attempt < MaxRetries - 1)
-            {
-                logger.LogWarning(ex,
-                    "Analysis attempt {Attempt} failed, retrying...",
-                    attempt + 1);
-
-                await Task.Delay(RetryDelays[attempt], cancellationToken);
-            }
-        }
-
-        throw new {Feature}ProcessingException("Analysis failed after all retries");
-    }
-
-    #region Private Methods
-
-    private static string BuildPrompt({Feature}Data data)
-    {
-        return $"""
-            You are an expert analyst for {Feature} data.
-
-            Analyze the following data and provide insights:
-
-            <data>
-            {data.Content}
-            </data>
-
-            Provide your analysis in the following JSON format:
-            {{
-                "summary": "Brief summary of the analysis (1-2 sentences)",
-                "insights": ["insight 1", "insight 2", "insight 3"],
-                "recommendations": ["recommendation 1", "recommendation 2"],
-                "confidenceScore": 0.85
-            }}
-
-            Guidelines:
-            - Be concise and actionable
-            - Confidence score should be between 0 and 1
-            - Provide at least 2 insights
-            - Provide at least 1 recommendation
-            - Focus on practical, business-relevant observations
-
-            Respond ONLY with the JSON object, no additional text.
-            """;
-    }
-
-    private {Feature}AnalysisResult ParseResponse(string response)
-    {
-        try
-        {
-            // Clean up response (remove markdown code blocks if present)
-            var json = response
-                .Replace("```json", "")
-                .Replace("```", "")
-                .Trim();
-
-            var parsed = JsonSerializer.Deserialize<AnalysisResponse>(json,
-                new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
-
-            if (parsed is null)
-            {
-                throw new {Feature}ProcessingException("Failed to parse analysis response");
-            }
-
-            return new {Feature}AnalysisResult(
-                parsed.Summary ?? "Analysis completed",
-                parsed.Insights ?? new List<string>(),
-                parsed.Recommendations ?? new List<string>(),
-                parsed.ConfidenceScore
-            );
-        }
-        catch (JsonException ex)
-        {
-            logger.LogError(ex, "Failed to parse AI response: {Response}", response);
-            throw new {Feature}ProcessingException("Failed to parse analysis response", ex);
-        }
-    }
-
-    private class AnalysisResponse
-    {
-        public string? Summary { get; set; }
-        public List<string>? Insights { get; set; }
-        public List<string>? Recommendations { get; set; }
-        public double ConfidenceScore { get; set; }
-    }
-
-    #endregion
-}
-
-// ============================================================
-// DEPENDENCY INJECTION SETUP
-// ============================================================
-//
-// In Program.cs or a DI extension:
-//
-// public static IServiceCollection AddAgents(
-//     this IServiceCollection services,
-//     IConfiguration configuration)
-// {
-//     // Configure Semantic Kernel with Azure OpenAI
-//     var builder = Kernel.CreateBuilder();
-//
-//     builder.AddAzureOpenAIChatCompletion(
-//         deploymentName: "gpt-4o-mini",
-//         endpoint: configuration["AzureOpenAI:Endpoint"]!,
-//         apiKey: configuration["AzureOpenAI:ApiKey"]!);
-//
-//     // Or with Managed Identity (preferred):
-//     // builder.AddAzureOpenAIChatCompletion(
-//     //     deploymentName: "gpt-4o-mini",
-//     //     endpoint: configuration["AzureOpenAI:Endpoint"]!,
-//     //     credentials: new DefaultAzureCredential());
-//
-//     services.AddSingleton(builder.Build());
-//     services.AddScoped<I{Feature}AnalyzerAgent, {Feature}AnalyzerAgent>();
-//
-//     return services;
-// }
-//
-// ============================================================
+// ============================================================
+// MICROSOFT AGENT FRAMEWORK TEMPLATE
+// Generated by MORPH Framework
+// ============================================================
+
+using System.ComponentModel;
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
+
+namespace MyProject.Agents.{Feature};
+
+/// <summary>
+/// AI Agent for analyzing {Feature} data.
+/// Uses Microsoft Agent Framework with IChatClient (gpt-4o-mini by default).
+/// </summary>
+public class {Feature}AnalyzerAgent(
+    IChatClient chatClient,
+    ILogger<{Feature}AnalyzerAgent> logger) : I{Feature}AnalyzerAgent
+{
+    /// <inheritdoc />
+    public async Task<{Feature}AnalysisResult> AnalyzeAsync(
+        {Feature}Data data,
+        CancellationToken cancellationToken = default)
+    {
+        logger.LogInformation("Starting {Feature} analysis for: {Content}",
+            data.Content.Length > 100 ? data.Content[..100] + "..." : data.Content);
+
+        var agent = new ChatClientAgent(
+            chatClient,
+            new ChatClientAgentOptions
+            {
+                Name = "{Feature}Analyzer",
+                Instructions = """
+                    You are an expert analyst for {Feature} data.
+
+                    Analyze the provided data and return a JSON object with:
+                    - summary: Brief summary (1-2 sentences)
+                    - insights: Array of at least 2 insights
+                    - recommendations: Array of at least 1 recommendation
+                    - confidenceScore: Number between 0 and 1
+
+                    Respond ONLY with valid JSON, no additional text.
+                    """,
+                ChatOptions = new ChatOptions
+                {
+                    Tools =
+                    [
+                        AIFunctionFactory.Create(GetContextAsync),
+                        AIFunctionFactory.Create(GetMetricsAsync)
+                    ]
+                }
+            });
+
+        var response = await agent.RunAsync(
+            $"Analyze this data:\n{data.Content}",
+            cancellationToken: cancellationToken);
+
+        var result = ParseResponse(response.Text);
+
+        logger.LogInformation(
+            "Analysis completed. Confidence: {Confidence:P0}",
+            result.ConfidenceScore);
+
+        return result;
+    }
+
+    #region Tools
+
+    [Description("Gets additional context for the analysis")]
+    private async Task<string> GetContextAsync(
+        [Description("What context is needed")] string query,
+        CancellationToken ct = default)
+    {
+        // TODO: Implement context retrieval (e.g., from database or search)
+        await Task.CompletedTask;
+        return $"Context for: {query}";
+    }
+
+    [Description("Gets relevant metrics for the analysis")]
+    private async Task<string> GetMetricsAsync(
+        [Description("Metric type to retrieve")] string metricType,
+        CancellationToken ct = default)
+    {
+        // TODO: Implement metrics retrieval
+        await Task.CompletedTask;
+        return $"Metrics for: {metricType}";
+    }
+
+    #endregion
+
+    #region Response Parsing
+
+    private {Feature}AnalysisResult ParseResponse(string response)
+    {
+        try
+        {
+            var json = response
+                .Replace("```json", "")
+                .Replace("```", "")
+                .Trim();
+
+            var parsed = JsonSerializer.Deserialize<AnalysisResponse>(json,
+                new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
+
+            if (parsed is null)
+                throw new {Feature}ProcessingException("Failed to parse analysis response");
+
+            return new {Feature}AnalysisResult(
+                parsed.Summary ?? "Analysis completed",
+                parsed.Insights ?? [],
+                parsed.Recommendations ?? [],
+                parsed.ConfidenceScore);
+        }
+        catch (JsonException ex)
+        {
+            logger.LogError(ex, "Failed to parse AI response: {Response}", response);
+            throw new {Feature}ProcessingException("Failed to parse analysis response", ex);
+        }
+    }
+
+    private class AnalysisResponse
+    {
+        public string? Summary { get; set; }
+        public List<string>? Insights { get; set; }
+        public List<string>? Recommendations { get; set; }
+        public double ConfidenceScore { get; set; }
+    }
+
+    #endregion
+}
+
+// ============================================================
+// DEPENDENCY INJECTION SETUP
+// ============================================================
+//
+// In Program.cs:
+//
+// // Register IChatClient (Azure OpenAI with Managed Identity)
+// builder.Services.AddSingleton<IChatClient>(sp =>
+// {
+//     var cfg = sp.GetRequiredService<IConfiguration>();
+//     return new AzureOpenAIClient(
+//             new Uri(cfg["AzureOpenAI:Endpoint"]!),
+//             new DefaultAzureCredential())
+//         .GetChatClient(cfg["AzureOpenAI:DeploymentName"] ?? "gpt-4o-mini")
+//         .AsIChatClient();
+// });
+//
+// // Option A: Register as scoped service
+// builder.Services.AddScoped<I{Feature}AnalyzerAgent, {Feature}AnalyzerAgent>();
+//
+// // Option B: Register as keyed agent (recommended for multiple agents)
+// builder.AddAIAgent("{Feature}Analyzer", (sp, key) =>
+// {
+//     var chatClient = sp.GetRequiredService<IChatClient>();
+//     return new ChatClientAgent(chatClient,
+//         name: key,
+//         instructions: "You are an expert {Feature} analyst.");
+// });
+//
+// ============================================================

package/content/.morph/templates/clarify-questions.md

@@ -0,0 +1,159 @@
+# Checklist de Clarificação - {{FEATURE_NAME_TITLE}}
+
+> Template para FASE 3: CLARIFY
+> Use este checklist para identificar ambiguidades e fazer perguntas estruturadas
+
+---
+
+## 🎯 Contexto da Feature
+
+**Feature:** {{FEATURE_NAME}}
+**Fase atual:** CLARIFY
+**Data:** {{DATE}}
+
+---
+
+## 📋 Checklist de Clarificação Padrão
+
+### 1. Fluxo de Usuário
+
+- [ ] Existe fluxo gratuito vs pago?
+- [ ] O que acontece em edge cases (erro, timeout, dados inválidos)?
+- [ ] Qual o fluxo de primeiro acesso (onboarding)?
+- [ ] Existem diferentes tipos de usuário com permissões diferentes?
+- [ ] O que acontece se o usuário cancelar no meio do processo?
+
+**Perguntas específicas:**
+1. _[Adicionar pergunta específica da feature]_
+2. _[Adicionar pergunta específica da feature]_
+
+---
+
+### 2. Integrações Externas
+
+- [ ] Quais campos são obrigatórios para cada API externa?
+- [ ] Há fallbacks se a API externa falhar?
+- [ ] Qual o timeout aceitável para chamadas externas?
+- [ ] Como tratar rate limiting?
+- [ ] Precisa de webhook para eventos da API?
+
+**Perguntas específicas:**
+1. _[Adicionar pergunta sobre integração]_
+2. _[Adicionar pergunta sobre integração]_
+
+---
+
+### 3. Dados e Persistência
+
+- [ ] Qual a política de retenção de dados?
+- [ ] Precisa de soft delete ou hard delete?
+- [ ] Quais dados são sensíveis e precisam de criptografia?
+- [ ] Precisa de histórico/auditoria de alterações?
+- [ ] Qual o volume esperado de dados?
+
+**Perguntas específicas:**
+1. _[Adicionar pergunta sobre dados]_
+2. _[Adicionar pergunta sobre dados]_
+
+---
+
+### 4. Performance e Escalabilidade
+
+- [ ] Qual o SLA esperado (tempo de resposta)?
+- [ ] Precisa de cache? Se sim, qual estratégia?
+- [ ] Quantos usuários simultâneos são esperados?
+- [ ] Existem operações que podem ser assíncronas?
+- [ ] Precisa de paginação para listas grandes?
+
+**Perguntas específicas:**
+1. _[Adicionar pergunta sobre performance]_
+2. _[Adicionar pergunta sobre performance]_
+
+---
+
+### 5. Segurança e Autorização
+
+- [ ] Quem pode acessar esta funcionalidade?
+- [ ] Existem diferentes níveis de permissão?
+- [ ] Precisa de validação de ownership (usuário só vê seus dados)?
+- [ ] Existem dados que não devem ser expostos em logs?
+- [ ] Precisa de CAPTCHA ou proteção contra bots?
+
+**Perguntas específicas:**
+1. _[Adicionar pergunta sobre segurança]_
+2. _[Adicionar pergunta sobre segurança]_
+
+---
+
+### 6. UI/UX (se aplicável)
+
+- [ ] Qual o estado inicial da tela (vazia, loading, dados)?
+- [ ] O que mostrar quando não há dados?
+- [ ] Quais mensagens de erro/sucesso exibir?
+- [ ] Precisa de confirmação antes de ações destrutivas?
+- [ ] Como tratar formulários muito longos (wizard, seções)?
+
+**Perguntas específicas:**
+1. _[Adicionar pergunta sobre UI]_
+2. _[Adicionar pergunta sobre UI]_
+
+---
+
+### 7. Notificações e Comunicação
+
+- [ ] Precisa enviar email/SMS/push em algum momento?
+- [ ] Quais eventos disparam notificações?
+- [ ] O usuário pode configurar preferências de notificação?
+- [ ] Precisa de notificações em tempo real (SignalR)?
+
+**Perguntas específicas:**
+1. _[Adicionar pergunta sobre notificações]_
+
+---
+
+### 8. Regras de Negócio
+
+- [ ] Existem validações específicas do domínio?
+- [ ] Existem limites (máximo de itens, tamanho de arquivo, etc)?
+- [ ] Existem estados/transições de status?
+- [ ] Existem cálculos ou fórmulas específicas?
+- [ ] Existem regras de agendamento (cron, jobs)?
+
+**Perguntas específicas:**
+1. _[Adicionar pergunta sobre regras de negócio]_
+2. _[Adicionar pergunta sobre regras de negócio]_
+
+---
+
+## 📝 Respostas Coletadas
+
+> Preencher com as respostas do usuário
+
+| # | Pergunta | Resposta | Impacto no Spec |
+|---|----------|----------|-----------------|
+| 1 | | | |
+| 2 | | | |
+| 3 | | | |
+
+---
+
+## ✅ Ações Resultantes
+
+- [ ] Atualizar spec.md com clarificações
+- [ ] Adicionar edge cases identificados
+- [ ] Atualizar contracts.cs se necessário
+- [ ] Documentar decisões em decisions.md
+
+---
+
+## 🎯 Status
+
+- **Total de perguntas:** _X_
+- **Perguntas respondidas:** _Y_
+- **Pendentes:** _Z_
+
+**Pronto para avançar para FASE 4: TASKS?** [ ] Sim [ ] Não
+
+---
+
+_Gerado por MORPH-SPEC Framework_