feat(ai): introduce retrieval domain models and validation - #869
Open
aotenjou wants to merge 5 commits into
Open
feat(ai): introduce retrieval domain models and validation#869aotenjou wants to merge 5 commits into
aotenjou wants to merge 5 commits into
Conversation
Contributor
Author
There was a problem hiding this comment.
🟡 Changes recommended
The new unit test includes a tautological hashCode assertion (always passes), and a small UTF-8 handling fix is needed to match existing repository practices.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Introduces a foundational retrieval domain model layer for geaflow-ai, defining immutable value objects and a validated JSON boundary intended to keep model construction/validation deterministic and consistent across ingestion/retrieval.
Changes:
- Adds retrieval domain model types (documents, graph refs, evidence, and version identifiers) with
sameIdentityAsidentity semantics distinct fromequals. - Adds centralized constructor validation helpers/exceptions (
ModelValidation,RetrievalModelValidationException). - Adds a validated JSON codec (
RetrievalModelJson) plus unit tests and JSON fixtures for round-tripping and validation behavior.
File summaries
| File | Description |
|---|---|
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/codec/RetrievalModelJson.java | Validated JSON serialization/deserialization that routes through public constructors to enforce invariants. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/package-info.java | Package-level contract documentation for identity semantics and JSON compatibility/validation expectations. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/document/SourceDocument.java | Source document metadata value object with identity comparison and validation. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/document/TextChunk.java | Position-aware chunk model with offset/range validation and identity semantics. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/document/SourceRef.java | Citation/span reference model with paired-offset validation. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/graph/EntityRef.java | Entity reference model with sorted/immutable collections for stable equality. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/graph/GraphVertexRef.java | Vertex reference model with full-field identity/equality. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/graph/GraphEdgeRef.java | Edge reference model with sorted provenance chunk IDs and identity semantics. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/graph/GraphPathRef.java | Ordered path model enforcing hop/vertex/edge count invariants. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/evidence/Evidence.java | Evidence container with identity based on nested reference identities and multiset semantics. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/evidence/EvidenceKind.java | Evidence kind enum for retrieval payload categorization. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/evidence/ChannelScore.java | Per-channel scoring/ranking metadata with range validation. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/version/GraphVersion.java | Graph snapshot identifier value object. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/version/IndexVersion.java | Index snapshot identifier tied to a source graph version. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/validation/ModelValidation.java | Centralized validation + defensive-copy helpers used by the models. |
| geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/validation/RetrievalModelValidationException.java | Dedicated exception type for model-boundary validation failures. |
| geaflow-ai/src/test/java/org/apache/geaflow/ai/retrieval/model/RetrievalDomainModelTest.java | Unit tests covering identity/equality, validation, and JSON round-trips. |
| geaflow-ai/src/test/resources/retrieval/model/source-document.json | JSON fixture for SourceDocument round-trip. |
| geaflow-ai/src/test/resources/retrieval/model/evidence.json | JSON fixture for a fully-populated Evidence round-trip. |
| geaflow-ai/src/test/resources/retrieval/model/identity-cases.json | Fixture documenting field-based identity comparisons across models. |
Review details
- Files reviewed: 20/20 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| private String readFixture(String name) throws IOException { | ||
| InputStream stream = getClass().getClassLoader().getResourceAsStream(name); | ||
| Assertions.assertNotNull(stream); | ||
| try (BufferedReader reader = new BufferedReader(new InputStreamReader(stream, "UTF-8"))) { |
yaozhongq
reviewed
Sep 9, 2026
| return rank; | ||
| } | ||
|
|
||
| public boolean sameIdentityAs(Evidence other) { |
Contributor
There was a problem hiding this comment.
sameIdentityAs ignores both evidenceId and text, comparing only kind and the four reference collections. However, the codec explicitly supports legacy evidence without references and normalizes missing collections to empty ones. As a result, unrelated entries such as CHUNK/"Alice" and CHUNK/"Bob" are considered identical and may be incorrectly merged, causing evidence to be lost. Please either require at least one identity-bearing reference or fall back to comparing text and/or evidenceId when all reference collections are empty.
Contributor
|
Also, please link this PR to the parent issue so that everyone can understand the motivation and context behind these changes. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduce the foundational retrieval domain model layer for the AI module.
This PR defines the typed data structures required by the retrieval pipeline, including source documents, text chunks, graph references, evidence, and version metadata. It also adds JSON serialization/deserialization and centralized model validation.
#860 #863 #864
Changes
SourceDocumentSourceRefTextChunkEntityRefGraphVertexRefGraphEdgeRefGraphPathRefEvidenceEvidenceKindChannelScoreGraphVersionIndexVersionRetrievalModelJsonRetrievalModelValidationExceptionHow was this PR tested?