ragleap-rag (Java)

Install

Requires Java 21+. Independently versioned from the Python package — this version number does not correspond to any PyPI release.

<dependency>
    <groupId>io.github.antonyrag</groupId>
    <artifactId>ragleap-rag</artifactId>
    <version>0.13.0</version>
</dependency>

Quick start

ConnectionPool pool = new ConnectionPool(databaseUrl);
SchemaManager.initSchema(pool, 3072);

EmbeddingService embedder = new EmbeddingService(
    new EmbeddingConfig("gemini", apiKey, "gemini-embedding-001", 3072, null));
PgVectorBackend store = new PgVectorBackend(pool);
GenerationService generator = new GenerationService(
    new ProviderConfig("gemini", apiKey, "gemini-2.5-flash", null));

VectorRetrievalService retrieval = new VectorRetrievalService(pool, embedder);
List<SearchResult> chunks = retrieval.searchSimilarChunks(pool, "What were Q3's key findings?", 5, 3072);
GenerationResult answer = generator.generateAnswer(
    "What were Q3's key findings?", chunks, null, null, null, "", null, null);

How it fits together

Same pipeline shape as the Python package's core: embed → store → retrieve → generate, plus conversation memory and query rewriting layered on top.

com.ragleap.rag.db.ConnectionPool            (HikariCP)
com.ragleap.rag.schema.SchemaManager
com.ragleap.rag.embedding.EmbeddingService   (7 providers)
com.ragleap.rag.vectorstore.PgVectorBackend  (dense, sparse, hybrid RRF)
com.ragleap.rag.retrieval.VectorRetrievalService
com.ragleap.rag.generation.GenerationService (streaming, structured output, vision, fallback chain)
com.ragleap.rag.memory.ConversationMemory    (Postgres-backed, session-scoped)
com.ragleap.rag.queryrewrite.QueryRewriter   (contextual rewrite, HyDE, multi-query, RRF)

Ported modules

Every module below is genuinely tested against real infrastructure where practical, and documented per-class where it is not (mainly: paid LLM providers with no test account available, verified via local HTTP stubs instead).

Core pipeline

Ingestion and entry point

Utility modules

Provider & backend counts

Every count below is from real, current source — not carried over from the Python package's numbers.

⚠ not live-verified  Gemini, Anthropic, and most OpenAI-compatible generation/embedding providers are code-complete but verified via local HTTP stubs rather than real paid accounts — documented per-class in the source. Ollama is live-verified throughout, since it runs free and local.

Known limitations

Stated upfront, matching this project's own standard for the Python package.

• All 6 vector backends the Python package has are now ported — pgvector, FAISS, Qdrant, Weaviate, Milvus, and Pinecone. FAISS is a pure-Java brute-force reimplementation (no native FAISS library, no JNI) with a custom, non-FAISS-compatible persistence format; Qdrant, Weaviate, Milvus, and Pinecone are all accessed over their plain REST APIs (no gRPC client dependency) — all deviations documented in their respective classes. Notably, this Java WeaviateBackend is live-verified against a real Weaviate instance, unlike the Python package's own WeaviateBackend, which its source documents as never having had one available to test against.
• MilvusBackend and PineconeBackend are NOT live-verified — same honest caveat their Python counterparts carry. Self-hosting Milvus requires a three-service stack (etcd, MinIO, milvus-standalone), judged too resource-risky on this project's VPS; Pinecone is managed-only with no self-hosted or emulator option at all. Both are code-complete against their official REST API reference documentation (fetched and read directly before writing any code, not assumed), and tested via a local HTTP stub server rather than a real service. PineconeBackend's delete-by-ids request shape follows an older documentation example rather than the pinned API version's own reference page — the likeliest place for a real account to disagree with this class.
• Four vector backends behave differently in a few edge cases — the cross-backend benchmark and failure-mode matrix found identical retrieval on pgvector, FAISS, Qdrant and Weaviate (overlap@10 = 1.000 on 296 documents and 60 queries) and five bugs, all fixed in 0.11.0; four documented differences remain (duplicate chunk inserts, an all-zero vector, a wrong-dimension query, and the exception type when the server is unreachable). It does not measure approximate-search recall at scale, and Milvus and Pinecone are not covered.
• 5 tests depend on a live local Ollama instance and are occasionally flaky under this VPS's CPU contention (not a code defect) — see the module's CI history for current pass rate.
• Ingestion is partly ported — the document parser covers 27 of the Python package's 28 formats (no Parquet). Text, file, image, audio and video ingestion are ported; web-page (URL) ingestion is not among the methods listed in the 0.13.0 notes. Whisper and Deepgram transcription are stub-tested only.
• The RagLeap entry point is not live-verified against paid providers — it was compared with the real Python class on 33 scenarios using fake collaborators and exercised after release against a local Postgres, but not run end to end against real paid LLM or embedding providers.
• No streaming token usage — same limitation as the Python package; providers report usage inconsistently mid-stream.
• generateAnswerStream() uses a callback, not an Iterator — a deliberate Java-idiomatic deviation from the Python source, since Java has no generator/yield.

