@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

package/framework/templates/code/dotnet/abstractions/result.cs

@@ -63,10 +63,8 @@ namespace {{pascalCase PROJECT_NAME}}.Abstractions
             ? _value!
             : throw new InvalidOperationException("The value of a failure result can not be accessed.");
 
-        // ✅ SUCCESS implicit conversion
         public static implicit operator Result<TValue>(TValue? value) => Create(value);
 
-        // ✅ ADD THIS (Failure implicit conversion)
         public static implicit operator Result<TValue>(Error error)
             => Failure<TValue>(error);
     }

package/framework/templates/code/dotnet/ai-agents/AgentBootstrap.cs.template

@@ -1,39 +1,26 @@
-// TEMPLATE: AgentBootstrap.cs
-// PURPOSE: Extension method to register ModelRegistry + a default agent in DI.
-// READS STANDARDS: ai-agents-setup, ai-agents-providers-model-registry
-// PLACEHOLDERS:
-//   {{PROJECT_NAMESPACE}}     — root namespace of the project
-//   {{DEFAULT_AGENT_NAME}}    — first agent name (e.g., "DefaultAssistant")
-//   {{DEFAULT_INSTRUCTIONS}}  — system prompt for default agent (1 line)
-// LAST-VERIFIED: 2026-05-19 (MAF 1.0 GA)
-
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.DependencyInjection;
-
-namespace {{PROJECT_NAMESPACE}}.AI;
-
-public static class AgentBootstrap
-{
-    /// <summary>
-    /// Register ModelRegistry (singleton) and the default agent.
-    /// Additional agents register themselves via builder.AddAIAgent("Name", ...).
-    /// </summary>
-    public static WebApplicationBuilder AddMafAgents(this WebApplicationBuilder builder)
-    {
-        // Single source of truth for model selection
-        builder.Services.AddSingleton<ModelRegistry>();
-
-        // Default agent — uses the default alias from model-registry.json
-        builder.Services.AddKeyedSingleton<AIAgent>("{{DEFAULT_AGENT_NAME}}", (sp, _) =>
-        {
-            var registry = sp.GetRequiredService<ModelRegistry>();
-            var chatClient = registry.GetChatClient(registry.DefaultAlias);
-            return chatClient.AsAIAgent(
-                instructions: "{{DEFAULT_INSTRUCTIONS}}",
-                name: "{{DEFAULT_AGENT_NAME}}");
-        });
-
-        return builder;
-    }
-}
+// READS STANDARDS: ai-agents-setup, ai-agents-providers-model-registry
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+public static class AgentBootstrap
+{
+    public static WebApplicationBuilder AddMafAgents(this WebApplicationBuilder builder)
+    {
+        builder.Services.AddSingleton<ModelRegistry>();
+
+        builder.Services.AddKeyedSingleton<AIAgent>("{{DEFAULT_AGENT_NAME}}", (sp, _) =>
+        {
+            var registry = sp.GetRequiredService<ModelRegistry>();
+            var chatClient = registry.GetChatClient(registry.DefaultAlias);
+            return chatClient.AsAIAgent(
+                instructions: "{{DEFAULT_INSTRUCTIONS}}",
+                name: "{{DEFAULT_AGENT_NAME}}");
+        });
+
+        return builder;
+    }
+}

package/framework/templates/code/dotnet/ai-agents/EmbeddingService.cs.template

