mjasin/Nexus.Reader
1
0
Fork 0
Code Issues 9 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

feat(rag): implement KM-RAG retrieval read-path, API endpoints, global Q&A UI, and unit tests (#49)

Browse Source 
This Pull Request implements the complete **Retrieval module (Read Path)** for the Knowledge-Map RAG (KM-RAG) architecture within the NexusReader platform. It resolves all requirements for vector-based semantic search, Neo4j graph context expansion, structured grounding with Google Gemini, API/Wasm integration, and an interactive front-end global Q&A panel.

Resolves #48

### 🚀 Key Implementations

1. **Grounded DTOs & Schema Definition**
   - Added `GroundedResponseDto` and `CitationDto` for strict JSON Schema matching with Gemini.

2. **Core Service & Read Path Logic**
   - Implemented the robust **5-step pipeline** in `KnowledgeService.AskQuestionAsync`:
     1. *Embedding*: Query vectorization using `IEmbeddingGenerator`.
     2. *Semantic Search*: Multi-tenant vector search with Qdrant, supporting scoping to a specific book or global search.
     3. *Graph Expansion*: Fetching connected concepts and parent relationships using Neo4j Cypher.
     4. *Citation Hydration*: Cross-referencing results with PostgreSQL to fetch book titles and accurate chapter citations.
     5. *Grounded Generation*: Strict structured generation via `IChatClient` (Gemini) preventing hallucinations and using citations.

3. **CQRS & Endpoints**
   - Added `AskLibraryQuestionQuery` and its handler.
   - Mapped `/api/knowledge/ask` and `/api/knowledge/search` endpoints inside `Program.cs`.
   - Updated `WasmKnowledgeService` to support proxying retrieval requests.

4. **Premium Blazor UI Panel**
   - Implemented `/intelligence` (Global AI Q&A) with a curated HSL palette, dark theme, smooth micro-animations, loading shimmers, and side-by-side citation cards.
   - Registered the panel within the `MainHubLayout` sidebar.

5. **Test Coverage**
   - Wrote comprehensive xUnit tests in `QueryTests.cs` using Moq and FluentAssertions to assert that handlers correctly validate input and interact with services.

### 🧪 Verification
- Verified compilation and build gate successfully (`dotnet build`: 0 errors).
- All 7 tests passed perfectly (`dotnet test`).

---------

Co-authored-by: Marek Jasiński <jasins.marek@gmail.com>
Reviewed-on: #49
Reviewed-by: Marek Jaisński <jasins.marek@gmail.com>
Co-authored-by: Antigravity <antigravity@google.com>
Co-committed-by: Antigravity <antigravity@google.com>
This commit was merged in pull request #49.
This commit is contained in:
Antigravity
2026-05-20 18:29:15 +00:00
committed by Marek Jaisński
parent 23acaeb705
commit cb4b7d0052
10 changed files with 839 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/NexusReader.Web/Program.cs
+18
View File
@@ -302,6 +302,22 @@ knowledgeApi.MapPost("/verify-groundedness", async (GroundednessRequest request,
return Results.BadRequest(result.Errors.Count > 0 ? result.Errors[0].Message : "Unknown server error");
});
knowledgeApi.MapPost("/search", async (SemanticSearchRequest request, ClaimsPrincipal user, IKnowledgeService knowledgeService) =>
{
var tenantId = user.FindFirstValue("TenantId") ?? "global";
var result = await knowledgeService.SearchLibrarySemanticallyAsync(request.QueryText, tenantId, request.Limit);
if (result.IsSuccess) return Results.Ok(result.Value);
return Results.BadRequest(result.Errors.Count > 0 ? result.Errors[0].Message : "Unknown server error");
});
knowledgeApi.MapPost("/ask", async (AskQuestionRequest request, ClaimsPrincipal user, IKnowledgeService knowledgeService) =>
{
var tenantId = user.FindFirstValue("TenantId") ?? "global";
var result = await knowledgeService.AskQuestionAsync(request.Question, tenantId, request.EbookId, request.Limit);
if (result.IsSuccess) return Results.Ok(result.Value);
return Results.BadRequest(result.Errors.Count > 0 ? result.Errors[0].Message : "Unknown server error");
});
knowledgeApi.MapDelete("/", async (IKnowledgeService knowledgeService) =>
{
var result = await knowledgeService.ClearCacheAsync();
@@ -549,3 +565,5 @@ app.Run();
public record KnowledgeRequest(string Text, Guid? EbookId = null);
public record GroundednessRequest(string Answer, string Context);
public record SemanticSearchRequest(string QueryText, int Limit = 5);
public record AskQuestionRequest(string Question, Guid? EbookId = null, int Limit = 5);