What does it take to port a graph-retrieval library from Python to Java without relying on API similarity alone?
For RagLeap Graph Java v0.2.0, the answer was a combination of parity tests, deliberate mutations, database integration tests, and validation of the actual published artifact.
Release: RagLeap Graph Java v0.2.0
Features in this release
The Java library now includes:
- Optional LLM-based entity and relation extraction.
- Configurable extraction and entity deduplication.
- Cross-chunk relation handling.
- Hybrid vector + graph retrieval and graph-only retrieval.
- Chunk and graph-path citations.
- Pluggable graph and vector search interfaces.
- Backfill utilities and a schema migration runner.
Regex-based extraction remains the default. LLM integration is optional.
How we approached parity testing
We compared the Java implementation against the Python ragleap-graph v0.9.0 implementation.
Rather than comparing method names, we exercised behavior using recorded calls, parameters, outputs, and scripted model responses.
The test scenarios covered:
- 422 string-similarity pairs.
- 25 extraction-configuration cases.
- Entity and relation extraction.
- Graph upserts, including Cypher statements and parameters.
- Backfills and migration behavior.
- Retrieval scenarios and retrieval configurations.
We also ran 27 deliberate mutations across the new functionality. Every injected break was caught by the parity tests.
This is evidence for the tested cases, not a mathematical guarantee of complete equivalence.
Why mutation testing matters
A passing test suite can still miss bugs if its assertions are too weak.
Mutation testing deliberately changes behavior to check whether the tests notice. For this release, the 27 deliberate breaks were caught by the parity tests.
That gave us additional confidence that the tests were checking behavior rather than merely executing code paths.
Testing the real release
The full local run used generated parity fixtures and a live Neo4j 5.26.29 Community instance:
- 129 tests
- 0 failures
- 0 skipped tests
After publishing, we resolved the Maven artifact in a clean project and exercised health checks, upserts, backfills, and graph-only retrieval against live Neo4j.
Maven coordinates:
io.github.antonyrag:ragleap-graph:0.2.0\
What still needs testing?
LLM extraction hasn't been verified against a real model provider. Compatibility with other Neo4j deployments also needs more testing, and the optional vector-search adapter hasn't been tested against a live RagLeap facade.
The PostgreSQL audit writer hasn't been ported yet.
Documenting these limitations is part of making a library easier to evaluate responsibly.
Try it and share feedback
Source and release notes:
https://github.com/antonyrag/ragleap-core/releases/tag/ragleap-graph-java-v0.2.0
RagLeap is fully open-source and self-hosted, with a wider ecosystem of retrieval, graph, and AI tooling libraries.
If you work with Java or Neo4j, I'd appreciate feedback on the API, compatibility, test coverage, and integration experience.
What integration test would you add before using this library in production?
Top comments (0)