@polymorphism-tech/morph-spec 7.9.4 → 8.1.0

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

@@ -1,39 +1,39 @@
-// 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;
-    }
-}
+// 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;
+    }
+}

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

@@ -1,68 +1,68 @@
-// 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)];
-    }
-}
+// 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)];
+    }
+}

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

@@ -1,117 +1,117 @@
-// 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
-    );
-}
+// 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
+    );
+}

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

@@ -1,95 +1,95 @@
-// TEMPLATE: PromptRepository.cs
-// PURPOSE: Loads agent system prompts from the agent_prompts table, with in-memory caching.
-// READS STANDARD: ai-agents-prompts-in-db
-// 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>
-public sealed class AgentPrompt
-{
-    public Guid Id { get; init; } = Guid.CreateVersion7();
-    public required string AgentKey { get; init; }
-    public int Version { get; init; }
-    public required string Content { get; init; }
-    public bool IsActive { get; set; }
-    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>
-public sealed class PromptRepository(YourDbContext db, IMemoryCache cache) : IPromptRepository
-{
-    private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(5);
-
-    public async Task<string> GetActivePromptAsync(string agentKey, CancellationToken ct = default)
-    {
-        var cacheKey = $"agent_prompt:{agentKey}";
-
-        if (cache.TryGetValue(cacheKey, out string? cached) && cached is not null)
-            return cached;
-
-        var content = await db.AgentPrompts
-            .Where(p => p.AgentKey == agentKey && p.IsActive)
-            .Select(p => p.Content)
-            .FirstOrDefaultAsync(ct);
-
-        if (content is null)
-            throw new InvalidOperationException(
-                $"No active prompt found for agent '{agentKey}'. " +
-                "Insert a row in agent_prompts with is_active = true for this agent_key.");
-
-        cache.Set(cacheKey, content, new MemoryCacheEntryOptions
-        {
-            SlidingExpiration = CacheTtl
-        });
-
-        return content;
-    }
-}
+// TEMPLATE: PromptRepository.cs
+// PURPOSE: Loads agent system prompts from the agent_prompts table, with in-memory caching.
+// READS STANDARD: ai-agents-prompts-in-db
+// 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>
+public sealed class AgentPrompt
+{
+    public Guid Id { get; init; } = Guid.CreateVersion7();
+    public required string AgentKey { get; init; }
+    public int Version { get; init; }
+    public required string Content { get; init; }
+    public bool IsActive { get; set; }
+    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>
+public sealed class PromptRepository(YourDbContext db, IMemoryCache cache) : IPromptRepository
+{
+    private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(5);
+
+    public async Task<string> GetActivePromptAsync(string agentKey, CancellationToken ct = default)
+    {
+        var cacheKey = $"agent_prompt:{agentKey}";
+
+        if (cache.TryGetValue(cacheKey, out string? cached) && cached is not null)
+            return cached;
+
+        var content = await db.AgentPrompts
+            .Where(p => p.AgentKey == agentKey && p.IsActive)
+            .Select(p => p.Content)
+            .FirstOrDefaultAsync(ct);
+
+        if (content is null)
+            throw new InvalidOperationException(
+                $"No active prompt found for agent '{agentKey}'. " +
+                "Insert a row in agent_prompts with is_active = true for this agent_key.");
+
+        cache.Set(cacheKey, content, new MemoryCacheEntryOptions
+        {
+            SlidingExpiration = CacheTtl
+        });
+
+        return content;
+    }
+}