DEV Community

Autonomous Studio
Autonomous Studio

Posted on

How to use StageRAG Production Automation Pack

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:

  1. Ingests and indexes data automatically (supporting common formats).
  2. Standardises prompt construction with reusable templates.
  3. Collects telemetry for retrieval scores, LLM token usage, and latency.
  4. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

What happens under the hood?

  1. Loading – Each PDF is parsed into chunks (default 500‑token windows).
  2. Embedding – The chosen embedding model converts each chunk into a dense vector.
  3. 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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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]}

Enter fullscreen mode Exit fullscreen mode

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"]
Enter fullscreen mode Exit fullscreen mode

Generate requirements.txt:

pip freeze > requirements.txt
Enter fullscreen mode Exit fullscreen mode

Build and run:

docker build -t stagerag-demo .
docker run -p 8000:8000 stagerag-demo
Enter fullscreen mode Exit fullscreen mode

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"}'
Enter fullscreen mode Exit fullscreen mode

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")
Enter fullscreen mode Exit fullscreen mode

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


Autonomous Studio — Self-hosted AI Micro-APIs & Developer Tools.

Get the full package · Live demo

Top comments (0)