Hugging Face's logo

Spaces:
ammaraak
/
todo-api
Configuration error

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

Phase III Feature Documentation

AI-Powered Todo Chatbot - Complete Feature List

Version: 1.0.0 Status: ✅ Production Ready Last Updated: 2026-01-25

🎯 Core Features

1. Natural Language Task Management

Create Tasks

English Examples:

  • "Add a task to buy milk"
  • "Create task 'Finish project' with high priority"
  • "Add task 'Submit report' due 2026-02-01"
  • "Create task 'Meeting' with tag 'work' and high priority"

Urdu Examples:

  • "دودھ لینے کا ٹاسک شامل کرو"
  • "پروجیکت مکمل کرنے کا ٹاسک بناؤ"
  • "ہائی پرئورٹی والا ٹاسک شامل کرو"

Supported Fields:

  • ✅ Title (required, 1-200 chars)
  • ✅ Description (optional)
  • ✅ Priority: low/medium/high
  • ✅ Due Date: ISO format
  • ✅ Tags: Array of strings

View Tasks

English Examples:

  • "Show my tasks"
  • "List all pending tasks"
  • "Show high priority tasks"
  • "What are my tasks due this week?"

Urdu Examples:

  • "میرے ٹاسک دکھاؤ"
  • "زیر التوا ٹاسک دکھاؤ"
  • "ہائی پرئورٹی والے ٹاسک"

Filtering Options:

  • ✅ By status (pending/completed)
  • ✅ By priority (low/medium/high)
  • ✅ By due date range
  • ✅ By tags

Update Tasks

English Examples:

  • "Update task 1 title to 'Buy groceries'"
  • "Change task 2 priority to high"
  • "Add tag 'urgent' to task 3"

Urdu Examples:

  • "ٹاسک 1 کا عنوان تبدیل کرو"
  • "ٹاسک 2 کی پرئورٹی ہائی کر دو"

Complete Tasks

English Examples:

  • "Mark task 1 as done"
  • "Complete task 2"
  • "Task 3 is finished"

Urdu Examples:

  • "ٹاسک 1 مکمل کر دو"
  • "پہلا ٹاسک ختم کر دیں"

Delete Tasks

English Examples:

  • "Delete task 5"
  • "Remove task number 3"

Urdu Examples:

  • "ٹاسک 5 حذف کرو"
  • "پانچواں ٹاسک ہٹا دو"

2. Bilingual Support

Language Detection:

  • ✅ Automatic detection from input text
  • ✅ Urdu Unicode range detection (\u0600-\u06FF)
  • ✅ Falls back to English if no Urdu detected

System Prompts:

  • ✅ English system prompt for English input
  • ✅ Urdu system prompt for Urdu input
  • ✅ Consistent language throughout conversation

Response Language:

  • ✅ AI responds in same language as input
  • ✅ Mixed language handled gracefully
  • ✅ Error messages in detected language

3. Conversation Management

Persistence:

  • ✅ All messages saved to database
  • ✅ Conversation history loaded on every request
  • ✅ Stateless server architecture
  • ✅ Conversation ID tracking

Context:

  • ✅ Last 10 messages included in AI context
  • ✅ Thread-safe conversation handling
  • ✅ User-specific conversations (user_id isolation)

Message Types:

  • ✅ User messages
  • ✅ Assistant messages
  • ✅ Tool call messages (metadata)

4. MCP (Model Context Protocol) Tools

Available Tools:

  1. create_task

    • Creates new todo
    • Returns created task details
    • Validates input

  2. list_tasks

    • Lists user's tasks
    • Optional filters (status, priority)
    • Configurable limit (default 50)

  3. update_task

    • Updates any task field
    • Validates ownership
    • Returns updated task

  4. delete_task

    • Deletes task by ID
    • Validates ownership
    • Returns confirmation

  5. complete_task

    • Marks task as completed
    • Sets completion timestamp
    • Returns updated task

Tool Execution:

  • ✅ Async execution
  • ✅ Error handling
  • ✅ User isolation enforced
  • ✅ Result formatting for AI

5. AI Integration (Qwen)

Hugging Face API:

  • ✅ Model: Qwen/Qwen-14B-Chat
  • ✅ Inference API integration
  • ✅ Retry logic with exponential backoff
  • ✅ Timeout handling (30s)

