docs/QUICK_START.md

🚀 Quick Start Guide - Agentic AI Backend

Prerequisites

Step 1: Verify Installation ✅

Dependencies are already installed. Verify with:

python -c "import chromadb, sentence_transformers; print('✅ Vector Store packages installed')"

Step 2: Configure Environment 🔧

Option 1: GitHub Models (Recommended) ⭐

Free, fast, and reliable!

1. Get a GitHub token: https://github.com/settings/tokens
2. Edit .env:

Copy-Item .env.template .env
notepad .env

3. Add your tokens:

GITHUB_TOKEN=ghp_your_github_token_here
OPENWEATHERMAP_API_KEY=your_weather_api_key_here

See detailed setup: GITHUB_MODELS_SETUP.md

Option 2: Local with Ollama

If you prefer running locally:

1. Install a capable Ollama model:

ollama pull llama3.2  # Better than qwen3:0.6b

2. Configure .env:

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2
OPENWEATHERMAP_API_KEY=your_weather_api_key_here

Note: GitHub Models recommended for better reliability and tool calling.

Step 3: Initialize Database 💾

python seed_data.py

This creates:

Expected output:

Database initialized
Sample meetings created successfully

Step 4: Run Tests 🧪

python test_agents.py

This runs 6 comprehensive tests:

1. ✅ Weather Agent - Current weather
2. ✅ Meeting Agent - Weather-conditional scheduling
3. ✅ SQL Agent - Database queries
4. ✅ Document RAG - High confidence retrieval
5. ✅ Web Fallback - Low confidence web search
6. ✅ Specific Retrieval - Precise information extraction

First run will download the embedding model (~80MB) - this is normal!

Step 5: Start the API Server 🌐

python main.py

Server starts at: http://127.0.0.1:8000

API docs available at: http://127.0.0.1:8000/docs

Step 6: Test API Endpoints 📡

Test 1: Weather Query

$body = @{
    query = "What's the weather in Paris today?"
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8000/chat" `
    -ContentType "application/json" -Body $body

Test 2: Upload Document

$filePath = "C:\path\to\your\document.pdf"
curl -X POST "http://127.0.0.1:8000/upload" -F "file=@$filePath"

Response will include file_path - use it in the next request.

Test 3: RAG Query

$body = @{
    query = "What does the document say about remote work?"
    file_path = "D:\python_workspace\multi-agent\uploads\uuid.pdf"
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8000/chat" `
    -ContentType "application/json" -Body $body

Test 4: Meeting Scheduling

$body = @{
    query = "Schedule a team meeting tomorrow at 3 PM in London if weather is good. Include Alice and Bob."
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8000/chat" `
    -ContentType "application/json" -Body $body

Test 5: SQL Query

$body = @{
    query = "Show me all meetings scheduled for this week"
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8000/chat" `
    -ContentType "application/json" -Body $body

Expected Behavior 🎯

Weather Agent

Document RAG Agent

Meeting Agent

SQL Agent

Troubleshooting 🔧

Issue: "No valid LLM configured"

Solution: Ensure Ollama is running at http://localhost:11434

# Check if Ollama is running
Invoke-WebRequest http://localhost:11434

Issue: "Weather API key not configured"

Solution: Add your API key to .env:

OPENWEATHERMAP_API_KEY=your_key_here

Issue: "Document ingestion failed"

Solution: Check file format (PDF/TXT/MD/DOCX) and size (<10MB)

Issue: Slow first RAG query

Expected: First run downloads sentence-transformers model (~80MB) Subsequent queries will be fast.

Issue: Import errors in IDE

Normal: VSCode may show import warnings until packages are fully indexed. Code will run fine.

Understanding the RAG Workflow 📚

User uploads document.pdf
         ↓
1. Parse with Docling
         ↓
2. Chunk into 500-char pieces (50-char overlap)
         ↓
3. Generate embeddings with sentence-transformers
         ↓
4. Store in ChromaDB (./chroma_db/)
         ↓
User asks: "What is the policy?"
         ↓
5. Search vector store for similar chunks
         ↓
6. Check similarity score
         ↓
   ┌─────────────┬──────────────┐
   │ Score ≥ 0.7 │ Score < 0.7  │
   │ (confident) │ (uncertain)  │
   └─────────────┴──────────────┘
         │              │
         ↓              ↓
   Return doc      Search web
   answer          + combine
                   results

File Structure 📁

multi-agent/
├── main.py                 # FastAPI server
├── agents.py              # LangGraph agents
├── tools.py               # Agent tools
├── vector_store.py        # ChromaDB manager (NEW)
├── database.py            # SQLite config
├── models.py              # SQLAlchemy models
├── test_agents.py         # Test suite
├── seed_data.py           # DB initialization
├── .env                   # Your configuration
├── .env.template          # Configuration template
├── database.db            # SQLite database
├── chroma_db/             # Vector store (auto-created)
├── uploads/               # Uploaded documents
└── IMPLEMENTATION_COMPLETE.md  # Full documentation

Next Steps 🎯

1. Explore the API: Visit http://127.0.0.1:8000/docs
2. Try different queries: Test edge cases and complex scenarios
3. Upload your documents: Try PDFs, policies, resumes
4. Check vector store: Inspect ./chroma_db/ directory
5. Review logs: Monitor agent decisions and tool calls

Performance Tips ⚡

Support 📞

You're all set! 🎉 Start making requests to your AI backend!