Metadata-Version: 2.4
Name: perfectrag
Version: 1.0.0
Summary: Dynamic RAG framework scaffolder — wizard-driven, hardware-aware, docker-ready, with eval/observability/agent addons
Project-URL: Homepage, https://github.com/your-org/perfectrag
Project-URL: Issues, https://github.com/your-org/perfectrag/issues
Author: perfectRAG
License: Apache-2.0
Keywords: docker,graphrag,mcp,ollama,rag,scaffolder,wizard
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Requires-Dist: copier>=9.3
Requires-Dist: distro>=1.9
Requires-Dist: inquirerpy>=0.3.4
Requires-Dist: jinja2>=3.1
Requires-Dist: nvidia-ml-py>=12.535
Requires-Dist: psutil>=5.9
Requires-Dist: py-cpuinfo>=9.0
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'dev'
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'web'
Description-Content-Type: text/markdown

# 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

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

## Quickstart — the one-liner

```bash
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](https://github.com/infiniflow/ragflow) |
| `lightrag-stack` | GraphRAG / multi-hop reasoning | [LightRAG](https://github.com/HKUDS/LightRAG) |
| `dify-stack` | Workflow / agent / no-code team | [Dify](https://github.com/langgenius/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](https://github.com/paperclipai/paperclip) |

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

## Browser wizard

```bash
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](docs/ui.md).

## Deploy to production

```bash
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/deploy.md).

## Docs

- [Addons](docs/addons.md)
- [Eval](docs/eval.md)
- [Observability](docs/observability.md)
- [Deploy](docs/deploy.md)
- [Browser UI](docs/ui.md)
- [Templates](docs/templates.md)
- [MCP registry](docs/mcp.md)
- [Skills](docs/skills.md)

## License

Apache-2.0