Prompt Engineering:

  • ✅ Bilingual system prompts
  • ✅ Tool definitions included
  • ✅ Conversation history context
  • ✅ Clear instruction formatting

Response Processing:

  • ✅ Tool call extraction (TOOL_CALL: format)
  • ✅ Result formatting
  • ✅ Error handling
  • ✅ Fallback responses

6. Authentication & Security

JWT Authentication:

  • ✅ Required on all endpoints
  • ✅ User ID extraction from token
  • ✅ Token validation
  • ✅ Error handling for invalid tokens

User Isolation:

  • ✅ All queries filter by user_id
  • ✅ Foreign key constraints
  • ✅ Ownership validation
  • ✅ No cross-user data access

Input Validation:

  • ✅ Message length: 1-1000 characters
  • ✅ Title length: 1-200 characters
  • ✅ UUID format validation
  • ✅ Enum validation (status, priority)

Security Measures:

  • ✅ SQL injection prevention (parameterized queries)
  • ✅ XSS prevention (React escaping)
  • ✅ CORS configuration
  • ✅ Environment variables for secrets

7. Frontend UI Features

Chat Interface:

  • ✅ Animated robot avatar
  • ✅ Message history display
  • ✅ Auto-scroll to latest message
  • ✅ Real-time language detection
  • ✅ Character counter (1000 max)
  • ✅ Loading indicator
  • ✅ Error display
  • ✅ Copy message button
  • ✅ Clear chat button

Visual Design:

  • ✅ Modern gradient styling
  • ✅ Dark mode support
  • ✅ Responsive layout (mobile-friendly)
  • ✅ Smooth animations
  • ✅ Professional typography
  • ✅ Color-coded messages (user/AI)

User Experience:

  • ✅ Suggestion buttons
  • ✅ Empty state with examples
  • ✅ Focused input on mount
  • ✅ Enter to send
  • ✅ Shift+Enter for new line
  • ✅ Disabled state during loading

Animations:

  • ✅ Fade-in messages
  • ✅ Slide animations
  • ✅ Pulse glow effects
  • ✅ Floating robot
  • ✅ Typing indicator
  • ✅ Sparkle effects
  • ✅ Blinking eyes (robot)
  • ✅ Talking mouth (robot)

8. Database Features

Tables:

  1. users (from Phase II)

    • User authentication data
    • Profile information

  2. todos (from Phase II)

    • Task management
    • Tags, priorities, due dates
    • User foreign key

  3. conversation (Phase III)

    • Chat sessions
    • User foreign key
    • Timestamps

  4. message (Phase III)

    • Chat messages
    • Conversation foreign key
    • Role (user/assistant/tool)
    • Tool call metadata

Indexes:

  • ✅ ix_users_email (unique)
  • ✅ ix_users_id
  • ✅ ix_conversation_user_id
  • ✅ ix_message_conversation_id
  • ✅ ix_message_created_at

Relationships:

  • ✅ User → Todos (1:N)
  • ✅ User → Conversations (1:N)
  • ✅ Conversation → Messages (1:N)

🧪 Testing Checklist

