@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

package/framework/standards/ai-agents/prompts-in-db.md

@@ -1,214 +1,214 @@
-# Prompts in DB — Editable, versioned agent instructions
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 1 (on-keyword)
-> **Keywords:** prompts in db, agent prompts, prompt versioning, prompt hot-reload, editable instructions, prompt management
-> **Read by Claude in:** implement (when an agent's instructions should be runtime-editable)
-
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
-
----
-
-## Por que prompts no DB
-
-Hardcoded instructions in source code mean every prompt tweak requires a full build and deploy cycle. With prompts in the database the team can tune agent behavior without touching code, pushing a commit, or triggering CI.
-
-Key benefits:
-
-| Benefit | Explanation |
-|---------|-------------|
-| **No deploy to tune** | Product/ML team edits prompts via a backoffice or SQL — the agent picks up the change on next load |
-| **Versioning and rollback** | Every version is kept as an immutable row; rollback = flip `is_active` |
-| **A/B testing** | Two rows for the same `agent_key`, activate one; compare metrics; flip back if needed |
-| **Audit trail** | `created_at` per version gives a full timeline of what prompt was active when |
-
-The agent receives its `instructions:` value from the repository at construction time — not from a string literal in code.
-
----
-
-## O pattern
-
-```
-┌─────────────────┐       ┌──────────────────┐       ┌──────────────────────┐
-│  Agent Handler  │──────▶│ PromptRepository │──────▶│  agent_prompts table │
-│  (constructs    │       │ (IMemoryCache    │       │  (PostgreSQL)        │
-│   AIAgent)      │◀──────│  TTL: 5 min)     │◀──────│                      │
-└─────────────────┘       └──────────────────┘       └──────────────────────┘
-```
-
-1. The handler (or DI factory) calls `IPromptRepository.GetActivePromptAsync(agentKey, ct)`.
-2. `PromptRepository` checks `IMemoryCache`. On a hit, returns the cached string. On a miss, queries the DB for the single row where `agent_key = @key AND is_active = true`, caches it with a short TTL (e.g. 5 minutes), and returns it.
-3. The handler constructs the agent: `chatClient.AsAIAgent(instructions: prompt, name: "MyAgent")`.
-4. **Agents are cheap to construct** — recreate on every request (or per scoped lifetime). Do NOT attempt to mutate a running agent's instructions.
-
----
-
-## Schema da tabela
-
-The `agent_prompts` table stores one row per prompt version. See the full migration in:
-
-```
-templates/code/sql/ai-agents/agent-prompts-migration.sql.template
-```
-
-Column summary:
-
-| Column | Type | Notes |
-|--------|------|-------|
-| `id` | `uuid` | PK, `gen_random_uuid()` |
-| `agent_key` | `text NOT NULL` | Logical identifier, e.g. `"proposal-agent"` |
-| `version` | `int NOT NULL` | Monotonically increasing per `agent_key` |
-| `content` | `text NOT NULL` | The full system-prompt text |
-| `is_active` | `boolean NOT NULL DEFAULT false` | Only one row active per `agent_key` |
-| `created_at` | `timestamptz NOT NULL DEFAULT now()` | Immutable audit timestamp |
-
-### Unique-partial-index trick
-
-```sql
-CREATE UNIQUE INDEX ix_agent_prompts_active
-    ON {{SCHEMA}}.agent_prompts (agent_key)
-    WHERE is_active;
-```
-
-This index enforces at the database level that only one row per `agent_key` can have `is_active = true`. An attempt to activate a second row for the same key will fail with a unique-constraint violation — no application logic needed to guard this invariant.
-
----
-
-## O repository
-
-Reference implementation:
-
-```
-templates/code/dotnet/ai-agents/PromptRepository.cs.template
-```
-
-Interface contract:
-
-```csharp
-public interface IPromptRepository
-{
-    /// <summary>
-    /// Returns the content of the currently active prompt for the given agent key.
-    /// Throws <see cref="InvalidOperationException"/> if no active prompt exists.
-    /// </summary>
-    Task<string> GetActivePromptAsync(string agentKey, CancellationToken ct = default);
-}
-```
-
-The concrete `PromptRepository`:
-
-- Receives `DbContext` and `IMemoryCache` via primary constructor.
-- Uses a cache key of `$"agent_prompt:{agentKey}"` with a sliding expiration of 5 minutes.
-- On a cache miss, queries `AgentPrompts.Where(p => p.AgentKey == agentKey && p.IsActive)` via EF Core.
-- Throws `InvalidOperationException($"No active prompt found for agent '{agentKey}'.")` when no row matches — fail fast so misconfiguration is immediately visible.
-- Does NOT catch DB exceptions — let the caller decide how to handle transient failures.
-
-DI registration (in `Program.cs` or a bootstrap extension):
-
-```csharp
-builder.Services.AddMemoryCache();
-builder.Services.AddScoped<IPromptRepository, PromptRepository>();
-```
-
----
-
-## Integração com o agente
-
-### Scoped construction (recommended)
-
-```csharp
-public sealed class ProposalAgentHandler(
-    IPromptRepository promptRepo,
-    ModelRegistry modelRegistry)
-{
-    public async Task<string> RunAsync(string userMessage, CancellationToken ct)
-    {
-        var prompt = await promptRepo.GetActivePromptAsync("proposal-agent", ct);
-
-        var agent = modelRegistry
-            .GetChatClient("text-default")
-            .AsAIAgent(instructions: prompt, name: "ProposalAgent");
-
-        var response = await agent.RunAsync(userMessage, ct);
-        return response.Text;
-    }
-}
-```
-
-### Hot-reload semantics
-
-When a new prompt is saved with `is_active = true`:
-
-1. The old active row is set to `is_active = false` (see §Versionamento).
-2. The cache entry expires within the configured TTL (5 min by default).
-3. The next agent construction after expiry picks up the new prompt automatically.
-
-**Do NOT mutate a running agent.** Agents are lightweight value-like objects in MAF — recreate on each scoped lifetime instead of attempting to patch `instructions` on a live instance.
-
-### Keyed singleton (long-lived, explicit refresh)
-
-For agents registered as keyed singletons (e.g. via `builder.AddAIAgent`), hot-reload requires explicit invalidation. In that pattern, call `IMemoryCache.Remove($"agent_prompt:{key}")` from an admin endpoint or background job after saving a new version, then recreate the agent in the factory. This is more complex; prefer scoped construction unless the agent carries expensive state (e.g. an embedded tool pipeline that is costly to rebuild).
-
----
-
-## Versionamento
-
-**Rule: never UPDATE the `content` column.** The content of a prompt row is immutable once written.
-
-To release a new prompt version:
-
-```sql
--- 1. Deactivate the current active version
-UPDATE {{SCHEMA}}.agent_prompts
-   SET is_active = false
- WHERE agent_key = 'proposal-agent' AND is_active = true;
-
--- 2. Insert the new version (version = previous max + 1)
-INSERT INTO {{SCHEMA}}.agent_prompts (agent_key, version, content, is_active)
-VALUES (
-    'proposal-agent',
-    (SELECT COALESCE(MAX(version), 0) + 1 FROM {{SCHEMA}}.agent_prompts WHERE agent_key = 'proposal-agent'),
-    'Your new system prompt text here...',
-    true
-);
-```
-
-This keeps a complete, auditable history. Rollback = deactivate the current row and reactivate any previous row.
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Por quê é problema | Solução |
-|---|---|---|
-| Hardcoded prompt string in production code | Every tune requires a build + deploy | Move to `agent_prompts` table |
-| `UPDATE agent_prompts SET content = '...'` without a version | Destroys history; no rollback | INSERT new row with version+1, flip `is_active` |
-| No cache — DB query on every agent invocation | High latency + DB load under traffic | Use `IMemoryCache` with a short TTL |
-| `appsettings.json` prompts | Still requires a deploy to change; no versioning | Move to DB or environment-variable-agnostic store |
-| Single global `IMemoryCache` key collisions | Two agents with similar keys overwrite each other | Always prefix: `$"agent_prompt:{agentKey}"` |
-| Activating a new row without deactivating the old one | Two active rows for the same key — undefined behavior | The partial unique index prevents this at DB level; always deactivate first in app code |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] `agent_prompts` table exists with all required columns (`id`, `agent_key`, `version`, `content`, `is_active`, `created_at`)
-- [ ] Unique partial index `ix_agent_prompts_active` on `(agent_key) WHERE is_active` is present
-- [ ] `IPromptRepository` registered in DI (`AddScoped`)
-- [ ] `IMemoryCache` registered (`builder.Services.AddMemoryCache()`)
-- [ ] No prompt string literals in production agent construction code
-- [ ] `GetActivePromptAsync` throws `InvalidOperationException` (not returns null) when no active prompt found
-- [ ] Versionamento pattern followed: INSERT + flip, never UPDATE content
-- [ ] At least one seed row per `agent_key` in migrations or seed script
-
----
-
-## References
-
-- `ai-agents-setup` — how to construct an `AIAgent` via `AsAIAgent(instructions:)`
-- `ai-agents-providers-model-registry` — how to obtain the `IChatClient` from the Model Registry
-- `backend-database-postgresql-database` — naming conventions, timestamptz, uuid PKs, partial indexes
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/prompts-in-db.md v1.0 (2026-05-19)*
+# Prompts in DB — Editable, versioned agent instructions
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** prompts in db, agent prompts, prompt versioning, prompt hot-reload, editable instructions, prompt management
+> **Read by Claude in:** implement (when an agent's instructions should be runtime-editable)
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Por que prompts no DB
+
+Hardcoded instructions in source code mean every prompt tweak requires a full build and deploy cycle. With prompts in the database the team can tune agent behavior without touching code, pushing a commit, or triggering CI.
+
+Key benefits:
+
+| Benefit | Explanation |
+|---------|-------------|
+| **No deploy to tune** | Product/ML team edits prompts via a backoffice or SQL — the agent picks up the change on next load |
+| **Versioning and rollback** | Every version is kept as an immutable row; rollback = flip `is_active` |
+| **A/B testing** | Two rows for the same `agent_key`, activate one; compare metrics; flip back if needed |
+| **Audit trail** | `created_at` per version gives a full timeline of what prompt was active when |
+
+The agent receives its `instructions:` value from the repository at construction time — not from a string literal in code.
+
+---
+
+## O pattern
+
+```
+┌─────────────────┐       ┌──────────────────┐       ┌──────────────────────┐
+│  Agent Handler  │──────▶│ PromptRepository │──────▶│  agent_prompts table │
+│  (constructs    │       │ (IMemoryCache    │       │  (PostgreSQL)        │
+│   AIAgent)      │◀──────│  TTL: 5 min)     │◀──────│                      │
+└─────────────────┘       └──────────────────┘       └──────────────────────┘
+```
+
+1. The handler (or DI factory) calls `IPromptRepository.GetActivePromptAsync(agentKey, ct)`.
+2. `PromptRepository` checks `IMemoryCache`. On a hit, returns the cached string. On a miss, queries the DB for the single row where `agent_key = @key AND is_active = true`, caches it with a short TTL (e.g. 5 minutes), and returns it.
+3. The handler constructs the agent: `chatClient.AsAIAgent(instructions: prompt, name: "MyAgent")`.
+4. **Agents are cheap to construct** — recreate on every request (or per scoped lifetime). Do NOT attempt to mutate a running agent's instructions.
+
+---
+
+## Schema da tabela
+
+The `agent_prompts` table stores one row per prompt version. See the full migration in:
+
+```
+templates/code/sql/ai-agents/agent-prompts-migration.sql.template
+```
+
+Column summary:
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `id` | `uuid` | PK, `gen_random_uuid()` |
+| `agent_key` | `text NOT NULL` | Logical identifier, e.g. `"proposal-agent"` |
+| `version` | `int NOT NULL` | Monotonically increasing per `agent_key` |
+| `content` | `text NOT NULL` | The full system-prompt text |
+| `is_active` | `boolean NOT NULL DEFAULT false` | Only one row active per `agent_key` |
+| `created_at` | `timestamptz NOT NULL DEFAULT now()` | Immutable audit timestamp |
+
+### Unique-partial-index trick
+
+```sql
+CREATE UNIQUE INDEX ix_agent_prompts_active
+    ON {{SCHEMA}}.agent_prompts (agent_key)
+    WHERE is_active;
+```
+
+This index enforces at the database level that only one row per `agent_key` can have `is_active = true`. An attempt to activate a second row for the same key will fail with a unique-constraint violation — no application logic needed to guard this invariant.
+
+---
+
+## O repository
+
+Reference implementation:
+
+```
+templates/code/dotnet/ai-agents/PromptRepository.cs.template
+```
+
+Interface contract:
+
+```csharp
+public interface IPromptRepository
+{
+    /// <summary>
+    /// Returns the content of the currently active prompt for the given agent key.
+    /// Throws <see cref="InvalidOperationException"/> if no active prompt exists.
+    /// </summary>
+    Task<string> GetActivePromptAsync(string agentKey, CancellationToken ct = default);
+}
+```
+
+The concrete `PromptRepository`:
+
+- Receives `DbContext` and `IMemoryCache` via primary constructor.
+- Uses a cache key of `$"agent_prompt:{agentKey}"` with a sliding expiration of 5 minutes.
+- On a cache miss, queries `AgentPrompts.Where(p => p.AgentKey == agentKey && p.IsActive)` via EF Core.
+- Throws `InvalidOperationException($"No active prompt found for agent '{agentKey}'.")` when no row matches — fail fast so misconfiguration is immediately visible.
+- Does NOT catch DB exceptions — let the caller decide how to handle transient failures.
+
+DI registration (in `Program.cs` or a bootstrap extension):
+
+```csharp
+builder.Services.AddMemoryCache();
+builder.Services.AddScoped<IPromptRepository, PromptRepository>();
+```
+
+---
+
+## Integração com o agente
+
+### Scoped construction (recommended)
+
+```csharp
+public sealed class ProposalAgentHandler(
+    IPromptRepository promptRepo,
+    ModelRegistry modelRegistry)
+{
+    public async Task<string> RunAsync(string userMessage, CancellationToken ct)
+    {
+        var prompt = await promptRepo.GetActivePromptAsync("proposal-agent", ct);
+
+        var agent = modelRegistry
+            .GetChatClient("text-default")
+            .AsAIAgent(instructions: prompt, name: "ProposalAgent");
+
+        var response = await agent.RunAsync(userMessage, ct);
+        return response.Text;
+    }
+}
+```
+
+### Hot-reload semantics
+
+When a new prompt is saved with `is_active = true`:
+
+1. The old active row is set to `is_active = false` (see §Versionamento).
+2. The cache entry expires within the configured TTL (5 min by default).
+3. The next agent construction after expiry picks up the new prompt automatically.
+
+**Do NOT mutate a running agent.** Agents are lightweight value-like objects in MAF — recreate on each scoped lifetime instead of attempting to patch `instructions` on a live instance.
+
+### Keyed singleton (long-lived, explicit refresh)
+
+For agents registered as keyed singletons (e.g. via `builder.AddAIAgent`), hot-reload requires explicit invalidation. In that pattern, call `IMemoryCache.Remove($"agent_prompt:{key}")` from an admin endpoint or background job after saving a new version, then recreate the agent in the factory. This is more complex; prefer scoped construction unless the agent carries expensive state (e.g. an embedded tool pipeline that is costly to rebuild).
+
+---
+
+## Versionamento
+
+**Rule: never UPDATE the `content` column.** The content of a prompt row is immutable once written.
+
+To release a new prompt version:
+
+```sql
+-- 1. Deactivate the current active version
+UPDATE {{SCHEMA}}.agent_prompts
+   SET is_active = false
+ WHERE agent_key = 'proposal-agent' AND is_active = true;
+
+-- 2. Insert the new version (version = previous max + 1)
+INSERT INTO {{SCHEMA}}.agent_prompts (agent_key, version, content, is_active)
+VALUES (
+    'proposal-agent',
+    (SELECT COALESCE(MAX(version), 0) + 1 FROM {{SCHEMA}}.agent_prompts WHERE agent_key = 'proposal-agent'),
+    'Your new system prompt text here...',
+    true
+);
+```
+
+This keeps a complete, auditable history. Rollback = deactivate the current row and reactivate any previous row.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Hardcoded prompt string in production code | Every tune requires a build + deploy | Move to `agent_prompts` table |
+| `UPDATE agent_prompts SET content = '...'` without a version | Destroys history; no rollback | INSERT new row with version+1, flip `is_active` |
+| No cache — DB query on every agent invocation | High latency + DB load under traffic | Use `IMemoryCache` with a short TTL |
+| `appsettings.json` prompts | Still requires a deploy to change; no versioning | Move to DB or environment-variable-agnostic store |
+| Single global `IMemoryCache` key collisions | Two agents with similar keys overwrite each other | Always prefix: `$"agent_prompt:{agentKey}"` |
+| Activating a new row without deactivating the old one | Two active rows for the same key — undefined behavior | The partial unique index prevents this at DB level; always deactivate first in app code |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `agent_prompts` table exists with all required columns (`id`, `agent_key`, `version`, `content`, `is_active`, `created_at`)
+- [ ] Unique partial index `ix_agent_prompts_active` on `(agent_key) WHERE is_active` is present
+- [ ] `IPromptRepository` registered in DI (`AddScoped`)
+- [ ] `IMemoryCache` registered (`builder.Services.AddMemoryCache()`)
+- [ ] No prompt string literals in production agent construction code
+- [ ] `GetActivePromptAsync` throws `InvalidOperationException` (not returns null) when no active prompt found
+- [ ] Versionamento pattern followed: INSERT + flip, never UPDATE content
+- [ ] At least one seed row per `agent_key` in migrations or seed script
+
+---
+
+## References
+
+- `ai-agents-setup` — how to construct an `AIAgent` via `AsAIAgent(instructions:)`
+- `ai-agents-providers-model-registry` — how to obtain the `IChatClient` from the Model Registry
+- `backend-database-postgresql-database` — naming conventions, timestamptz, uuid PKs, partial indexes
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/prompts-in-db.md v1.0 (2026-05-19)*