Skip to content

library.md

Latest commit

 

History

History
314 lines (230 loc) · 7.31 KB

library.md

File metadata and controls

314 lines (230 loc) · 7.31 KB
Raw

xrag Python Library Guide

This guide is for Python users building with xrag as a library.

What xrag gives you

xrag is a typed Python library for document ingest, chunk indexing, retrieval, and retrieve-plus-generate workflows.

Use it when you want one library for:

  • ingesting source documents into a vector-backed retrieval system
  • indexing pre-chunked offline data
  • retrieving typed chunks for your own LLM application
  • running a full RAG flow from one client

Choose your entrypoint

xrag has three main entrypoints:

  • Xrag High-level async client for application code
  • run_ingest / run_rag Lower-level functional API for callers that want direct AppConfig control
  • CLI Local workflows, debugging, artifact inspection, and evaluation runs

For most application code, start with Xrag.

Quickstart

from xrag import Xrag

client = Xrag(
    qdrant_path="data/dev/xrag_quickstart",
    generation="openai:gpt-4.1-nano",
)

doc = await client.documents.ingest("ir-sample-b.docx", collection="ir_docs")
result = await client.rag.ask(
    query="What is this document about?",
    collection="ir_docs",
)

print(doc.id)
print(result.answer)

Runnable example:

Common tasks

Ingest a document

doc = await client.documents.ingest(
    "ir-sample-b.docx",
    collection="ir_docs",
)

Use this when you want xrag to run parser, chunker, embedding, and indexing for you.

Examples:

Index offline chunks

doc = await client.documents.index_chunks(
    "data/chunks.json",
    collection="ir_docs",
)

Use this when your chunks already exist outside xrag's ingest path.

Examples:

Retrieve chunks only

result = await client.retrievals.search(
    query="What was revenue?",
    collection="ir_docs",
    top_k=5,
)

Use this when your application owns prompting and answer generation.

Example:

Ask a question

result = await client.rag.ask(
    query="What was revenue?",
    collection="ir_docs",
)

Use this when you want xrag to do retrieval and answer generation in one call.

Examples:

Client configuration

The Xrag(...) constructor is the main application-facing config surface.

Minimal configuration

Most users only need:

  • qdrant_url or qdrant_path
  • embedding
  • generation if they use client.rag.ask(...)

Example:

from xrag import Xrag

client = Xrag(
    qdrant_url="http://localhost:6333",
    embedding="openai:text-embedding-3-small",
    generation="openai:gpt-4.1-nano",
)

Full constructor surface

from xrag import Xrag
from xrag.config.models import RetrievalConfig

client = Xrag(
    qdrant_url="http://localhost:6333",
    qdrant_path=None,
    embedding="openai:text-embedding-3-small",
    generation="openai:gpt-4.1-nano",
    enrichment=("auto_keywords", "auto_questions"),
    reranker=None,
    parser="unstructured",
    chunker="section_table",
    retrieval_defaults=RetrievalConfig(
        provider="hybrid",
        options={
            "top_k": 10,
            "bm25_candidates": 50,
            "vector_candidates": 50,
            "rrf_k": 60,
            "dedup_family": False,
        },
    ),
    upload_dir="/tmp/xrag_uploads",
    artifacts_dir=None,
    timeout_s=30.0,
    ingest_timeout_s=600.0,
    tracing=None,
)

Parameter summary

Storage

  • qdrant_url URL of a running Qdrant server
  • qdrant_path Local filesystem path for Qdrant local mode

Set exactly one of them.

Model and backend selection

  • embedding Embedding provider string used for indexing and retrieval
  • generation Answer-generation provider string used by rag.ask
  • reranker Optional reranker configuration
  • tracing Optional tracing backend configuration

Ingest behavior

  • parser Parser provider configuration for documents.ingest. Default is the hosted unstructured API parser. unstructured_local:fast works for the lightweight local path in the base install. Add xrag[parser-unstructured-local-pdf] only for local PDF/OCR parsing.
  • chunker Chunking strategy for documents.ingest
  • enrichment Optional ingest-time enrichment stages
  • upload_dir Local spool location for bytes and file-like ingest inputs
  • artifacts_dir Base location for ingest artifacts

Retrieval behavior

  • retrieval_defaults Default retrieval config for retrievals.search and rag.ask

Timeouts

  • timeout_s General request timeout
  • ingest_timeout_s Ingest timeout budget

Environment-based setup

from xrag import Xrag

client = Xrag.from_env()

Useful environment variables:

  • XRAG_QDRANT_URL
  • XRAG_QDRANT_PATH
  • XRAG_DEFAULT_EMBEDDING
  • XRAG_DEFAULT_GENERATION
  • XRAG_DEFAULT_RERANKER
  • XRAG_UPLOAD_DIR
  • XRAG_ARTIFACTS_DIR

Multi-tenant usage

If your application scopes operations by tenant:

acme = client.for_tenant("acme")
result = await acme.rag.ask(query="Summarise the risks.", collection="ir_docs")

Example:

Retrieve-only usage

If your application already owns prompting, answer generation, or agent logic, omit generation= and use xrag only for ingest plus retrieval.

client = Xrag(
    qdrant_url="http://localhost:6333",
    embedding="openai:text-embedding-3-small",
)

Then call client.documents.* and client.retrievals.search(...).

Error handling

All high-level client operations raise from XragError.

Catch specific subclasses when you need narrower behavior, such as:

  • XragCollectionNotFound
  • XragDocumentNotFound
  • XragChunksInvalid
  • XragValidationError
  • XragGenerationNotConfigured

Example:

Example gallery

What to read next