Release notes

v0.13.0 — adds the RagLeap entry point, the Java counterpart of the Python RagLeap class (ask, askStream, retrieve, evaluate, conversation history, document methods, ingestion helpers and ingestBatch). Compared with the real Python class (ragleap-rag 0.13.0, commit d210dab) on 33 scenarios. 502 tests ran in the release build (0 failures, 8 skipped); five live-Ollama tests are excluded because they are timing-sensitive. Not live-verified: the facade was not run end to end against real paid LLM or embedding providers; Milvus, Pinecone, Whisper and Deepgram are stub-tested only.

v0.12.0 — adds ingestion: IngestionService for text, files, images, audio and video, OCR through the Tesseract binary, audio extraction from video through ffmpeg, and transcription with OpenAI Whisper, Deepgram or a custom function (not live-verified). Behaviour change: archives with more than 1,000 members or more than 100 MB declared uncompressed are rejected. 497 tests, 0 failing in a full local run.

v0.11.0 — adds the document parser (DocumentParser): 27 of the Python package's 28 formats, each checked against the real Python parser's output on 79 generated fixture files. Parquet is deliberately not ported (Java Parquet readers need a very heavy Hadoop dependency tree) and legacy .xls needs the optional Apache POI dependency. Also fixes five inconsistencies found by a new cross-backend benchmark and failure-mode matrix. Behaviour changes: FAISS and Weaviate scores are now on the same [0, 1] scale as pgvector and Qdrant (they previously returned raw cosine in [-1, 1], so re-check any score thresholds); insertChunk rejects a wrong-dimension vector on FAISS, Qdrant and Weaviate; Weaviate returns no results instead of an error when searching an empty collection or filtering on a key no chunk has yet; Qdrant and Weaviate no longer leave a local row behind when a server write fails. New dependencies: PDFBox 3.0.8 and jsoup 1.23.2. 422 tests, 0 failing in a full local run with Postgres, Qdrant, Weaviate and Ollama (tests that need live services skip themselves in CI). Not yet ported: OCR, web, audio and video ingestion. The Maven Central description, which still described the 0.5.0 feature set, now matches the library.

v0.10.0 — adds PineconeBackend, completing all 6 vector backends the Python package has. Not live-verified (same caveat as the Python PineconeBackend) — Pinecone is managed-only, no account was available. Grounded in Pinecone's official REST API docs, with the API version pinned to 2026-04 (2026-07 introduced a schema-based Documents API that changed the create-index request). Cosine scores normalized to [0,1] to match the other backends, based on Pinecone's own documentation that cosine similarity ranges over [-1,1] — the Python PineconeBackend returns the raw score and likely has the same latent inconsistency Qdrant and Milvus had before their own fixes. 22 new tests via a local HTTP stub server.

v0.9.0 — adds MilvusBackend, a fifth vector backend. Not live-verified (same caveat as the Python MilvusBackend) — no Milvus/Zilliz Cloud instance was available; self-hosting needs a three-service stack (etcd, MinIO, milvus-standalone) judged too resource-risky on this VPS. Grounded in Milvus's official REST v2 API docs, fetched and read before writing any code. No UUID indirection needed - Milvus's VarChar primary key accepts documentId:chunkIndex directly. 18 new tests via a local HTTP stub server, matching this codebase's existing pattern for testing unavailable providers.

v0.8.0 — adds WeaviateBackend, a fourth vector backend: talks to Weaviate's REST + GraphQL API directly (no gRPC client, no new Maven dependency), with deterministic object IDs, a SQLite text sidecar, self-provided vectors (no built-in vectorizer), and a cosine-distance-to-similarity conversion confirmed against a real live instance before any code was written. 17 new tests, all live against a real running Weaviate instance — the first live-verified Weaviate backend across either language for this project.

v0.7.0 — adds QdrantBackend, a third vector backend: talks to Qdrant's plain REST API directly (no gRPC client, no new Maven dependency), with deterministic point IDs, a SQLite text sidecar, and a built-in fix for Qdrant's raw [-1,1] cosine-similarity range (normalized to [0,1] to match pgvector's convention — the same bug already found and fixed in the Python source). 16 new tests, all live against a real running Qdrant instance rather than mocked.

v0.6.0 — adds FaissBackend, a second vector backend alongside pgvector: a pure-Java brute-force exact search (no native FAISS library, no JNI) over an in-memory index, with a SQLite metadata sidecar and a custom, documented, non-FAISS-compatible binary persistence format. 12 new tests, all live-verified.

v0.5.0 — first public release. Core pipeline (connection pooling, embeddings, pgvector storage, retrieval, generation with streaming/structured-output/vision/fallback), conversation memory, and query rewriting, all ported from the real Python source and genuinely tested. Published to Maven Central after namespace verification, GPG signing setup, and a version scheme deliberately kept independent from the Python package's PyPI versioning.