fix: improve static citation relevance and stream admission - #112
Conversation
Warning Review limit reached
Next review available in:29 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (31)
📝 WalkthroughWalkthroughThe PR adds Java API method-selector parsing, sparse citation query expansion, deterministic Javadoc candidate ranking, canonical document metadata constants, and bounded-elastic scheduling for chat streaming. Tests cover selector parsing, retrieval behavior, citation ordering, SSE preparation, cancellation, and completion. ChangesJava API citation selection
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant Client
participant HybridSearchService
participant Qdrant
participant RetrievalService
participant CitationCandidateRanker
Client->>HybridSearchService: submit citation query
HybridSearchService->>HybridSearchService: expand selector terms
HybridSearchService->>Qdrant: perform sparse retrieval
Qdrant-->>RetrievalService: return candidates
RetrievalService->>CitationCandidateRanker: rank candidates
CitationCandidateRanker-->>RetrievalService: return ordered candidates
RetrievalService-->>Client: return citations
Possibly related PRs
Suggested labels: Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR improves chat streaming admission and static citation relevance by ensuring an early “preparing” SSE event is emitted before potentially blocking work, and by making Java API citation discovery more deterministic and schema-consistent across ingestion/retrieval.
Changes:
- Emit the preparation SSE status event before blocking retrieval/provider work and validate cancellation behavior across that boundary.
- Improve static citation discovery for Java API type/member queries by expanding sparse queries and deterministically reordering candidates before deduplication/limiting.
- Centralize ownership of Java API
docTypeand Qdrant payload metadata field keys to eliminate scattered string literals.
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/main/java/com/williamcallahan/javachat/web/ChatController.java | Moves blocking preparation work behind a deferred boundary and schedules it on bounded elastic while keeping preparation SSE first. |
| src/test/java/com/williamcallahan/javachat/web/ChatPreparationSseIntegrationTest.java | Adds an integration test ensuring the server flushes the preparation SSE event before blocked retrieval completes. |
| src/test/java/com/williamcallahan/javachat/web/ChatControllerStreamingFailureTest.java | Adds unit tests verifying subscription returns after preparation, and that disposal interrupts blocked preparation without downstream work. |
| src/main/java/com/williamcallahan/javachat/service/RetrievalService.java | Orders citation candidates deterministically for Java API selectors and removes version-boost query distortion from citation discovery dispatch. |
| src/main/java/com/williamcallahan/javachat/service/HybridSearchService.java | Expands sparse citation query terms for Java API selectors before sparse encoding. |
| src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.java | Introduces selector parsing and sparse-query expansion for explicit Type.method queries. |
| src/test/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelectorTest.java | Adds coverage for selector parsing and path matching behavior. |
| src/main/java/com/williamcallahan/javachat/service/CitationCandidateRanker.java | Adds deterministic, local candidate ordering for citation conversion using selector evidence. |
| src/test/java/com/williamcallahan/javachat/service/CitationCandidateRankerTest.java | Adds tests validating ranker ordering rules and failure propagation for malformed URLs. |
| src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java | Defines canonical Java API document type token for consistent provenance and retrieval behavior. |
| src/main/java/com/williamcallahan/javachat/service/QdrantPayloadFieldSchema.java | Centralizes canonical metadata field keys used across Qdrant write/read paths. |
| src/main/java/com/williamcallahan/javachat/service/ingestion/IngestionProvenanceDeriver.java | Projects Java API doc type via canonical constant during provenance derivation. |
| src/test/java/com/williamcallahan/javachat/service/ingestion/IngestionProvenanceDeriverTest.java | Adds a test asserting Java API mirrors project the canonical doc type. |
| src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java | Updates tests to use canonical official doc-set identities and adds citation ordering coverage. |
| src/test/java/com/williamcallahan/javachat/service/RetrievalServiceCitationTest.java | Updates tests to use canonical Java API doc type and URL helpers. |
| src/test/java/com/williamcallahan/javachat/service/QdrantRetrievalConstraintBuilderTest.java | Updates constrained filter test to use canonical doc type and official doc identities. |
| src/test/java/com/williamcallahan/javachat/service/HybridSearchServiceTest.java | Updates hybrid/citation search tests for exact version filtering and selector expansion behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.java`:
- Around line 203-209: Update requireNonBlank to trim the validated text before
returning it, while continuing to reject null and blank values using the
existing fieldName-specific exceptions. Ensure direct construction of selector
components stores normalized text so surrounding whitespace cannot produce
invalid paths or sparse terms.
In
`@src/test/java/com/williamcallahan/javachat/service/ingestion/IngestionProvenanceDeriverTest.java`:
- Around line 53-70: Replace positional same-typed test constructions with named
factories or builders: update IngestionProvenanceDeriverTest.java lines 53-70 to
use named provenance construction, QdrantRetrievalConstraintBuilderTest.java
lines 31-39 to use a named constrained-retrieval factory or builder, and
CitationCandidateRankerTest.java lines 122-142 to replace the five-string helper
with role-specific candidate factories. Preserve each test’s existing values and
behavior while eliminating ambiguous argument trains.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 99fe71e5-0e7c-4585-8b8c-8defad1a95f3
📒 Files selected for processing (17)
src/main/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelector.javasrc/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.javasrc/main/java/com/williamcallahan/javachat/service/CitationCandidateRanker.javasrc/main/java/com/williamcallahan/javachat/service/HybridSearchService.javasrc/main/java/com/williamcallahan/javachat/service/QdrantPayloadFieldSchema.javasrc/main/java/com/williamcallahan/javachat/service/RetrievalService.javasrc/main/java/com/williamcallahan/javachat/service/ingestion/IngestionProvenanceDeriver.javasrc/main/java/com/williamcallahan/javachat/web/ChatController.javasrc/test/java/com/williamcallahan/javachat/application/search/JavaApiMethodSelectorTest.javasrc/test/java/com/williamcallahan/javachat/service/CitationCandidateRankerTest.javasrc/test/java/com/williamcallahan/javachat/service/HybridSearchServiceTest.javasrc/test/java/com/williamcallahan/javachat/service/QdrantRetrievalConstraintBuilderTest.javasrc/test/java/com/williamcallahan/javachat/service/RetrievalServiceCitationTest.javasrc/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.javasrc/test/java/com/williamcallahan/javachat/service/ingestion/IngestionProvenanceDeriverTest.javasrc/test/java/com/williamcallahan/javachat/web/ChatControllerStreamingFailureTest.javasrc/test/java/com/williamcallahan/javachat/web/ChatPreparationSseIntegrationTest.java
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit:13c7627331
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Uh oh!
There was an error while loading. Please reload this page.
Summary
Verification