Hybrid search in .NET con Qdrant, BM25 e Ollama

# a ogni ricerca
dense_hits  = vector_search(embed(q), top=20)   # semantica
sparse_hits = bm25_search(q, top=20)            # keyword esatte

# fusione per POSIZIONE, non per punteggio
for hit in dense_hits + sparse_hits:
    score[hit.id] += 1 / (k + rank(hit))        # RRF

return top(score, limit)                        # una sola classifica

name: hybrid-search-dotnet-qdrant-ollama

# External dependencies only: the ASP.NET Core app runs on the host with
# `dotnet run` and talks to these services on localhost. `docker compose up -d`
# starts Qdrant, Ollama, Redis 8 and MongoDB, and pulls the two models into
# the Ollama volume. MongoDB uses host port 27018 to avoid the 27017 conflict.
services:
  qdrant:
    image: qdrant/qdrant:v1.18.1
    container_name: hybrid-search-qdrant
    ports:
      - "6333:6333"   # REST + web dashboard (http://localhost:6333/dashboard)
      - "6334:6334"   # gRPC — the .NET client (Qdrant.Client) uses this one
    volumes:
      - qdrant-data:/qdrant/storage
    healthcheck:
      test: ["CMD-SHELL", "bash -c ':> /dev/tcp/127.0.0.1/6333' || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 15
    restart: unless-stopped

  ollama:
    image: ollama/ollama:latest
    container_name: hybrid-search-ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    healthcheck:
      test: ["CMD-SHELL", "ollama list >/dev/null 2>&1 || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 15
    restart: unless-stopped

  # One-shot init: waits for Ollama to be healthy, pulls both models, exits.
  # nomic-embed-text feeds the vectors; llama3.1 answers the RAG questions.
  ollama-init:
    image: ollama/ollama:latest
    depends_on:
      ollama:
        condition: service_healthy
    environment:
      - OLLAMA_HOST=ollama:11434
    entrypoint: ["/bin/sh", "-c", "ollama pull nomic-embed-text && ollama pull llama3.1"]
    restart: "no"

  # Redis backs the OUTPUT cache (/users responses) and the exact-match
  # cache of the chat pipeline. The SEMANTIC cache lives in Qdrant.
  redis:
    image: redis:8
    container_name: hybrid-search-redis
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    command: ["redis-server", "--save", "60", "1"]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 15
    restart: unless-stopped

  # Backs the /users API: database created on first write; indexes + Bogus
  # seeding happen in the awaited startup initializer.
  mongodb:
    image: mongo:8
    container_name: hybrid-search-mongodb
    ports:
      - "27018:27017"
    volumes:
      - mongo-data:/data/db
    healthcheck:
      test: ["CMD-SHELL", "mongosh --quiet --eval 'db.runCommand({ ping: 1 }).ok' | grep -q 1"]
      interval: 10s
      timeout: 5s
      retries: 15
    restart: unless-stopped

volumes:
  qdrant-data:
  ollama-data:
  redis-data:
  mongo-data:

$ dotnet new web -n HybridSearchDemo && cd HybridSearchDemo

$ dotnet add package Microsoft.Extensions.AI
$ dotnet add package OllamaSharp
$ dotnet add package Qdrant.Client
$ dotnet add package MongoDB.Driver
$ dotnet add package Bogus
$ dotnet add package Microsoft.Extensions.Caching.StackExchangeRedis
$ dotnet add package Microsoft.AspNetCore.OutputCaching.StackExchangeRedis
$ dotnet add package FluentValidation.DependencyInjectionExtensions

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "HybridSearch": {
    "OllamaEndpoint": "http://localhost:11434",
    "EmbeddingModel": "nomic-embed-text",
    "ChatModel": "llama3.1",
    "EmbeddingDimensions": 768,
    "QdrantHost": "localhost",
    "QdrantPort": 6334,
    "CollectionName": "kb_hybrid",
    "DenseVectorName": "dense",
    "SparseVectorName": "bm25",
    "PrefetchLimit": 20,
    "RagTopK": 3,
    "CacheCollectionName": "semantic_cache",
    "CacheMinScore": 0.85,
    "CacheTtl": "1.00:00:00",
    "RedisConnection": "localhost:6379"
  },
  "Mongo": {
    "ConnectionString": "mongodb://localhost:27018",
    "DatabaseName": "pochybrid-search",
    "EnableLogQueries": false
  }
}

namespace HybridSearchDemo.Configuration;

// Strongly-typed configuration bound from the "HybridSearch" section of
// appsettings.json: Ollama (embeddings + chat), Qdrant (gRPC), the two named
// vectors, the semantic-cache collection and Redis. Changing model, host or
// collection never touches the code.
public sealed class HybridSearchOptions
{
    public const string SectionName = "HybridSearch";

    // Ollama serves both models locally: nomic-embed-text for the vectors,
    // llama3.1 to generate the RAG answers of POST /ask.
    public string OllamaEndpoint { get; init; } = "http://localhost:11434";
    public string EmbeddingModel { get; init; } = "nomic-embed-text";
    public string ChatModel { get; init; } = "llama3.1";

    // Must match the embedding model: nomic-embed-text returns 768 dimensions.
    public int EmbeddingDimensions { get; init; } = 768;

    // Qdrant gRPC endpoint: the .NET client speaks gRPC on 6334, not REST on 6333.
    public string QdrantHost { get; init; } = "localhost";
    public int QdrantPort { get; init; } = 6334;

    public string CollectionName { get; init; } = "kb_hybrid";

    // The two named vectors of the search collection: dense (semantic, from
    // Ollama) and sparse (BM25, computed server-side by Qdrant).
    public string DenseVectorName { get; init; } = "dense";
    public string SparseVectorName { get; init; } = "bm25";

    // How many candidates each prefetch branch feeds into the RRF fusion stage.
    public ulong PrefetchLimit { get; init; } = 20;

    // How many fused hits POST /ask packs into the LLM context.
    public int RagTopK { get; init; } = 3;

    // Semantic cache of the RAG answers — a SECOND Qdrant collection, dense-only.
    public string CacheCollectionName { get; init; } = "semantic_cache";

    // Min cosine SIMILARITY (1 = identical) accepted as a semantic hit.
    public float CacheMinScore { get; init; } = 0.85f;

    // Qdrant has no native TTL: entries carry createdAt and lookups filter it.
    public TimeSpan CacheTtl { get; init; } = TimeSpan.FromDays(1);

    // Redis backs the OUTPUT cache (/users) and the exact-match chat cache.
    public string RedisConnection { get; init; } = "localhost:6379";
}

// Idempotent: one collection, TWO named vectors per point. The sparse side
// enables the IDF modifier — mandatory with BM25: Qdrant maintains the
// corpus statistics and applies IDF at query time.
public async Task EnsureCollectionAsync(CancellationToken ct = default)
{
    if (await client.CollectionExistsAsync(_opt.CollectionName, ct))
        return;

    await client.CreateCollectionAsync(
        collectionName: _opt.CollectionName,
        vectorsConfig: new VectorParamsMap
        {
            Map =
            {
                [_opt.DenseVectorName] = new VectorParams
                {
                    Size = (ulong)_opt.EmbeddingDimensions,
                    Distance = Distance.Cosine,
                },
            },
        },
        sparseVectorsConfig: (_opt.SparseVectorName, new SparseVectorParams { Modifier = Modifier.Idf }),
        cancellationToken: ct);
}

// Seeds the corpus once: skips when the collection already holds points.
public async Task SeedFromFileAsync(string path, CancellationToken ct = default)
{
    if (await client.CountAsync(_opt.CollectionName, cancellationToken: ct) > 0)
        return;

    await using var file = File.OpenRead(path);
    var docs = await JsonSerializer.DeserializeAsync<List<KbDocument>>(file, JsonSerializerOptions.Web, ct) ?? [];

    // One Ollama call per document: fine for a seed of ~15 KB articles.
    var points = new List<PointStruct>();
    foreach (var (doc, index) in docs.Select((d, i) => (d, i)))
    {
        var dense = await embedder.GenerateVectorAsync($"{doc.Title}. {doc.Text}", cancellationToken: ct);

        points.Add(new PointStruct
        {
            Id = (ulong)(index + 1),
            Vectors = new Dictionary<string, Vector>
            {
                // Dense side: the embedding computed locally by Ollama.
                [_opt.DenseVectorName] = dense.ToArray(),

                // Sparse side: raw text. Qdrant tokenizes, stems and turns it
                // into a BM25 sparse vector on the server — no client-side math.
                [_opt.SparseVectorName] = new Document { Model = Bm25Model, Text = $"{doc.Title}. {doc.Text}" },
            },
            Payload = { ["title"] = doc.Title, ["text"] = doc.Text },
        });
    }

    await client.UpsertAsync(_opt.CollectionName, points, cancellationToken: ct);
}

// One entry point, three strategies over the same collection.
public async Task<IReadOnlyList<SearchHit>> SearchAsync(
    string query, SearchMode mode, int limit, CancellationToken ct = default)
{
    var results = mode switch
    {
        SearchMode.Dense => await DenseAsync(query, limit, ct),
        SearchMode.Keyword => await KeywordAsync(query, limit, ct),
        _ => await HybridAsync(query, limit, ct),
    };

    return [.. results.Select(point => new SearchHit(
        point.Id.Num,
        point.Score,
        point.Payload["title"].StringValue,
        point.Payload["text"].StringValue))];
}

// Dense only: embed the query with Ollama, nearest neighbours by cosine.
private async Task<IReadOnlyList<ScoredPoint>> DenseAsync(string query, int limit, CancellationToken ct)
{
    var vector = await embedder.GenerateVectorAsync(query, cancellationToken: ct);

    return await client.QueryAsync(
        _opt.CollectionName,
        query: vector.ToArray(),
        usingVector: _opt.DenseVectorName,
        limit: (ulong)limit,
        payloadSelector: true,
        cancellationToken: ct);
}

// Keyword only: BM25. The query string becomes a sparse vector inside
// Qdrant, and IDF is applied against the collection-level statistics.
private async Task<IReadOnlyList<ScoredPoint>> KeywordAsync(string query, int limit, CancellationToken ct) =>
    await client.QueryAsync(
        _opt.CollectionName,
        query: new Document { Model = Bm25Model, Text = query },
        usingVector: _opt.SparseVectorName,
        limit: (ulong)limit,
        payloadSelector: true,
        cancellationToken: ct);

// Hybrid: both branches run inside Qdrant as prefetches, then Reciprocal
// Rank Fusion merges the two rankings into a single one. One round-trip.
private async Task<IReadOnlyList<ScoredPoint>> HybridAsync(string query, int limit, CancellationToken ct)
{
    var vector = await embedder.GenerateVectorAsync(query, cancellationToken: ct);

    return await client.QueryAsync(
        _opt.CollectionName,
        prefetch:
        [
            new PrefetchQuery
            {
                Query = vector.ToArray(),
                Using = _opt.DenseVectorName,
                Limit = _opt.PrefetchLimit,
            },
            new PrefetchQuery
            {
                Query = new Document { Model = Bm25Model, Text = query },
                Using = _opt.SparseVectorName,
                Limit = _opt.PrefetchLimit,
            },
        ],
        query: Fusion.Rrf,
        limit: (ulong)limit,
        payloadSelector: true,
        cancellationToken: ct);
}

using HybridSearchDemo.Caching;
using HybridSearchDemo.Configuration;
using HybridSearchDemo.Rag;
using HybridSearchDemo.Search;
using Microsoft.Extensions.AI;
using OllamaSharp;
using Qdrant.Client;

namespace HybridSearchDemo.Extensions;

public static class ServiceCollectionExtensions
{
    // One call wires the whole hybrid stack: typed options, the Qdrant gRPC
    // client, the Ollama embedding + chat clients, the hybrid store, the
    // Qdrant semantic cache and the RAG service.
    public static IServiceCollection AddHybridSearch(this IServiceCollection services, IConfiguration configuration)
    {
        var section = configuration.GetSection(HybridSearchOptions.SectionName);
        services.Configure<HybridSearchOptions>(section);
        var options = section.Get<HybridSearchOptions>() ?? new HybridSearchOptions();

        // gRPC client, port 6334. The REST port (6333) only serves the dashboard here.
        services.AddSingleton(_ => new QdrantClient(options.QdrantHost, options.QdrantPort));

        var endpoint = new Uri(options.OllamaEndpoint);

        // Embeddings: a dedicated Ollama client bound to the embedding model.
        services.AddEmbeddingGenerator(new OllamaApiClient(endpoint) { SelectedModel = options.EmbeddingModel });

        // Chat pipeline for /ask, outermost first: Redis exact-match cache -> Ollama.
        // Paraphrases are caught EARLIER, by the Qdrant semantic cache in RagService.
        services.AddStackExchangeRedisCache(redis => redis.Configuration = options.RedisConnection);
        services.AddChatClient(new OllamaApiClient(endpoint) { SelectedModel = options.ChatModel })
            .UseDistributedCache()
            .UseLogging();

        services.AddSingleton<IHybridSearchStore, QdrantHybridSearchStore>();
        services.AddSingleton<ISemanticCacheStore, QdrantSemanticCacheStore>();
        services.AddSingleton<IRagService, RagService>();
        return services;
    }
}

using FluentValidation;
using HybridSearchDemo.Caching;
using HybridSearchDemo.Configuration;
using HybridSearchDemo.Endpoints;
using HybridSearchDemo.Extensions;
using HybridSearchDemo.HostedServices;
using HybridSearchDemo.Search;

var builder = WebApplication.CreateBuilder(args);

// Search + RAG side: Qdrant (hybrid search + semantic cache), Ollama
// (embeddings + chat) and the Redis exact-match cache for the chat pipeline.
builder.Services.AddHybridSearch(builder.Configuration);

// Data side: MongoDB (single database, generic IRepository<>), user service,
// FluentValidation and the awaited startup initializer for indexes + fake users.
builder.Services.AddMongoInfrastructure(builder.Configuration);
builder.Services.AddValidatorsFromAssemblyContaining<Program>();

// OUTPUT caching on the same Redis: whole HTTP responses, tagged for eviction.
var redisConnection = builder.Configuration
    .GetSection(HybridSearchOptions.SectionName)[nameof(HybridSearchOptions.RedisConnection)]!;
builder.Services.AddStackExchangeRedisOutputCache(options => options.Configuration = redisConnection);
builder.Services.AddOutputCache();

var app = builder.Build();

// Create the two Qdrant collections (search + semantic cache) and seed the KB
// corpus BEFORE Kestrel accepts requests. Every operation is idempotent.
var store = app.Services.GetRequiredService<IHybridSearchStore>();
await store.EnsureCollectionAsync(app.Lifetime.ApplicationStopping);
await store.SeedFromFileAsync(
    Path.Combine(AppContext.BaseDirectory, "Data", "seed-documents.json"),
    app.Lifetime.ApplicationStopping);
await app.Services.GetRequiredService<ISemanticCacheStore>()
    .EnsureCollectionAsync(app.Lifetime.ApplicationStopping);

// Finish MongoDB indexes and seed before the server can answer and cache /users.
await app.Services.GetRequiredService<UserCollectionInitializer>()
    .InitializeAsync(app.Lifetime.ApplicationStopping);

app.UseOutputCache();

app.MapSearchEndpoints(); // GET /search           -> dense | keyword | hybrid
app.MapAskEndpoints();    // POST /ask             -> RAG + Qdrant semantic cache
app.MapUserEndpoints();   // GET /users            -> Mongo + Redis output cache
app.MapCacheEndpoints();  // DELETE /cache/output  -> flush the output cache

app.Run();

using System.Diagnostics;
using FluentValidation;
using HybridSearchDemo.Models;
using HybridSearchDemo.Search;

namespace HybridSearchDemo.Endpoints;

public static class SearchEndpoints
{
    // GET /search?q=...&mode=dense|keyword|hybrid&limit=5 — one endpoint, three
    // strategies, same JSON shape, so the differences are easy to eyeball.
    public static void MapSearchEndpoints(this IEndpointRouteBuilder app) =>
        app.MapGet("/search", async (
            [AsParameters] SearchRequest request,
            IValidator<SearchRequest> validator,
            IHybridSearchStore store,
            CancellationToken ct) =>
        {
            var validation = await validator.ValidateAsync(request, ct);
            if (!validation.IsValid)
                return Results.ValidationProblem(validation.ToDictionary());

            var mode = request.ParseMode();

            // Time the whole call so the reply shows what each strategy costs.
            var stopwatch = Stopwatch.StartNew();
            var hits = await store.SearchAsync(request.Q, mode, request.Limit, ct);
            stopwatch.Stop();

            return Results.Ok(new SearchResponse(
                request.Q, mode.ToString().ToLowerInvariant(), stopwatch.ElapsedMilliseconds, hits));
        });
}

# 1) codice esatto, modalita' densa: il documento NB-1042 non emerge
$ curl -s "localhost:5080/search?q=NB-1042&mode=dense"

# 2) stesso codice, BM25: primo risultato, senza nessun embedding
$ curl -s "localhost:5080/search?q=NB-1042&mode=keyword"

# 3) query mista, ibrido: esatto al primo posto + vicini semantici
$ curl -s "localhost:5080/search?q=NB-1042+signature+check+fails&mode=hybrid"

# bonus: parafrasi senza parole in comune — qui vince il denso
$ curl -s "localhost:5080/search?q=second+factor+login&mode=keyword"
$ curl -s "localhost:5080/search?q=second+factor+login&mode=hybrid"

public async Task<AskReply> AskAsync(string question, CancellationToken ct = default)
{
    var stopwatch = Stopwatch.StartNew();

    // 1) One embedding, two uses: semantic-cache key AND dense retrieval branch.
    var embedding = await embedder.GenerateVectorAsync(question, cancellationToken: ct);

    // 2) Cache probe: a semantically-close question already answered within the
    //    TTL short-circuits everything — no retrieval, no LLM call.
    var cached = await cacheStore.FindAsync(embedding, ct);
    if (cached is not null)
        return new AskReply(cached, "semantic-cache", stopwatch.ElapsedMilliseconds, []);

    // 3) Retrieval: hybrid (dense + BM25 + RRF) over the KB collection.
    var hits = await searchStore.HybridSearchAsync(embedding, question, _opt.RagTopK, ct);

    // 4) Generation: the retrieved chunks become the grounding context of a
    //    single prompt; the model must answer from them or say it cannot.
    var response = await chat.GetResponseAsync(BuildPrompt(question, hits), cancellationToken: ct);

    // 5) Persist for the next paraphrase — only non-blank answers.
    if (!string.IsNullOrWhiteSpace(response.Text))
        await cacheStore.SaveAsync(embedding, question, response.Text, ct);

    stopwatch.Stop();
    return new AskReply(response.Text, "model", stopwatch.ElapsedMilliseconds,
        [.. hits.Select(hit => new RagSource(hit.Id, hit.Score, hit.Title))]);
}

// One nearest neighbour, gated by similarity AND freshness: an entry older
// than CacheTtl is invisible even when its vector is a perfect match.
public async Task<string?> FindAsync(ReadOnlyMemory<float> embedding, CancellationToken ct = default)
{
    var oldestValid = DateTimeOffset.UtcNow.Subtract(_opt.CacheTtl).ToUnixTimeSeconds();

    var hits = await client.QueryAsync(
        _opt.CacheCollectionName,
        query: embedding.ToArray(),
        filter: Conditions.Range("createdAt", new Range { Gte = oldestValid }),
        limit: 1,
        scoreThreshold: _opt.CacheMinScore,   // cosine similarity >= 0.85
        payloadSelector: true,
        cancellationToken: ct);

    return hits.Count > 0 ? hits[0].Payload["answer"].StringValue : null;
}

// Stores a fresh question/answer pair keyed by the question embedding.
public async Task SaveAsync(
    ReadOnlyMemory<float> embedding, string question, string answer, CancellationToken ct = default)
{
    var point = new PointStruct
    {
        Id = Guid.NewGuid(),
        Vectors = embedding.ToArray(),
        Payload =
        {
            ["question"] = question,
            ["answer"] = answer,
            ["createdAt"] = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
        },
    };

    await client.UpsertAsync(_opt.CacheCollectionName, [point], cancellationToken: ct);
}

// Chat pipeline for /ask, outermost first: Redis exact-match cache -> Ollama.
// Paraphrases are caught EARLIER, by the Qdrant semantic cache in RagService.
services.AddStackExchangeRedisCache(redis => redis.Configuration = options.RedisConnection);
services.AddChatClient(new OllamaApiClient(endpoint) { SelectedModel = options.ChatModel })
    .UseDistributedCache()
    .UseLogging();

// GET /users — the WHOLE HTTP response is cached on Redis for 60 seconds,
// varied by the paging params and tagged for one-shot eviction.
app.MapGet("/users", async ([AsParameters] GetUsersRequest request, ...) => { ... })
    .CacheOutput(policy => policy
    .Expire(TimeSpan.FromSeconds(60))
    .SetVaryByQuery("page", "pageSize", "search")
    .Tag("users"));

// DELETE /cache/output — evict every cached /users response at once.
app.MapDelete("/cache/output", async (IOutputCacheStore store, CancellationToken ct) =>
{
    await store.EvictByTagAsync("users", ct);
    return Results.NoContent();
});

public async Task<PagedResult<UserResponse>> GetPagedAsync(GetUsersRequest request, CancellationToken ct = default)
{
    // 1) Typed LINQ expression: blank search matches everything, otherwise the
    //    Regex.Escaped term is matched (case-insensitive $regex) on three fields.
    var search = request.Search;
    Expression<Func<User, bool>> predicate;
    if (string.IsNullOrWhiteSpace(search))
    {
        predicate = _ => true;
    }
    else
    {
        var pattern = Regex.Escape(search);
        predicate = u => Regex.IsMatch(u.LastName, pattern, RegexOptions.IgnoreCase) ||
                         Regex.IsMatch(u.FirstName, pattern, RegexOptions.IgnoreCase) ||
                         Regex.IsMatch(u.Email, pattern, RegexOptions.IgnoreCase);
    }

    // 2) Server-side paging — the repository issues count + sorted page in
    //    parallel and returns the filtered total alongside the slice.
    var (users, totalCount) = await repository.FindAsync(
        predicate,
        u => u.LastName,
        ascending: true,
        skip: (request.Page - 1) * request.PageSize,
        take: request.PageSize,
        ct: ct);

    // 3) Project entities -> DTOs and wrap them in the paged envelope.
    return users.ToPagedResult(request, totalCount);
}

git clone https://github.com/fscamuzzi/hybrid-search-dotnet-qdrant-ollama.git
cd hybrid-search-dotnet-qdrant-ollama
docker compose up -d                 # Qdrant + Ollama
docker compose logs -f ollama-init   # attendi exit code 0
cd HybridSearchDemo && dotnet run --urls http://localhost:5080

### Search: dense vs keyword vs hybrid sullo stesso codice
GET {{host}}/search?q=NB-1042&mode=dense
GET {{host}}/search?q=NB-1042&mode=keyword
GET {{host}}/search?q=NB-1042 signature check fails&mode=hybrid

### RAG: prima domanda -> "source": "model" + fonti
POST {{host}}/ask
Content-Type: application/json

{ "question": "Why does NB-1042 keep failing on my webhook endpoint?" }

### Parafrasi -> "source": "semantic-cache", nessuna chiamata LLM
POST {{host}}/ask
Content-Type: application/json

{ "question": "My webhook endpoint keeps getting the NB-1042 failure, what is wrong?" }

### Utenti: paginazione Mongo + output cache Redis (60s, tag "users")
GET {{host}}/users?page=1&pageSize=10
GET {{host}}/users?page=1&pageSize=5&search=an

### Svuota l'output cache: la prossima /users torna fresca da Mongo
DELETE {{host}}/cache/output

// SwaggerGen: XML comments + required dalla nullability + code samples.
services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "Hybrid Search + RAG API", Version = "v1" });

    // Non-nullable (string) => required nello schema; string? resta optional.
    options.SupportNonNullableReferenceTypes();
    options.NonNullableReferenceTypesAsRequired();

    // I commenti /// di questo assembly diventano le descrizioni di schema e campi.
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "HybridSearchDemo.xml"));

    options.OperationFilter<CodeSamplesOperationFilter>();
});

// Due UI sullo stesso documento: /swagger (try-it-out) e /redoc (reference).
app.UseSwagger();
app.UseSwaggerUI(ui => ui.SwaggerEndpoint("/swagger/v1/swagger.json", "Hybrid Search + RAG API v1"));
app.UseReDoc(redoc => { redoc.RoutePrefix = "redoc"; redoc.SpecUrl = "/swagger/v1/swagger.json"; });

// L'operation filter: tab di codice per ReDoc, un set per endpoint.
operation.Extensions["x-codeSamples"] = new OpenApiArray
{
    new OpenApiObject
    {
        ["lang"] = new OpenApiString("Shell"),
        ["label"] = new OpenApiString("curl"),
        ["source"] = new OpenApiString("curl -s -X POST http://localhost:5080/ask ..."),
    },
    // ... C#, JavaScript, Python
};

// Sulle request, la nullability e gli attributi decidono required/optional:
public sealed record AskRequest(
    [property: Required, MaxLength(500), Description("The question. REQUIRED.")]
    string Question);