Skip to main content

​
Hippo Quickstart - 5 Minutes to Q&A 🦛

Build an AI Q&A system that answers questions from your documents with source citations.

​
Prerequisites

Before you start:
  • Python 3.9+ installed
  • Cerevox API key (get one here)
  • pip install cerevox completed

​
The 4-Step Workflow

Hippo follows a simple pattern:

​
Step-by-Step Implementation

1

Create a Folder

Folders organize documents into searchable knowledge bases.
from cerevox import Hippo

hippo = Hippo(api_key="your-api-key")

# Create a folder for your documents
folder = hippo.create_folder(
    name="Product Documentation",
    description="User guides and API docs"
)

print(f"Created folder: {folder.name}")
print(f"Folder ID: {folder.id}")
Tip: Use descriptive folder names - they help with organization when you have multiple knowledge bases.
2

Upload Files

Add documents to your folder from files or URLs.
# 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}")
print(f"Uploaded: {file2.name}")
Supported formats: PDF, DOCX, PPTX, XLSX, TXT, HTML, CSV, and more
Large files (100+ pages) may take 2-5 minutes to process. Use async API for better performance.
3

Create a Chat Session

Chat sessions maintain conversation context for Q&A.
# Create chat linked to the folder
chat = hippo.create_chat(
    folder_id=folder.id,
    chat_name="Technical Support Q&A"
)

print(f"Created chat: {chat.name}")
print(f"Chat ID: {chat.id}")
Multiple chats per folder: You can create different chats for different purposes (e.g., “Customer Support”, “Internal Q&A”).
4

Ask Questions

Submit questions and get AI-powered answers with citations!
# Ask a question
answer = hippo.submit_ask(
    chat_id=chat.id,
    question="How do I authenticate users in the API?"
)

# Print the answer
print(f"Question: {answer.question}")
print(f"Answer: {answer.response}")
print(f"Confidence: {answer.confidence_score}")

# Show source citations
print(f"\nSources ({len(answer.sources)} citations):")
for source in answer.sources:
    print(f"  - {source.file_name} (Page {source.page_number})")
You’re done! You’ve built a RAG Q&A system with 80% cost savings! 🎉

​
Complete Code Example

from cerevox import Hippo

# Initialize Hippo
hippo = Hippo(api_key="your-api-key")

# 1. Create folder
folder = hippo.create_folder(
    name="Product Documentation",
    description="User guides and API docs"
)

# 2. Upload files
file1 = hippo.upload_file(folder.id, "user-guide.pdf")
file2 = hippo.upload_file_from_url(
    folder.id,
    "https://example.com/api-docs.pdf",
    "api-docs.pdf"
)

# 3. Create chat
chat = hippo.create_chat(folder.id, "Technical Support")

# 4. Ask questions
questions = [
    "How do I authenticate?",
    "What are the API rate limits?",
    "How do I handle errors?"
]

for question in questions:
    answer = hippo.submit_ask(chat.id, question)
    print(f"\nQ: {question}")
    print(f"A: {answer.response}")
    print(f"Sources: {len(answer.sources)} citations")

​
What You Get Back

When you submit a question, Hippo returns:
​
response
string
The AI-generated answer to your question
​
question
string
The original question (as processed)
​
confidence_score
float
Confidence score (0-1) indicating answer quality
​
sources
array
List of source documents with citations
  • file_name: Name of the source document
  • file_id: Unique file identifier
  • page_number: Page where information was found
  • relevance_score: How relevant this source is

​
Testing Your Setup

Run this verification script: 
from cerevox import Hippo

def test_hippo():
    hippo = Hippo(api_key="your-api-key")

    # Quick test
    folder = hippo.create_folder("Test Folder")

    # Upload test content
    test_file = hippo.upload_file(folder.id, "test.pdf")

    # Create chat and ask
    chat = hippo.create_chat(folder.id, "Test Chat")
    answer = hippo.submit_ask(chat.id, "What is this document about?")

    # Verify
    if answer and answer.response:
        print("✅ Hippo is working correctly!")
        print(f"Answer: {answer.response}")
        return True
    else:
        print("❌ Something went wrong")
        return False

# Run test
test_hippo()

​
Common First Questions

  • Small files (< 10 pages): 10-30 seconds
  • Medium files (10-100 pages): 30-120 seconds
  • Large files (> 100 pages): 2-5 minutes
Files are processed automatically in the background. You can ask questions as soon as upload completes - the system will wait for indexing to finish.
Hippo pricing is based on:
  • Number of documents uploaded
  • Number of questions asked
  • Processing complexity
80% cheaper than traditional RAG with full document retrieval!Check pricing for current rates.
Supported formats:
  • Documents: PDF, DOCX, PPTX, TXT, RTF
  • Spreadsheets: XLSX, CSV
  • Web: HTML, MHTML
  • Others: Contact support for custom formats
Max file size: 100MB per file (contact for larger files)
Hippo supports 100+ languages for both documents and questions, including:
  • English, Spanish, French, German, Italian
  • Chinese (Simplified & Traditional), Japanese, Korean
  • Arabic, Hebrew, Hindi, and more
Same accuracy across all languages!
Yes! Cerevox is enterprise-ready:
  • Data encryption at rest and in transit
  • SOC 2 compliance (in progress)
  • Privacy controls: Delete data anytime
  • No training: Your data is never used to train models
See our privacy policy for details.

​
Next Steps

Folder Management

Learn to organize documents effectively

File Operations

Advanced file upload and management

Chat Sessions

Manage conversations and context

Best Practices

Optimize answer quality and costs
Need help? Join our Discord community or check out complete examples.