Retriever

Retrievers connect agents to your documents stored in vector databases. When you ask a question, the retriever searches your indexed documents for relevant content and automatically includes it in the agent’s context. This lets agents answer questions about your specific documents, even if that information wasn’t in their training data. To use a retriever, you first index your documents in a vector database, then pass the retriever to your agent. The agent automatically uses retrieved documents to enhance its responses.

Supported Vector Databases

Hypertic supports multiple vector database providers. Click on a provider to see setup and usage examples:

ChromaDB

View guide >

MongoDB Atlas

View guide >

Pinecone

View guide >

PgVector

View guide >

Qdrant

View guide >

Supported Embedders

Hypertic supports multiple embedding providers. Click on a provider to see setup and usage examples:

Cohere

View guide >

Google

View guide >

Mistral

View guide >

OpenAI

View guide >

Sentence Transformers

View guide >

Setup

Create a vector database with an embedder. Hypertic supports multiple vector database providers:

import os
from hypertic.vectordb import ChromaDB
from hypertic.embedders import OpenAIEmbedder

# Create embedder
embedder = OpenAIEmbedder(
    api_key=os.getenv("OPENAI_API_KEY"),
    model="text-embedding-3-small"
)

# Create vector DB
vector_db = ChromaDB(
    collection="my_collection",
    embedder=embedder,
    path="./chromadb_data"
)

Adding Documents

Add documents from local files or URLs:

# Add documents with metadata
vector_db.add(
  files=["data/index.pdf", "data/sample.txt"],
  metadatas=[
      {"source": "invoice.pdf", "type": "invoice", "category": "financial"},
      {"source": "sample.txt", "type": "text", "category": "general"}
  ]
)

# Add from URL
vector_db.add(
  files=["https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"],
  metadatas=[{"source": "url_test.pdf", "type": "url", "category": "test"}]
)

# Check document count
count = vector_db.count()
print(f"Document count: {count}")

# Add documents with metadata
await vector_db.async_add(
    files=["data/index.pdf", "data/sample.txt"],
    metadatas=[
        {"source": "invoice.pdf", "type": "invoice", "category": "financial"},
        {"source": "sample.txt", "type": "text", "category": "general"}
    ]
)

# Add from URL
await vector_db.async_add(
    files=["https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"],
    metadatas=[{"source": "url_test.pdf", "type": "url", "category": "test"}]
)

# Check document count
count = await vector_db.async_count()
print(f"Document count: {count}")

Searching Documents

Search for relevant documents:

# Create retriever
retriever = vector_db.as_retriever(k=3)

# Search for relevant content
docs = retriever.search("invoice payment")
print(docs)

# Create retriever
retriever = vector_db.as_retriever(k=3)

# Search for relevant content
docs = await retriever.async_search("invoice payment")
print(docs)

Updating Documents

Update document content or metadata:

# Get document ID
all_docs = vector_db.get(limit=1)
if all_docs['ids']:
  doc_id = all_docs['ids'][0]
  
  # Update metadata only
  vector_db.update(
      ids=[doc_id],
      metadatas=[{"source": "updated_invoice.pdf", "type": "invoice", "status": "processed"}]
  )
  
  # Update document content and metadata
  vector_db.update(
      ids=[doc_id],
      documents=["Updated invoice content with new payment terms"],
      metadatas=[{"source": "updated_invoice.pdf", "status": "content_updated"}]
  )

# Get document ID
all_docs = await vector_db.async_get(limit=1)
if all_docs['ids']:
    doc_id = all_docs['ids'][0]
    
    # Update metadata only
    await vector_db.async_update(
        ids=[doc_id],
        metadatas=[{"source": "updated_invoice.pdf", "type": "invoice", "status": "processed"}]
    )
    
    # Update document content and metadata
    await vector_db.async_update(
        ids=[doc_id],
        documents=["Updated invoice content with new payment terms"],
        metadatas=[{"source": "updated_invoice.pdf", "status": "content_updated"}]
    )

Upsert Operations

Upsert documents (insert or update if exists):

vector_db.upsert(
  ids=["doc_123"],
  documents=["This is a new document created via upsert"],
  metadatas=[{"source": "upsert_test.txt", "type": "test"}]
)

await vector_db.async_upsert(
    ids=["doc_123"],
    documents=["This is a new document created via upsert"],
    metadatas=[{"source": "upsert_test.txt", "type": "test"}]
)

Querying by Metadata

Query documents using metadata filters:

# Get documents by metadata
financial_docs = vector_db.get(
  where={"category": "financial"},
  limit=5,
  include=['embeddings', 'metadatas', 'documents']
)
print(f"Financial documents: {financial_docs}")

# Get documents by metadata
financial_docs = await vector_db.async_get(
    where={"category": "financial"},
    limit=5,
    include=['embeddings', 'metadatas', 'documents']
)
print(f"Financial documents: {financial_docs}")

Deleting Documents

Delete documents by ID or metadata filter:

# Delete by ID
vector_db.delete(ids=["doc_123"])

# Delete by metadata filter
vector_db.delete(where={"category": "test"})

# Check count after deletion
count = vector_db.count()
print(f"Documents after delete: {count}")

# Delete by ID
await vector_db.async_delete(ids=["doc_123"])

# Delete by metadata filter
await vector_db.async_delete(where={"category": "test"})

# Check count after deletion
count = await vector_db.async_count()
print(f"Documents after delete: {count}")

Using with an Agent

Connect the retriever to your agent. The agent automatically uses retrieved documents to enhance its responses:

from hypertic.agents import Agent
from hypertic.models import OpenAIChat

model = OpenAIChat(model="gpt-5.2")

# Create retriever from vector DB
retriever = vector_db.as_retriever(k=3)  # Retrieve top 3 most relevant documents

# Add retriever to agent
agent = Agent(
    model=model,
    retriever=retriever,
)

# Agent automatically uses retriever when relevant
response = agent.run("What does the documentation say about invoices?")
print(response.content)
# Response includes information from your indexed documents

Get started

Agent

Workflow

Supported Vector Databases

ChromaDB

MongoDB Atlas

Pinecone

PgVector

Qdrant

Supported Embedders

Cohere

Google

Mistral

OpenAI

Sentence Transformers

Setup

Adding Documents

Searching Documents

Updating Documents

Upsert Operations

Querying by Metadata

Deleting Documents

Using with an Agent

​Supported Vector Databases

ChromaDB

MongoDB Atlas

Pinecone

PgVector

Qdrant

​Supported Embedders

Cohere

Google

Mistral

OpenAI

Sentence Transformers

​Setup

​Adding Documents

​Searching Documents

​Updating Documents

​Upsert Operations

​Querying by Metadata

​Deleting Documents

​Using with an Agent

Supported Vector Databases

Supported Embedders

Setup

Adding Documents

Searching Documents

Updating Documents

Upsert Operations

Querying by Metadata

Deleting Documents

Using with an Agent