> ## Documentation Index > Fetch the complete documentation index at: https://docs.cerevox.ai/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart # 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) ```bash Terminal theme={null} pip install cerevox ``` ```bash Alternative Methods theme={null} # Using conda conda install -c conda-forge cerevox # Using poetry poetry add cerevox # Using pipenv pipenv install cerevox ``` ## Step 2: Get API Key (30 seconds) Visit [cerevox.ai](https://cerevox.ai) and sign up for your free API key Save your API key - you'll need it in the next step ## Step 3: Authentication Setup (30 seconds) ```bash theme={null} export CEREVOX_API_KEY="your-api-key-here" ``` ```python theme={null} from cerevox import Hippo hippo = Hippo(api_key="your-api-key-here") ``` ```bash .env theme={null} CEREVOX_API_KEY=your-api-key-here ``` ```python theme={null} import os from dotenv import load_dotenv from cerevox import Hippo load_dotenv() hippo = Hippo() # Automatically reads from environment ``` ## Step 4: Build RAG Q\&A System (3 minutes) Copy and run this code to create your first AI Q\&A system: ```python Complete RAG Workflow theme={null} 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!") ``` ```python Async Version (Recommended) theme={null} import asyncio from cerevox import AsyncHippo async def main(): async with AsyncHippo() as hippo: # 1. Create folder folder = await hippo.create_folder("Product Docs") # 2. Upload multiple files concurrently files = await asyncio.gather( hippo.upload_file(folder.id, "guide.pdf"), hippo.upload_file(folder.id, "docs.pdf") ) print(f"✅ Uploaded {len(files)} documents") # 3. Create chat chat = await hippo.create_chat(folder.id, "Support Q&A") # 4. Ask questions answer = await hippo.submit_ask( chat.id, "How do I get started?" ) print(f"💡 {answer.response}") print(f"📚 {len(answer.sources)} sources") asyncio.run(main()) ``` ```python Simple Q&A Example theme={null} from cerevox import Hippo hippo = Hippo() # Quick setup: Create folder, upload, create chat folder = hippo.create_folder("My Docs") hippo.upload_file(folder.id, "document.pdf") chat = hippo.create_chat(folder.id, "Q&A") # Ask your first question answer = hippo.submit_ask( chat_id=chat.id, question="What is the main topic of this document?" ) print(f"Answer: {answer.response}") print(f"Confidence: {answer.confidence_score}") # That's it! 80% cost reduction, flagship accuracy ``` **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 Complete guide to RAG capabilities Organize documents effectively Optimize answer quality Real-world implementation patterns Need to extract structured data from documents before using Hippo? Use **Lexa** for document parsing. ```python theme={null} from cerevox import Lexa client = Lexa() # Parse documents into structured data documents = client.parse(["contract.pdf"]) # Get vector DB optimized chunks chunks = documents.get_all_text_chunks(target_size=500) print(f"Ready for embedding: {len(chunks)} chunks") ``` Learn about document parsing capabilities ```python theme={null} from cerevox import Account account = Account() # Get account info info = account.get_account_info() print(f"Plan: {info.plan}") # Check usage usage = account.get_usage() print(f"API calls: {usage.total_requests}") ``` Manage authentication and usage ## Common Operations ```python theme={null} # Get all folders folders = hippo.get_folders() for folder in folders: print(f"{folder.name}: {folder.file_count} files") ``` ```python theme={null} # Get files in a folder files = hippo.get_files(folder_id=folder.id) for file in files: print(f"{file.name} - {file.status}") ``` ```python theme={null} # 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") ``` ```python theme={null} # 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") ``` ```python theme={null} # 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 key` **Quick fixes:** * Double-check your API key from [cerevox.ai](https://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 out **Quick 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](/hippo/questions) for more tips *** **Ready to scale?** Check out our [RAG optimization guide](/guides/rag-optimization) or join the [Discord community](https://discord.gg/cerevox) for help.