@polymorphism-tech/morph-spec 8.45.0 → 8.47.0

package/framework/standards/backend/database/vector-search-rag.md

@@ -1,11 +1,13 @@
 # Vector Search + RAG — EF Core 10 + pgvector (.NET 10)
 
-> **Scope:** blazor-azure
+> **Scope:** backend/database — pipeline RAG sobre pgvector
 > **Layer:** 2 (on keyword)
 > **Keywords:** postgres, pgvector, vector, embedding, search, rag, ai
 > **Load When:** vector search or rag keywords detected
 
-EF Core 10 (.NET 10) com PostgreSQL + extensão `pgvector` para vector search em workloads de AI. Para a modelagem da coluna `vector`, índices `ivfflat`/`hnsw` e os operadores de distância do `pgvector`, ver `infrastructure/neon/neon-pgvector.md` — este standard cobre o pipeline RAG end-to-end (embeddings, search, geração) sobre essa base.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + Npgsql.EntityFrameworkCore.PostgreSQL 10.0.3 + Pgvector.EntityFrameworkCore 0.3.0 + Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08). Os blocos de indexação, indexação em lote, busca+geração (RAG), endpoint e job compilam com `TreatWarningsAsErrors` sobre o `Result`/`IHandler`/`ErrorHttpMapping` de `result-pattern.md`/`vertical-slice.md` e o `Document`/`ApplicationDbContext` de `neon-pgvector.md`; o registro do `IEmbeddingGenerator` por provedor, os custos e o SQL são verificação documental. Last-verified: 2026-10-03.
+
+EF Core 10 (.NET 10) com PostgreSQL + extensão `pgvector` para vector search em workloads de AI. A modelagem da coluna `vector` (`Document`, `DocumentConfiguration`, `UseVector()`, colunas snake_case), os índices `hnsw`/`ivfflat` e os operadores de distância estão em `infrastructure/neon/neon-pgvector.md` — este standard cobre o pipeline RAG end-to-end (embeddings, busca, geração) em slices VSA sobre essa base: cada operação é um handler que injeta o `ApplicationDbContext` e o `IEmbeddingGenerator` direto, sem `EmbeddingService`/`SearchService` no meio.
 
 ---
 
@@ -42,76 +44,23 @@ Texto → Embedding (vetor de números) → Busca por similaridade
 
 ```xml
 <!-- .csproj -->
-<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.0" />
-<PackageReference Include="Pgvector.EntityFrameworkCore" Version="0.2.2" />
-<PackageReference Include="Microsoft.Extensions.AI" Version="9.9.1" />
+<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.3" />
+<PackageReference Include="Pgvector.EntityFrameworkCore" Version="0.3.0" />
+<PackageReference Include="Microsoft.Extensions.AI" Version="10.9.0" />
+<PackageReference Include="Microsoft.Agents.AI" Version="1.20.0" />
 ```
 
-### 2. PostgreSQL + pgvector Requerido
+As versões de IA vêm do pin (`framework/ai-pin.json`). A ponte do provedor (`Microsoft.Extensions.AI.OpenAI` para `.AsIEmbeddingGenerator()`) não está no pin e tem uma armadilha de restore (NU1608 contra `OpenAI` 2.13.0): ver `ai-agents/setup.md`.
 
-**Requisito:** PostgreSQL com a extensão `pgvector` instalada (`CREATE EXTENSION vector;`).
-Neon, Supabase e Azure Database for PostgreSQL já trazem `pgvector` disponível.
+### 2. PostgreSQL + pgvector Requerido
 
-**Nota:** habilite a extensão via migration EF Core — `migrationBuilder.Sql("CREATE EXTENSION IF NOT EXISTS vector;")` — antes de criar as colunas de vetor.
+**Requisito:** PostgreSQL com a extensão `pgvector` (`CREATE EXTENSION vector;`). Neon já traz `pgvector` disponível. Registre `modelBuilder.HasPostgresExtension("vector")` no `OnModelCreating` e a migration EF Core cria a extensão antes das colunas de vetor.
 
 ---
 
 ## 🗄️ Modelo de Dados com Vectors
 