@@ -1,68 +1,28 @@
-// TEMPLATE: EmbeddingService.cs
-// PURPOSE: Generates embeddings for RAG indexing and query, via IEmbeddingGenerator.
-// READS STANDARD: ai-agents-rag-custom-pgvector
-// PLACEHOLDERS:
-//   {{PROJECT_NAMESPACE}}  — root namespace of the project (e.g., MyProject)
-// LAST-VERIFIED: 2026-05-19
-//
-// IMPORTANT — IEmbeddingGenerator registration (in Program.cs of the project):
-//   The project must register IEmbeddingGenerator<string, Embedding<float>> in DI.
-//   Example for OpenAI text-embedding-3-small (the canonical "embeddings" alias):
-//
-//   builder.Services.AddSingleton<IEmbeddingGenerator<string, Embedding<float>>>(sp =>
-//   {
-//       var cfg = sp.GetRequiredService<IConfiguration>();
-//       return new OpenAIClient(cfg["OpenAI:ApiKey"]!)
-//           .GetEmbeddingClient("text-embedding-3-small")
-//           .AsIEmbeddingGenerator();
-//   });
-//
-//   For other providers (Google, Anthropic, Ollama) adapt the client construction —
-//   see ai-agents-providers-model-registry §providers for verified SDKs.
-
-using Microsoft.Extensions.AI;
-
-namespace {{PROJECT_NAMESPACE}}.AI;
-
-/// <summary>
-/// Generates text embeddings for RAG indexing and query.
-/// Wraps <see cref="IEmbeddingGenerator{TInput,TEmbedding}"/> so the rest of the project
-/// does not take a direct dependency on the underlying provider SDK.
-/// </summary>
-public sealed class EmbeddingService(IEmbeddingGenerator<string, Embedding<float>> generator)
-{
-    /// <summary>
-    /// Generates an embedding vector for a single text (used at query time).
-    /// </summary>
-    /// <param name="text">The text to embed.</param>
-    /// <param name="ct">Cancellation token.</param>
-    /// <returns>The embedding vector as <see cref="ReadOnlyMemory{T}"/> of float.</returns>
-    public async Task<ReadOnlyMemory<float>> EmbedAsync(
-        string text,
-        CancellationToken ct = default)
-    {
-        // GenerateAsync is the verified API: returns GeneratedEmbeddings<Embedding<float>>.
-        // Each Embedding<float>.Vector is a ReadOnlyMemory<float>.
-        // Source: Microsoft Learn — microsoft-extensions-ai (verified 2026-05-19).
-        GeneratedEmbeddings<Embedding<float>> result =
-            await generator.GenerateAsync([text], cancellationToken: ct);
-
-        return result[0].Vector;
-    }
-
-    /// <summary>
-    /// Generates embedding vectors for a batch of texts (used during document indexing).
-    /// </summary>
-    /// <param name="texts">The texts to embed.</param>
-    /// <param name="ct">Cancellation token.</param>
-    /// <returns>Embedding vectors in the same order as the input texts.</returns>
-    public async Task<IReadOnlyList<ReadOnlyMemory<float>>> EmbedBatchAsync(
-        IReadOnlyList<string> texts,
-        CancellationToken ct = default)
-    {
-        GeneratedEmbeddings<Embedding<float>> result =
-            await generator.GenerateAsync(texts, cancellationToken: ct);
-
-        return [.. result.Select(e => e.Vector)];
-    }
-}
+// READS STANDARD: ai-agents-rag-custom-pgvector
+
+using Microsoft.Extensions.AI;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+public sealed class EmbeddingService(IEmbeddingGenerator<string, Embedding<float>> generator)
+{
+    public async Task<ReadOnlyMemory<float>> EmbedAsync(
+        string text,
+        CancellationToken ct = default)
+    {
+        GeneratedEmbeddings<Embedding<float>> result =
+            await generator.GenerateAsync([text], cancellationToken: ct);
+
+        return result[0].Vector;
+    }
+
+    public async Task<IReadOnlyList<ReadOnlyMemory<float>>> EmbedBatchAsync(
+        IReadOnlyList<string> texts,
+        CancellationToken ct = default)
+    {
+        GeneratedEmbeddings<Embedding<float>> result =
+            await generator.GenerateAsync(texts, cancellationToken: ct);
+
+        return [.. result.Select(e => e.Vector)];
+    }
+}

package/framework/templates/code/dotnet/ai-agents/ModelRegistry.cs.template

