> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Knowledge Base
> Add document and URL knowledge to agents for grounded, accurate answers
The knowledge system lets agents retrieve relevant information from PDFs, documents, and URLs before answering, grounding responses in your own sources.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Research Assistant",
instructions="Answer questions using the knowledge base.",
knowledge=["research_paper.pdf", "data.txt"],
)
agent.start("What are the key findings?")
```
The user asks about their documents; the agent embeds, searches, and answers from your PDFs and URLs.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
Sources[📄 Sources] --> Chunk[✂️ Chunk + Embed]
Chunk --> Store[(🗃️ Vector Store)]
Store --> Answer[✅ Grounded Answer]
classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class Sources input
class Chunk,Store process
class Answer output
```
## Key Features
Process PDFs, documents, spreadsheets, images, and web content
Multiple strategies for optimal text segmentation
Vector-based search with optional reranking
User, agent, and run-specific knowledge scoping
Optional relationship extraction and storage
Automatic quality assessment for stored knowledge
## Quick Start
Pass a list of files or URLs and the agent answers from them.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Research Assistant",
instructions="Answer questions using the knowledge base.",
knowledge=["research_paper.pdf", "data.txt"],
)
agent.start("What are the key findings?")
```
Use a dict to pick a vector store while still passing sources inline.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Research Assistant",
instructions="Answer questions using the knowledge base.",
knowledge={
"sources": ["research_paper.pdf", "data.txt"],
"vector_store": {
"provider": "chroma",
"config": {"collection_name": "research_docs", "path": ".praison"},
},
},
)
agent.start("What are the key findings?")
```
Use `KnowledgeConfig` for typed control over chunking, retrieval, and reranking.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, KnowledgeConfig
agent = Agent(
name="Research Assistant",
instructions="Answer questions using the knowledge base.",
knowledge=KnowledgeConfig(
sources=["research_paper.pdf", "data.txt"],
chunking_strategy="semantic",
retrieval_k=5,
rerank=True,
),
)
agent.start("What are the key findings?")
```
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Knowledge
participant VectorStore
participant LLM
User->>Agent: Question about documents
Agent->>Knowledge: search(query)
Knowledge->>VectorStore: Embed query + semantic search
VectorStore-->>Knowledge: Top-k chunks
Knowledge-->>Agent: Retrieved context
Agent->>LLM: Prompt + context
LLM-->>Agent: Grounded answer
Agent-->>User: Response
```
| Phase | What happens |
| ----------- | ------------------------------------------------------------------------------------- |
| 1. Add | Documents are chunked, embedded, and stored in the vector store via `knowledge.add()` |
| 2. Search | `knowledge.search(query)` embeds the query and returns top-k similar chunks |
| 3. Retrieve | Agent injects the chunks as context before calling the LLM |
| 4. Generate | LLM answers using the retrieved knowledge; responses are grounded in your data |
***
## Configuration Options
Full parameter reference for KnowledgeConfig
The most common options at a glance:
| Option | Type | Default | Description |
| ------------------- | ----------- | ------------ | ------------------------------------------------------- |
| `sources` | `list[str]` | `[]` | Files, directories, or URLs to index |
| `embedder` | `str` | `"openai"` | Embedder to use for vector encoding |
| `chunking_strategy` | `str` | `"semantic"` | `"fixed"` / `"semantic"` / `"sentence"` / `"paragraph"` |
| `retrieval_k` | `int` | `5` | Number of chunks to retrieve per query |
| `rerank` | `bool` | `False` | Apply reranking to improve result order |
### Basic Configuration
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
knowledge_config = {
"vector_store": {
"provider": "chroma",
"config": {
"collection_name": "knowledge_base",
"path": ".praison",
"distance_metric": "cosine"
}
},
"embedder": {
"provider": "openai",
"config": {
"model": "text-embedding-3-small"
}
}
}
```
### Advanced Configuration with Graph Store
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
knowledge_config = {
"vector_store": {
"provider": "chroma",
"config": {
"collection_name": "knowledge_base",
"path": ".praison"
}
},
"graph_store": {
"provider": "neo4j",
"config": {
"url": "bolt://localhost:7687",
"username": "neo4j",
"password": "password"
}
},
"llm": {
"provider": "openai",
"config": {
"model": "gpt-4o-mini",
"temperature": 0
}
},
"reranker": {
"enabled": True,
"default_rerank": False
}
}
```
## Choosing Sources and Chunking
Pick a source type, then a chunking strategy that matches your content.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
subgraph Sources
S1[Files: PDF / DOCX / TXT]
S2[URLs and web pages]
S3[In-memory strings]
end
subgraph Chunking
C1[token: fixed size]
C2[sentence: natural bounds]
C3[semantic: topic bounds]
end
S1 --> C1
S2 --> C2
S3 --> C3
classDef source fill:#6366F1,stroke:#7C90A0,color:#fff
classDef strat fill:#10B981,stroke:#7C90A0,color:#fff
class S1,S2,S3 source
class C1,C2,C3 strat
```
## Chunking Strategies
```python Token-based Chunking theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
kb = Knowledge({
"chunker": {
"name": "token",
"chunk_size": 500,
"chunk_overlap": 50
}
})
```
Best for: Consistent chunk sizes, token-limited models
```python Sentence-based Chunking theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
kb = Knowledge({
"chunker": {
"name": "sentence",
"chunk_size": 10, # sentences per chunk
"min_chunk_size": 3
}
})
```
Best for: Natural text boundaries, Q\&A systems
```python Semantic Chunking theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
kb = Knowledge({
"chunker": {
"name": "semantic",
"threshold": 0.7,
"min_chunk_size": 100
}
})
```
Best for: Topic-based segmentation, research papers
```python SDPM Chunking theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
kb = Knowledge({
"chunker": {
"name": "sdpm",
"max_chunk_size": 1000
}
})
```
Best for: Document structure preservation
## Document Processing
### Supported File Types
* PDF (.pdf)
* Word (.doc, .docx)
* Text (.txt)
* Markdown (.md)
* RTF (.rtf)
* Excel (.xls, .xlsx)
* CSV (.csv)
* JSON (.json)
* XML (.xml)
* Images (OCR)
* HTML pages
* Web URLs
* YouTube videos
### Processing Options
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Add with metadata
kb.add(
"research.pdf",
user_id="user123",
metadata={
"category": "AI Research",
"year": 2024,
"author": "Dr. Smith"
}
)
# Batch processing
documents = ["doc1.pdf", "doc2.txt", "doc3.md"]
for doc in documents:
kb.add(doc, user_id="user123")
# URL processing
kb.add("https://arxiv.org/pdf/2301.00000.pdf", user_id="user123")
```
## Search Features
### Basic Search
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple search
results = kb.search("artificial intelligence", limit=5)
# User-scoped search
results = kb.search(
query="machine learning",
user_id="user123",
limit=10
)
```
### Advanced Search Options
```python With Reranking theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Enable Mem0 reranking for better relevance
results = kb.search(
query="neural networks",
user_id="user123",
rerank=True,
top_k=20 # Retrieve more before reranking
)
```
```python Hybrid Search theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Combine keyword and semantic search
results = kb.search(
query="transformer architecture",
user_id="user123",
keyword_search=True, # Better recall
filter_memories=True # Better precision
)
```
```python Metadata Filtering theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Filter by metadata
results = kb.search(
query="implementation details",
user_id="user123",
filters={
"category": "technical",
"year": {"$gte": 2023}
}
)
```
## Memory Integration
When used with agents, knowledge automatically integrates with memory:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
name="Research Assistant",
knowledge={
"sources": ["papers/"],
"vector_store": {
"provider": "chroma",
"config": {"collection_name": "research_docs"}
}
},
memory=True # Enable memory integration
)
# Knowledge is automatically searched during conversations
response = agent.start("What does the research say about transformers?")
```
## Graph Store Features
Graph stores add relationship extraction and connection queries on top of semantic search.
### Configuration
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
knowledge_config = {
"graph_store": {
"provider": "neo4j", # or "memgraph"
"config": {
"url": "bolt://localhost:7687",
"username": "neo4j",
"password": "password"
}
},
"extract_relationships": True
}
```
### Relationship Queries
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Find related concepts
results = kb.search_graph(
"What concepts are related to transformers?",
user_id="user123"
)
# Explore connections
results = kb.search_graph(
"How is attention mechanism connected to BERT?",
user_id="user123"
)
```
## Best Practices
Use smaller chunks (100-200 tokens) for precise fact retrieval. Use larger chunks (500-1000 tokens) when answers need more context. Semantic chunking works best for research papers and long-form documents.
Use a different `collection_name` per knowledge domain (e.g., `product_docs`, `legal_contracts`). This prevents cross-contamination and allows targeted filtering by domain.
Add `metadata` when indexing documents to enable `filters=` in searches. Filter by `category`, `year`, or `author` to narrow results without changing query text.
Set `rerank=True` in `kb.search()` when you need top-quality results. Reranking retrieves more candidates then scores them for relevance — best for Q\&A and research assistants.
## Example: Research Assistant
```python Complete Example theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import Knowledge
# Configure knowledge base
knowledge_config = {
"vector_store": {
"provider": "chroma",
"config": {
"collection_name": "research_papers",
"path": "./knowledge_db"
}
},
"chunker": {
"name": "semantic",
"threshold": 0.7
},
"embedder": {
"provider": "openai",
"config": {
"model": "text-embedding-3-small"
}
},
"reranker": {
"enabled": True
}
}
# Create research assistant
research_agent = Agent(
name="Research Assistant",
instructions="""You are an expert research assistant.
Use the knowledge base to provide accurate, well-sourced answers.
Always cite the specific documents you reference.""",
knowledge={
"sources": ["research_papers"],
**knowledge_config
}
)
# Use the assistant
response = research_agent.start(
"What are the main approaches to AI alignment?"
)
# Direct knowledge queries
kb = research_agent.knowledge
papers = kb.search("alignment techniques", limit=5)
for paper in papers:
print(f"- {paper['text'][:100]}...")
print(f" Source: {paper.get('metadata', {}).get('source')}")
```
## Related
Build retrieval-augmented generation pipelines
Store and query embeddings with a pluggable, namespace-aware backend