ragfactory
Generate standalone Python RAG projects from YAML or JSON. Choose LangChain or
LlamaIndex, validate compatibility, and export editable code through a CLI or
REST API. Generated projects call upstream SDKs directly, with no ragfactory
runtime dependency.
Quick start
Requires Python 3.11 or newer. Generated SDK integration tests use Python 3.12.
# From this checkout, install the refreshed generator.
pip install -e ".[api]"
ragfactory init --name my-rag --vector-db qdrant --retrieval dense --output ./my-rag
cd my-rag
pip install .
cp .env.example .env
# Set API keys in .env. Start Qdrant locally or set QDRANT_URL.
python ingestion.py ./documents
uvicorn api:app --host 127.0.0.1 --port 8000
For an embedded database use --vector-db chromadb. It needs no database server;
API-backed embeddings and generation still need credentials. Generated entrypoints
load .env; existing process environment variables take precedence.
curl -X POST http://127.0.0.1:8000/query \
-H 'Content-Type: application/json' \
-d '{"query":"What do these documents describe?","return_contexts":true}'
Configuration
name: support-rag
framework: langchain # or llamaindex
indexing:
chunking: {type: recursive, chunk_size: 512, chunk_overlap: 50}
embedding: {type: openai, model: text-embedding-3-small}
vector_db: {type: qdrant, collection_name: support-docs, url: 'http://localhost:6333'}
retrieval: {type: dense, top_k: 10}
generation:
llm: {type: openai, model: gpt-5.4-mini, max_tokens: 2048}
ragfactory validate --config pipeline.yaml
ragfactory generate --config pipeline.yaml --output ./support-rag
LLM model IDs accept nonempty strings so new releases do not require a schema change. Availability depends on provider, account, region, and SDK support. Embedding dimensions must be known or explicitly supplied where supported. Changing the embedding model or dimensions requires a new collection and full reindexing. Temperature is omitted by default for providers with reasoning models that restrict it.
Commands and API
| Command | Purpose |
|---|---|
ragfactory init --name NAME |
Generate from defaults and optional component flags |
ragfactory init --name NAME --save-config pipeline.yaml |
Save configuration only |
ragfactory validate --config pipeline.yaml |
Check schema and compatibility |
ragfactory generate --config pipeline.yaml --output DIR |
Render and syntax-check output |
ragfactory options --json |
List component choices |
ragfactory api --host 127.0.0.1 --port 8000 |
Serve factory API, requires api extra |
Factory endpoints: POST /api/v1/validate, POST /api/v1/generate returning ZIP,
and GET /api/v1/schema. The generated project's separate API exposes POST /query.
Output includes pipeline.py, ingestion.py, api.py, config.yaml,
pyproject.toml, .env.example, Dockerfile, and README.md. External database
choices add Compose; evaluation adds eval.py. Generating into an existing
directory can overwrite files. Back up edited output first.
Compatibility and limits
The dependency matrix targets LangChain 1.x, LangGraph 1.x, and LlamaIndex core
0.14 with independently versioned integrations. Legacy LangChain retrievers use
langchain-classic. Retired Google embedding IDs text-embedding-004 and
embedding-001 are rejected with migration guidance.
- Dense retrieval is the baseline. LangChain hybrid uses a corpus sidecar saved during ingestion; keep it with the generated project. LlamaIndex native hybrid is restricted to the implemented database path.
- LangChain ingestion preserves explicit file globs and loads UTF-8 text formats,
including
.txt,.md,.rst,.csv,.json,.jsonl,.yaml,.yml,.html,.htm,.xml, and.log. Unsupported formats such as PDF and DOCX fail before indexing; add a parser to the generated script to support them. With no configured source, directory ingestion defaults to**/*.txt. - Contextual, proposition, and late chunking remain parseable for migration but
generation rejects their incomplete ingestion implementations.
--forcecannot bypass that check. Enabled CRAG and FLARE are also rejected. - Agentic mode generates a graph/workflow scaffold; it does not implement autonomous planning, reflection, web search, or arbitrary tool execution.
- Parent-document and sentence-window retrieval require corresponding ingestion metadata/docstores. Routing, compression, alternate parsers, and non-file sources are not all implemented by generated ingestion. Start with the default text loader and inspect generated code before using these advanced combinations.
- Compose is a local development scaffold. Configure endpoints for container networking, credentials, readiness, and backups before deployment.
- AST checks prove Python syntax, not SDK/API compatibility or retrieval quality.
Evaluation
Choose evaluation.framework: ragas, deepeval, or both. Supported metrics:
faithfulness, answer_relevancy, context_precision. Configure judge_model,
pass_threshold, and num_test_cases, then run python eval.py in the output
project. Supply eval_dataset.json, an array with question and ground_truth.
Context precision needs reference answers. Evaluation incurs provider API costs.
Malformed datasets and invalid or non-finite scores fail the evaluation gate.
Development
python -m venv .venv
.venv/bin/python -m pip install -e ".[dev,api]"
.venv/bin/ruff check .
.venv/bin/ruff format . --check
.venv/bin/mypy ragfactory
.venv/bin/pytest
CI runs static checks and the full suite on Python 3.11–3.14. Separate generated runtime jobs install both frameworks on Python 3.12 and test real SDK retrieval with local Qdrant and fake models, without paid API calls or model downloads. An evaluation job checks Ragas scoring with intercepted provider calls, plus Ragas and DeepEval imports and metric constructors. Not every optional provider/store combination has this runtime coverage.
Refresh evidence
- Verification results and migration risks
- Model research and lifecycle notes
- SDK research and compatibility bands
- Runtime findings
The older research library is historical background, not a current guarantee for pricing, benchmarks, model availability, or implementation.
License metadata: Apache-2.0.
Metadata
Release files for ragfactory 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ragfactory-0.2.1.tar.gz | 96.6 kB | Without provenance | Details for ragfactory-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ragfactory-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for ragfactory-0.2.1-py3-none-any.whl |
Total release size: 175.1 kB
Release files / ragfactory-0.2.1.tar.gz
| Download URL | ragfactory-0.2.1.tar.gz |
|---|---|
| Size | 96.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4be4b5c0e6f6b0451abe865e357a8eb47347cbb15a9afc70d2ed18f8e6dade89
|
|
BLAKE2b-256 checksum How to use checksums |
ba8e931228cf752fd83a74e096dcbd9cb77400a15ed14fe368df2fed68498c55
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Release files / ragfactory-0.2.1-py3-none-any.whl
| Download URL | ragfactory-0.2.1-py3-none-any.whl |
|---|---|
| Size | 78.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5bf4c3703e140952dc0f630791640cb5cf92be8d36981c8af80878c050c680fe
|
|
BLAKE2b-256 checksum How to use checksums |
3c5258cae24bd4e3ff336ecb3e4377c52315039aca4737ba929a1abeb69b962e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Security for ragfactory 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.