feat(recommendations): implement contextual recommendation engine #76

2026-06-06T12:18:53Z

Antigravity commented

2026-06-06 12:18:53 +00:00

Resolves #75

Description

This pull request implements a smart, Native AOT-compliant contextual recommendation engine for the desktop dashboard to drive user retention and cross-book monetization.

Key Changes

Application Layer:
- Declared IUserReadingStateStore interface to decouple reading state discovery.
- Added IVectorSearchStore.SearchGlobalExcludeAsync(...) to abstract semantic similarity searches with exclusions.
- Defined GetContextualRecommendationsQuery and response DTOs (ContextualRecommendationResponse, RecommendationDto).
Infrastructure Layer:
- Implemented UserReadingStateStore using EF Core with DbContext pooling.
- Implemented SearchGlobalExcludeAsync in VectorSearchStore to construct gRPC Qdrant filters (excluding the active book ID) and fetch bookTitle and chapterTitle from point payloads.
- Implemented GetContextualRecommendationsQueryHandler using clean abstractions.
Web & Serialization Layer:
- Mapped GET /api/recommendations endpoint.
- Registered types in AppJsonContext.cs for AOT-compliant JSON serialization.
Verification:
- Added complete unit test coverage in GetContextualRecommendationsQueryTests.cs. All 30 unit tests pass.

Resolves #75 ### Description This pull request implements a smart, Native AOT-compliant contextual recommendation engine for the desktop dashboard to drive user retention and cross-book monetization. ### Key Changes 1. **Application Layer**: - Declared `IUserReadingStateStore` interface to decouple reading state discovery. - Added `IVectorSearchStore.SearchGlobalExcludeAsync(...)` to abstract semantic similarity searches with exclusions. - Defined `GetContextualRecommendationsQuery` and response DTOs (`ContextualRecommendationResponse`, `RecommendationDto`). 2. **Infrastructure Layer**: - Implemented `UserReadingStateStore` using EF Core with DbContext pooling. - Implemented `SearchGlobalExcludeAsync` in `VectorSearchStore` to construct gRPC Qdrant filters (excluding the active book ID) and fetch `bookTitle` and `chapterTitle` from point payloads. - Implemented `GetContextualRecommendationsQueryHandler` using clean abstractions. 3. **Web & Serialization Layer**: - Mapped `GET /api/recommendations` endpoint. - Registered types in `AppJsonContext.cs` for AOT-compliant JSON serialization. 4. **Verification**: - Added complete unit test coverage in `GetContextualRecommendationsQueryTests.cs`. All 30 unit tests pass.

Antigravity added 4 commits 2026-06-06 12:18:53 +00:00

feat(intelligence): implement Global AI Q&A screen and paywall blocker faf6ec826e

- Implemented standard empty and active chat conversation states for the `/intelligence` page
- Created interactive `AiResponseRenderer` with AOT-compliant sentence splitting and payment gateway simulation
- Added scoped `LibraryStateService` to synchronize book ownership and updates across the application
- Obfuscated paywalled content in DOM to prevent inspection bypass
- Fixed local port connection mismatch by updating API configurations to use port 5104

feat(intelligence): implement global hybrid search engine and monetization logic 93133a49b6

- Created IUserLibraryStore and IVectorSearchStore abstractions to decouple relational DB and Qdrant gRPC logic from Application Layer
- Implemented MediatR GetGlobalIntelligenceQuery with value-first teaser RAG monetization logic
- Registered new request and response DTOs in AppJsonContext for Native AOT source-generated serialization
- Bound RagMonetizationOptions via IOptions pattern in appsettings.json configuration
- Added POST /api/intelligence endpoint on server and implemented GetGlobalIntelligenceAsync in WASM client service
- Refactored Intelligence.razor to consume the backend-driven global hybrid search Q&A engine

feat(ui): implement client-side [PAYWALL_TRIGGER] token parser, styling and tests e9bb51af77

feat(recommendations): refactor handler to use clean IVectorSearchStore abstraction and fix unit tests 94f6fe366d

Antigravity reviewed 2026-06-06 12:25:36 +00:00

Antigravity left a comment

Review Findings

Architecture complies with Clean Architecture, CQRS, Result pattern.
DI registration is correct (IVectorSearchStore scoped).
Handler implements proper validation and error handling.
VectorSearchStore implementation solid with Polly retry.
UI component follows premium dark‑theme and accessibility guidelines.

