Skip to main content

ragpick

Pick the right RAG architecture for your system, define it as code, and prove it works on your data.

CI PyPI Python License

Why ragpick

Building a RAG pipeline is easy. Choosing the right one is the hard part. Plain vector search misses the product codes and IDs your customers type. Internal documents leak into answers for the wrong users. A "better" pipeline ships without evidence that it is better.

ragpick makes the architecture an explicit, testable decision:

  • Recommend. Describe your requirements and get a blueprint plus the reasons for it, the alternatives, and warnings.
  • Build. The pipeline is a validated rag.yaml (architecture as code), with document-level access control built in.
  • Evaluate. Compare blueprints on your own questions: hit rate, MRR, faithfulness, latency and cost, side by side.

ragpick works alongside LangChain and LlamaIndex rather than replacing them. It owns the interfaces, config, selector and evaluation; anything else plugs in as a component.

60-second quickstart (offline, no API key)

pip install ragpick
git clone https://github.com/kavishkakalhara1/ragpick && cd ragpick   # for the sample data

ragpick init --blueprint naive --yes          # writes rag.yaml with fake, offline models
ragpick ingest examples/data                  # load → chunk → embed → index
ragpick query "How do I reset my password?"   # answer with citations
╭──────────────────────────────── Answer ────────────────────────────────╮
│ On the sign-in screen of the Lumen app, tap "Forgot password" and      │
│ enter the email address on your account. [1] You will receive a reset  │
│ link that is valid for 30 minutes. [1]                                 │
╰────────────────────────────────────────────────────────────────────────╯
Citations: account-and-password.md#0

Ask which architecture fits, then compare two blueprints on a question set:

ragpick recommend --config examples/hybrid.yaml
ragpick eval examples/eval.jsonl --config examples/naive.yaml --config examples/hybrid.yaml
           Evaluation results
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Metric           ┃   naive ┃   hybrid ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ hit_rate@k       │   0.929 │    1.000 │
│ mrr              │   0.774 │    0.893 │
│ precision@k      │   0.357 │    0.381 │
│ ...              │         │          │

The fake components are deterministic stand-ins for tests and demos: the embedder is a hashing trick and the generator quotes the best-matching sentences.

Quickstart with OpenAI

pip install "ragpick[openai]"
export OPENAI_API_KEY=sk-...

ragpick init --blueprint hybrid --provider openai --yes
ragpick ingest ./docs
ragpick query "How do I reset my password?" --groups support --show-contexts

Or in Python:

from ragpick import Pipeline

p = Pipeline.from_yaml("rag.yaml")
p.ingest("./docs")
ans = p.query("How do I reset my password?", groups=["support"])
print(ans.text, ans.citations)

A rag.yaml names a blueprint and overrides only what differs:

version: 1
name: my-support-bot
blueprint: hybrid
requirements: {corpus_size: medium, keyword_heavy: true, access_control: true}
components:
  embedder:  {type: openai, params: {model: text-embedding-3-small}}
  generator: {type: openai, params: {model: gpt-4o-mini, temperature: 0}}
query: {top_k: 5}

Restrict a document to groups with front matter. Queries without matching --groups never see it:

---
allowed_groups: [support]
---

Blueprints

Blueprint Status Best for
naive ✅ stable prototypes, small corpora
hybrid ✅ stable default for commercial systems; keyword-heavy domains (BM25 + vector + RRF, optional cross-encoder)
parent_child 🗺 planned long structured documents
sql 🗺 planned structured data, analytics questions
graph 🗺 planned multi-hop and global questions (GraphRAG)
agentic 🗺 planned multi-step questions and tool use
corrective 🗺 planned noisy corpora with retrieval grading

CLI

Command What it does
ragpick init interactive questions → rag.yaml (--blueprint NAME --yes for scripts)
ragpick recommend blueprint, reasons, alternatives, warnings
ragpick blueprints catalogue and roadmap
ragpick ingest PATH load, chunk, embed, index, persist
ragpick query "…" answer with citations (--groups, --show-contexts)
ragpick eval DATASET -c a.yaml -c b.yaml comparison table (--output results.json/.csv)
ragpick validate print the merged config (secrets masked)

Optional extras

Extra Adds
openai OpenAI embeddings and chat models (and OpenAI-compatible servers)
local sentence-transformers embeddings
rerank cross-encoder reranker
qdrant Qdrant vector store
pdf PDF loader
all everything above

The Ollama generator needs no extra.

Documentation

Concepts · Blueprints · Config reference · Writing a plugin · Evaluation · Design decisions

Roadmap

  • v0.2: parent_child blueprint, ragpick bench (automatic blueprint comparison), LangChain and LlamaIndex adapters
  • v0.3: sql and corrective blueprints, tracing, caching
  • Later: graph and agentic blueprints, ragpick serve HTTP API, multi-tenancy, TypeScript SDK

Contributing

Contributions are very welcome, especially new loaders, stores and blueprints. See CONTRIBUTING.md to get set up in two minutes with uv.

Author

Created and maintained by Kavishka Kalhara: kavishka-kalhara.me · GitHub @kavishkakalhara1

License

Copyright 2026 Kavishka Kalhara. Licensed under Apache-2.0.

Metadata

Release files for ragpick 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ragpick 0.1.0
File Size Uploaded Provenance Actions
ragpick-0.1.0.tar.gz 88.4 kB Without provenance Details for ragpick-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ragpick 0.1.0
File Interpreter ABI Platform Actions
ragpick-0.1.0-py3-none-any.whl Python 3 none any Details for ragpick-0.1.0-py3-none-any.whl

Total release size: 155.4 kB

Release files / ragpick-0.1.0.tar.gz

Download URL ragpick-0.1.0.tar.gz
Size 88.4 kB
Tags Source
SHA-256 checksum
How to use checksums
5d33312d071b07b158357be7742ba890cfb52075e0f5a8079f3914e0f5fcfa2a
BLAKE2b-256 checksum
How to use checksums
93f65efcbd7c691f02b292e38994815aa7b8bdef0627e1cfaa7279774f33630e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / ragpick-0.1.0-py3-none-any.whl

Download URL ragpick-0.1.0-py3-none-any.whl
Size 67.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7d97205be08368d2fb4e2936006658cec19720149eb9e3f6832f80f2e6f7614b
BLAKE2b-256 checksum
How to use checksums
7cd0b908b73b6673a22ca68d9f8dc5931f39a0d60a9c9ee6c651848c19f5aafe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for ragpick 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page