-### Entidade com Embedding
-
-```csharp
-using Microsoft.EntityFrameworkCore;
-using Pgvector;
-
-public class Document
-{
-    public int Id { get; set; }
-    public string Title { get; set; } = null!;
-    public string Content { get; set; } = null!;
-    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
-
-    // Vector embedding (1536 dimensões para text-embedding-3-small).
-    // O tipo `Vector` vem do pacote Pgvector — EF Core não mapeia `float[]`.
-    public Vector Embedding { get; set; } = null!;
-}
-```
-
-### DbContext Configuração
-
-```csharp
-public class AppDbContext : DbContext
-{
-    public DbSet<Document> Documents { get; set; }
-
-    protected override void OnModelCreating(ModelBuilder modelBuilder)
-    {
-        // Registra a extensão pgvector — gera `CREATE EXTENSION vector` na migration
-        modelBuilder.HasPostgresExtension("vector");
-
-        modelBuilder.Entity<Document>(entity =>
-        {
-            entity.HasKey(d => d.Id);
-
-            // Configurar coluna de vector
-            entity.Property(d => d.Embedding)
-                .HasColumnType("vector(1536)") // 1536 = dimensões do embedding
-                .IsRequired();
-
-            // Índice de vector para performance — operador de distância cosseno
-            entity.HasIndex(d => d.Embedding)
-                .HasMethod("hnsw") // ou "ivfflat"
-                .HasOperators("vector_cosine_ops")
-                .HasStorageParameter("m", 16)
-                .HasStorageParameter("ef_construction", 64);
-        });
-    }
-}
-```
-
-> O provider Npgsql precisa de `UseVector()` no `NpgsqlDataSourceBuilder` (ou
-> no `UseNpgsql(...)`) para mapear o tipo `vector` — ver a configuração do
-> `Program.cs` abaixo e `infrastructure/neon/neon-pgvector.md`.
+Use o `Document` e o `DocumentConfiguration` de `infrastructure/neon/neon-pgvector.md`: `Id` `Guid` gerado no handler com `Guid.CreateVersion7()`, `Embedding` do tipo `Pgvector.Vector` com `vector(1536)` (EF Core não mapeia `float[]`), índice `hnsw` com `vector_cosine_ops`, `UseVector()` dentro do `UseNpgsql(...)` e colunas snake_case via `HasColumnName`.
 
 ### Migration
 
@@ -120,149 +69,60 @@ dotnet ef migrations add AddVectorSearch
 dotnet ef database update
 ```
 
-**SQL Gerado:**
+**SQL Gerado (essencial):**
 ```sql
 CREATE EXTENSION IF NOT EXISTS vector;
-ALTER TABLE "Documents" ADD "Embedding" vector(1536) NOT NULL;
-CREATE INDEX "IX_Documents_Embedding" ON "Documents"
-  USING hnsw ("Embedding" vector_cosine_ops) WITH (m = 16, ef_construction = 64);
+CREATE TABLE documents (
+  id uuid NOT NULL PRIMARY KEY,
+  title text NOT NULL,
+  content text NOT NULL,
+  metadata jsonb,
+  embedding vector(1536),
+  created_at timestamp with time zone NOT NULL
+);
+CREATE INDEX ix_documents_embedding ON documents
+  USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);
 ```
 
 ---
 
 ## 🔢 Gerando Embeddings
 
-### Serviço de Embedding
+O handler injeta `IEmbeddingGenerator<string, Embedding<float>>` (de `Microsoft.Extensions.AI`) e converte o resultado em `Pgvector.Vector`:
 
 ```csharp
-using Microsoft.Extensions.AI;
-using Pgvector;
-
-public interface IEmbeddingService
-{
-    Task<Vector> GenerateEmbeddingAsync(string text, CancellationToken ct = default);
-}
-
-public class EmbeddingService : IEmbeddingService
-{
-    private readonly IEmbeddingGenerator<string, Embedding<float>> _embeddingGenerator;
-
-    public EmbeddingService(IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator)
-    {
-        _embeddingGenerator = embeddingGenerator;
-    }
-
-    public async Task<Vector> GenerateEmbeddingAsync(
-        string text,
-        CancellationToken ct = default)
-    {
-        // GenerateVectorAsync devolve o ReadOnlyMemory<float> diretamente
-        var vector = await _embeddingGenerator.GenerateVectorAsync(text, cancellationToken: ct);
-        return new Vector(vector);
-    }
-}
+var vector = new Vector(await embeddings.GenerateVectorAsync(text, cancellationToken: cancellationToken));
 ```
 
-### Configuração no Program.cs
-
-```csharp
-using Azure.AI.OpenAI;
-using Microsoft.Extensions.AI;
-using System.ClientModel;
-
-// DbContext com o type handler do pgvector registrado
-builder.Services.AddDbContext<AppDbContext>(options =>
-    options.UseNpgsql(
-        builder.Configuration.GetConnectionString("Default"),
-        npgsql => npgsql.UseVector()));
+`GenerateVectorAsync` devolve `ReadOnlyMemory<float>` para um texto; para muitos textos use `GenerateAsync(IEnumerable<string>)`, que faz **uma** chamada ao provedor (ver *Indexação em lote*).
 
