Skip to main content

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. --force cannot 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

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)

Source distribution for ragfactory 0.2.1
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)

Table of built distributions (wheels) for ragfactory 0.2.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page