RagLeap Packages
Looking for the RagLeap platform? This page documents the open-source pip install ragleap-rag library. For the hosted business platform (AI Office, WhatsApp/Voice bots, billing), see docs.ragleap.com instead.
244 / 244 tests passing · live-verified against real infrastructure

ragleap-rag

A narrow, opinionated hybrid retrieval engine — six vector backends, eight embedding providers, twelve-plus generation providers, one honest package.

0.12.2
PyPI version
244
Tests passing
4,853
Lines audited end-to-end
28
Ingestion formats

Install

Requires Python 3.9+. Vector backends beyond PgVector, and non-default embedding providers, are optional extras.

pip install ragleap-rag
# or, with uv
uv add ragleap-rag

Quick start

from ragleap import RagLeap, ProviderConfig, EmbeddingConfig

rag = RagLeap(
    database_url="postgresql://...",
    primary=ProviderConfig(provider="gemini", api_key="..."),
    embedder=EmbeddingConfig(provider="gemini", api_key="..."),
)
rag.init_schema()
rag.ingest("report.pdf")

answer = rag.ask("What were Q3's key findings?")
chunks = rag.retrieve("What were Q3's key findings?", top_k=5)  # new in v0.12.0, no generation

Full public API surface

Confirmed via direct source reading during this session's full audit — not via inspect().

from ragleap import RagLeap, ProviderConfig, EmbeddingConfig, TranscriptionConfig
from ragleap.vectorstores import (
    VectorBackend, PgVectorBackend, FAISSBackend,
    PineconeBackend, WeaviateBackend, QdrantBackend, MilvusBackend,
)
from ragleap.guardrails import GuardrailViolation
from ragleap.query_rewrite import contextual_rewrite, hyde_document, multi_query_variants, reciprocal_rank_fusion
from ragleap.structured import parse_and_validate, parse_and_validate_object
from ragleap.cost import CostTracker, compute_cost, SEED_PRICING_TABLE

Ingestion

rag.ingest(path)
Ingest a file — 28 supported formats.
rag.ingest_text(text)
Ingest raw text directly.
rag.ingest_url(url)
Fetch and ingest a web page.
rag.ingest_image(path)
Ingest an image (vision-capable providers).
rag.ingest_audio(path)
Transcribe and ingest audio via Whisper.
rag.ingest_video(path)
Extract audio track, transcribe, and ingest.

Query

rag.ask(query, ...)
Full pipeline: embed → search → (optional rerank) → generate.
rag.ask_stream(query, ...)
Streaming variant of ask(). Does not report token usage — each provider streams differently.
rag.retrieve(query, top_k=5, hybrid=True, rerank=False, metadata_filter=None)
New in v0.12.0. Reuses ask()'s exact retrieval pipeline, stopping before generation. Does not support query_rewrite= or session_id= — those need LLM calls ask() owns.
rag.evaluate(test_cases)
Run a labeled evaluation set against the pipeline.

Document management

rag.list_documents()
List ingested documents.
rag.delete_document(id)
Remove a document and its chunks.
rag.update_document(id, ...)
Re-ingest or patch an existing document.
rag.get_history() / rag.clear_session()
Conversation history for session-based ask() calls.
rag.cache_stats()
Inspect embedding-cache hit/miss counters.

Async

aingest* / aask / aask_stream / ingest_batch
Async variants of the above, plus batch ingestion.

retrieve() — why it exists

Added specifically so ragleap-graph's GraphRetriever could reach chunk-level retrieval without touching RagLeap's private internals (_vector_backend, _embed_query_cached()) across a package boundary. Shipped as a proper, tested, public method instead.

chunks = rag.retrieve(
    query: str,
    top_k: int = 5,
    hybrid: bool = True,
    rerank: bool = False,
    metadata_filter: Optional[Dict] = None,
) -> List[Dict]

6 new tests shipped with this method, including one that makes the generator raise if called — proving retrieve() never triggers generation.

Provider & backend counts

Every count below was cross-checked against real code this session, not carried forward from marketing copy.

6
Vector backends
PgVector, FAISS, Pinecone, Weaviate, Qdrant, Milvus
8
Embedding providers
Gemini + 4 OpenAI-compatible + 2 custom-shape + custom
12+
Generation providers
10 base URLs + Gemini + Anthropic + custom = 13

⚠ not live-verified  Pinecone, Weaviate, Qdrant, and Milvus backends, and Mistral/Together/Cohere/Voyage embeddings, are code-complete but have no real test account available. Labeled honestly in each module's own docstring.

Known limitations

Drawn from the package's own docstrings, plus two findings from this session's full audit — neither fixed yet.

  • not fixed
    token_count is word-count, not real LLM tokenization. chunker.py's _tokenize() does a whitespace split. Consistent across chunker.py, schema.py's DDL, and all 6 vector backends — internally consistent, just not what the field name implies.
  • not fixed
    Milvus's similarity_score may not be normalized like the other 5 backends. PgVector/FAISS/Pinecone return true cosine similarity; Weaviate converts distance→similarity; Milvus returns raw distance directly.
  • ask_stream() reports no token usage — each provider streams differently.
  • MAX_CONTEXT_CHARS is a char-count approximation, not exact tokenization.
  • Hybrid search's ranking-quality improvement is unverified beyond fusion-math correctness.
  • Whisper transcription accuracy varies by language.

Metadata corrections

v0.12.1 — The first-draft v0.12.0 PyPI description claimed "knowledge-graph integration via ragleap-graph" — backwards. ragleap-rag has zero dependency on or awareness of ragleap-graph; it's the other way around. Caught before the session moved on and published as a metadata-only patch, along with removing a "neo4j" keyword that implied a dependency that doesn't exist.

v0.12.2 — The PyPI Documentation URL pointed to docs.ragleap.com, the commercial platform's docs, which have zero content about this package. Corrected to point to this reference page instead.