-// Embedding generator do Azure OpenAI exposto como IEmbeddingGenerator
-builder.Services.AddSingleton<IEmbeddingGenerator<string, Embedding<float>>>(sp =>
-{
-    var config = sp.GetRequiredService<IConfiguration>();
-
-    var azureClient = new AzureOpenAIClient(
-        new Uri(config["AzureOpenAI:Endpoint"]!),
-        new ApiKeyCredential(config["AzureOpenAI:ApiKey"]!));
-
-    return azureClient
-        .GetEmbeddingClient("text-embedding-3-small") // 1536 dimensões
-        .AsIEmbeddingGenerator();
-});
-
-builder.Services.AddScoped<IEmbeddingService, EmbeddingService>();
-```
+**Registro no DI:** o projeto registra o `IEmbeddingGenerator` do provedor escolhido pelo alias `embeddings` do Model Registry — o exemplo de registro OpenAI está em `ai-agents/rag-custom-pgvector.md` (*EmbeddingService*, a parte do `AddSingleton<IEmbeddingGenerator<...>>`), e a escolha de modelo em `ai-agents-providers-model-registry`. A chave do provedor vem de configuração (user-secrets em dev, variável de ambiente no Coolify), nunca do código. O `DbContext` é registrado como em `neon-pgvector.md` (*DbContext Setup*).
 
 ---
 
 ## 🔍 Vector Search com EF Core 10
 
-### Query de Similaridade
+A busca semântica pura (endpoint de busca, sem LLM) é a slice `SearchDocuments` de `infrastructure/neon/neon-pgvector.md` (*Search handler*). O padrão de query, que o RAG abaixo repete dentro da própria slice:
 
 ```csharp
-using Microsoft.EntityFrameworkCore;
-
-public class DocumentSearchService
-{
-    private readonly AppDbContext _context;
-    private readonly IEmbeddingService _embeddingService;
-
-    public DocumentSearchService(
-        AppDbContext context,
-        IEmbeddingService embeddingService)
-    {
-        _context = context;
-        _embeddingService = embeddingService;
-    }
-
-    public async Task<List<DocumentSearchResult>> SearchAsync(
-        string query,
-        int limit = 5,
-        CancellationToken ct = default)
-    {
-        // 1. Gerar embedding da query
-        var queryEmbedding = await _embeddingService.GenerateEmbeddingAsync(query, ct);
-
-        // 2. Buscar documentos similares — EF.Functions.CosineDistance traduz para
-        //    o operador `<=>` do pgvector e usa o índice HNSW vector_cosine_ops
-        var results = await _context.Documents
-            .Select(d => new DocumentSearchResult
-            {
-                Document = d,
-                // Distância cosseno (menor = mais similar)
-                Distance = EF.Functions.CosineDistance(d.Embedding, queryEmbedding)
-            })
-            .OrderBy(r => r.Distance)
-            .Take(limit)
-            .ToListAsync(ct);
-
-        return results;
-    }
-}
-
-public class DocumentSearchResult
-{
-    public Document Document { get; set; } = null!;
-    public double Distance { get; set; }
-    public double Similarity => 1 - Distance; // Converter distância em similaridade
-}
+.Where(d => d.Embedding != null)
+.Select(d => new { d.Id, d.Title, d.Content, Distance = d.Embedding!.CosineDistance(query) })
+.OrderBy(x => x.Distance)
+.Take(limit)
 ```
 
+Traduz para `ORDER BY d.embedding <=> @query` (ASC), que usa o índice HNSW `vector_cosine_ops`. Similaridade = `1 - distância`.
+
 ### Funções de Distância
 
-O `Pgvector.EntityFrameworkCore` expõe as funções de distância como métodos
-`EF.Functions.*`, cada uma traduzida para o operador correspondente do `pgvector`:
+O `Pgvector.EntityFrameworkCore` expõe as distâncias como métodos de extensão sobre `Vector` (namespace `Pgvector.EntityFrameworkCore`), cada um traduzido para o operador correspondente do `pgvector`:
 
-| Função (`EF.Functions.*`) | Operador pgvector | Quando Usar |
-|---------------------------|-------------------|-------------|
+| Método | Operador pgvector | Quando Usar |
+|--------|-------------------|-------------|
 | `CosineDistance` | `<=>` | **Recomendado** para texto / embeddings normalizados |
 | `L2Distance` | `<->` | Distância euclidiana — dados numéricos |
 | `MaxInnerProduct` | `<#>` | Produto interno negativo — vetores normalizados |
 
