docs/CHATBOT_INTEGRATION.md

AI Chatbot Integration Guide

[From]: Phase III Integration Setup

This guide explains how to integrate and test the AI chatbot feature.

Prerequisites

1. Python 3.13+ installed
2. UV package manager installed
3. Gemini API key from Google AI Studio
4. PostgreSQL database (Neon or local)

Setup Steps

1. Backend Configuration

Environment Variables

Add to your backend/.env file:

# Database
DATABASE_URL=postgresql://user:password@host/database

# Gemini API (Required for AI chatbot)
GEMINI_API_KEY=your-gemini-api-key-here
GEMINI_MODEL=gemini-2.0-flash-exp

# JWT
JWT_SECRET=your-jwt-secret-here
JWT_ALGORITHM=HS256

# CORS
FRONTEND_URL=http://localhost:3000

# Environment
ENVIRONMENT=development

Get Gemini API Key

1. Go to Google AI Studio
2. Sign in with your Google account
3. Click "Get API Key"
4. Copy the API key
5. Add it to your .env file as GEMINI_API_KEY

Note: Gemini API has a free tier that's sufficient for development and testing.

2. Database Migration

The chatbot requires two additional tables: conversation and message.

Run the migration:

cd backend
python migrations/run_migration.py

Expected output:

✅ 2/2 migrations completed successfully
🎉 All migrations completed!

3. Install Dependencies

cd backend
uv sync

This installs:

• openai>=1.0.0 - OpenAI SDK (for AsyncOpenAI adapter)
• agents - OpenAI Agents SDK
• All other dependencies

4. Validate Integration

Run the integration validation script:

cd backend
python scripts/validate_chat_integration.py

This checks:

• ✅ Dependencies installed
• ✅ Environment variables configured
• ✅ Database tables exist
• ✅ MCP tools registered
• ✅ AI agent initialized
• ✅ Chat API routes registered

5. Start the Backend Server

cd backend
uv run python main.py

Expected output:

INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

6. Test the Chat API

Option A: Interactive API Docs

Open browser: http://localhost:8000/docs

Find the POST /api/{user_id}/chat endpoint and test it:

Request:

{
  "message": "Create a task to buy groceries"
}

Expected Response:

{
  "response": "I'll create a task titled 'Buy groceries' for you.",
  "conversation_id": "uuid-here",
  "tasks": []
}

Option B: cURL

curl -X POST "http://localhost:8000/api/{user_id}/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a task to buy groceries"
  }'

Replace {user_id} with a valid user UUID.

Option C: Python Test Script

import requests
import uuid

# Replace with actual user ID from your database
user_id = "your-user-uuid-here"

response = requests.post(
    f"http://localhost:8000/api/{user_id}/chat",
    json={"message": "Create a task to buy groceries"}
)

print(response.json())

7. Frontend Integration (Optional)

If you have the frontend running:

1. Start the frontend:

   cd frontend
   pnpm dev
   

2. Open browser: http://localhost:3000/chat

3. Test the chat interface with messages like:

   • "Create a task to buy groceries"
   • "What are my tasks?"
   • "Show me my pending tasks"
   • "Create a high priority task to finish the report by Friday"

API Endpoints

Chat Endpoint

POST /api/{user_id}/chat

Request Body:

{
  "message": "Create a task to buy groceries",
  "conversation_id": "optional-uuid-to-continue-conversation"
}

Response:

{
  "response": "I'll create a task titled 'Buy groceries' for you.",
  "conversation_id": "uuid",
  "tasks": []
}

Error Responses:

• 400 Bad Request: Invalid message (empty or >10,000 characters)
• 429 Too Many Requests: Daily message limit exceeded (100/day)
• 503 Service Unavailable: AI service not configured or unreachable
• 504 Gateway Timeout: AI service timeout

Troubleshooting

"AI service not configured"

Cause: GEMINI_API_KEY not set in .env

Fix:

1. Get API key from https://aistudio.google.com
2. Add to .env: GEMINI_API_KEY=your-key-here
3. Restart server

"Database error: relation 'conversation' does not exist"

Cause: Migration not run

Fix:

cd backend
python migrations/run_migration.py

"Daily message limit exceeded"

Cause: User has sent 100+ messages today

Fix: Wait until midnight UTC or use a different user ID for testing

Import errors for agents or openai

Cause: Dependencies not installed

Fix:

cd backend
uv sync

Testing Checklist

• Environment variables configured (especially GEMINI_API_KEY)
• Database migrations run successfully
• Validation script passes all checks
• Backend server starts without errors
• Can access API docs at http://localhost:8000/docs
• Can send message via /api/{user_id}/chat endpoint
• AI responds with task creation confirmation
• Can list tasks via chat
• Conversation persists across requests (using conversation_id)
• Frontend chat page works (if applicable)

Rate Limiting

The chatbot enforces a limit of 100 messages per user per day (NFR-011).

This includes both user and assistant messages in conversations.

The limit resets at midnight UTC.

Architecture Overview

Frontend (React)
    ↓
ChatInterface.tsx → POST /api/{user_id}/chat
    ↓
Backend (FastAPI)
    ↓
chat.py endpoint
    ├→ Rate limiting check (T021)
    ├→ Get/create conversation (T016)
    ├→ Persist user message (T017)
    ├→ Load conversation history (T016)
    ├→ Run AI agent (T014)
    │   ↓
    │   Agent → MCP Tools
    │       ├→ add_task (T013)
    │       └→ list_tasks (T024, T027)
    └→ Persist AI response (T018)

MCP Tools

The AI agent has access to two MCP tools:

add_task

Creates a new task.

Parameters:

• user_id (required): User UUID
• title (required): Task title
• description (optional): Task description
• due_date (optional): Due date (ISO 8601 or relative)
• priority (optional): "low", "medium", or "high"

list_tasks

Lists and filters tasks.

Parameters:

• user_id (required): User UUID
• status (optional): "all", "pending", or "completed"
• due_within_days (optional): Filter by due date
• limit (optional): Max tasks to return (1-100, default 50)

Next Steps

After successful integration:

1. Test User Story 1: Create tasks via natural language
2. Test User Story 2: List and filter tasks via natural language
3. Monitor rate limiting: Ensure 100/day limit works
4. Test error handling: Try without API key, with invalid user ID, etc.
5. Proceed to User Story 3: Task updates via natural language

Support

For issues or questions:

• Check the validation script output: python scripts/validate_chat_integration.py
• Review API docs: http://localhost:8000/docs
• Check backend logs for detailed error messages