@polymorphism-tech/morph-spec 7.0.0 → 7.1.0

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

@@ -0,0 +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)*

package/framework/standards/ai-agents/providers/model-registry.md

@@ -0,0 +1,158 @@
+# Model Registry — Provider-agnostic agent configuration
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 0 (always-load via persona maf-expert)
+> **Keywords:** model registry, provider agnostic, model alias, IChatClient factory, multi-model, model selection, model config
+> **Read by Claude in:** plan (cita este standard quando feature menciona >1 modelo ou multi-provider) + implement (copia o template ModelRegistry.cs e gera config no projeto)
+
+**Verified against:** MAF 1.0 GA + tier list research (2026-05-18). Last-verified: 2026-05-19.
+
+---
+
+## Pattern
+
+The project consuming morph-spec maintains a **single JSON file** mapping aliases (`text-default`, `vision`, `reasoning`, etc.) to `{ provider, model, options }`. Agents reference aliases — never hardcoded model strings. Switching provider or model is a one-file change.
+
+```
+Standard (this file, in framework) — explains the pattern + canonical schema
+        │ Claude reads + copies template
+        ▼
+Project (consumer) — config/model-registry.json + src/.../ModelRegistry.cs
+```
+
+---
+
+## Schema (canonical)
+
+```jsonc
+// config/model-registry.json — IN THE PROJECT (not in framework)
+{
+  "$schema": "./model-registry.schema.json",
+  "version": "1.0",
+  "defaultAlias": "text-default",
+  "aliases": {
+    "text-default":  { "provider": "openai",    "model": "gpt-4o-mini",             "options": { "temperature": 0.7 } },
+    "text-heavy":    { "provider": "openai",    "model": "gpt-4o",                  "options": { "temperature": 0.5 } },
+    "reasoning":     { "provider": "openai",    "model": "o3-mini",                 "options": { "reasoningEffort": "medium" } },
+    "long-form":     { "provider": "anthropic", "model": "claude-sonnet-4-6",       "options": {} },
+    "vision":        { "provider": "google",    "model": "gemini-2.5-flash",        "options": {} },
+    "embeddings":    { "provider": "openai",    "model": "text-embedding-3-small",  "options": { "dimensions": 1536 } },
+    "transcription": { "provider": "openai",    "model": "whisper-1",               "options": {} },
+    "local-dev":     { "provider": "ollama",    "model": "llama3.2:3b",             "options": { "endpoint": "http://localhost:11434/v1" } }
+  },
+  "fallback": {
+    "text-default": "anthropic/claude-haiku-4-5",
+    "text-heavy":   "anthropic/claude-sonnet-4-6"
+  }
+}
+```
+
+> The aliases above are an **example**. Each project defines its own — provider choices vary per feature.
+
+**Field semantics:**
+- `provider`: SDK family — one of `openai`, `google`, `anthropic`, `ollama` (first-class). `azure-openai` is supported as an opt-in branch (see §providers).
+- `model`: model id for that provider.
+- `options`: provider-specific extras (temperature, reasoning effort, `endpoint` for Ollama, etc.).
+- `fallback`: when the primary provider fails (rate limit, outage), switch to this alias. Format `provider/model`.
+
+---
+
+## Providers (first-class)
+
+> **This section is the single source of truth for provider SDKs.** Provider SDKs change names/versions often — keep this section verified with a date; templates stay stable.
+
+| Provider | `provider` value | NuGet SDK (LAST-VERIFIED 2026-05-19) | Notes |
+|----------|------------------|--------------------------------------|-------|
+| **OpenAI** | `openai` | `OpenAI` 2.* | `new ChatClient(model, apiKey).AsIChatClient()` |
+| **Ollama** | `ollama` | `OpenAI` 2.* (OpenAI-compatible endpoint) | Same `ChatClient` with custom `Endpoint` + dummy key |
+| **Google Gemini** | `google` | Confirm current SDK on NuGet before use | Adapt provider client to `IChatClient` |
+| **Anthropic Claude** | `anthropic` | Confirm current SDK on NuGet before use | Adapt provider client to `IChatClient` |
+| **Azure OpenAI** (opt-in, not default) | `azure-openai` | `Azure.AI.OpenAI` 2.* + `Azure.Identity` | Add only when a client requires data residency |
+
+**Adding a provider branch:** the `ModelRegistry.cs` template implements `openai` + `ollama`. To add `google`, `anthropic`, or `azure-openai`:
+1. Confirm the current NuGet SDK — community SDKs evolve; check NuGet/context7 before coding.
+2. Add a `case "<provider>":` branch in `ModelRegistry.GetChatClient`'s switch, following the `openai`/`ollama` pattern.
+3. Add the SDK `PackageReference` to the project's `.csproj`.
+4. The branch returns an `IChatClient`. If the SDK doesn't expose `IChatClient` natively, wrap it with an adapter.
+
+**Direct models only:** never use a hosted agent service. Every provider above is reached as a direct model.
+
+---
+
+## Implementation pattern
+
+```csharp
+// WRONG — hardcoded model + provider
+var agent = new ChatClient("gpt-4o-mini", apiKey)
+    .AsIChatClient()
+    .AsAIAgent(instructions: prompt);
+
+// RIGHT — alias-based, provider-agnostic
+var agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(instructions: prompt);
+```
+
+The `ModelRegistry` class in the project owns the mapping. See template `templates/code/dotnet/ai-agents/ModelRegistry.cs.template`.
+
+---
+
+## How Claude implements this in a project
+
+When a task says "register the X agent" and the project has >1 model or >1 provider, Claude:
+
+1. Read this standard.
+2. Copy `templates/code/dotnet/ai-agents/ModelRegistry.cs.template` to `src/.../ModelRegistry.cs` in the project. Substitute placeholders.
+3. Copy `templates/code/dotnet/ai-agents/model-registry.json.template` to `config/model-registry.json`. Adjust aliases to project needs.
+4. Wire `ModelRegistry` into DI (see `AgentBootstrap.cs.template`).
+5. Future agents reference `_modelRegistry.GetChatClient(alias)`.
+
+---
+
+## Recommended aliases & models (orientativo — maio/2026)
+
+> Tabela orientativa. Actual values live in the project's `model-registry.json`. Models evolve fast.
+
+| Alias | Provider sugerido | Modelo (maio/2026) | Use case |
+|-------|-------------------|--------------------|----------|
+| `text-default` | openai | gpt-4o-mini | Geração padrão de texto |
+| `text-heavy` | openai / anthropic | gpt-4o / claude-sonnet-4-6 | Análise complexa |
+| `reasoning` | openai | o3-mini | Decisões, planejamento, math |
+| `long-form` | anthropic | claude-sonnet-4-6 | Escrita longa, análise de documento |
+| `vision` | google / openai | gemini-2.5-flash / gpt-4o | Image → Text |
+| `embeddings` | openai | text-embedding-3-small | RAG, similarity |
+| `transcription` | openai | whisper-1 | Audio → Text |
+| `local-dev` | ollama | llama3.2:3b | Dev local, sem custo |
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Why | Right way |
+|--------------|-----|-----------|
+| Hardcode `"gpt-4o-mini"` in agent code | Switching model = grep + replace | Use `_modelRegistry.GetChatClient("text-default")` |
+| Put `model-registry.json` in `.morph/` | `.morph/framework` is framework-only; `.morph/config/config.json` is reserved for morph-spec metadata | Put it in `config/` of the project |
+| Different `ModelRegistry` class per agent | Defeats the purpose | One class per project, singleton in DI |
+| Use a hosted agent service to "simplify" | Hosted lags 6-9 months, removes control | Always direct models |
+| Mix providers without a `fallback` block | Hard to diagnose outages | Declare `fallback` in `model-registry.json` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Project has `config/model-registry.json` (or declared equivalent).
+- [ ] Project has a `ModelRegistry` class registered as singleton in DI.
+- [ ] No agent code has hardcoded model strings — `grep -rE 'gpt-[0-9]|claude-|gemini-|whisper-' src/` matches only `ModelRegistry.cs`.
+- [ ] Aliases used in agent code exist in `model-registry.json`.
+
+---
+
+## References
+
+- `ai-agents-setup` — provider SDKs
+- Template: `templates/code/dotnet/ai-agents/ModelRegistry.cs.template`
+- Template: `templates/code/dotnet/ai-agents/model-registry.json.template`
+- Template: `templates/code/dotnet/ai-agents/AgentBootstrap.cs.template`
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/providers/model-registry.md v1.0 (2026-05-19)*

