Your First Query

Learn by doing! This step-by-step tutorial will take you from zero to your first successful query.

What You'll Build

A simple document Q&A application that:

Ingests PDF documents

Answers questions about them

Maintains conversation context

Time to complete: ~10 minutes

Prerequisites

✅ Shadai installed (Installation Guide)

✅ API key configured (Authentication Guide)

✅ Python 3.10+ with async support

Step 1: Prepare Your Documents

Create a folder with some PDF files:

For this tutorial, you can use any PDF - research papers, reports, books, etc.

Step 2: Create Your Script

Create first_query.py:

Step 3: Run Your First Query

You should see output like:

🚀 Starting Shadai session...
📥 Ingesting documents...
✅ Successfully ingested: 3
❌ Failed: 0
⊘ Skipped (too large): 0

🔍 Asking question...
Q: What are the main topics covered in these documents?

A: Based on the documents provided, the main topics include:
1. Machine learning algorithms and their applications
2. Data preprocessing techniques
3. Model evaluation metrics...

Step 4: Add Follow-Up Questions

The magic of Shadai is context! Let's add a follow-up:

Notice how the second question doesn't need to repeat context - Shadai remembers "the first topic" from the previous answer!

Understanding the Code

The Context Manager

async with - Ensures proper cleanup

name="my-first-query" - Creates a persistent session

Session stores: documents, chat history, context

Ingestion

What happens behind the scenes:

🔍 Scans folder recursively

📄 Extracts text from PDFs

✂️ Chunks documents intelligently

🧠 Creates embeddings

💾 Stores in vector database

Querying

What happens:

🧠 Converts question to embedding

🔍 Finds relevant document chunks

🤖 Generates answer with context

⚡ Streams tokens in real-time

Troubleshooting

No documents ingested

Problem: Successfully ingested: 0

Solutions:

Check folder path is correct

Ensure PDFs are under 35MB

Verify PDFs aren't corrupted

Slow ingestion

Problem: Ingestion takes a long time

Explanation:

First ingestion is slower (processing + embedding)

Large files take longer

This is normal! Subsequent queries are fast

Generic answers

Problem: Answers don't reference your documents

Solutions:

Check documents were actually ingested

Make questions more specific

Verify documents contain relevant information

Authentication errors

Problem: AuthenticationError

Solution:

Next Level: Interactive Q&A

Let's make it interactive:

Run it:

Example interaction:

📥 Loading documents...
✅ Ready! Ask your questions (type 'quit' to exit)

You: What is this document about?
AI: This document discusses machine learning algorithms...

You: What are the key benefits?
AI: The key benefits mentioned include improved accuracy...

You: quit

What You Learned

✅ How to create a Shadai session
✅ How to ingest documents
✅ How to query your knowledge base
✅ How streaming responses work
✅ How context is maintained automatically

Next Steps

Now that you've run your first query, explore more:

📖 Learn More

Session Management - Organize your data

Memory & Context - Control conversation flow

Streaming Responses - Handle real-time data

💡 See Examples

Document Q&A - Production-ready Q&A system

Research Assistant - Advanced research workflows

Multi-Document Analysis - Analyze multiple sources

🚀 Go Advanced

Custom Tools - Build your own tools

Intelligent Agents - Orchestrate complex workflows

Performance Optimization - Scale to production

Need Help?

💬 Having issues? Check Error Handling Guide

🐛 Found a bug? Open an issue

💡 Have questions? Email support@shadai.com

🎉 Congratulations! You've completed your first query. Ready to build something amazing?

What You'll Build#

Prerequisites#

Step 1: Prepare Your Documents#

Step 2: Create Your Script#

Step 3: Run Your First Query#

Step 4: Add Follow-Up Questions#

Understanding the Code#

The Context Manager#

Ingestion#

Querying#

Troubleshooting#

No documents ingested#

Slow ingestion#

Generic answers#

Authentication errors#

Next Level: Interactive Q&A#

What You Learned#

Next Steps#

📖 Learn More#

💡 See Examples#

🚀 Go Advanced#

Need Help?#