RAG (Retrieval Augmented Generation)

RAG enables agents to retrieve relevant information from documents before generating responses, producing accurate, grounded answers with citations.

Quick Start

Install

pip install "praisonaiagents[knowledge]"
export OPENAI_API_KEY=your_key

Create Agent with Knowledge

from praisonaiagents import Agent

agent = Agent(
    name="RAG Agent",
    instructions="Answer questions using the knowledge base",
    knowledge=["docs/manual.pdf"]  # Your documents
)

agent.start("What are the key features?")

Get Answer with Citations

# Use query() for structured results with citations
result = agent.query("What are the main findings?")

print(result.answer)
for citation in result.citations:
    print(f"  [{citation.id}] {citation.source}")

How RAG Works

The RAG Process

Phase	What Happens	When
Indexing	Documents → Chunks → Embeddings → Vector DB	Once per document
Retrieval	Query → Embedding → Similarity Search → Top-K chunks	Every query
Generation	Query + Context → LLM → Answer + Citations	Every query

Agent Methods for RAG

Method	Returns	Use Case
`agent.start(prompt)`	String	Interactive terminal with RAG
`agent.chat(prompt)`	String	Programmatic RAG
`agent.query(prompt)`	`RAGResult`	Structured answer + citations
`agent.retrieve(prompt)`	`ContextPack`	Context only, no LLM generation

Example: All Methods

from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Answer using the knowledge base",
    knowledge=["research_paper.pdf"]
)

# Method 1: Interactive (verbose output)
agent.start("Summarize the findings")

# Method 2: Programmatic (silent)
answer = agent.chat("What methodology was used?")

# Method 3: Structured with citations
result = agent.query("What are the conclusions?")
print(result.answer)
print(result.citations)

# Method 4: Retrieval only (no LLM)
context = agent.retrieve("key findings")
print(f"Found {len(context.citations)} sources")
print(context.context)  # Raw retrieved text

Knowledge Configuration

Basic: File List

agent = Agent(
    name="Agent",
    knowledge=["doc1.pdf", "doc2.txt", "folder/"]
)

Advanced: Full Configuration

from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    name="Advanced RAG Agent",
    instructions="Answer with high precision",
    knowledge=KnowledgeConfig(
        sources=["docs/"],
        
        # Retrieval settings
        retrieval_k=5,              # Number of chunks to retrieve
        rerank=True,                # Rerank for better relevance
        
        # Chunking settings
        chunking_strategy="semantic",  # semantic, fixed, sentence
        chunk_size=1000,
        chunk_overlap=200,
        
        # Vector store
        vector_store={
            "provider": "chroma",
            "config": {
                "collection_name": "my_docs",
                "path": ".praison"
            }
        }
    )
)

Configuration Options

Option	Type	Default	Description
`sources`	`list`	`[]`	Files, folders, or URLs
`retrieval_k`	`int`	`5`	Number of chunks to retrieve
`rerank`	`bool`	`False`	Enable reranking
`chunking_strategy`	`str`	`"semantic"`	How to split documents
`chunk_size`	`int`	`1000`	Max tokens per chunk
`chunk_overlap`	`int`	`200`	Overlap between chunks
`auto_retrieve`	`bool`	`True`	Auto-inject context

Retrieval Strategies

PraisonAI automatically selects the optimal strategy based on corpus size:

Strategy	Files	Technique
DIRECT	< 10	Load all content into context
BASIC	< 100	Embedding-based semantic search
HYBRID	< 1000	Keyword + semantic search
RERANKED	< 10000	Hybrid + cross-encoder reranking
COMPRESSED	< 100000	Reranked + contextual compression
HIERARCHICAL	≥ 100000	Summaries + top-down routing

Force a Strategy

agent = Agent(
    knowledge={
        "sources": ["large_corpus/"],
        "strategy": "reranked"  # Force reranking
    }
)

RAG vs Knowledge vs Memory vs Context

Comparison Table

Aspect	RAG	Knowledge	Memory	Context
What	Search technique	Pre-loaded docs	Persistent storage	Runtime data
When	Query time	Before execution	Across sessions	During execution
Lifetime	N/A	Permanent	Permanent	Session only
Direction	Read-only	Read-only	Read + Write	Read-only
Agent Param	Part of `knowledge=`	`knowledge=`	`memory=`	`context=`

