perfectrag 1.4.0

RAG scaffolder + embedded library: 7 backbones incl. code-graph/R2R/Onyx, advanced retrieval (contextual, parent-doc, query-expansion+RRF, CRAG), scored advisor, SaaS Query API with auth + rate limit

Stop gluing RAG docker-compose files by hand.

A RAG scaffolder and an embedded Python library — run it with Docker, without Docker, or as a SaaS API. Your hardware, your backbone, your call.

---

perfectrag detects your hardware, asks what you're building, picks an opinionated recipe, and renders a complete project — docker-compose.yml + .env + mcp.yaml + skills/ — wrapping one of 7 open-source RAG backbones. Run perfectrag up and you have a RAG service + UI. No YAML archaeology.

Don't want Docker? The same engine ships as a pip-installable library: from perfectrag import RAG.

✨ Three ways to use it

# 1️⃣  Embedded Python library — zero Docker
from perfectrag import RAG

rag = RAG.from_config("perfectrag.yml")
rag.ingest("./docs")
print(rag.query("What is RAG?").answer)

# 2️⃣  Scaffolded docker-compose stack — same config, same API
perfectrag init my-rag
cd my-rag && perfectrag up

# 3️⃣  SaaS API for external clients — bearer auth + rate limit built in
perfectrag key issue --name "prod app" --rate 100 -p .
curl -H "Authorization: Bearer sk-rag-..." \
  -d '{"question":"..."}' http://localhost:8000/v1/query

🧠 How it works

Five pure stages, from bare metal to a running stack:

   detect hardware  →  ask use-case  →  pick recipe  →  scaffold  →  orchestrate
   CPU/GPU/Apple       Q&A/graph/         LLM+embed+      compose+     up · doctor ·
   + VRAM tier         agent/code         reranker+db     env+mcp      logs · eval · deploy

1. Detects hardware — CPU / NVIDIA / Apple Silicon / AMD, with a VRAM tier.
2. Asks use-case questions — Q&A · GraphRAG · agent · multimodal · code · web.
3. Picks a recipe — LLM + embedding + reranker + vector DB + parser, tuned to your tier.
4. Scaffolds a full project — docker-compose.yml + .env + mcp.yaml + skills/ + optional addons.
5. Orchestrates — perfectrag up / doctor / logs / eval / deploy, or a Next.js browser wizard if you'd rather click than type.

📦 Install

pip install perfectrag           # CLI + embedded library
pip install 'perfectrag[web]'    # + FastAPI backend for the Next.js UI

🚀 Quickstart — the one-liner

perfectrag init my-rag --with eval,observability,paperclip
cd my-rag
perfectrag up

…and you have a RAG service, an eval dashboard, an observability gateway, and a multi-agent orchestrator running on localhost — in one shot.

🧩 The 7 backbones

Template	Best for	Backbone
custom-naive-rag	Learning · CPU-only · tiny corpus	FastAPI + Qdrant + Ollama + open-webui
ragflow-stack	Production Q&A · hybrid search · agentic	RAGFlow
lightrag-stack	GraphRAG · multi-hop reasoning	LightRAG
dify-stack	Workflow / agent builder · no-code teams	Dify
code-graph-rag	Code intelligence for AI coding agents	Serena (LSP) + ast-grep MCP (+ Memgraph)
r2r-stack	All-in-one agentic RAG	R2R
onyx-stack	Enterprise connector search	Onyx

The wizard auto-routes to the right one (GraphRAG → LightRAG, code → code-graph-rag, …) — or force any with --template. Bring your own via [project.entry-points."perfectrag.templates"]; users get it after pip install. See docs/templates.md.

🎯 Advanced retrieval — measure, don't guess

The embedded library ships techniques you toggle in perfectrag.yml (the wizard turns them on based on your answers):

Technique	Config	When it helps
Contextual Retrieval	contextual: true	recall on terse chunks (needs a capable LLM)
Parent-document	parent_chunk_size: 2048	precise match + richer context, free
Query expansion + RRF	query_expansion: 3	terse / multi-hop queries
Corrective RAG (CRAG)	corrective: true	re-retrieve when results look off

Then let the data decide which to keep:

perfectrag tune --docs ./docs --golden ./golden.jsonl --apply   # benchmarks each technique on YOUR corpus, writes the winner
perfectrag eval --retrieval -d golden.jsonl --gate              # recall@k / MRR / nDCG as a CI gate — no Docker

See docs/retrieval.md.

🧩 Extend it with decorators

perfectRAG is a framework, not a black box. Plug in your own data sources, retrieval logic, post-processing, tools, and skills with one decorator — no subclassing:

from perfectrag import RAG, inject, transform, tool, Document

@inject("notion")                     # a custom data source
def notion(database_id: str):
    for page in notion_client.query(database_id):
        yield Document(text=page.text, source=f"notion:{page.id}")

@transform("boost_recent")            # a post-retrieval hook (rerank/filter/expand)
def boost_recent(ctx, query, hits):
    return sorted(hits, key=lambda h: h.chunk.metadata.get("date", 0), reverse=True)

@tool                                 # a callable tool (schema inferred from type hints)
def calculator(expression: str) -> str:
    "Evaluate a basic arithmetic expression."
    return str(eval(expression, {"__builtins__": {}}, {}))

rag = RAG.from_config("perfectrag.yml")      # extensions/retriever/transforms in the yaml
rag.ingest_from("notion", database_id="…")   # uses @inject
rag.agent("What's 12×9, and what do the docs say about CRAG?")  # ReAct loop over your @tool(s)
rag.tool_schemas()                           # OpenAI/Anthropic/MCP-ready function schemas

Five decorators — @inject, @retrieve, @transform, @tool, @skill — wired in via config (extensions: [./my_ext.py]), constructor, or a pip entry point. Plus rag.agent(...) for ReAct tool-calling, and perfectrag export-tools to expose your tools as an MCP server. See docs/extensions.md and examples/my_extensions.py.

🛠️ Commands

Command	What it does
perfectrag init [DIR]	Wizard → scaffold a project
perfectrag init DIR --with a,b,c	Install addons at init time
perfectrag init DIR --template ragflow-stack	Force a specific backbone
perfectrag add mcp/skill/addon <name>	Extend a generated project
perfectrag up / down / logs / doctor	Orchestrate the generated project
perfectrag eval --dataset qa.jsonl	Generation metrics — RAGAS + DeepEval (needs eval addon)
perfectrag eval --retrieval -d golden.jsonl --gate	Retrieval metrics + CI gate, no Docker
perfectrag tune --docs ./docs --golden g.jsonl --apply	Auto-pick the best retrieval technique on your data
perfectrag advise "..."	Scored, evaluative recipe recommendation
perfectrag deploy helm/flyio/railway	Render production deploy assets
perfectrag web	Start the FastAPI backend for the Next.js UI
perfectrag list templates/mcp/skills/addons/extensions/installed	Show catalogues
perfectrag list extensions --from ./ext.py	Inspect your registered @inject/@tool/…
perfectrag export-tools --from ./ext.py	Expose your @tools as an MCP server (→ mcp.yaml)
perfectrag hw	Show detected hardware + tier

🔌 Addons

One-flag overlays that perfectrag up auto-merges (compose.<name>.yml):

Addon	Purpose	Based on
eval	RAG quality measurement	RAGAS, DeepEval
observability	LLM gateway + tracing	LiteLLM, Langfuse
context-eng	Prompt compression + memory	DSPy, LLMLingua, mem0
ingest-worker	Scheduled web crawl → vector store	Crawl4AI
notion-sync · gdrive-sync · confluence-sync	Sources → vector store	official SDKs
paperclip	Multi-agent orchestrator	Paperclip

See docs/addons.md.

🖥️ Browser wizard

Prefer clicking to typing?

pip install 'perfectrag[web]'
perfectrag web                        # backend on :7777
cd ui && pnpm install && pnpm dev     # UI on :3001

See docs/ui.md.

☁️ Deploy to production

perfectrag deploy helm --project ./my-rag --out ./chart
helm lint ./chart && helm install my-rag ./chart

Also renders flyio and railway assets. See docs/deploy.md.

📚 Docs

Retrieval · Extensions · Code intelligence · Templates · Addons · Eval · Observability · Deploy · Browser UI · MCP registry · Skills · Stack-boot test findings · Changelog

📄 License

Apache-2.0

_{Built for people who want a working RAG stack, not a weekend of YAML.}