@polymorphism-tech/morph-spec 7.4.0 → 7.6.0

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

@@ -1,243 +1,246 @@
-# 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)*
+# 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.
+
+> **This is the default.** `Microsoft.Extensions.VectorData` (see `ai-agents-vector-data-extensions`) is Microsoft's official, provider-agnostic vector-store abstraction, but its Postgres connector is still a prerelease package as of last-verified date. Adopt VectorData only when genuine multi-backend portability is required — do not migrate this working implementation to a preview dependency by default.
+
+---
+
+## 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
+- `ai-agents-vector-data-extensions` — the official `Microsoft.Extensions.VectorData` abstraction, and when it's worth adopting instead of this custom implementation
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/rag-custom-pgvector.md v1.0 (2026-05-19)*

package/framework/standards/ai-agents/setup.md

@@ -76,6 +76,8 @@ Está adicionando um agente AI a um projeto .NET?
 - `Microsoft.Extensions.AI.OpenAI` 9.* — replaced by `Microsoft.Agents.AI.OpenAI` in GA.
 - Hosted agent services (Foundry Agent Service, etc.) — use direct models.
 
+> **Exceção — conectores de Vector Store:** the ban above targets the SK **orchestration** surface (`Kernel`, `KernelFunction`, `ChatHistory`, `Kernel.InvokePromptAsync()`). It does **not** apply to `Microsoft.SemanticKernel.Connectors.*` packages (PgVector, Qdrant, SqlServer, CosmosNoSQL, InMemory) — those are `Microsoft.Extensions.VectorData` backend connectors with zero SK orchestration code, despite the package name. See `ai-agents-vector-data-extensions` before treating one of these as forbidden.
+
 ---
 
 ## 2. Quick Start (canonical minimal agent)
@@ -250,6 +252,7 @@ var instrumented = agent.WithOpenTelemetry();
 - `ai-agents-providers-model-registry` — provider-agnostic pattern
 - `ai-agents-structured-output` (Onda 2) — typed responses
 - `ai-agents-middleware-patterns` (Onda 2) — telemetry, retry, anti-hallucination, streaming agent responses
+- `ai-agents-vector-data-extensions` — the `Microsoft.SemanticKernel.Connectors.*` exception to the Forbidden list above
 - Microsoft.Agents.AI docs: https://learn.microsoft.com/agent-framework/
 - Verified packages list (context7 /microsoft/agent-framework): retrieved 2026-05-19