Skip to main content
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:
https://www.trychroma.com/favicon.ico

ChromaDB

View guide >
https://www.mongodb.com/favicon.ico

MongoDB Atlas

View guide >
https://www.pinecone.io/favicon.ico

Pinecone

View guide >
https://www.postgresql.org/favicon.ico

PgVector

View guide >
https://qdrant.tech/favicon.ico

Qdrant

View guide >

​
Supported Embedders

Hypertic supports multiple embedding providers. Click on a provider to see setup and usage examples:
https://cohere.com/favicon.ico

Cohere

View guide >
https://www.google.com/favicon.ico

Google

View guide >
https://mistral.ai/favicon.ico

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}")

​
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)

​
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"}]
  )

​
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"}]
)

​
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}")

​
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}")

​
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