ZerdaZerda

Tutorial: Getting Started

On this page

This tutorial builds on the Quickstart with a step-by-step walkthrough of every major feature, using the same in-memory stub components so it's fully runnable without external services.

Step 1 — Minimal setup

Python
from zerda.rag.core import RAGSystem, RAGConfig

Reuse the ToyVectorDB, SimpleChunker, SimpleContextManager, and EchoLLM stub classes from the Quickstart.

Python · 6 lines
rag = RAGSystem(
    vector_db=ToyVectorDB(),
    llm=EchoLLM(),
    chunker=SimpleChunker(),
    context_manager=SimpleContextManager(),
)

At this point, defaults from RAGConfig() apply: reranking is off, prompt routing is on, query expansion is on, retrieval caching is on.

Step 2 — Ingest documents

Python · 6 lines
rag.add_texts({
    "hr_1": "New employees receive 21 days of paid annual leave.",
    "hr_2": "Sick leave requires a doctor's note after 3 consecutive days.",
    "it_1": "Password resets can be self-served via the IT portal.",
})
print(rag.get_stats())

Step 3 — Retrieve without generating

Useful for debugging what the system considers relevant before spending an LLM call:

Python · 2 lines
for chunk, score in rag.retrieve("How many vacation days?"):
    print(f"{score:.2f}  {chunk.text}")

Step 4 — Ask a question

Python
print(rag.ask("How many vacation days do new hires get?"))

Because enable_prompt_routing=True by default and no custom prompt was passed, this goes through PromptRouter, which detects the question is FACTUAL in English and builds a matching prompt.

Step 5 — Enable reranking

Python · 7 lines
from zerda.rag.core import RAGConfig

rag2 = RAGSystem(
    vector_db=ToyVectorDB(), llm=EchoLLM(),
    chunker=SimpleChunker(), context_manager=SimpleContextManager(),
    config=RAGConfig(enable_reranking=True, rerank_mode="heuristic"),
)

Heuristic mode requires no LLM relevance calls — it uses term overlap, chunk-length bonus, and per-document diversity. See Reranker for the exact scoring formula.

Step 6 — Inspect cache behavior

Python · 4 lines
rag2.add_texts({"a": "text A", "b": "text B"})
rag2.retrieve("text A")             # cache miss
rag2.retrieve("text A")             # cache hit
print(rag2.get_cache_stats())

Step 7 — Async usage

Python · 7 lines
import asyncio

async def main():
    answer = await rag.agenerate("How many vacation days?")
    print(answer)

asyncio.run(main())

See the Async Usage cookbook entry for streaming.

Next steps

Related pages