Skip to main content

​
Overview

This guide demonstrates how to build a complete Retrieval-Augmented Generation (RAG) system using KnowledgeBase, Agent, and Task.

​
Complete Example

from upsonic import Agent, Task, KnowledgeBase
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig
from upsonic.vectordb import ChromaProvider, ChromaConfig, ConnectionConfig, Mode
from upsonic.loaders.pdf import PdfLoader
from upsonic.loaders.config import PdfLoaderConfig

# Step 1: Setup embedding provider
embedding = OpenAIEmbedding(OpenAIEmbeddingConfig(
    model_name="text-embedding-3-small"
))

# Step 2: Setup vector database
vectordb = ChromaProvider(ChromaConfig(
    collection_name="my_rag_kb",
    vector_size=1536,
    connection=ConnectionConfig(
        mode=Mode.EMBEDDED,
        db_path="./rag_database"
    )
))

# Step 3: Setup PDF loader
loader = PdfLoader(PdfLoaderConfig())

# Step 4: Create knowledge base with documents
kb = KnowledgeBase(
    sources=["document.pdf"],
    embedding_provider=embedding,
    vectordb=vectordb,
    loaders=[loader]
)

# Step 5: Create agent
agent = Agent("openai/gpt-4o")

# Step 6: Create task with knowledge base context
task = Task(
    description="What is the daily working hours policy described in the text?",
    context=[kb]
)

# Step 7: Execute and get results
result = agent.do(task)
print(result)

​
Step-by-Step Explanation

​
1. Setup Embedding Provider

The embedding provider converts text into vector representations for semantic search. 
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig

embedding = OpenAIEmbedding(OpenAIEmbeddingConfig(
    model_name="text-embedding-3-small"
))

​
2. Setup Vector Database

The vector database stores the embedded documents for fast similarity search. 
from upsonic.vectordb import ChromaProvider, ChromaConfig, ConnectionConfig, Mode

vectordb = ChromaProvider(ChromaConfig(
    collection_name="my_rag_kb",
    vector_size=1536,  # Must match embedding model dimension
    connection=ConnectionConfig(
        mode=Mode.EMBEDDED,
        db_path="./rag_database"
    )
))

​
3. Create Knowledge Base

KnowledgeBase automatically processes documents, creates chunks, generates embeddings, and stores them. 
from upsonic import KnowledgeBase
from upsonic.loaders.pdf import PdfLoader
from upsonic.loaders.config import PdfLoaderConfig

loader = PdfLoader(PdfLoaderConfig())

kb = KnowledgeBase(
    sources=["document.pdf"],
    embedding_provider=embedding,
    vectordb=vectordb,
    loaders=[loader]
)

​
4. Create Agent

Create an agent that will use the knowledge base to answer questions. 
from upsonic import Agent

agent = Agent("openai/gpt-4o")

​
5. Create Task with Context

Pass the knowledge base as context to the task. The agent will automatically query it. 
from upsonic import Task

task = Task(
    description="What is the main topic?",
    context=[kb]
)

​
6. Execute Task

Execute the task to get the answer with RAG context. 
result = agent.do(task)
print(result)

​
Async Version

For better performance, use async/await: 
import asyncio
from upsonic import Agent, Task, KnowledgeBase
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig
from upsonic.vectordb import ChromaProvider, ChromaConfig, ConnectionConfig, Mode
from upsonic.loaders.pdf import PdfLoader
from upsonic.loaders.config import PdfLoaderConfig

async def main():
    embedding = OpenAIEmbedding(OpenAIEmbeddingConfig())
    vectordb = ChromaProvider(ChromaConfig(
        collection_name="my_rag_kb",
        vector_size=1536,
        connection=ConnectionConfig(mode=Mode.IN_MEMORY)
    ))

    loader = PdfLoader(PdfLoaderConfig())

    kb = KnowledgeBase(
        sources=["document.pdf"],
        embedding_provider=embedding,
        vectordb=vectordb,
        loaders=[loader]
    )

    agent = Agent("openai/gpt-4o")
    task = Task(
        description="What is the main topic?",
        context=[kb]
    )

    result = await agent.do_async(task)
    print(result)

asyncio.run(main())

​
What Happens Behind the Scenes

  1. Document Loading: KnowledgeBase detects the file type and loads the PDF
  2. Text Chunking: The document is split into smaller chunks for better retrieval
  3. Embedding Generation: Each chunk is converted to a vector embedding
  4. Vector Storage: Embeddings are stored in the vector database
  5. Query Processing: When you ask a question, it’s embedded and matched against stored chunks
  6. Context Retrieval: The most relevant chunks are retrieved
  7. Response Generation: The agent uses the retrieved context to generate an answer

​
Next Steps