@@ -1,117 +1,99 @@
-// TEMPLATE: ModelRegistry.cs
-// PURPOSE: Reads config/model-registry.json at startup and exposes IChatClient by alias.
-// READS STANDARD: ai-agents-providers-model-registry
-// PROVIDERS: openai + ollama implemented below. To add google / anthropic / azure-openai,
-//            follow the same pattern — see ai-agents-providers-model-registry §providers
-//            (that standard is the source of truth for provider SDKs).
-// PLACEHOLDERS:
-//   {{PROJECT_NAMESPACE}}     — root namespace of the project (e.g., MyProject)
-//   {{REGISTRY_PATH}}         — path to model-registry.json relative to app base
-//                              (default: "config/model-registry.json")
-// LAST-VERIFIED: 2026-05-19 (MAF 1.0 GA, OpenAI SDK 2.x)
-
-using System.ClientModel;
-using System.Text.Json;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.Configuration;
-using Microsoft.Extensions.Hosting;
-using OpenAI;
-using OpenAI.Chat;
-
-namespace {{PROJECT_NAMESPACE}}.AI;
-
-public sealed class ModelRegistry
-{
-    private readonly Dictionary<string, ModelAlias> _aliases;
-    private readonly Dictionary<string, IChatClient> _chatClientCache = new();
-    private readonly IConfiguration _config;
-    private readonly object _lock = new();
-
-    public ModelRegistry(IConfiguration config, IHostEnvironment env)
-    {
-        _config = config;
-        var path = Path.Combine(env.ContentRootPath, "{{REGISTRY_PATH}}");
-        if (!File.Exists(path))
-            throw new InvalidOperationException($"Model registry not found at {path}");
-
-        var json = File.ReadAllText(path);
-        var doc = JsonSerializer.Deserialize<RegistryDocument>(json, JsonOpts)
-            ?? throw new InvalidOperationException("Empty model-registry.json");
-        _aliases = doc.Aliases;
-        DefaultAlias = doc.DefaultAlias;
-    }
-
-    /// <summary>The alias used when a caller does not specify one (from model-registry.json).</summary>
-    public string DefaultAlias { get; }
-
-    public IChatClient GetChatClient(string alias)
-    {
-        if (!_aliases.TryGetValue(alias, out var spec))
-            throw new InvalidOperationException($"Unknown model alias: {alias}");
-
-        lock (_lock)
-        {
-            if (_chatClientCache.TryGetValue(alias, out var cached))
-                return cached;
-
-            var client = spec.Provider switch
-            {
-                "openai" => BuildOpenAI(spec),
-                "ollama" => BuildOllama(spec),
-                // To add a provider, implement Build<Provider>(spec) following the
-                // pattern below and add a case here. Confirm the NuGet SDK first —
-                // see ai-agents-providers-model-registry §providers.
-                //   "google"       => BuildGoogle(spec),
-                //   "anthropic"    => BuildAnthropic(spec),
-                //   "azure-openai" => BuildAzureOpenAI(spec),
-                _ => throw new NotSupportedException(
-                    $"Provider '{spec.Provider}' has no branch. Add it following " +
-                    $"the pattern in ai-agents-providers-model-registry.")
-            };
-
-            _chatClientCache[alias] = client;
-            return client;
-        }
-    }
-
-    private IChatClient BuildOpenAI(ModelAlias spec)
-    {
-        var apiKey = _config["OpenAI:ApiKey"]
-            ?? throw new InvalidOperationException("OpenAI:ApiKey not configured");
-        return new ChatClient(spec.Model, apiKey).AsIChatClient();
-    }
-
-    private IChatClient BuildOllama(ModelAlias spec)
-    {
-        // Ollama exposes an OpenAI-compatible endpoint — reuse the OpenAI ChatClient.
-        var endpoint = spec.Options?.GetValueOrDefault("endpoint")?.ToString()
-            ?? "http://localhost:11434/v1";
-        return new ChatClient(
-                spec.Model,
-                new ApiKeyCredential("ollama"),  // any non-empty string
-                new OpenAIClientOptions { Endpoint = new Uri(endpoint) })
-            .AsIChatClient();
-    }
-
-    private static readonly JsonSerializerOptions JsonOpts = new()
-    {
-        PropertyNameCaseInsensitive = true,
-        ReadCommentHandling = JsonCommentHandling.Skip,
-        AllowTrailingCommas = true
-    };
-
-    // NOTE: Fallback is parsed but not yet acted on. Implementing automatic
-    // provider failover (retry on rate-limit/outage) is reserved for a later wave.
-    private sealed record RegistryDocument(
-        string Version,
-        string DefaultAlias,
-        Dictionary<string, ModelAlias> Aliases,
-        Dictionary<string, string>? Fallback
-    );
-
-    public sealed record ModelAlias(
-        string Provider,
-        string Model,
-        Dictionary<string, object>? Options
-    );
-}
+// READS STANDARD: ai-agents-providers-model-registry
+
+using System.ClientModel;
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Hosting;
+using OpenAI;
+using OpenAI.Chat;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+public sealed class ModelRegistry
+{
+    private readonly Dictionary<string, ModelAlias> _aliases;
+    private readonly Dictionary<string, IChatClient> _chatClientCache = new();
+    private readonly IConfiguration _config;
+    private readonly object _lock = new();
+
+    public ModelRegistry(IConfiguration config, IHostEnvironment env)
+    {
+        _config = config;
+        var path = Path.Combine(env.ContentRootPath, "{{REGISTRY_PATH}}");
+        if (!File.Exists(path))
+            throw new InvalidOperationException($"Model registry not found at {path}");
+
+        var json = File.ReadAllText(path);
+        var doc = JsonSerializer.Deserialize<RegistryDocument>(json, JsonOpts)
+            ?? throw new InvalidOperationException("Empty model-registry.json");
+        _aliases = doc.Aliases;
+        DefaultAlias = doc.DefaultAlias;
+    }
+
+    public string DefaultAlias { get; }
+
+    public IChatClient GetChatClient(string alias)
+    {
+        if (!_aliases.TryGetValue(alias, out var spec))
+            throw new InvalidOperationException($"Unknown model alias: {alias}");
+
+        lock (_lock)
+        {
+            if (_chatClientCache.TryGetValue(alias, out var cached))
+                return cached;
+
+            var client = spec.Provider switch
+            {
+                "openai" => BuildOpenAI(spec),
+                "ollama" => BuildOllama(spec),
+                _ => throw new NotSupportedException(
+                    $"Provider '{spec.Provider}' has no branch. Add it following " +
+                    $"the pattern in ai-agents-providers-model-registry.")
+            };
+
+            _chatClientCache[alias] = client;
+            return client;
+        }
+    }
+
+    private IChatClient BuildOpenAI(ModelAlias spec)
+    {
+        var apiKey = _config["OpenAI:ApiKey"]
+            ?? throw new InvalidOperationException("OpenAI:ApiKey not configured");
+        return new ChatClient(spec.Model, apiKey).AsIChatClient();
+    }
+
+    private IChatClient BuildOllama(ModelAlias spec)
+    {
+        var endpoint = spec.Options?.GetValueOrDefault("endpoint")?.ToString()
+            ?? "http://localhost:11434/v1";
+        // Ollama speaks the OpenAI protocol and ignores the key, but the SDK rejects an empty one.
+        return new ChatClient(
+                spec.Model,
+                new ApiKeyCredential("ollama"),
+                new OpenAIClientOptions { Endpoint = new Uri(endpoint) })
+            .AsIChatClient();
+    }
+
+    private static readonly JsonSerializerOptions JsonOpts = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        ReadCommentHandling = JsonCommentHandling.Skip,
+        AllowTrailingCommas = true
+    };
+
+    // Fallback is parsed but nothing fails over to it yet.
+    private sealed record RegistryDocument(
+        string Version,
+        string DefaultAlias,
+        Dictionary<string, ModelAlias> Aliases,
+        Dictionary<string, string>? Fallback
+    );
+
+    public sealed record ModelAlias(
+        string Provider,
+        string Model,
+        Dictionary<string, object>? Options
+    );
+}

