Introduction
Retrieval‑augmented generation (RAG) is now the go‑to pattern for building search‑oriented chatbots and knowledge‑base assistants. While the concept is simple—fetch relevant documents, feed them to a LLM, and let the model generate a grounded answer—getting a production‑ready pipeline up and running can be surprisingly time‑consuming.
Typical pain points for AI startups and SaaS teams include:
| Problem | Why it hurts |
|---|---|
| Manual data ingestion – Every new source (PDF, CSV, website) requires a custom scraper and indexer. | Slows down onboarding of new content and introduces bugs. |
| Fragmented prompting – Prompt templates are scattered across notebooks, making it hard to keep them consistent. | Leads to hallucinations and hard‑to‑debug responses. |
| No observability – No built‑in logging of retrieval scores, latency, or LLM usage. | Makes troubleshooting and cost‑control a guessing game. |
| Deployment friction – Moving from a local notebook to a cloud‑native service often means rewriting large parts of the code. | Delays time‑to‑market and forces engineers to duplicate effort. |
The StageRAG Production Automation Pack from RAGForge tackles these issues out of the box. It provides a modular, opinionated framework that:
- Ingests and indexes data automatically (supporting common formats).
- Standardises prompt construction with reusable templates.
- Collects telemetry for retrieval scores, LLM token usage, and latency.
- Exports a Docker‑ready FastAPI service that can be deployed to any cloud provider.
Below is a step‑by‑step, code‑first tutorial that shows how to turn a raw collection of PDFs into a fully‑instrumented RAG endpoint using the pack.
Prerequisites
| Requirement | Version |
|---|---|
| Python | 3.10+ |
| Docker | 24.0+ |
pip |
23.2+ |
| An OpenAI‑compatible LLM API key (or any other provider supported by LangChain) | – |
Create a fresh virtual environment to keep dependencies tidy:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
1. Install the Automation Pack
The pack is distributed as a pip‑installable wheel on Gumroad. Install it directly from the URL:
pip install https://autonomousstudio.gumroad.com/l/ecfosy/download
This pulls in the core stagerag library plus optional extras for PDF, CSV, and web‑scraping support.
2. Prepare Your Data
For this demo we’ll use a small folder of PDFs (./data/knowledge/). The pack expects a manifest file that tells it where to find the sources and how to label them.
Create manifest.yaml:
sources:
- type: pdf
path: ./data/knowledge/
metadata:
category: product_manual
You can add more entries (CSV, HTML, plain‑text) later; the pack will automatically pick the appropriate loader.
3. Build the Retrieval Index
StageRAG ships with a CLI that abstracts away the vector store setup. Run the following command to create a ChromaDB index (you can swap faiss, pinecone, etc., via a flag).
stagerag index create \
--manifest manifest.yaml \
--store chroma \
--embedding openai:text-embedding-ada-002 \
--output ./index/
What happens under the hood?
- Loading – Each PDF is parsed into chunks (default 500‑token windows).
- Embedding – The chosen embedding model converts each chunk into a dense vector.
-
Storing – Vectors, along with source metadata, are persisted in a local Chroma collection (
./index/).
The command prints a short summary:
✅ Indexed 12 documents → 3,842 chunks
🗄️ Stored in ./index/ (Chroma)
4. Define a Prompt Template
Consistent prompting is essential for reliable RAG. Create prompt.yaml:
template: |
You are a helpful assistant for {category} documentation.
Use only the information provided in the retrieved passages.
Answer the user query verbatim and cite the source IDs.
variables:
- category
The {category} placeholder will be filled from the metadata attached to each chunk, allowing you to tailor responses per knowledge domain.
5. Wire Up the FastAPI Service
StageRAG provides a starter FastAPI app that you can customise via a small app.py. Copy the scaffold:
# app.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from stagerag.core import RetrievalEngine, PromptRenderer, Telemetry
# Load the index we built earlier
engine = RetrievalEngine(
vector_store_path="./index/",
embedding_model="openai:text-embedding-ada-002",
)
# Load the prompt template
renderer = PromptRenderer.from_yaml("prompt.yaml")
# Telemetry collector (logs to stdout; can be swapped for Prometheus, etc.)
telemetry = Telemetry()
app = FastAPI(title="StageRAG Demo Service")
class QueryRequest(BaseModel):
query: str
category: str = "product_manual"
@app.post("/answer")
def answer(req: QueryRequest):
# 1️⃣ Retrieve top‑k chunks
results = engine.retrieve(req.query, k=5, metadata_filter={"category": req.category})
# 2️⃣ Render the prompt with retrieved passages
prompt = renderer.render(
query=req.query,
passages=[r.text for r in results],
category=req.category,
)
# 3️⃣ Call the LLM (using OpenAI API by default)
answer = engine.llm.complete(prompt)
# 4️⃣ Record telemetry
telemetry.record(
query=req.query,
latency=engine.last_latency,
token_usage=engine.last_token_usage,
retrieved_ids=[r.id for r in results],
)
return {"answer": answer, "sources": [r.id for r in results]}
Key points:
-
Metadata filtering ensures the engine only pulls documents that match the requested
category. - Telemetry captures latency and token usage automatically; you can plug in a Grafana dashboard later.
- The endpoint returns both the generated answer and the IDs of the source chunks, enabling downstream UI to display citations.
6. Containerise the Service
Running locally is fine for development, but production demands isolation. The pack includes a Dockerfile template; create Dockerfile in the project root:
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . /app
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
Generate requirements.txt:
pip freeze > requirements.txt
Build and run:
docker build -t stagerag-demo .
docker run -p 8000:8000 stagerag-demo
Your RAG service is now reachable at http://localhost:8000/answer. Test it with curl:
curl -X POST http://localhost:8000/answer \
-H "Content-Type: application/json" \
-d '{"query":"How do I reset my device?", "category":"product_manual"}'
You should receive a JSON payload containing the answer and the source IDs.
7. Add Observability (Optional)
If you already run Prometheus/Grafana, replace the Telemetry instance with a Prometheus exporter:
from stagerag.telemetry import PrometheusTelemetry
telemetry = PrometheusTelemetry(namespace="stagerag")
Expose the /metrics endpoint (FastAPI does this automatically) and you’ll see counters for queries_total, latency_seconds, and tokens_used.
8. Deploy to the Cloud
Because the service is just a container, you can push it to any registry and spin it up on:
-
AWS ECS/Fargate – use the provided
ecs-task-def.json. -
Google Cloud Run –
gcloud run deploy stagerag-demo --image gcr.io/…. -
Azure Container Apps –
az containerapp create ….
All you need is the same environment variable for the LLM API key (OPENAI_API_KEY or the equivalent for your provider).
Conclusion
The StageRAG Production Automation Pack removes the repetitive plumbing that usually surrounds a RAG pipeline. By following the steps above you can:
- Ingest any mix of PDFs, CSVs, or web pages with a single manifest.
- Index them into a vector store without writing custom embedding code.
- Serve a consistent, observable API that respects metadata filters and returns traceable citations.
This workflow lets AI startups focus on the value of their domain knowledge rather than the mechanics of retrieval and prompting.
Quick Links
- Live demo – see the demo UI in action: https://3km-collab.github.io/stagerag-production-automation-pack-11/
- Package download – grab the automation pack here: https://autonomousstudio.gumroad.com/l/ecfosy
Autonomous Studio — Self-hosted AI Micro-APIs & Developer Tools.
Top comments (0)