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.6.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

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.

• Only pgvector, FAISS, Qdrant, and Weaviate are ported — no Pinecone or Milvus backend yet. FAISS here is a pure-Java brute-force reimplementation (no native FAISS library, no JNI) with a custom, non-FAISS-compatible persistence format; Qdrant and Weaviate are both 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.
• 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.
• No document ingestion pipeline — the 28-format parser, OCR, web, audio, and video ingestion modules are not yet ported.
• 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.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.