package/framework/templates/code/dotnet/ai-agents/PromptRepository.cs.template

@@ -1,24 +1,11 @@
-// TEMPLATE: PromptRepository.cs
-// PURPOSE: Loads agent system prompts from the agent_prompts table, with in-memory caching.
 // READS STANDARD: ai-agents-prompt-sources
-// PLACEHOLDERS:
-//   {{PROJECT_NAMESPACE}}  — root namespace of the project
-// LAST-VERIFIED: 2026-05-19
 
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Caching.Memory;
 
 namespace {{PROJECT_NAMESPACE}}.AI;
 
-// ---------------------------------------------------------------------------
-// Entity — map this to the agent_prompts table (EF Core convention mapping).
-// Alternatively, configure via Fluent API in your DbContext.OnModelCreating.
-// ---------------------------------------------------------------------------
-
-/// <summary>
-/// EF Core entity for the agent_prompts table.
-/// Content is immutable once written — use INSERT + flip is_active for versioning.
-/// </summary>
+// Rows are never updated: a new version is an INSERT plus flipping is_active.
 public sealed class AgentPrompt
 {
     public Guid Id { get; init; } = Guid.CreateVersion7();
@@ -29,41 +16,12 @@ public sealed class AgentPrompt
     public DateTimeOffset CreatedAt { get; init; } = DateTimeOffset.UtcNow;
 }
 
-// ---------------------------------------------------------------------------
-// Interface
-// ---------------------------------------------------------------------------
-
-/// <summary>
-/// Provides the active system-prompt content for a named agent.
-/// </summary>
 public interface IPromptRepository
 {
-    /// <summary>
-    /// Returns the content of the currently active prompt for <paramref name="agentKey"/>.
-    /// </summary>
-    /// <exception cref="InvalidOperationException">
-    /// Thrown when no row with <c>is_active = true</c> exists for <paramref name="agentKey"/>.
-    /// </exception>
     Task<string> GetActivePromptAsync(string agentKey, CancellationToken ct = default);
 }
 