-```csharp
-EF.Functions.CosineDistance(d.Embedding, queryEmbedding)
-```
-
 > O `HasOperators` do índice precisa casar com a função usada na query —
 > `vector_cosine_ops` para `CosineDistance`, `vector_l2_ops` para `L2Distance`,
 > `vector_ip_ops` para `MaxInnerProduct`. Operador e índice divergentes fazem o
@@ -272,201 +132,224 @@ EF.Functions.CosineDistance(d.Embedding, queryEmbedding)
 
 ## 🤖 RAG Pattern Completo
 
-### Implementação RAG com Agent Framework
+### Slice `AskDocuments` (retrieval + augmentation + generation)
 
 ```csharp
+// Features/KnowledgeFeature/AskDocuments/AskDocumentsHandler.cs
+using Microsoft.Agents.AI;
+using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.AI;
+using Pgvector;
+using Pgvector.EntityFrameworkCore;
+
+public sealed record AskDocumentsRequest(string Question);
+public sealed record AskDocumentsResponse(string Answer, IReadOnlyList<Guid> SourceDocumentIds);
 
-public interface IDocumentAssistantAgent
+public static class KnowledgeErrors
 {
-    Task<string> AskQuestionAsync(string question, CancellationToken ct = default);
+    public static readonly Error NoRelevantDocuments =
+        Error.NotFound("Knowledge.NoRelevantDocuments", "Nenhum documento relevante para a pergunta.");
 }
 
-public class DocumentAssistantAgent : IDocumentAssistantAgent
+public sealed class AskDocumentsHandler(
+    ApplicationDbContext db,
+    IEmbeddingGenerator<string, Embedding<float>> embeddings,
+    IChatClient chatClient)
+    : IHandler<AskDocumentsRequest, Result<AskDocumentsResponse>>
 {
-    private readonly IChatClient _chatClient;
-    private readonly DocumentSearchService _searchService;
-    private readonly ILogger<DocumentAssistantAgent> _logger;
-
-    public DocumentAssistantAgent(
-        IChatClient chatClient,
-        DocumentSearchService searchService,
-        ILogger<DocumentAssistantAgent> logger)
-    {
-        _chatClient = chatClient;
-        _searchService = searchService;
-        _logger = logger;
-    }
+    private const int TopK = 3;
+    private const double MaxDistance = 0.5;
 
-    public async Task<string> AskQuestionAsync(string question, CancellationToken ct = default)
+    public async Task<Result<AskDocumentsResponse>> HandleAsync(
+        AskDocumentsRequest request, CancellationToken cancellationToken)
     {
-        // 1. Retrieval: Buscar documentos relevantes
-        var relevantDocs = await _searchService.SearchAsync(question, limit: 3, ct);
-
-        _logger.LogInformation(
-            "Encontrados {Count} documentos relevantes para: {Question}",
-            relevantDocs.Count,
-            question
-        );
-
-        // 2. Construir contexto
-        var context = string.Join("\n\n", relevantDocs.Select(r =>
-            $"[Documento {r.Document.Id} - Similaridade: {r.Similarity:P0}]\n" +
-            $"Título: {r.Document.Title}\n" +
-            $"Conteúdo: {r.Document.Content}"
-        ));
-
-        // 3. Augmentation: Criar agente com contexto
-        // VERIFY: _chatClient.CreateAgent / agent.RunAsync — superfície MAF; alinhar com o MAF Framework Revamp em andamento
-        var agent = _chatClient.CreateAgent(
-            instructions: """
+        var query = new Vector(await embeddings.GenerateVectorAsync(request.Question, cancellationToken: cancellationToken));
+
+        var relevant = await db.Documents
+            .Where(d => d.Embedding != null)
+            .Select(d => new { d.Id, d.Title, d.Content, Distance = d.Embedding!.CosineDistance(query) })
+            .Where(x => x.Distance <= MaxDistance)
+            .OrderBy(x => x.Distance)
+            .Take(TopK)
+            .ToListAsync(cancellationToken);
+
+        if (relevant.Count == 0)
+            return KnowledgeErrors.NoRelevantDocuments;
+
+        var context = string.Join("\n\n", relevant.Select(r =>
+            $"[Documento {r.Id} - Similaridade: {1 - r.Distance:P0}]\nTítulo: {r.Title}\nConteúdo: {r.Content}"));
+
+        var agent = chatClient.AsAIAgent(
+            instructions: $"""
                 Você é um assistente que responde perguntas baseado em documentos fornecidos.
 
                 Regras:
-                1. Use APENAS informações dos documentos fornecidos
-                2. Se a informação não estiver nos documentos, diga "Não encontrei informação sobre isso"
-                3. Cite o número do documento ao responder
-                4. Seja conciso e objetivo
+                - Use APENAS informações dos documentos fornecidos
+                - Se a informação não estiver nos documentos, diga "Não encontrei informação sobre isso"
+                - Cite o identificador do documento ao responder
+                - Seja conciso e objetivo
 
                 Documentos disponíveis:
-                """ + context,
-            name: "DocumentAssistant"
-        );
+                {context}
+                """,
+            name: "DocumentAssistant");
 
-        // 4. Generation: Gerar resposta
-        var response = await agent.RunAsync(question, cancellationToken: ct);
+        var response = await agent.RunAsync(request.Question, cancellationToken: cancellationToken);
 
-        return response.Content;
+        return new AskDocumentsResponse(response.Text, relevant.Select(r => r.Id).ToList());
     }
 }
 ```
 
