How to set up document search with Python in 5 minutes

TL;DR: Install the ragex Python package, create a client with your API key, create a knowledge base, upload a document, and search. Ragex handles parsing, chunking, embedding, and reranking for 16 file types. You get ranked results in five API calls with no infrastructure setup.

Step 1: Install the SDK

pip install ragex

The SDK uses httpx under the hood and has no other external dependencies. It works with Python 3.9+.

Step 2: Create a client and knowledge base

from ragex import RagexClient

client = RagexClient(api_key="YOUR_API_KEY")
kb = client.create_knowledge_base(name="Product Docs")
print(f"Knowledge base created: {kb['id']}")

A knowledge base is a logical collection of documents scoped to a use case. All searches are scoped to one knowledge base. You can create as many as your plan allows.

Step 3: Upload and process documents

import time

# Upload a file — supports PDF, DOCX, PPTX, XLSX, images, and more
doc = client.upload_document(kb["id"], "guide.pdf")

# Wait for async processing: pending → parsing → chunking → embedding → ready
while doc["status"] not in ("ready", "failed"):
    time.sleep(2)
    doc = client.get_document(kb["id"], doc["id"])

print(f"Document ready with {doc['chunk_count']} chunks")

Processing is asynchronous. The API parses the document, splits it into chunks, generates embeddings, and indexes everything. A 10-page PDF processes in seconds. You can also upload raw text directly:

text_doc = client.upload_text_document(
    kb["id"],
    text="Your raw content here...",
    name="notes.txt",
)

Step 4: Search

results = client.search(
    kb["id"],
    query="How do I configure authentication?",
    top_k=5,
)

for r in results["results"]:
    print(f"Score: {r['score']:.3f} — {r['text'][:100]}")

The search endpoint returns ranked text chunks with relevance scores, document metadata, and page numbers. Reranking is enabled by default — results are sorted by a cross-encoder for better relevance, not just raw vector similarity.

Step 5: Use results with your LLM

Pass the search results as context to any LLM:

context = "\n\n".join(r["text"] for r in results["results"])
prompt = f"Based on the following context, answer the question.\n\nContext:\n{context}\n\nQuestion: How do I configure authentication?"
# Send prompt to OpenAI, Anthropic, or any LLM

That is the complete integration. Five steps, under 5 minutes, no vector database or embedding model to manage.

What about metadata filtering?

You can attach metadata to documents at upload time and filter on it during search:

doc = client.upload_document(
    kb["id"], "engineering-specs.pdf",
    metadata={"department": "engineering", "version": 3},
)

results = client.search(
    kb["id"],
    query="deployment checklist",
    filter={"department": {"$eq": "engineering"}},
)

Supported filter operators include $eq, $ne, $gt, $gte, $lt, $lte, $in, and $nin. This makes it practical to build multi-tenant search where different users see different document subsets.

FAQ

What Python version do I need?

The SDK requires Python 3.9 or higher. It uses httpx for HTTP requests, which is installed automatically as a dependency when you run pip install ragex.

Can I upload multiple documents at once?

Yes. Call upload_document for each file — they process concurrently on the server. You do not need to wait for one document to finish before uploading the next. Each document becomes searchable as soon as its status reaches ready.

How do I handle errors during document processing?

Check the status field on the document. If it reaches failed, the error_detail field explains what went wrong (unsupported format, file corruption, etc.). You can re-upload the document after fixing the issue.

---

Last updated: 2026-03-09