Backend Tests

  • Health check endpoint
  • Root endpoint
  • Chat health endpoint
  • Chat endpoint with valid JWT
  • Chat endpoint with invalid JWT
  • Create task via tool
  • List tasks via tool
  • Update task via tool
  • Complete task via tool
  • Delete task via tool
  • User isolation (access another user's task)
  • Language detection (English)
  • Language detection (Urdu)
  • Long message handling (1000 chars)
  • Empty message rejection
  • Invalid UUID handling
  • Database connection retry
  • API timeout handling

Frontend Tests

  • Page loads without errors
  • Redirect to login if not authenticated
  • Chat interface renders
  • Robot avatar displays
  • Suggestions work
  • Input accepts English text
  • Input accepts Urdu text
  • Character counter updates
  • Send button enables/disables correctly
  • Enter key sends message
  • Messages appear in chat
  • Loading indicator shows
  • Error messages display
  • Copy button works
  • Clear chat button works
  • Auto-scroll works
  • Dark mode toggle
  • Mobile responsive
  • Session ID displays

Integration Tests

  • Full user flow: Login → Chat → Create task
  • English conversation end-to-end
  • Urdu conversation end-to-end
  • Mixed language conversation
  • Task creation → View → Complete → Delete
  • Error recovery (network failure)
  • Conversation persistence (refresh page)
  • Multiple users (no data leakage)

📊 Performance Metrics

Target Performance

  • Backend Response Time: < 2s (95th percentile)
  • AI Response Time: < 5s (95th percentile)
  • Database Query Time: < 100ms (95th percentile)
  • Frontend Load Time: < 1s (initial)
  • Message Rendering: < 100ms (per message)

Optimization Strategies

Backend:

  • Async I/O operations
  • Connection pooling
  • Query result caching
  • Lazy loading for conversations

Frontend:

  • React memoization
  • Virtual scrolling (future)
  • Image optimization
  • Code splitting

🔧 Configuration Options

Environment Variables

Backend:

NEON_DATABASE_URL=postgresql://...
HUGGINGFACE_API_KEY=hf_...
QWEN_MODEL=Qwen/Qwen-14B-Chat
JWT_SECRET=...
HOST=0.0.0.0
PORT=8000
RELOAD=true

Frontend:

NEXT_PUBLIC_API_URL=http://localhost:8000

Tunable Parameters

Backend:

  • MAX_MESSAGE_LENGTH: 1000 (configurable in Pydantic model)
  • MAX_TITLE_LENGTH: 200 (configurable in Pydantic model)
  • CONVERSATION_HISTORY_LIMIT: 10 messages
  • MCP_TOOL_TIMEOUT: 30s
  • QWEN_TIMEOUT: 30s
  • QWEN_MAX_RETRIES: 3

Frontend:

  • MAX_INPUT_LENGTH: 1000
  • DEBOUNCE_DELAY: 300ms (future)
  • AUTO_SCROLL_DELAY: 100ms

📈 Future Enhancements

Planned Features (Not Yet Implemented)

  1. Streaming Responses

    • WebSocket support
    • Real-time AI token streaming
    • Typing indicator cancellation

  2. Voice Input/Output

    • Speech-to-text for input
    • Text-to-speech for responses
    • Voice command shortcuts

  3. File Uploads

    • Image/file attachments
    • AI file analysis
    • Document parsing

  4. Task Reminders

    • Email notifications
    • Push notifications
    • SMS alerts (Twilio)

  5. Advanced Search

    • Full-text search
    • Fuzzy matching
    • Date range queries

  6. Collaboration

    • Shared tasks
    • Team conversations
    • Comments on tasks

  7. Analytics Dashboard

    • Task completion rates
    • User engagement metrics
    • AI usage statistics

🐛 Known Limitations

  1. SQLite Testing Mode

    • Tags feature disabled (ARRAY type not supported)
    • Use Neon PostgreSQL for full functionality

  2. AI Context Window

    • Only last 10 messages included
    • Long conversations may lose early context

  3. Tool Call Format

    • Requires specific TOOL_CALL: JSON format
    • AI may not always format correctly

  4. No Streaming

    • Responses are complete (not streamed)
    • Users see loading indicator

  5. Single Session

    • No multi-conversation support yet
    • All messages in one conversation per user

📚 API Reference

POST /api/chat

Request:

{
  "message": "Add a task to buy milk",
  "conversation_id": "optional-uuid"
}

Headers:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

Response (Success):

{
  "reply": "Task created successfully!",
  "conversation_id": "uuid-here",
  "tool_calls": [
    {
      "tool": "create_task",
      "success": true,
      "result": {
        "task": { ... }
      }
    }
  ]
}

Response (Error):

{
  "detail": "Error message here"
}

✅ Acceptance Criteria

All User Story 1 requirements met:

  • Users can create tasks via natural language (English)
  • Users can create tasks via natural language (Urdu)
  • AI extracts task details automatically
  • Tasks are saved to database
  • AI responds in same language as input
  • JWT authentication enforced
  • User data isolated
  • Conversation history persisted
  • MCP tools execute correctly
  • Error messages are user-friendly
  • UI is responsive and modern
  • Animations are smooth

Feature Status: ✅ COMPLETE Production Ready: YES Documentation Status: COMPLETE Test Coverage: MANUAL TESTING COMPLETE