-### Uso no Blazor
-
-```razor
-@page "/ask"
-@inject IDocumentAssistantAgent Assistant
+- Sem documento relevante, a slice devolve `NotFound` **antes** de chamar o LLM — não paga uma geração para responder "não sei".
+- O `IChatClient` vem do DI; com Model Registry, resolva-o pelo alias (`ai-agents/rag-custom-pgvector.md` → *Exemplo de uso*). Se o agente deve decidir **quando** buscar, exponha a busca como tool (`AIFunctionFactory.Create`) em vez de injetar o contexto — também em `rag-custom-pgvector.md`.
+- O prompt fica inline aqui por brevidade; em produção ele vem de `IPromptRepository` (`ai-agents/prompt-sources.md`).
 
-<h3>Assistente de Documentos</h3>
+### Endpoint
 
-<EditForm Model="_input" OnValidSubmit="AskQuestion">
-    <InputText @bind-Value="_input.Question" placeholder="Faça uma pergunta..." />
-    <button type="submit" disabled="@_isLoading">Perguntar</button>
-</EditForm>
+```csharp
+// Features/KnowledgeFeature/AskDocuments/AskDocumentsEndpoint.cs
+using ProjectName.Abstractions;
+using ProjectName.Extensions;
 
-@if (_isLoading)
-{
-    <p>Buscando resposta...</p>
-}
-else if (!string.IsNullOrEmpty(_answer))
+internal sealed class AskDocumentsEndpoint : IApiEndpoint
 {
-    <div class="answer">
-        <strong>Resposta:</strong>
-        <p>@_answer</p>
-    </div>
-}
-
-@code {
-    private QuestionInput _input = new();
-    private string _answer = "";
-    private bool _isLoading;
-
-    private async Task AskQuestion()
+    public void MapEndpoint(IEndpointRouteBuilder app)
     {
-        _isLoading = true;
-        _answer = "";
-
-        try
+        app.MapPost("knowledge/ask", async (
+            IHandler<AskDocumentsRequest, Result<AskDocumentsResponse>> handler,
+            AskDocumentsRequest request,
+            CancellationToken cancellationToken) =>
         {
-            _answer = await Assistant.AskQuestionAsync(_input.Question);
-        }
-        finally
-        {
-            _isLoading = false;
-        }
-    }
-
-    public class QuestionInput
-    {
-        public string Question { get; set; } = "";
+            var result = await handler.HandleAsync(request, cancellationToken);
+            return result.Match(
+                onSuccess: response => Results.Ok(response),
+                onFailure: error => error.ToHttpResult());
+        })
+        .Produces<AskDocumentsResponse>(StatusCodes.Status200OK)
+        .ProducesProblem(StatusCodes.Status400BadRequest)
+        .ProducesProblem(StatusCodes.Status404NotFound);
     }
 }
 ```
 
+O frontend Next.js chama `knowledge/ask` pelo proxy com TanStack Query (`useMutation`), como qualquer outro endpoint — a UI não fala com o banco nem com o provedor de IA.
+
 ---
 
 ## 📥 Indexação de Documentos
 
-### Serviço de Indexação
+### Slice `IndexDocument`
 
 ```csharp
