Skip to main content

​
Build Your First RAG Q&A System in 5 Minutes 🦛

This quickstart gets you from zero to asking questions over your documents with AI-powered answers and source citations.
Requirements: Python 3.9+ • 5 minutes of your time

​
Step 1: Installation (30 seconds)

pip install cerevox

​
Step 2: Get API Key (30 seconds)

1

Get your API key

Visit cerevox.ai and sign up for your free API key
2

Copy the key

Save your API key - you’ll need it in the next step

​
Step 3: Authentication Setup (30 seconds)

​
Step 4: Build RAG Q&A System (3 minutes)

Copy and run this code to create your first AI Q&A system: 
from cerevox import Hippo

# Initialize Hippo (uses CEREVOX_API_KEY from environment)
hippo = Hippo()

# 1. Create a folder for your knowledge base
folder = hippo.create_folder(
    name="Product Documentation",
    description="User guides and API docs"
)
print(f"✅ Created folder: {folder.name} (ID: {folder.id})")

# 2. Upload documents to the folder
print("📤 Uploading documents...")

# Upload from local file
file1 = hippo.upload_file(
    folder_id=folder.id,
    file_path="user-guide.pdf"
)

# Upload from URL
file2 = hippo.upload_file_from_url(
    folder_id=folder.id,
    file_url="https://example.com/api-docs.pdf",
    file_name="api-docs.pdf"
)

print(f"✅ Uploaded {file1.name} and {file2.name}")

# 3. Create a chat session
chat = hippo.create_chat(
    folder_id=folder.id,
    chat_name="Technical Support Q&A"
)
print(f"✅ Created chat session: {chat.name}")

# 4. Ask questions and get AI-powered answers!
questions = [
    "How do I authenticate users?",
    "What are the API rate limits?",
    "How do I handle errors?"
]

for question in questions:
    print(f"\n❓ Question: {question}")

    answer = hippo.submit_ask(
        chat_id=chat.id,
        question=question
    )

    print(f"💡 Answer: {answer.response}")
    print(f"📚 Sources: {len(answer.sources)} citations")

    # Show source details
    for source in answer.sources[:2]:  # First 2 sources
        print(f"  → {source.file_name} (Page {source.page_number})")

print("\n🎉 Your RAG Q&A system is working!")
You’re Ready! 🎉 You’ve built your first RAG Q&A system with 80% cost savings!

​
What Just Happened?

Folders organize your documents into searchable collections. Each folder becomes an isolated knowledge base for your AI agent.
Hippo automatically processes and indexes your documents for semantic search. Supports PDFs, DOCX, PPTX, and more.
Chat sessions maintain conversation context. Each chat remembers previous questions for follow-up queries.
submit_ask() retrieves relevant chunks (70% smaller context) and generates answers with source citations. 80% cost reduction vs. full document retrieval!

​
Understanding the Cost Savings

Traditional RAG
  • Sends entire documents
  • Large context windows
  • High token costs
  • Slower responses

Hippo RAG
  • Only relevant chunks (70% smaller)
  • Precision retrieval
  • 80% cost reduction
  • 99.5% accuracy match

​
Next Steps

​
Common Operations

# Get all folders
folders = hippo.get_folders()

for folder in folders:
    print(f"{folder.name}: {folder.file_count} files")

# Get files in a folder
files = hippo.get_files(folder_id=folder.id)

for file in files:
    print(f"{file.name} - {file.status}")

# Get all chats for a folder
chats = hippo.get_chats(folder_id=folder.id)

for chat in chats:
    print(f"{chat.name}: {chat.message_count} messages")

# Get all Q&A history for a chat
asks = hippo.get_asks(chat_id=chat.id)

for ask in asks:
    print(f"Q: {ask.question}")
    print(f"A: {ask.response}\n")

# Delete a chat
hippo.delete_chat(chat_id=chat.id)

# Delete a file
hippo.delete_file(file_id=file.id)

# Delete a folder (and all its contents)
hippo.delete_folder(folder_id=folder.id)

​
Having Issues?

Error: Authentication failed or Invalid API keyQuick fixes:
  • Double-check your API key from cerevox.ai
  • Verify CEREVOX_API_KEY environment variable is set correctly
  • Remove any extra spaces or quotes around the key
  • Try passing the key directly: Hippo(api_key="your-key")
Error: File upload fails or times outQuick fixes:
  • Check file exists: os.path.exists("your-file.pdf")
  • Verify file permissions (must be readable)
  • For large files, increase timeout: hippo.upload_file(folder_id, file, timeout=300)
  • Supported formats: PDF, DOCX, PPTX, XLSX, TXT, HTML, CSV
Question: How long does document processing take?Answer:
  • Small files (< 10 pages): 10-30 seconds
  • Medium files (10-100 pages): 30-120 seconds
  • Large files (> 100 pages): 2-5 minutes
  • Use async API for better performance with multiple files
  • Files are queued and processed automatically
Question: How can I improve answer quality?Tips:
  • Upload relevant documents only
  • Use descriptive folder and chat names
  • Ask specific, clear questions
  • Review source citations to verify answers
  • See Q&A Best Practices for more tips
Ready to scale? Check out our RAG optimization guide or join the Discord community for help.