-// ---------------------------------------------------------------------------
-// Implementation
-// ---------------------------------------------------------------------------
-
-// NOTE: Register in Program.cs (or a bootstrap extension):
-//   builder.Services.AddMemoryCache();
-//   builder.Services.AddScoped<IPromptRepository, PromptRepository>();
-//
-// The DbContext must expose:  public DbSet<AgentPrompt> AgentPrompts { get; set; }
-// Replace YourDbContext below with the actual DbContext type of the project.
-
-/// <summary>
-/// Reads the active agent prompt from the database with an in-memory cache
-/// (default TTL: 5 minutes sliding). Cache invalidation is time-based;
-/// for immediate invalidation after a prompt update call
-/// <c>IMemoryCache.Remove($"agent_prompt:{agentKey}")</c>.
-/// </summary>
+// Replace YourDbContext with the project's DbContext (it needs DbSet<AgentPrompt> AgentPrompts).
 public sealed class PromptRepository(YourDbContext db, IMemoryCache cache) : IPromptRepository
 {
     private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(5);

package/framework/templates/code/dotnet/ai-agents/ResilientToolMiddleware.cs.template

@@ -1,61 +1,40 @@
-// TEMPLATE: ResilientToolMiddleware.cs
-// PURPOSE: Function-calling middleware — retry/rate-limit resilience + anti-hallucination arg validation.
-// READS STANDARD: ai-agents-middleware-patterns
-// PLACEHOLDERS:
-//   {{PROJECT_NAMESPACE}}  — root namespace of the project
-// LAST-VERIFIED: 2026-05-19
-
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-namespace {{PROJECT_NAMESPACE}}.AI;
-
-/// <summary>
-/// Function-calling middleware that provides resilience (rate-limit + timeout handling)
-/// and anti-hallucination argument validation.
-///
-/// Registration:
-///   agent.AsBuilder().Use(ResilientToolMiddleware.Handle).Build();
-/// </summary>
-public static class ResilientToolMiddleware
-{
-    public static async ValueTask<object?> Handle(
-        AIAgent agent,
-        FunctionInvocationContext context,
-        Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
-        CancellationToken cancellationToken)
-    {
-        // ─── Anti-hallucination: validate LLM-generated arguments BEFORE calling the tool ───
-        // If an argument is malformed, return a descriptive error string — the agent will
-        // self-correct on the next iteration without needing an external retry.
-        //
-        // Example: validate 'date' is ISO 8601
-        if (context.Arguments.TryGetValue("date", out var dateArg)
-            && !DateTime.TryParse(dateArg?.ToString(), out _))
-        {
-            return $"Invalid date format for '{context.Function.Name}'. Expected ISO 8601 (e.g. 2026-01-31).";
-        }
-        //
-        // Add additional argument validations here following the same pattern:
-        //   if (context.Arguments.TryGetValue("argName", out var val) && <invalid condition>)
-        //       return $"Descriptive error for '{context.Function.Name}': <what was wrong>.";
-
-        // ─── Resilience: execute tool and handle failures ───
-        try
-        {
-            return await next(context, cancellationToken);
-        }
-        catch (HttpRequestException ex) when (ex.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
-        {
-            return "Service is temporarily busy. Please try again in a moment.";
-        }
-        catch (TimeoutException)
-        {
-            return $"Tool '{context.Function.Name}' timed out. Try a simpler query.";
-        }
-        catch (Exception ex)
-        {
-            return $"Error in {context.Function.Name}: {ex.Message}";
-        }
-    }
-}
+// READS STANDARD: ai-agents-middleware-patterns
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+public static class ResilientToolMiddleware
+{
+    public static async ValueTask<object?> Handle(
+        AIAgent agent,
+        FunctionInvocationContext context,
+        Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
+        CancellationToken cancellationToken)
+    {
+        // Return the error as text, not an exception: the agent reads it and fixes the arguments on its next turn.
+        if (context.Arguments.TryGetValue("date", out var dateArg)
+            && !DateTime.TryParse(dateArg?.ToString(), out _))
+        {
+            return $"Invalid date format for '{context.Function.Name}'. Expected ISO 8601 (e.g. 2026-01-31).";
+        }
+
+        try
+        {
+            return await next(context, cancellationToken);
+        }
+        catch (HttpRequestException ex) when (ex.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
+        {
+            return "Service is temporarily busy. Please try again in a moment.";
+        }
+        catch (TimeoutException)
+        {
+            return $"Tool '{context.Function.Name}' timed out. Try a simpler query.";
+        }
+        catch (Exception ex)
+        {
+            return $"Error in {context.Function.Name}: {ex.Message}";
+        }
+    }
+}