-public class DocumentIndexingService
-{
-    private readonly AppDbContext _context;
-    private readonly IEmbeddingService _embeddingService;
+// Features/KnowledgeFeature/IndexDocument/IndexDocumentHandler.cs
+using Microsoft.Extensions.AI;
+using Pgvector;
+
+public sealed record IndexDocumentRequest(string Title, string Content);
+public sealed record IndexDocumentResponse(Guid Id);
 
-    public async Task IndexDocumentAsync(
-        string title,
-        string content,
-        CancellationToken ct = default)
+public sealed class IndexDocumentHandler(
+    ApplicationDbContext db,
+    IEmbeddingGenerator<string, Embedding<float>> embeddings,
+    TimeProvider timeProvider)
+    : IHandler<IndexDocumentRequest, Result<IndexDocumentResponse>>
+{
+    public async Task<Result<IndexDocumentResponse>> HandleAsync(
+        IndexDocumentRequest request, CancellationToken cancellationToken)
     {
-        // 1. Gerar embedding do conteúdo
-        var embedding = await _embeddingService.GenerateEmbeddingAsync(
-            $"{title}\n{content}", // Combinar título e conteúdo
-            ct
-        );
+        var embedding = await embeddings.GenerateVectorAsync(
+            $"{request.Title}\n{request.Content}", cancellationToken: cancellationToken);
 
-        // 2. Criar documento
         var document = new Document
         {
-            Title = title,
-            Content = content,
-            Embedding = embedding,
-            CreatedAt = DateTime.UtcNow
+            Id = Guid.CreateVersion7(),
+            Title = request.Title,
+            Content = request.Content,
+            Embedding = new Vector(embedding),
+            CreatedAt = timeProvider.GetUtcNow()
         };
 
-        // 3. Salvar no banco
-        _context.Documents.Add(document);
-        await _context.SaveChangesAsync(ct);
+        db.Documents.Add(document);
+        await db.SaveChangesAsync(cancellationToken);
+
+        return new IndexDocumentResponse(document.Id);
     }
+}
+```
+
+### Indexação em lote
 
-    public async Task BulkIndexAsync(
-        List<(string Title, string Content)> documents,
-        CancellationToken ct = default)
+Uma chamada ao provedor por lote, um `SaveChangesAsync` por lote — nunca um loop que chama a slice unitária N vezes:
+
+```csharp
+// Features/KnowledgeFeature/IndexDocuments/IndexDocumentsHandler.cs
+using Microsoft.Extensions.AI;
+using Pgvector;
+
+public sealed record IndexDocumentsRequest(IReadOnlyList<IndexDocumentRequest> Documents);
+
+public sealed class IndexDocumentsHandler(
+    ApplicationDbContext db,
+    IEmbeddingGenerator<string, Embedding<float>> embeddings,
+    TimeProvider timeProvider)
+    : IHandler<IndexDocumentsRequest, Result<int>>
+{
+    public async Task<Result<int>> HandleAsync(IndexDocumentsRequest request, CancellationToken cancellationToken)
     {
-        foreach (var (title, content) in documents)
+        var generated = await embeddings.GenerateAsync(
+            request.Documents.Select(d => $"{d.Title}\n{d.Content}"), cancellationToken: cancellationToken);
+
+        var now = timeProvider.GetUtcNow();
+        db.Documents.AddRange(request.Documents.Zip(generated, (doc, embedding) => new Document
         {
-            await IndexDocumentAsync(title, content, ct);
-        }
+            Id = Guid.CreateVersion7(),
+            Title = doc.Title,
+            Content = doc.Content,
+            Embedding = new Vector(embedding.Vector),
+            CreatedAt = now
+        }));
+
+        return await db.SaveChangesAsync(cancellationToken);
     }
 }
 ```
 
-### Job de Indexação com Hangfire
+Lotes grandes: fatie a lista (ex.: 100 textos por chamada) para ficar abaixo do limite de tokens por request do provedor. Chunking por tipo de documento e ingestão delta por lookup-key: `ai-agents/rag-custom-pgvector.md`.
+
+### Job de Indexação com Hangfire (só com razão real)
+
+Reindexar uma fonte externa todo dia é razão real para um job; indexar o upload de um usuário não é — chame a slice no próprio request. O job é um ponto de entrada fino que chama o handler (`backend/integrations/hangfire/hangfire-jobs.md`):
 
 ```csharp
