perfectrag 1.4.0

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

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):

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

🔌 Addons

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

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