feat(rag): implement KM-RAG retrieval read-path, API endpoints, global Q&A UI, and unit tests (#49)
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:
@@ -34,6 +34,12 @@
|
||||
</div>
|
||||
<span class="nav-text">Concepts Map</span>
|
||||
</NavLink>
|
||||
<NavLink class="nav-item" href="/intelligence">
|
||||
<div class="nav-icon">
|
||||
<NexusIcon Name="cpu" Size="18" />
|
||||
</div>
|
||||
<span class="nav-text">Global AI Q&A</span>
|
||||
</NavLink>
|
||||
<NavLink class="nav-item" href="/profile">
|
||||
<div class="nav-icon">
|
||||
<NexusIcon Name="message-square" Size="18" />
|
||||
|
||||
@@ -0,0 +1,453 @@
|
||||
@page "/intelligence"
|
||||
@attribute [Authorize]
|
||||
@using NexusReader.Application.DTOs.AI
|
||||
@using NexusReader.Application.Abstractions.Services
|
||||
@using NexusReader.Application.DTOs.User
|
||||
@using System.Net.Http.Json
|
||||
@inject HttpClient Http
|
||||
@inject IKnowledgeService KnowledgeService
|
||||
|
||||
<div class="intelligence-page">
|
||||
<header class="intelligence-header">
|
||||
<div class="header-title-section">
|
||||
<h1>Global AI Q&A</h1>
|
||||
<p class="subtitle">Search, interrogate, and extract grounded facts from your library using Polyglot KM-RAG</p>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<div class="intelligence-layout glass-panel">
|
||||
<div class="search-scope-bar">
|
||||
<div class="input-group search-input-group">
|
||||
<input class="nexus-input"
|
||||
placeholder="Ask a question about your books..."
|
||||
@bind="_question"
|
||||
@bind:event="oninput"
|
||||
@onkeyup="HandleKeyUp" />
|
||||
<button class="btn-nexus primary search-btn"
|
||||
disabled="@(string.IsNullOrWhiteSpace(_question) || _isLoading)"
|
||||
@onclick="AskQuestionAsync">
|
||||
@if (_isLoading)
|
||||
{
|
||||
<div class="spinner-glow small btn-spinner"></div>
|
||||
}
|
||||
else
|
||||
{
|
||||
<span>Ask AI</span>
|
||||
}
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<div class="scope-selector">
|
||||
<label for="book-select">Scope:</label>
|
||||
<select id="book-select" class="nexus-select" @bind="_selectedBookId">
|
||||
<option value="">All Books (Global Search)</option>
|
||||
@if (_books != null)
|
||||
{
|
||||
@foreach (var book in _books)
|
||||
{
|
||||
<option value="@book.Id">@book.Title</option>
|
||||
}
|
||||
}
|
||||
</select>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="results-area">
|
||||
@if (_isLoading)
|
||||
{
|
||||
<div class="loading-state">
|
||||
<div class="nexus-spinner"></div>
|
||||
<span>Analyzing conceptual graph and synthesizing response...</span>
|
||||
</div>
|
||||
}
|
||||
else if (_response != null)
|
||||
{
|
||||
<div class="response-container">
|
||||
<div class="response-section">
|
||||
<h4><i class="bi bi-robot"></i> Answer</h4>
|
||||
<div class="answer-text">
|
||||
@_response.Answer
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@if (_response.Citations != null && _response.Citations.Any())
|
||||
{
|
||||
<div class="citations-section">
|
||||
<h4><i class="bi bi-journal-check"></i> Grounded Citations</h4>
|
||||
<div class="citations-grid">
|
||||
@foreach (var citation in _response.Citations)
|
||||
{
|
||||
<div class="citation-card">
|
||||
<div class="citation-header">
|
||||
<span class="source-badge">@citation.SourceBook</span>
|
||||
@if (!string.IsNullOrEmpty(citation.CitationId) && citation.CitationId.Length > 8)
|
||||
{
|
||||
<span class="id-badge">ID: @citation.CitationId.Substring(0, Math.Min(8, citation.CitationId.Length))</span>
|
||||
}
|
||||
</div>
|
||||
<div class="citation-body">
|
||||
"@citation.Snippet"
|
||||
</div>
|
||||
</div>
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
}
|
||||
</div>
|
||||
}
|
||||
else if (_hasSearched)
|
||||
{
|
||||
<div class="empty-state">
|
||||
<i class="bi bi-info-circle"></i>
|
||||
<p>No answers generated. Try adjusting your question.</p>
|
||||
</div>
|
||||
}
|
||||
else
|
||||
{
|
||||
<div class="welcome-state">
|
||||
<div class="welcome-icon">
|
||||
<svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
|
||||
<path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"></path>
|
||||
</svg>
|
||||
</div>
|
||||
<h3>Start Interrogating Your Library</h3>
|
||||
<p>Ask complex questions across all your books. The system will search vectors, pull concept graph relations, and formulate a grounded answer with precise citations.</p>
|
||||
</div>
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<style>
|
||||
.intelligence-page {
|
||||
padding: 3rem 2rem;
|
||||
max-width: 1100px;
|
||||
margin: 0 auto;
|
||||
animation: fadeIn 0.5s ease-out;
|
||||
}
|
||||
|
||||
.intelligence-header {
|
||||
margin-bottom: 2rem;
|
||||
}
|
||||
|
||||
.header-title-section h1 {
|
||||
font-family: var(--nexus-font-serif, 'Outfit', 'Georgia', serif);
|
||||
font-size: 2.8rem;
|
||||
font-weight: 700;
|
||||
margin: 0 0 0.5rem 0;
|
||||
background: linear-gradient(135deg, var(--nexus-text, #ffffff) 0%, rgba(255, 255, 255, 0.7) 100%);
|
||||
-webkit-background-clip: text;
|
||||
-webkit-text-fill-color: transparent;
|
||||
}
|
||||
|
||||
.subtitle {
|
||||
font-size: 1rem;
|
||||
color: rgba(255, 255, 255, 0.6);
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.intelligence-layout {
|
||||
padding: 2.5rem;
|
||||
border-radius: var(--nexus-radius-lg, 16px);
|
||||
background: rgba(15, 23, 42, 0.4);
|
||||
border: 1px solid rgba(255, 255, 255, 0.08);
|
||||
backdrop-filter: blur(20px);
|
||||
box-shadow: 0 20px 50px rgba(0, 0, 0, 0.3);
|
||||
}
|
||||
|
||||
.search-scope-bar {
|
||||
display: flex;
|
||||
gap: 1.5rem;
|
||||
align-items: center;
|
||||
margin-bottom: 2.5rem;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.search-input-group {
|
||||
flex-grow: 1;
|
||||
display: flex;
|
||||
background: rgba(15, 23, 42, 0.5);
|
||||
border: 1px solid rgba(255, 255, 255, 0.1);
|
||||
border-radius: 30px;
|
||||
padding: 0.25rem 0.25rem 0.25rem 1.25rem;
|
||||
transition: all 0.3s ease;
|
||||
}
|
||||
|
||||
.search-input-group:focus-within {
|
||||
border-color: var(--nexus-primary, #6366f1);
|
||||
box-shadow: 0 0 10px rgba(99, 102, 241, 0.2);
|
||||
}
|
||||
|
||||
.nexus-input {
|
||||
flex-grow: 1;
|
||||
background: transparent;
|
||||
border: none;
|
||||
color: #ffffff;
|
||||
font-size: 1rem;
|
||||
outline: none;
|
||||
padding: 0.5rem 0;
|
||||
}
|
||||
|
||||
.nexus-input::placeholder {
|
||||
color: rgba(255, 255, 255, 0.4);
|
||||
}
|
||||
|
||||
.search-btn {
|
||||
border-radius: 25px !important;
|
||||
padding: 0.5rem 1.5rem !important;
|
||||
font-size: 0.95rem !important;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.scope-selector {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.75rem;
|
||||
color: rgba(255, 255, 255, 0.7);
|
||||
}
|
||||
|
||||
.nexus-select {
|
||||
background: rgba(15, 23, 42, 0.6);
|
||||
border: 1px solid rgba(255, 255, 255, 0.1);
|
||||
color: #ffffff;
|
||||
padding: 0.5rem 1.5rem 0.5rem 1rem;
|
||||
border-radius: 20px;
|
||||
outline: none;
|
||||
cursor: pointer;
|
||||
transition: all 0.3s ease;
|
||||
}
|
||||
|
||||
.nexus-select:focus {
|
||||
border-color: var(--nexus-primary, #6366f1);
|
||||
}
|
||||
|
||||
.results-area {
|
||||
min-height: 250px;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.loading-state {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
gap: 1.5rem;
|
||||
color: rgba(255, 255, 255, 0.7);
|
||||
}
|
||||
|
||||
.nexus-spinner {
|
||||
width: 50px;
|
||||
height: 50px;
|
||||
border: 3px solid rgba(99, 102, 241, 0.1);
|
||||
border-radius: 50%;
|
||||
border-top-color: var(--nexus-primary, #6366f1);
|
||||
animation: spin 1s linear infinite;
|
||||
}
|
||||
|
||||
.welcome-state, .empty-state {
|
||||
text-align: center;
|
||||
color: rgba(255, 255, 255, 0.5);
|
||||
padding: 3rem 1rem;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.welcome-icon {
|
||||
color: rgba(255, 255, 255, 0.25);
|
||||
margin-bottom: 1.5rem;
|
||||
animation: pulse 2s infinite alternate;
|
||||
}
|
||||
|
||||
.welcome-state h3 {
|
||||
color: #ffffff;
|
||||
font-family: var(--nexus-font-sans);
|
||||
margin: 0 0 0.5rem 0;
|
||||
}
|
||||
|
||||
.welcome-state p, .empty-state p {
|
||||
max-width: 500px;
|
||||
margin: 0;
|
||||
font-size: 0.95rem;
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
.response-container {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 2.5rem;
|
||||
animation: slideUp 0.4s ease-out;
|
||||
}
|
||||
|
||||
.response-section h4, .citations-section h4 {
|
||||
font-size: 1.1rem;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 1px;
|
||||
color: rgba(255, 255, 255, 0.5);
|
||||
margin: 0 0 1rem 0;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
}
|
||||
|
||||
.answer-text {
|
||||
font-size: 1.15rem;
|
||||
line-height: 1.7;
|
||||
color: #ffffff;
|
||||
background: rgba(255, 255, 255, 0.03);
|
||||
padding: 1.5rem;
|
||||
border-radius: 12px;
|
||||
border: 1px solid rgba(255, 255, 255, 0.05);
|
||||
}
|
||||
|
||||
.citations-grid {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr;
|
||||
gap: 1.25rem;
|
||||
}
|
||||
|
||||
.citation-card {
|
||||
background: rgba(15, 23, 42, 0.4);
|
||||
border: 1px solid rgba(255, 255, 255, 0.05);
|
||||
border-radius: 12px;
|
||||
padding: 1.25rem;
|
||||
transition: all 0.3s ease;
|
||||
}
|
||||
|
||||
.citation-card:hover {
|
||||
border-color: rgba(99, 102, 241, 0.3);
|
||||
transform: translateY(-2px);
|
||||
}
|
||||
|
||||
.citation-header {
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
align-items: center;
|
||||
margin-bottom: 0.75rem;
|
||||
}
|
||||
|
||||
.source-badge {
|
||||
font-size: 0.8rem;
|
||||
font-weight: 600;
|
||||
color: var(--nexus-primary, #6366f1);
|
||||
background: rgba(99, 102, 241, 0.1);
|
||||
padding: 0.25rem 0.75rem;
|
||||
border-radius: 20px;
|
||||
}
|
||||
|
||||
.id-badge {
|
||||
font-size: 0.75rem;
|
||||
color: rgba(255, 255, 255, 0.4);
|
||||
font-family: monospace;
|
||||
}
|
||||
|
||||
.citation-body {
|
||||
font-size: 0.95rem;
|
||||
line-height: 1.5;
|
||||
color: rgba(255, 255, 255, 0.8);
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
.btn-spinner {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
/* Animations */
|
||||
@@keyframes fadeIn {
|
||||
from { opacity: 0; transform: translateY(15px); }
|
||||
to { opacity: 1; transform: translateY(0); }
|
||||
}
|
||||
|
||||
@@keyframes slideUp {
|
||||
from { opacity: 0; transform: translateY(10px); }
|
||||
to { opacity: 1; transform: translateY(0); }
|
||||
}
|
||||
|
||||
@@keyframes spin {
|
||||
0% { transform: rotate(0deg); }
|
||||
100% { transform: rotate(360deg); }
|
||||
}
|
||||
|
||||
@@keyframes pulse {
|
||||
0% { transform: scale(0.95); opacity: 0.7; }
|
||||
100% { transform: scale(1.05); opacity: 1; }
|
||||
}
|
||||
</style>
|
||||
|
||||
@code {
|
||||
private string _question = string.Empty;
|
||||
private string _selectedBookId = string.Empty;
|
||||
private bool _isLoading;
|
||||
private bool _hasSearched;
|
||||
private GroundedResponseDto? _response;
|
||||
private List<LastReadBookDto>? _books;
|
||||
|
||||
protected override async Task OnInitializedAsync()
|
||||
{
|
||||
try
|
||||
{
|
||||
_books = await Http.GetFromJsonAsync<List<LastReadBookDto>>("api/library/books");
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Console.WriteLine($"[Intelligence] Failed to load books for scope selector: {ex.Message}");
|
||||
}
|
||||
}
|
||||
|
||||
private async Task HandleKeyUp(KeyboardEventArgs e)
|
||||
{
|
||||
if (e.Key == "Enter" && !string.IsNullOrWhiteSpace(_question) && !_isLoading)
|
||||
{
|
||||
await AskQuestionAsync();
|
||||
}
|
||||
}
|
||||
|
||||
private async Task AskQuestionAsync()
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(_question) || _isLoading) return;
|
||||
|
||||
_isLoading = true;
|
||||
_hasSearched = true;
|
||||
_response = null;
|
||||
StateHasChanged();
|
||||
|
||||
try
|
||||
{
|
||||
Guid? ebookId = null;
|
||||
if (!string.IsNullOrEmpty(_selectedBookId) && Guid.TryParse(_selectedBookId, out var parsedId))
|
||||
{
|
||||
ebookId = parsedId;
|
||||
}
|
||||
|
||||
var result = await KnowledgeService.AskQuestionAsync(_question, "tenantId", ebookId);
|
||||
if (result.IsSuccess)
|
||||
{
|
||||
_response = result.Value;
|
||||
}
|
||||
else
|
||||
{
|
||||
_response = new GroundedResponseDto
|
||||
{
|
||||
Answer = $"Error: {result.Errors.FirstOrDefault()?.Message ?? "An error occurred."}",
|
||||
Citations = new List<CitationDto>()
|
||||
};
|
||||
}
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_response = new GroundedResponseDto
|
||||
{
|
||||
Answer = $"Network/API Error: {ex.Message}",
|
||||
Citations = new List<CitationDto>()
|
||||
};
|
||||
}
|
||||
finally
|
||||
{
|
||||
_isLoading = false;
|
||||
StateHasChanged();
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user