-public class DocumentIndexingJob
+// Features/KnowledgeFeature/IndexDocuments/ReindexKnowledgeJob.cs
+using Microsoft.Extensions.Logging;
+
+public interface IKnowledgeSource
 {
-    private readonly DocumentIndexingService _indexingService;
-    private readonly IDocumentProvider _documentProvider;
+    Task<IReadOnlyList<IndexDocumentRequest>> FetchAllAsync(CancellationToken cancellationToken);
+}
 
-    public async Task IndexAllDocumentsAsync()
+public sealed class ReindexKnowledgeJob(
+    IKnowledgeSource source,
+    IHandler<IndexDocumentsRequest, Result<int>> handler,
+    ILogger<ReindexKnowledgeJob> logger)
+{
+    public async Task RunAsync(CancellationToken cancellationToken)
     {
-        // Buscar documentos de fonte externa (API, arquivos, etc.)
-        var documents = await _documentProvider.GetAllDocumentsAsync();
+        var documents = await source.FetchAllAsync(cancellationToken);
+        var result = await handler.HandleAsync(new IndexDocumentsRequest(documents), cancellationToken);
 
-        await _indexingService.BulkIndexAsync(documents);
+        if (result.IsFailure)
+            logger.LogWarning("Reindexação falhou: {Code}", result.Error.Code);
+        else
+            logger.LogInformation("Reindexados {Count} documentos", result.Value);
     }
 }
