Hugging Face's logo

Spaces:
ammaraak
/
todo-api
Configuration error

App Files Community
todo-api / PHASE_III_QUICKSTART.md
Nanny7's picture
Nanny7
feat: Phase III - AI-Powered Todo Chatbot (Complete)
a0b9343
preview code
|
raw
history blame contribute delete
5.9 kB

Phase III Quick Start Guide

AI-Powered Todo Chatbot

Get up and running in 5 minutes! ⚑

πŸš€ Quick Start

Prerequisites Checklist

Step 1: Setup Environment (2 minutes)

Backend .env 

# In project root, create .env file:
NEON_DATABASE_URL=postgresql://user:password@ep-xxx.aws.neon.tech/neondb?sslmode=require
HUGGINGFACE_API_KEY=hf_your_api_key_here
QWEN_MODEL=Qwen/Qwen-14B-Chat
JWT_SECRET=your-jwt-secret-here

Frontend .env.local 

# In frontend/, create .env.local:
NEXT_PUBLIC_API_URL=http://localhost:8000

Step 2: Install Dependencies (1 minute) 

# Python dependencies
pip install -r requirements.txt

# Node dependencies
cd frontend
npm install
cd ..

Step 3: Setup Database (30 seconds) 

python backend/scripts/migrate_ai_tables.py

Expected output:

[OK] Checking database connection...
[OK] Creating Conversation table...
[OK] Creating Message table...
[OK] Migration complete!

Step 4: Start Backend (30 seconds) 

# Terminal 1
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

Verify it's running:

curl http://localhost:8000/health
# Should return: {"status":"healthy"...}

Step 5: Start Frontend (30 seconds) 

# Terminal 2
cd frontend
npm run dev

Open: http://localhost:3000/chat

Step 6: Test the Chat! (1 minute)

Login First

  1. Go to http://localhost:3000/login
  2. Enter your Phase II credentials
  3. You'll be redirected to chat

Try These Commands

English:

Add a task to buy milk
Show my tasks
Mark task 1 as complete

Urdu:

دودھ Ω„ΫŒΩ†Ϋ’ Ϊ©Ψ§ ΩΉΨ§Ψ³Ϊ© Ψ΄Ψ§Ω…Ω„ کرو
Ω…ΫŒΨ±Ϋ’ ΩΉΨ§Ψ³Ϊ© Ψ―Ϊ©ΪΎΨ§Ψ€
پہلا ΩΉΨ§Ψ³Ϊ© Ω…Ϊ©Ω…Ω„ کرو

🎯 What's Happening?

Architecture 

You (Frontend)
    ↓ "Add a task to buy milk"
    ↓ (JWT + HTTP)
Backend (/api/chat)
    ↓ Extract user_id
    ↓ Detect language (English)
    ↓ Send to Qwen AI
    ↓ AI responds: TOOL_CALL create_task
    ↓ Execute MCP tool
    ↓ Create task in database
    ↓ Format response
    ↓ Return: "Task created!"
You (Frontend)
    ↓ Display response

Components

Frontend:

  • ChatInterfaceAdvanced.tsx - Beautiful chat UI
  • RobotAvatar.tsx - Animated robot
  • /chat page - Main chat interface

Backend:

  • /api/chat - Main chat endpoint
  • QwenClient - Hugging Face integration
  • MCPTools - Task operations
  • TodoRepository - Database access

πŸ“ Common Commands

Backend 

# Start server
python -m uvicorn backend.main:app --reload

# Run migration
python backend/scripts/migrate_ai_tables.py

# Test chat endpoint
curl http://localhost:8000/api/chat/health

# View API docs
open http://localhost:8000/docs

Frontend 

# Start dev server
npm run dev

# Build for production
npm run build

# Start production server
npm run start

# Lint code
npm run lint

πŸ› Troubleshooting

"Port 8000 already in use" 

# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F

# Mac/Linux
lsof -ti:8000 | xargs kill -9

"Database connection failed"

Check your .env file has correct NEON_DATABASE_URL

"JWT token invalid"

  1. Logout from frontend
  2. Login again with Phase II credentials
  3. New token will be generated

"Hugging Face API error"

Verify:

  • API key is correct
  • Model name: Qwen/Qwen-14B-Chat
  • Account has API access enabled

πŸ“Š Test Cases

Test 1: Create Task (English)

Input: Add a task to finish the project with high priority

Expected:

  • AI responds in English
  • Task created with title "finish the project"
  • Priority set to "high"
  • Confirmation message displayed

Test 2: Create Task (Urdu)

Input: Ϊ―ΪΎΨ± ΩΎΨ± Ψ¬Ψ§ Π·Π°Π΄Π°Ρ‡Π°

Expected:

  • AI responds in Urdu
  • Task created with Urdu title
  • Confirmation in Urdu

Test 3: View Tasks

Input: Show my tasks

Expected:

  • AI lists all your tasks
  • Shows status, priority, due dates
  • Response in detected language

Test 4: Complete Task

Input: Mark task 1 as done

Expected:

  • Task status changed to "completed"
  • Completion timestamp set
  • Confirmation message

🎨 Features Available

βœ… Bilingual Support - English & Urdu βœ… Natural Language - No special commands needed βœ… Task CRUD - Create, Read, Update, Delete βœ… Priorities - Low, Medium, High βœ… Due Dates - ISO format supported βœ… Tags - Categorize tasks βœ… Animated Robot - Cute AI avatar βœ… Chat History - Conversations saved βœ… Dark Mode - Beautiful dark theme

πŸš€ Next Steps

  1. Customize Prompts: Edit backend/src/ai/prompt_builder.py
  2. Add More Tools: Create new MCP tools in backend/src/mcp/tools.py
  3. Style Customization: Modify frontend/src/styles/globals.css
  4. Deploy: Follow PHASE_III_DEPLOYMENT.md

πŸ“š Full Documentation

  • Deployment Guide: PHASE_III_DEPLOYMENT.md
  • Specification: specs/001-ai-chatbot/spec.md
  • Implementation Plan: specs/001-ai-chatbot/plan.md
  • Task List: specs/001-ai-chatbot/tasks.md

πŸ’‘ Tips

  1. Start Simple: Try basic commands first
  2. Be Specific: More details = better AI understanding
  3. Mix Languages: AI detects language automatically
  4. Use Conversations: AI remembers context (10 messages)
  5. Check Logs: Backend logs show tool executions

πŸŽ‰ You're ready to use the AI-Powered Todo Chatbot!

Time to complete: ~5 minutes Difficulty: Beginner-friendly Support: Check PHASE_III_DEPLOYMENT.md for detailed troubleshooting