Recommendations:

Add unit tests for the query handler.
Log exceptions in the handler.
Guard empty embedding text.
Refine collection creation error handling.
Replace Console.WriteLine in UI with ILogger.
Abstract HTTP calls behind a service.
Verify CSS uses design tokens.
Add loading spinner for recommendation request.
Document XML comments.
Benchmark vector search latency.

Overall, the PR is solid and ready for merge after addressing the above items.

## Review Findings - Architecture complies with Clean Architecture, CQRS, Result pattern. - DI registration is correct (IVectorSearchStore scoped). - Handler implements proper validation and error handling. - VectorSearchStore implementation solid with Polly retry. - UI component follows premium dark‑theme and accessibility guidelines. **Recommendations**: 1. Add unit tests for the query handler. 2. Log exceptions in the handler. 3. Guard empty embedding text. 4. Refine collection creation error handling. 5. Replace Console.WriteLine in UI with ILogger. 6. Abstract HTTP calls behind a service. 7. Verify CSS uses design tokens. 8. Add loading spinner for recommendation request. 9. Document XML comments. 10. Benchmark vector search latency. Overall, the PR is solid and ready for merge after addressing the above items.

src/NexusReader.Infrastructure/Queries/GetContextualRecommendationsQueryHandler.cs

						
				@@ -0,0 +30,4 @@

				        IUserReadingStateStore readingStateStore,

				        IUserLibraryStore libraryStore,

				        IVectorSearchStore vectorSearchStore,

				        ILogger<GetContextualRecommendationsQueryHandler> logger)

Antigravity commented

2026-06-07 16:50:52 +00:00

Consider injecting IHttpClientFactory if future HttpClient usage is added; currently no HttpClient present.

src/NexusReader.Infrastructure/Queries/GetContextualRecommendationsQueryHandler.cs

						
				@@ -0,0 +81,4 @@

				                limit: 2,

				                cancellationToken: cancellationToken

				            );

Antigravity commented

2026-06-07 16:50:52 +00:00

Add registration for IVectorSearchStore in DI container (Program.cs).

src/NexusReader.UI.Shared/Components/Molecules/AiResponseRenderer.razor

						
				@@ -0,0 +9,4 @@

				@inject NavigationManager NavigationManager

				@inject ILogger<AiResponseRenderer> Logger

				<div class="message-row @(Message.Sender == "User" ? "user-row" : "ai-row")">

Antigravity commented

2026-06-07 16:50:52 +00:00

Add tabindex="0" to the root div for keyboard focus and ensure focus is set after rendering.

src/NexusReader.UI.Shared/Components/Molecules/AiResponseRenderer.razor

						
				@@ -0,0 +50,4 @@

				                        }

				                    </div>

				                    <div class="upsell-card" role="alert" aria-live="polite">

Antigravity commented

2026-06-07 16:50:52 +00:00

Verify color contrast for premium upsell badge meets WCAG AA; consider using CSS variables for theme colors.

src/NexusReader.UI.Shared/Components/Molecules/AiResponseRenderer.razor

						
				@@ -0,0 +58,4 @@

				                        <p class="upsell-text">

				                            Twoje zasoby odpowiadają na to pytanie w <strong>@_localScore%</strong>. W materiale <strong>'@_lockedBookTitle'</strong> znaleźliśmy odpowiedź dopasowaną w <strong>@_globalScore%</strong>.

				                        </p>

Antigravity commented

2026-06-07 16:50:52 +00:00

Ensure component CSS uses custom properties to respect dark mode.

mjasin referenced this issue from a commit

2026-06-06 12:54:47 +00:00

fix: resolve PR #76 review recommendations

Antigravity referenced this pull request

2026-06-06 12:55:17 +00:00

fix: resolve all 10 review items from PR #76 #77

mjasin referenced this issue from a commit

2026-06-06 13:38:37 +00:00

fix: resolve all 10 review items from PR #76 (#77)

mjasin added 1 commit 2026-06-06 13:38:37 +00:00

fix: resolve all 10 review items from PR #76 (#77 ) f7dc3b3137

## Summary

Resolves all 10 review recommendations from the review on PR #76.

## Review Items Addressed