-
-// Program.cs - Agendar job diário
-RecurringJob.AddOrUpdate<DocumentIndexingJob>(
-    "index-documents",
-    job => job.IndexAllDocumentsAsync(),
-    Cron.Daily
-);
 ```
 
+Agendamento diário (UTC), no `Program.cs`: `RecurringJob.AddOrUpdate<ReindexKnowledgeJob>("reindex-knowledge", job => job.RunAsync(CancellationToken.None), Cron.Daily());` — o Hangfire troca o `CancellationToken.None` pelo token de cancelamento do job.
+
 ---
 
 ## 📊 Índices de Performance
@@ -522,7 +405,7 @@ HNSW é o padrão recomendado: melhor recall e não exige dados pré-carregados.
 | text-embedding-3-small | 1536 | $0.02 / 1M tokens |
 | text-embedding-3-large | 3072 | $0.13 / 1M tokens |
 
-**Recomendação:** Use `text-embedding-3-small` (melhor custo-benefício).
+**Recomendação:** Use `text-embedding-3-small` (melhor custo-benefício). Confira o preço vigente no provedor antes de orçar.
 
 ### Storage
 
@@ -535,15 +418,15 @@ HNSW é o padrão recomendado: melhor recall e não exige dados pré-carregados.
 
 ## ✅ Checklist de Implementação
 
-- [ ] EF Core 10 + `Npgsql.EntityFrameworkCore.PostgreSQL` + `Pgvector.EntityFrameworkCore` instalados
+- [ ] `Npgsql.EntityFrameworkCore.PostgreSQL` + `Pgvector.EntityFrameworkCore` instalados; versões de IA do pin
 - [ ] PostgreSQL com extensão `pgvector` (`HasPostgresExtension("vector")`)
 - [ ] `UseVector()` chamado no `UseNpgsql(...)`
-- [ ] Entidade com propriedade `Pgvector.Vector`
+- [ ] Entidade com propriedade `Pgvector.Vector`, `Id` via `Guid.CreateVersion7()`, `CreatedAt` via `TimeProvider`
 - [ ] Índice de vector criado (`hnsw` ou `ivfflat`) com `HasOperators("vector_cosine_ops")`
-- [ ] `IEmbeddingService` configurado
-- [ ] Serviço de search implementado com `EF.Functions.CosineDistance`
-- [ ] RAG pattern com Agent Framework
-- [ ] Job de indexação configurado
+- [ ] `IEmbeddingGenerator<string, Embedding<float>>` registrado no DI e injetado **direto** nos handlers (sem `EmbeddingService`/`SearchService`)
+- [ ] Busca com `CosineDistance` + `OrderBy` da distância
+- [ ] Slice RAG devolve `Result`, com `NotFound` quando não há documento relevante; endpoint mapeia com `error.ToHttpResult()`
+- [ ] Indexação em lote com `GenerateAsync(IEnumerable<string>)`; job Hangfire só com razão real
 - [ ] Testes de similaridade funcionando
 
 ---
@@ -554,22 +437,21 @@ HNSW é o padrão recomendado: melhor recall e não exige dados pré-carregados.
 
 **Causa:** extensão `pgvector` não instalada no banco.
 
-**Solução:** rode `CREATE EXTENSION vector;` — ou registre `HasPostgresExtension("vector")`
-no `OnModelCreating` para que a migration EF Core a crie automaticamente.
+**Solução:** registre `HasPostgresExtension("vector")` no `OnModelCreating` para que a migration EF Core a crie (ou rode `CREATE EXTENSION vector;`).
 
 ### Erro: "column ... is of type vector but expression is of type ..."
 
 **Causa:** `UseVector()` não foi chamado — o Npgsql não mapeia o tipo `vector`.
 
 **Solução:** chame `npgsql.UseVector()` no `UseNpgsql(...)` (ou `UseVector()` no
-`NpgsqlDataSourceBuilder`).
+`NpgsqlDataSourceBuilder` quando usa Npgsql sem EF Core).
 
 ### Performance lenta em queries
 
 **Causa:** índice não criado, ou operador da query difere do `HasOperators` do índice.
 
 **Solução:**
-- Verifique se o índice existe: `SELECT * FROM pg_indexes WHERE indexname LIKE '%Embedding%'`
+- Verifique se o índice existe: `SELECT * FROM pg_indexes WHERE indexname LIKE '%embedding%'`
 - Confirme com `EXPLAIN ANALYZE` que a query usa o índice (e não `Seq Scan`)
 - Garanta que o operador casa: `CosineDistance` ↔ `vector_cosine_ops`
 - Ajuste parâmetros `m`/`ef_construction` (HNSW) ou `lists` (IVFFlat)
@@ -581,18 +463,19 @@ no `OnModelCreating` para que a migration EF Core a crie automaticamente.
 **Solução:**
 - `text-embedding-3-small` → 1536 dimensões
 - `text-embedding-3-large` → 3072 dimensões
-- Atualize `vector(N)` na migration
+- Atualize `vector(N)` na configuração e gere nova migration
 
 ---
 
 ## 📚 Referências
 
 - [pgvector](https://github.com/pgvector/pgvector) — extensão PostgreSQL para vector search
-- [Pgvector.EntityFrameworkCore](https://github.com/pgvector/pgvector-dotnet) — type handler + `EF.Functions` de distância
+- [Pgvector.EntityFrameworkCore](https://github.com/pgvector/pgvector-dotnet) — type handler + métodos de distância
 - [Npgsql EF Core Provider](https://www.npgsql.org/efcore/) — `UseVector()`, `HasPostgresExtension`
 - [Microsoft.Extensions.AI - Embeddings](https://learn.microsoft.com/dotnet/ai/microsoft-extensions-ai)
 - [OpenAI Embeddings](https://platform.openai.com/docs/guides/embeddings)
-- `infrastructure/neon/neon-pgvector.md` — modelagem da coluna, índices e operadores pgvector
+- `infrastructure/neon/neon-pgvector.md` — modelagem da coluna, índices, operadores e a slice de busca
+- `ai-agents/rag-custom-pgvector.md` — chunking, ingestão delta, RAG como tool, registro do `IEmbeddingGenerator`
 
 ---