@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

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}";
+        }
+    }
+}

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

@@ -1,107 +1,54 @@
-// TEMPLATE: VectorSearchTool.cs
-// PURPOSE: A typed MAF tool that retrieves relevant chunks from the pgvector knowledge base.
-// READS STANDARD: ai-agents-rag-custom-pgvector
-// PLACEHOLDERS:
-//   {{PROJECT_NAMESPACE}}  — root namespace of the project (e.g., MyProject)
-// LAST-VERIFIED: 2026-05-19
-//
-// SECURITY NOTE — tenant_id:
-//   tenant_id is resolved from the injected ITenantContext (or equivalent auth accessor),
-//   NEVER from a tool parameter visible to the LLM. A model-facing tenant parameter would
-//   allow prompt-injection to cross tenant boundaries.
-//
-// NPGSQL + PGVECTOR PARAMETER BINDING:
-//   This template uses NpgsqlDataSource (raw SQL) for the cosine-distance query.
-//   The project must call dataSourceBuilder.UseVector() before building the data source
-//   so Npgsql can map the vector type — see infrastructure-neon-pgvector.
-//
-//   // VERIFY: The exact Npgsql parameter binding for a pgvector type has been written
-//   // conservatively below using new Pgvector.Vector(float[]).
-//   // Confirmed pattern from neon-pgvector standard (Pgvector package):
-//   //   cmd.Parameters.AddWithValue("queryVec", new Pgvector.Vector(embedding.ToArray()));
-//   // If the project uses a different Npgsql/Pgvector version, verify the parameter API.
-//
-// REGISTRATION (in agent setup code):
-//   var tool = sp.GetRequiredService<VectorSearchTool>();
-//   var agent = modelRegistry.GetChatClient("text-default")
-//       .AsAIAgent(
-//           instructions: systemPrompt,
-//           tools: [AIFunctionFactory.Create(tool.SearchAsync)]);
-//
-// ALTERNATIVE — EF Core:
-//   If the project already wires pgvector through EF Core (UseVector(), HasMethod("hnsw")),
-//   replace the NpgsqlDataSource usage with db.Database.SqlQuery<string>() per
-//   infrastructure-neon-pgvector. The tool method signature stays identical.
-
-using System.ComponentModel;
-using Npgsql;
-using Pgvector;
-
-namespace {{PROJECT_NAMESPACE}}.AI;
-
-/// <summary>
-/// MAF tool: searches the knowledge base for chunks semantically similar to a query.
-/// Registered on an agent via <c>AIFunctionFactory.Create(tool.SearchAsync)</c>.
-/// The agent calls this autonomously when it needs grounding context.
-/// </summary>
-public sealed class VectorSearchTool(
-    EmbeddingService embeddingService,
-    NpgsqlDataSource dataSource,
-    ITenantContext tenantContext)   // Resolved from DI — scoped to the authenticated request.
-                                    // Replace with Guid currentTenantId if a simpler accessor is preferred.
-{
-    private const int DefaultTopK = 5;
-
-    /// <summary>
-    /// Searches the knowledge base for context relevant to a question.
-    /// </summary>
-    /// <param name="query">The natural-language search query.</param>
-    /// <param name="ct">Cancellation token.</param>
-    /// <returns>
-    /// Concatenated text of the top matching chunks, separated by double newlines.
-    /// Returns an empty string if no results are found.
-    /// </returns>
-    [Description("Searches the knowledge base for context relevant to a question")]
-    public async Task<string> SearchAsync(
-        [Description("the natural-language search query")] string query,
-        CancellationToken ct = default)
-    {
-        // 1. Embed the query at search time.
-        ReadOnlyMemory<float> queryVector = await embeddingService.EmbedAsync(query, ct);
-
-        // 2. Resolve tenant from auth context — never from a model-supplied parameter.
-        Guid tenantId = tenantContext.CurrentTenantId;
-
-        // 3. Run parameterized cosine-distance query.
-        //    ORDER BY embedding <=> @queryVec sorts ascending by distance (most similar first).
-        const string sql = """
-            SELECT content
-            FROM   kb_embeddings
-            WHERE  tenant_id = @tenant
-            ORDER  BY embedding <=> @queryVec
-            LIMIT  @topK
-            """;
-
-        var chunks = new List<string>(DefaultTopK);
-
-        await using var conn = await dataSource.OpenConnectionAsync(ct);
-        await using var cmd = new NpgsqlCommand(sql, conn);
-
-        cmd.Parameters.AddWithValue("tenant", tenantId);
-
-        // VERIFY: Pgvector.Vector wraps a float[] for Npgsql parameter binding.
-        // The project must have called dataSourceBuilder.UseVector() on NpgsqlDataSourceBuilder.
-        // NuGet: Pgvector (matches the Pgvector.EntityFrameworkCore used in neon-pgvector.md).
-        cmd.Parameters.AddWithValue("queryVec", new Vector(queryVector.ToArray()));
-
-        cmd.Parameters.AddWithValue("topK", DefaultTopK);
-
-        await using var reader = await cmd.ExecuteReaderAsync(ct);
-        while (await reader.ReadAsync(ct))
-        {
-            chunks.Add(reader.GetString(0));
-        }
-
-        return string.Join("\n\n", chunks);
-    }
-}
+// READS STANDARD: ai-agents-rag-custom-pgvector
+
+using System.ComponentModel;
+using Npgsql;
+using Pgvector;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+public sealed class VectorSearchTool(
+    EmbeddingService embeddingService,
+    NpgsqlDataSource dataSource,
+    ITenantContext tenantContext)
+{
+    private const int DefaultTopK = 5;
+
+    [Description("Searches the knowledge base for context relevant to a question")]
+    public async Task<string> SearchAsync(
+        [Description("the natural-language search query")] string query,
+        CancellationToken ct = default)
+    {
+        ReadOnlyMemory<float> queryVector = await embeddingService.EmbedAsync(query, ct);
+
+        // Tenant comes from auth, never a tool parameter: the model could be prompt-injected into another tenant.
+        Guid tenantId = tenantContext.CurrentTenantId;
+
+        const string sql = """
+            SELECT content
+            FROM   kb_embeddings
+            WHERE  tenant_id = @tenant
+            ORDER  BY embedding <=> @queryVec
+            LIMIT  @topK
+            """;
+
+        var chunks = new List<string>(DefaultTopK);
+
+        await using var conn = await dataSource.OpenConnectionAsync(ct);
+        await using var cmd = new NpgsqlCommand(sql, conn);
+
+        cmd.Parameters.AddWithValue("tenant", tenantId);
+
+        // VERIFY: binding Pgvector.Vector needs dataSourceBuilder.UseVector(); confirm against the project's Npgsql/Pgvector versions.
+        cmd.Parameters.AddWithValue("queryVec", new Vector(queryVector.ToArray()));
+
+        cmd.Parameters.AddWithValue("topK", DefaultTopK);
+
+        await using var reader = await cmd.ExecuteReaderAsync(ct);
+        while (await reader.ReadAsync(ct))
+        {
+            chunks.Add(reader.GetString(0));
+        }
+
+        return string.Join("\n\n", chunks);
+    }
+}