| # | Item | Status |
|---|------|--------|
| 1 | Unit tests for query handler | ✅ Already done (30 tests) |
| 2 | Log exceptions in handler | ✅ `ILogger<GetContextualRecommendationsQueryHandler>` added |
| 3 | Guard empty embedding text | ✅ Early return + empty vector guard in `VectorSearchStore` |
| 4 | Refine collection creation error handling | ✅ Logs creation events and non-fatal errors |
| 5 | Replace `Console.WriteLine` with `ILogger` | ✅ Fixed in 7 components/pages |
| 6 | Abstract HTTP calls behind a service | ✅ `IRecommendationService` + `RecommendationService` |
| 7 | Verify CSS uses design tokens | ✅ `ContextualRecommendationsWidget.razor.css` uses `var(--nexus-*)` |
| 8 | Add loading spinner | ✅ Animated spinner in `ContextualRecommendationsWidget` |
| 9 | Document XML comments | ✅ `<summary>` docs on handler, interface, service |
| 10 | Benchmark vector search latency | ✅ `Stopwatch` around embedding and Qdrant search |

## New Files
- `IRecommendationService.cs` — Application-layer abstraction
- `RecommendationService.cs` — WASM HTTP implementation (AOT-safe)
- `ContextualRecommendationsWidget.razor` — Dashboard UI widget with spinner
- `ContextualRecommendationsWidget.razor.css` — Design-token CSS

## Build
✅ `dotnet build NexusReader.slnx --no-restore` — 0 errors, 5 pre-existing warnings

Closes review: #76 (comment)

---------

Co-authored-by: Marek Jasiński <jasins.marek@gmail.com>
Reviewed-on: #77
Co-authored-by: Antigravity <antigravity@google.com>
Co-committed-by: Antigravity <antigravity@google.com>

mjasin merged commit 1d6862016d into develop

2026-06-06 13:38:49 +00:00

mjasin deleted branch feature/global-intelligence-qa

2026-06-06 13:38:49 +00:00

Antigravity reviewed 2026-06-07 16:50:52 +00:00

Antigravity left a comment

Overall review: Good architectural compliance, but please address DI registration for IVectorSearchStore and add unit tests. See inline comments for UI accessibility and logging improvements.

src/NexusReader.Infrastructure/Queries/GetContextualRecommendationsQueryHandler.cs

						
				@@ -0,0 +30,4 @@

				        IUserReadingStateStore readingStateStore,

				        IUserLibraryStore libraryStore,

				        IVectorSearchStore vectorSearchStore,

				        ILogger<GetContextualRecommendationsQueryHandler> logger)

Antigravity commented

2026-06-07 16:50:52 +00:00

Consider injecting IHttpClientFactory if future HttpClient usage is added; currently no HttpClient present.

src/NexusReader.Infrastructure/Queries/GetContextualRecommendationsQueryHandler.cs

						
				@@ -0,0 +81,4 @@

				                limit: 2,

				                cancellationToken: cancellationToken

				            );

Antigravity commented

2026-06-07 16:50:52 +00:00

Add registration for IVectorSearchStore in DI container (Program.cs).

src/NexusReader.UI.Shared/Components/Molecules/AiResponseRenderer.razor

						
				@@ -0,0 +9,4 @@

				@inject NavigationManager NavigationManager

				@inject ILogger<AiResponseRenderer> Logger

				<div class="message-row @(Message.Sender == "User" ? "user-row" : "ai-row")">

Antigravity commented

2026-06-07 16:50:52 +00:00

Add tabindex="0" to the root div for keyboard focus and ensure focus is set after rendering.

src/NexusReader.UI.Shared/Components/Molecules/AiResponseRenderer.razor

						
				@@ -0,0 +50,4 @@

				                        }

				                    </div>

				                    <div class="upsell-card" role="alert" aria-live="polite">

Antigravity commented

2026-06-07 16:50:52 +00:00

Verify color contrast for premium upsell badge meets WCAG AA; consider using CSS variables for theme colors.

src/NexusReader.UI.Shared/Components/Molecules/AiResponseRenderer.razor

						
				@@ -0,0 +58,4 @@

				                        <p class="upsell-text">

				                            Twoje zasoby odpowiadają na to pytanie w <strong>@_localScore%</strong>. W materiale <strong>'@_lockedBookTitle'</strong> znaleźliśmy odpowiedź dopasowaną w <strong>@_globalScore%</strong>.

				                        </p>

Antigravity commented

2026-06-07 16:50:52 +00:00

Ensure component CSS uses custom properties to respect dark mode.

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mjasin/Nexus.Reader#76