package/framework/standards/ai-agents/rag-custom-pgvector.md

@@ -0,0 +1,243 @@
+# RAG Custom with pgvector — Knowledge retrieval you control
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** rag, vector search, pgvector, embeddings, custom rag, retrieval, semantic search, knowledge base, RAG tool
+> **Read by Claude in:** implement (when an agent needs to retrieve knowledge)
+
+**Verified against:** MAF 1.0 GA + Microsoft.Extensions.AI. Last-verified: 2026-05-19.
+
+---
+
+## Por que RAG custom
+
+Hosted RAG (uploading PDFs to a service) hands control of chunking, embedding, and storage to a third party. You cannot tune chunk size for your document type, cannot switch embedding models without re-indexing, and cannot add tenant isolation at the storage layer. Custom RAG gives you all three.
+
+- **Chunking:** you choose the strategy per document type (catalog, contract, technical doc). See `data-vector-search-rag-chunking`.
+- **Embedding:** provider-agnostic. The embedding model is chosen via the `embeddings` alias in the project's Model Registry (see `ai-agents-providers-model-registry`). The project wires an `IEmbeddingGenerator<string, Embedding<float>>` for that alias — switching from `text-embedding-3-small` to another model is a one-file config change.
+- **Storage:** pgvector on Neon — a column you own, indexed by HNSW, with RLS for tenant isolation.
+
+---
+
+## Arquitetura
+
+```
+[Document ingestion]
+        │
+        ▼
+ EmbeddingService                  (generates float vectors via IEmbeddingGenerator)
+        │
+        ▼
+  kb_embeddings table              (pgvector column, HNSW index, tenant_id partition)
+        │
+        ▼
+  VectorSearchTool  ◄── MAF agent  (tool registered via AIFunctionFactory.Create)
+        │
+        ▼
+  Top-k chunks → agent context     (agent decides when to call the tool)
+```
+
+Three pieces:
+
+1. **EmbeddingService** — wraps `IEmbeddingGenerator<string, Embedding<float>>` from `Microsoft.Extensions.AI`. Called during indexing (batch) and at query time (single text).
+2. **`kb_embeddings` table** — stores chunk text + `vector(1536)` + `tenant_id` + `metadata jsonb`. HNSW index with `vector_cosine_ops`.
+3. **VectorSearchTool** — a typed MAF tool. A `[Description]`-decorated method the agent can call. Embeds the query, runs cosine-distance SQL, returns top-k chunks as concatenated text.
+
+---
+
+## Chunking por tipo de documento
+
+Chunk strategy varies by document type:
+
+| Document type | Recommended strategy | Chunk size |
+|---------------|----------------------|------------|
+| Product catalog | Fixed-size | 256–512 tokens |
+| Legal contract | Sentence-aware | 256 tokens |
+| Technical docs | Semantic (split on headers) | Variable |
+| Q&A pairs | Keep whole pair | Whole Q+A |
+| Code files | Function boundary | Whole function |
+
+For implementation of each strategy, see `data-vector-search-rag-chunking`. Do not duplicate chunking code here — that standard is the single source of truth for chunk implementations and the `Chunk` metadata record.
+
+---
+
+## EmbeddingService
+
+Reference template: `templates/code/dotnet/ai-agents/EmbeddingService.cs.template`
+
+The service wraps `IEmbeddingGenerator<string, Embedding<float>>` (from `Microsoft.Extensions.AI`) and exposes two methods:
+
+```csharp
+// Single text → embedding vector (used at query time)
+Task<ReadOnlyMemory<float>> EmbedAsync(string text, CancellationToken ct = default);
+
+// Batch of texts → list of vectors (used during document indexing)
+Task<IReadOnlyList<ReadOnlyMemory<float>>> EmbedBatchAsync(
+    IReadOnlyList<string> texts, CancellationToken ct = default);
+```
+
+Both call `GenerateAsync(IEnumerable<string>, ...)` on the injected `IEmbeddingGenerator` (verified via context7 / Microsoft Learn). `GenerateAsync` returns `GeneratedEmbeddings<Embedding<float>>`; each element's `.Vector` property is a `ReadOnlyMemory<float>`.
+
+**Wiring the `IEmbeddingGenerator`:** the project registers its chosen embedding provider in DI (e.g., via the OpenAI embedding client's `.AsIEmbeddingGenerator()` extension, or the equivalent for another provider). The `embeddings` alias in `model-registry.json` declares the model (`text-embedding-3-small`, dimensions 1536). The `EmbeddingService` is registered as a scoped or singleton service and injected wherever indexing or search happens.
+
+```csharp
+// Example DI registration (Program.cs, in the project — not in framework)
+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();
+});
+builder.Services.AddScoped<EmbeddingService>();
+```
+
+---
+
+## A tabela pgvector
+
+Reference template: `templates/code/sql/ai-agents/pgvector-embeddings-migration.sql.template`
+
+```sql
+CREATE TABLE kb_embeddings (
+    id          uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id   uuid        NOT NULL,
+    source      text        NOT NULL,   -- document identifier / URL
+    chunk_index int         NOT NULL,   -- position within source document
+    content     text        NOT NULL,   -- chunk text returned to the agent
+    embedding   vector(1536) NOT NULL,  -- matches embedding model dimensions
+    metadata    jsonb       NOT NULL DEFAULT '{}',
+    created_at  timestamptz NOT NULL DEFAULT now()
+);
+
+-- HNSW index — cosine distance, production-grade recall
+CREATE INDEX ix_kb_embeddings_hnsw
+    ON kb_embeddings
+    USING hnsw (embedding vector_cosine_ops);
+
+-- Index for tenant filter (applied in every query)
+CREATE INDEX ix_kb_embeddings_tenant
+    ON kb_embeddings (tenant_id);
+```
+
+For pgvector extension setup (`CREATE EXTENSION IF NOT EXISTS vector;`, `UseVector()` on `NpgsqlDataSourceBuilder`, HNSW parameter tuning), see `infrastructure-neon-pgvector`.
+
+> **Dimension match:** `vector(1536)` matches `text-embedding-3-small` (default 1536 dimensions). If the project switches models, re-create the column with the new dimension. Never mix models on a single column.
+
+---
+
+## VectorSearchTool (tool MAF)
+
+Reference template: `templates/code/dotnet/ai-agents/VectorSearchTool.cs.template`
+
+A sealed class with a `[Description]`-decorated method the agent calls when it needs context from the knowledge base.
+
+```csharp
+// Registration — in the agent setup code
+var tool = sp.GetRequiredService<VectorSearchTool>();
+var agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(
+        instructions: systemPrompt,
+        tools: [AIFunctionFactory.Create(tool.SearchAsync)]);
+```
+
+The tool:
+1. Takes a natural-language `query` string (the only parameter the LLM sees).
+2. Calls `EmbeddingService.EmbedAsync(query)` to get a query vector.
+3. Runs a parameterized SQL `SELECT content FROM kb_embeddings WHERE tenant_id = @tenant ORDER BY embedding <=> @queryVec LIMIT 5`.
+4. Concatenates chunk contents and returns them as a single string — the agent uses this as grounding context.
+
+The `tenant_id` filter is **never a tool parameter** (that would allow the LLM to cross tenant boundaries). It is injected via a constructor dependency — e.g., a scoped `ITenantContext` or a `Guid currentTenantId` resolved from the authenticated request. See §Multi-tenant below.
+
+Note on raw Npgsql vs EF Core: this template uses `NpgsqlDataSource` (raw SQL) for the cosine-distance query, since pgvector operators (`<=>`) are easier to express and verify in raw SQL. If the project already wires pgvector through EF Core (`UseVector()`, `HasMethod("hnsw")`), the equivalent `db.Database.SqlQuery<>` form per `infrastructure-neon-pgvector` is equally valid — choose whichever is already in use.
+
+---
+
+## Exemplo de uso
+
+```csharp
+// In an agent feature handler (the project's code)
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+public sealed class KnowledgeAgentHandler(
+    ModelRegistry modelRegistry,
+    VectorSearchTool searchTool,
+    IPromptRepository prompts)
+{
+    public async Task<string> AnswerAsync(string question, CancellationToken ct = default)
+    {
+        var systemPrompt = await prompts.GetActivePromptAsync("knowledge-agent", ct);
+
+        var agent = modelRegistry.GetChatClient("text-default")
+            .AsAIAgent(
+                instructions: systemPrompt,
+                tools: [AIFunctionFactory.Create(searchTool.SearchAsync)]);
+
+        var response = await agent.RunAsync(question, ct);
+        return response.Text;
+    }
+}
+```
+
+The agent decides autonomously when to call `VectorSearchTool.SearchAsync`. It receives the top-k chunks as a string and incorporates them into its response. The handler code stays clean — no manual retrieval loop.
+
+---
+
+## Multi-tenant
+
+Each tenant's knowledge is partitioned by `tenant_id`:
+
+- Every row in `kb_embeddings` has a `tenant_id UUID NOT NULL`.
+- Every query filters on `tenant_id = @tenant` before any cosine-distance ordering.
+- `VectorSearchTool` resolves `tenant_id` from the authenticated request context (injected at construction time) — **never from a tool parameter the LLM supplies**.
+- For database-level enforcement, enable Row-Level Security:
+
+```sql
+ALTER TABLE kb_embeddings ENABLE ROW LEVEL SECURITY;
+-- See the project's RLS policy template (templates/code/sql/postgresql-rls-policy.sql)
+-- for the policy pattern that binds app.current_tenant_id to the session.
+```
+
+> **Rule:** never query across tenants without the filter. One missing `WHERE tenant_id = @tenant` leaks every tenant's data to the requester.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Right way |
+|--------------|----------------|-----------|
+| Hosted RAG (upload PDFs to a service) | Loses control of chunking, embedding, and storage; vendor lock-in | Custom RAG: own all three layers |
+| Embeddings column without an index | Full table scan — 100 ms becomes 30 s at 100k rows | HNSW index on the embedding column always |
+| One fixed chunk size for all document types | Contracts need dense sentences; catalogs need short snippets; mixed chunks degrade recall | Choose strategy per document type (see `data-vector-search-rag-chunking`) |
+| `tenant_id` as a tool parameter the LLM passes | LLM can be prompted to pass any GUID — cross-tenant data leak | Inject `tenant_id` from auth context at construction; never expose as a model-facing parameter |
+| Embedding with model A, querying with model B | Vectors live in different spaces — cosine distance is meaningless | One embedding model per column; re-index when switching models |
+| `ORDER BY similarity DESC` in SQL | `<=>` returns distance (0 = identical), not similarity | `ORDER BY embedding <=> @queryVec` (ascending distance = most similar first) |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] EmbeddingService (concrete class) registered in DI; it injects IEmbeddingGenerator<string, Embedding<float>> for the project's chosen embedding model.
+- [ ] Embedding model declared in `model-registry.json` under the `embeddings` alias.
+- [ ] `kb_embeddings` table has `embedding vector(1536)` and HNSW index with `vector_cosine_ops`.
+- [ ] `tenant_id` column present and filtered in every query.
+- [ ] `VectorSearchTool.SearchAsync` takes only `query` + `ct` — no tenant param visible to the LLM.
+- [ ] `VectorSearchTool` registered on the agent via `AIFunctionFactory.Create(tool.SearchAsync)`.
+- [ ] No `Microsoft.SemanticKernel` references in the project.
+- [ ] Vector dimensions consistent between embedding model and `vector(N)` column definition.
+- [ ] RLS enabled on `kb_embeddings` (or equivalent app-level guard documented in `decisions.md`).
+- [ ] Re-indexing strategy documented when document content changes (content hash check).
+
+---
+
+## References
+
+- `ai-agents-setup` — MAF packages, `AsAIAgent`, `AIFunctionFactory.Create`
+- `ai-agents-providers-model-registry` — `embeddings` alias, `IEmbeddingGenerator` wiring
+- `data-vector-search-rag-chunking` — chunk strategies per document type
+- `infrastructure-neon-pgvector` — extension setup, `UseVector()`, HNSW parameter tuning
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/rag-custom-pgvector.md v1.0 (2026-05-19)*