perfectrag 1.1.0

RAG scaffolder + embedded library: Docker-free local mode, multi-backend (Qdrant/Milvus/Chroma/LanceDB/pgvector), Gemini advisor, SaaS Query API with auth + rate limit

perfectRAG

RAG scaffolder + embedded Python library. Run with Docker, without Docker, or as a SaaS API — your choice.

v1.1 adds: Docker-free local mode (from perfectrag import RAG), full component matrix (5 vector DBs × 5 embeddings × 4 rerankers × 6 LLM runtimes), Gemini advisor, and a built-in OpenAI-style Query API with bearer auth + rate limit.

Three ways to use it

# 1. Embedded Python library (no 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
perfectrag key issue --name "prod app" --rate 100 -p .
curl -H "Authorization: Bearer sk-rag-..." \
  -d '{"question":"..."}' http://localhost:8000/v1/query

Instead of gluing RAGFlow/Dify/LightRAG docker-compose files by hand, perfectrag:

1. Detects hardware (CPU / NVIDIA / Apple Silicon / AMD) + 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 hardware.
4. Scaffolds a full project (docker-compose.yml + .env + mcp.yaml + skills/ + optional addons).
5. Orchestrates with perfectrag up / doctor / logs / eval / deploy.
6. Ships a browser wizard (Next.js) if you'd rather click than type.

Install

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

Quickstart — the one-liner

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

That gives you a RAG service, eval dashboard, observability gateway, and multi-agent orchestrator running on localhost in one shot.

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	Run RAGAS + DeepEval (needs eval addon)
perfectrag deploy helm/flyio/railway	Render production deploy assets
perfectrag web	Start FastAPI backend for Next.js UI
perfectrag list templates/mcp/skills/addons/installed	Show catalogues
perfectrag hw	Show detected hardware + tier

Templates (v1.0)

Template	Use-case	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 / no-code team	Dify

Third-party templates: publish via [project.entry-points."perfectrag.templates"] — users get them after pip install.

Addons (v1.0)

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	Notion → vector store	notion-client
gdrive-sync	Google Drive → vector store	google-api-python-client
confluence-sync	Confluence → vector store	atlassian-python-api
paperclip	Multi-agent orchestrator	Paperclip

Each addon is a compose.<name>.yml overlay that perfectrag up auto-merges. See docs/addons.md.

Browser wizard

pip install 'perfectrag[web]'
perfectrag web           # backend on :7777

# in another terminal
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 supports flyio and railway. See docs/deploy.md.

Docs

• Addons
• Eval
• Observability
• Deploy
• Browser UI
• Templates
• MCP registry
• Skills

License

Apache-2.0