perfectrag 1.0.0

Dynamic RAG framework scaffolder — wizard-driven, hardware-aware, docker-ready, with eval/observability/agent addons

perfectRAG

Dynamic RAG framework scaffolder — wizard + docker-compose + UI + eval + observability + agents, all free & open-source.

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