When to Use What

Agent with Knowledge (Simple)

For small document sets where you don’t need advanced retrieval:

from praisonaiagents import Agent

# Simple knowledge - loads documents, enables basic search
agent = Agent(
    name="FAQ Agent",
    instructions="Answer questions from the FAQ",
    knowledge=["faq.txt"]  # Small file, basic search
)

agent.start("What is the return policy?")

Agent with RAG (Advanced)

For large document sets requiring sophisticated retrieval:

from praisonaiagents import Agent, KnowledgeConfig

# Advanced RAG - full retrieval pipeline
agent = Agent(
    name="Research Agent",
    instructions="Answer with citations from research papers",
    knowledge=KnowledgeConfig(
        sources=["papers/"],
        retrieval_k=10,
        rerank=True,
        chunking_strategy="semantic"
    )
)

# Get structured result with citations
result = agent.query("What are the latest findings on X?")

Multi-Agent RAG

Share knowledge across multiple agents:

from praisonaiagents import Agent, Knowledge, AgentTeam

# Create shared knowledge base
knowledge = Knowledge(config={
    "vector_store": {
        "provider": "chroma",
        "config": {"collection_name": "shared_docs"}
    }
})
knowledge.add("company_docs/")

# Multiple agents share the same knowledge
researcher = Agent(
    name="Researcher",
    instructions="Find relevant information",
    knowledge=knowledge
)

writer = Agent(
    name="Writer",
    instructions="Write based on research findings"
)

team = AgentTeam(
    agents=[researcher, writer],
    process="sequential"
)

team.start("Write a report on Q4 performance")

Supported File Types

Documents

PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX

Text

TXT, CSV, JSON, XML, MD, HTML

Media

Images (with OCR), Audio (with transcription)

Vector Store Backends

# ChromaDB (default)
knowledge={"sources": ["docs/"], "vector_store": {"provider": "chroma"}}

# MongoDB Atlas
knowledge={"sources": ["docs/"], "vector_store": {"provider": "mongodb"}}

# Qdrant
knowledge={"sources": ["docs/"], "vector_store": {"provider": "qdrant"}}

# Pinecone
knowledge={"sources": ["docs/"], "vector_store": {"provider": "pinecone"}}

Citations

RAG automatically provides source citations:

result = agent.query("What is the main conclusion?")

# Access citations
for citation in result.citations:
    print(f"[{citation.id}] {citation.source}")
    print(f"  Score: {citation.score:.2f}")
    print(f"  Text: {citation.text[:100]}...")

Citation Modes

from praisonaiagents import Agent, RetrievalConfig, CitationsMode

agent = Agent(
    knowledge=RetrievalConfig(
        sources=["docs/"],
        citations=True,
        citations_mode=CitationsMode.APPEND  # or INLINE, HIDDEN
    )
)

Mode	Description
`APPEND`	Add sources at end of response
`INLINE`	Insert citation markers in text
`HIDDEN`	Include in metadata only

Best Practices

Chunk Size

Use 500-1000 tokens per chunk. Too small = lost context. Too large = noise.

Overlap

Use 10-20% overlap to preserve context across chunk boundaries.

Reranking

Enable reranking for large corpora to improve relevance.

Top-K

Start with k=5, increase if answers lack detail.

Troubleshooting

No relevant results

Check if documents were indexed: knowledge.stats()
Lower the similarity threshold
Try different chunking strategy

Slow retrieval

Reduce retrieval_k
Disable reranking for faster results
Use persistent vector store

Missing context

Increase chunk overlap
Use semantic chunking
Increase retrieval_k

Knowledge

Document loading and indexing

Memory

Persistent agent memory

Context

Runtime data flow

Quality RAG

Advanced quality patterns

​Quick Start

​How RAG Works

​The RAG Process

​Agent Methods for RAG

​Example: All Methods

​Knowledge Configuration

​Basic: File List

​Advanced: Full Configuration

​Configuration Options

​Retrieval Strategies

​Force a Strategy

​RAG vs Knowledge vs Memory vs Context

​Comparison Table

​When to Use What

​Agent with Knowledge (Simple)

​Agent with RAG (Advanced)

​Multi-Agent RAG

​Supported File Types