taskflow todo app

.env.example

@@ -0,0 +1,18 @@
+# Database Configuration
+DATABASE_URL=postgresql://neondb_owner:npg_E1weFcD5YCsp@ep-wandering-waterfall-ai9cg8eu-pooler.c-4.us-east-1.aws.neon.tech/neondb?sslmode=require&channel_binding=require
+
+
+# JWT Configuration
+JWT_SECRET=c93afeb6710d2845
+JWT_ALGORITHM=HS256
+JWT_EXPIRATION_HOURS=168
+
+# Better Auth Secret (must match frontend)
+BETTER_AUTH_SECRET=3gHSWlEDitVGXMw9B9d1YcXriLhyxltr
+
+# CORS Configuration
+CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+
+# Environment
+ENVIRONMENT=development
+DEBUG=true

.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

API_DOCUMENTATION.md

@@ -0,0 +1,840 @@
+# KIro Todo API Documentation
+
+**Version**: 1.0.0
+**Base URL**: `http://localhost:8001`
+**Authentication**: JWT Bearer Token
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Authentication](#authentication)
+3. [Task Management](#task-management)
+4. [Data Models](#data-models)
+5. [Error Handling](#error-handling)
+6. [Security](#security)
+7. [Examples](#examples)
+
+---
+
+## Overview
+
+The KIro Todo API is a RESTful API built with FastAPI that provides secure, multi-user task management with complete data isolation. Each user can only access their own tasks, enforced through JWT authentication and database-level filtering.
+
+**Key Features:**
+- JWT-based authentication
+- User-scoped data isolation
+- Complete CRUD operations for tasks
+- Task completion tracking
+- Comprehensive error handling
+- Automatic timestamp management
+
+---
+
+## Authentication
+
+All task endpoints require a valid JWT token in the `Authorization` header.
+
+### User Signup
+
+Create a new user account.
+
+**Endpoint:** `POST /api/auth/signup`
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "SecurePass123"
+}
+```
+
+**Response:** `201 Created`
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer",
+  "user": {
+    "id": 1,
+    "email": "user@example.com"
+  }
+}
+```
+
+**Validation Rules:**
+- Email must be valid format
+- Password minimum 8 characters
+- Password must contain: uppercase, lowercase, number
+- Email must be unique
+
+**Error Responses:**
+- `400 Bad Request` - Invalid email format or weak password
+- `409 Conflict` - Email already exists
+
+---
+
+### User Signin
+
+Authenticate an existing user.
+
+**Endpoint:** `POST /api/auth/signin`
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "SecurePass123"
+}
+```
+
+**Response:** `200 OK`
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer",
+  "user": {
+    "id": 1,
+    "email": "user@example.com"
+  }
+}
+```
+
+**Error Responses:**
+- `401 Unauthorized` - Invalid credentials
+
+---
+
+## Task Management
+
+All task endpoints require authentication via JWT token.
+
+**Authentication Header:**
+```
+Authorization: Bearer <your_jwt_token>
+```
+
+---
+
+### List All Tasks
+
+Retrieve all tasks for the authenticated user.
+
+**Endpoint:** `GET /api/tasks`
+
+**Headers:**
+```
+Authorization: Bearer <token>
+```
+
+**Response:** `200 OK`
+```json
+[
+  {
+    "id": 1,
+    "title": "Complete project documentation",
+    "description": "Write comprehensive API docs",
+    "completed": false,
+    "user_id": 1,
+    "created_at": "2026-02-03T10:30:00Z",
+    "updated_at": "2026-02-03T10:30:00Z"
+  },
+  {
+    "id": 2,
+    "title": "Review pull requests",
+    "description": null,
+    "completed": true,
+    "user_id": 1,
+    "created_at": "2026-02-03T09:15:00Z",
+    "updated_at": "2026-02-03T11:45:00Z"
+  }
+]
+```
+
+**Query Parameters:** None
+
+**Notes:**
+- Returns only tasks owned by authenticated user
+- Ordered by creation date (newest first)
+- Empty array if user has no tasks
+
+---
+
+### Create Task
+
+Create a new task for the authenticated user.
+
+**Endpoint:** `POST /api/tasks`
+
+**Headers:**
+```
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "title": "Buy groceries",
+  "description": "Milk, eggs, bread, and coffee"
+}
+```
+
+**Response:** `201 Created`
+```json
+{
+  "id": 3,
+  "title": "Buy groceries",
+  "description": "Milk, eggs, bread, and coffee",
+  "completed": false,
+  "user_id": 1,
+  "created_at": "2026-02-03T12:00:00Z",
+  "updated_at": "2026-02-03T12:00:00Z"
+}
+```
+
+**Field Requirements:**
+- `title` (required): 1-200 characters, cannot be empty or whitespace
+- `description` (optional): 0-2000 characters, can be null
+
+**Error Responses:**
+- `400 Bad Request` - Missing or empty title
+- `401 Unauthorized` - Invalid or missing token
+
+**Notes:**
+- `user_id` is automatically set from JWT token
+- `completed` defaults to `false`
+- Timestamps are automatically generated
+
+---
+
+### Get Single Task
+
+Retrieve a specific task by ID.
+
+**Endpoint:** `GET /api/tasks/{task_id}`
+
+**Headers:**
+```
+Authorization: Bearer <token>
+```
+
+**Path Parameters:**
+- `task_id` (integer): The task ID
+
+**Response:** `200 OK`
+```json
+{
+  "id": 1,
+  "title": "Complete project documentation",
+  "description": "Write comprehensive API docs",
+  "completed": false,
+  "user_id": 1,
+  "created_at": "2026-02-03T10:30:00Z",
+  "updated_at": "2026-02-03T10:30:00Z"
+}
+```
+
+**Error Responses:**
+- `401 Unauthorized` - Invalid or missing token
+- `403 Forbidden` - Task belongs to another user
+- `404 Not Found` - Task does not exist
+
+**Security:**
+- Ownership is verified before returning task
+- Users cannot access other users' tasks
+
+---
+
+### Update Task
+
+Update an existing task's title and/or description.
+
+**Endpoint:** `PUT /api/tasks/{task_id}`
+
+**Headers:**
+```
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Path Parameters:**
+- `task_id` (integer): The task ID
+
+**Request Body:**
+```json
+{
+  "title": "Complete project documentation (Updated)",
+  "description": "Write comprehensive API docs with examples"
+}
+```
+
+**Partial Update Supported:**
+```json
+{
+  "title": "New title only"
+}
+```
+
+**Response:** `200 OK`
+```json
+{
+  "id": 1,
+  "title": "Complete project documentation (Updated)",
+  "description": "Write comprehensive API docs with examples",
+  "completed": false,
+  "user_id": 1,
+  "created_at": "2026-02-03T10:30:00Z",
+  "updated_at": "2026-02-03T12:30:00Z"
+}
+```
+
+**Field Requirements:**
+- `title` (optional): If provided, 1-200 characters, cannot be empty
+- `description` (optional): If provided, 0-2000 characters
+
+**Error Responses:**
+- `400 Bad Request` - Empty title provided
+- `401 Unauthorized` - Invalid or missing token
+- `403 Forbidden` - Task belongs to another user
+- `404 Not Found` - Task does not exist
+
+**Notes:**
+- Only provided fields are updated
+- `updated_at` timestamp is automatically updated
+- Ownership is verified before update
+
+---
+
+### Delete Task
+
+Permanently delete a task.
+
+**Endpoint:** `DELETE /api/tasks/{task_id}`
+
+**Headers:**
+```
+Authorization: Bearer <token>
+```
+
+**Path Parameters:**
+- `task_id` (integer): The task ID
+
+**Response:** `200 OK`
+```json
+{
+  "message": "Task deleted successfully"
+}
+```
+
+**Error Responses:**
+- `401 Unauthorized` - Invalid or missing token
+- `403 Forbidden` - Task belongs to another user
+- `404 Not Found` - Task does not exist
+
+**Notes:**
+- Deletion is permanent (no soft delete)
+- Ownership is verified before deletion
+
+---
+
+### Toggle Task Completion
+
+Toggle a task's completion status (complete ↔ incomplete).
+
+**Endpoint:** `PATCH /api/tasks/{task_id}/complete`
+
+**Headers:**
+```
+Authorization: Bearer <token>
+```
+
+**Path Parameters:**
+- `task_id` (integer): The task ID
+
+**Request Body:** None
+
+**Response:** `200 OK`
+```json
+{
+  "id": 1,
+  "title": "Complete project documentation",
+  "description": "Write comprehensive API docs",
+  "completed": true,
+  "user_id": 1,
+  "created_at": "2026-02-03T10:30:00Z",
+  "updated_at": "2026-02-03T13:00:00Z"
+}
+```
+
+**Behavior:**
+- `completed: false` → `completed: true`
+- `completed: true` → `completed: false`
+
+**Error Responses:**
+- `401 Unauthorized` - Invalid or missing token
+- `403 Forbidden` - Task belongs to another user
+- `404 Not Found` - Task does not exist
+
+**Notes:**
+- `updated_at` timestamp is automatically updated
+- Ownership is verified before toggle
+
+---
+
+## Data Models
+
+### User
+
+```typescript
+{
+  id: number;              // Auto-generated primary key
+  email: string;           // Unique, valid email format
+  password_hash: string;   // Bcrypt hashed password (never exposed in API)
+  created_at: datetime;    // Auto-generated timestamp
+}
+```
+
+### Task
+
+```typescript
+{
+  id: number;              // Auto-generated primary key
+  title: string;           // Required, 1-200 characters
+  description: string | null;  // Optional, 0-2000 characters
+  completed: boolean;      // Default: false
+  user_id: number;         // Foreign key to User (from JWT)
+  created_at: datetime;    // Auto-generated timestamp
+  updated_at: datetime;    // Auto-updated on changes
+}
+```
+
+### JWT Token Payload
+
+```typescript
+{
+  user_id: number;         // User's database ID
+  email: string;           // User's email
+  exp: number;             // Token expiration timestamp
+  iat: number;             // Token issued at timestamp
+}
+```
+
+---
+
+## Error Handling
+
+All errors follow a consistent format:
+
+```json
+{
+  "error": "Detailed error message",
+  "message": "User-friendly message",
+  "details": null
+}
+```
+
+### HTTP Status Codes
+
+| Code | Meaning | When Used |
+|------|---------|-----------|
+| `200` | OK | Successful GET, PUT, PATCH, DELETE |
+| `201` | Created | Successful POST (resource created) |
+| `400` | Bad Request | Invalid input, validation failure |
+| `401` | Unauthorized | Missing or invalid JWT token |
+| `403` | Forbidden | Valid token but insufficient permissions |
+| `404` | Not Found | Resource does not exist |
+| `409` | Conflict | Resource already exists (e.g., duplicate email) |
+| `500` | Internal Server Error | Unexpected server error |
+
+### Common Error Scenarios
+
+**Missing Authentication:**
+```json
+{
+  "error": "Not authenticated",
+  "message": "Authentication is required to access this resource",
+  "details": null
+}
+```
+
+**Invalid Token:**
+```json
+{
+  "error": "Invalid token",
+  "message": "Authentication is required to access this resource",
+  "details": null
+}
+```
+
+**Accessing Another User's Task:**
+```json
+{
+  "error": "You do not have permission to access this task",
+  "message": "You do not have permission to access this resource",
+  "details": null
+}
+```
+
+**Task Not Found:**
+```json
+{
+  "error": "Task not found",
+  "message": "The requested resource was not found",
+  "details": null
+}
+```
+
+**Validation Error:**
+```json
+{
+  "error": "Title is required and cannot be empty",
+  "message": "The request contains invalid data",
+  "details": null
+}
+```
+
+---
+
+## Security
+
+### Authentication Flow
+
+1. **User Registration/Login:**
+   - User provides email and password
+   - Backend validates credentials
+   - Backend generates JWT token with user_id
+   - Token returned to client
+
+2. **Authenticated Requests:**
+   - Client includes token in `Authorization: Bearer <token>` header
+   - Backend verifies token signature
+   - Backend extracts `user_id` from token payload
+   - Backend uses `user_id` for all database queries
+
+### Security Guarantees
+
+✅ **User Identity from JWT Only:**
+- User ID is NEVER accepted from client input
+- All user identification comes from verified JWT token
+- Prevents user impersonation attacks
+
+✅ **Complete Data Isolation:**
+- All database queries filtered by authenticated `user_id`
+- Users cannot view, edit, or delete other users' tasks
+- Ownership verified on every operation
+
+✅ **Password Security:**
+- Passwords hashed with bcrypt before storage
+- Plain-text passwords never stored
+- Password hashes never exposed in API responses
+
+✅ **SQL Injection Prevention:**
+- All queries use SQLModel ORM with parameterization
+- No raw SQL with string concatenation
+
+✅ **CORS Protection:**
+- CORS middleware configured with allowed origins
+- Prevents unauthorized cross-origin requests
+
+### Token Management
+
+**Token Expiration:** 7 days (168 hours)
+
+**Token Format:**
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJlbWFpbCI6InVzZXJAZXhhbXBsZS5jb20iLCJleHAiOjE3MDcwNTI4MDB9.signature
+```
+
+**Token Verification:**
+- Signature verified using `JWT_SECRET`
+- Expiration checked on every request
+- Invalid tokens rejected with 401 Unauthorized
+
+---
+
+## Examples
+
+### Complete Workflow Example
+
+#### 1. Create Account
+
+```bash
+curl -X POST http://localhost:8001/api/auth/signup \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "john@example.com",
+    "password": "SecurePass123"
+  }'
+```
+
+**Response:**
+```json
+{
+  "access_token": "eyJhbGc...",
+  "token_type": "bearer",
+  "user": {
+    "id": 1,
+    "email": "john@example.com"
+  }
+}
+```
+
+#### 2. Create Task
+
+```bash
+curl -X POST http://localhost:8001/api/tasks \
+  -H "Authorization: Bearer eyJhbGc..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Learn FastAPI",
+    "description": "Build a REST API with authentication"
+  }'
+```
+
+**Response:**
+```json
+{
+  "id": 1,
+  "title": "Learn FastAPI",
+  "description": "Build a REST API with authentication",
+  "completed": false,
+  "user_id": 1,
+  "created_at": "2026-02-03T14:00:00Z",
+  "updated_at": "2026-02-03T14:00:00Z"
+}
+```
+
+#### 3. List Tasks
+
+```bash
+curl -X GET http://localhost:8001/api/tasks \
+  -H "Authorization: Bearer eyJhbGc..."
+```
+
+**Response:**
+```json
+[
+  {
+    "id": 1,
+    "title": "Learn FastAPI",
+    "description": "Build a REST API with authentication",
+    "completed": false,
+    "user_id": 1,
+    "created_at": "2026-02-03T14:00:00Z",
+    "updated_at": "2026-02-03T14:00:00Z"
+  }
+]
+```
+
+#### 4. Mark Task Complete
+
+```bash
+curl -X PATCH http://localhost:8001/api/tasks/1/complete \
+  -H "Authorization: Bearer eyJhbGc..."
+```
+
+**Response:**
+```json
+{
+  "id": 1,
+  "title": "Learn FastAPI",
+  "description": "Build a REST API with authentication",
+  "completed": true,
+  "user_id": 1,
+  "created_at": "2026-02-03T14:00:00Z",
+  "updated_at": "2026-02-03T14:30:00Z"
+}
+```
+
+#### 5. Update Task
+
+```bash
+curl -X PUT http://localhost:8001/api/tasks/1 \
+  -H "Authorization: Bearer eyJhbGc..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Master FastAPI",
+    "description": "Build production-ready APIs"
+  }'
+```
+
+#### 6. Delete Task
+
+```bash
+curl -X DELETE http://localhost:8001/api/tasks/1 \
+  -H "Authorization: Bearer eyJhbGc..."
+```
+
+**Response:**
+```json
+{
+  "message": "Task deleted successfully"
+}
+```
+
+---
+
+### JavaScript/TypeScript Example
+
+```typescript
+// API Client Configuration
+const API_BASE_URL = 'http://localhost:8001';
+let authToken: string | null = null;
+
+// Signup
+async function signup(email: string, password: string) {
+  const response = await fetch(`${API_BASE_URL}/api/auth/signup`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, password })
+  });
+
+  const data = await response.json();
+  authToken = data.access_token;
+  return data;
+}
+
+// Create Task
+async function createTask(title: string, description?: string) {
+  const response = await fetch(`${API_BASE_URL}/api/tasks`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${authToken}`
+    },
+    body: JSON.stringify({ title, description })
+  });
+
+  return response.json();
+}
+
+// List Tasks
+async function listTasks() {
+  const response = await fetch(`${API_BASE_URL}/api/tasks`, {
+    headers: {
+      'Authorization': `Bearer ${authToken}`
+    }
+  });
+
+  return response.json();
+}
+
+// Toggle Task Completion
+async function toggleTaskComplete(taskId: number) {
+  const response = await fetch(`${API_BASE_URL}/api/tasks/${taskId}/complete`, {
+    method: 'PATCH',
+    headers: {
+      'Authorization': `Bearer ${authToken}`
+    }
+  });
+
+  return response.json();
+}
+
+// Delete Task
+async function deleteTask(taskId: number) {
+  const response = await fetch(`${API_BASE_URL}/api/tasks/${taskId}`, {
+    method: 'DELETE',
+    headers: {
+      'Authorization': `Bearer ${authToken}`
+    }
+  });
+
+  return response.json();
+}
+```
+
+---
+
+## Testing the API
+
+### Using Swagger UI
+
+FastAPI provides interactive API documentation:
+
+1. Start the backend server
+2. Open browser to: http://localhost:8001/docs
+3. Click "Authorize" button
+4. Enter JWT token from signup/signin response
+5. Test endpoints interactively
+
+### Using Postman
+
+1. Import the API endpoints
+2. Set `Authorization` header: `Bearer <token>`
+3. Set `Content-Type` header: `application/json`
+4. Test each endpoint
+
+### Using curl
+
+See examples above for complete curl commands.
+
+---
+
+## Rate Limiting & Performance
+
+**Current Implementation:**
+- No rate limiting (suitable for development/hackathon)
+- Database connection pooling via Neon PostgreSQL
+- Async/await for non-blocking I/O
+
+**Production Recommendations:**
+- Add rate limiting middleware
+- Implement request caching
+- Add database query optimization
+- Monitor API performance metrics
+
+---
+
+## Support & Troubleshooting
+
+**Common Issues:**
+
+1. **401 Unauthorized on all requests**
+   - Check token is included in Authorization header
+   - Verify token format: `Bearer <token>`
+   - Ensure JWT_SECRET matches between backend and frontend
+
+2. **403 Forbidden when accessing task**
+   - Task belongs to another user
+   - Verify you're using correct user's token
+
+3. **CORS errors from frontend**
+   - Check CORS_ORIGINS in backend .env
+   - Ensure frontend URL is in allowed origins list
+
+4. **Database connection errors**
+   - Verify DATABASE_URL in .env
+   - Check Neon PostgreSQL is accessible
+   - Test connection with database client
+
+---
+
+## API Versioning
+
+**Current Version:** v1.0.0
+
+**Endpoint Prefix:** `/api/`
+
+**Future Versioning Strategy:**
+- Breaking changes will use new prefix: `/api/v2/`
+- Current endpoints will remain stable
+- Deprecation notices will be provided in advance
+
+---
+
+## Changelog
+
+### v1.0.0 (2026-02-03)
+- Initial release
+- User authentication (signup, signin)
+- Task CRUD operations
+- Task completion tracking
+- JWT-based security
+- Complete data isolation
+
+---
+
+**Last Updated:** 2026-02-03
+**Maintained By:** KIro Todo Development Team

Dockerfile

@@ -0,0 +1,32 @@
+# Backend Dockerfile
+FROM python:3.11-slim
+
+# Working directory set karein
+WORKDIR /app
+
+# System dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    postgresql-client \
+    && rm -rf /var/lib/apt/lists/*
+
+# Requirements copy aur install karein
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Baaki saara code copy karein
+COPY . .
+
+# Hugging Face ke liye Permissions (User 1000)
+RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
+USER appuser
+
+# Hugging Face ke liye PORT 7860 lazmi hai
+EXPOSE 7860
+
+# Health check (Port 7860 ke saath)
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+    CMD python -c "import requests; requests.get('http://localhost:7860/health')"
+
+# Run application (Yahan main:app check karlein)
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "7860"]

alembic.ini

@@ -0,0 +1,147 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/alembic
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.  for multiple paths, the path separator
+# is defined by "path_separator" below.
+prepend_sys_path = .
+
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the tzdata library which can be installed by adding
+# `alembic[tz]` to the pip requirements.
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration.  This is also consumed by the user-maintained
+# env.py script only.
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration.

alembic/env.py

@@ -0,0 +1,90 @@
+from logging.config import fileConfig
+import sys
+import os
+
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+
+from alembic import context
+
+# Add parent directory to path to import src modules
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+# Import SQLModel and models
+from sqlmodel import SQLModel
+from src.config import settings
+from src.models import User, Task, Conversation, Message
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Override sqlalchemy.url with DATABASE_URL from environment
+config.set_main_option("sqlalchemy.url", settings.DATABASE_URL)
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+# Use SQLModel metadata for autogenerate
+target_metadata = SQLModel.metadata
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection, target_metadata=target_metadata
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

alembic/versions/78c5de432ae1_add_sequence_number_to_messages_and_.py

@@ -0,0 +1,59 @@
+"""Add sequence_number to messages and create tool_call_logs table
+
+Revision ID: 78c5de432ae1
+Revises: f00ef5a9ad43
+Create Date: 2026-02-04 01:56:44.861631
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '78c5de432ae1'
+down_revision: Union[str, Sequence[str], None] = 'f00ef5a9ad43'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('tool_call_logs',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('message_id', sa.Integer(), nullable=True),
+    sa.Column('conversation_id', sa.Integer(), nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('tool_name', sa.String(length=50), nullable=False),
+    sa.Column('arguments', sa.JSON(), nullable=True),
+    sa.Column('result', sa.JSON(), nullable=True),
+    sa.Column('status', sa.Enum('SUCCESS', 'ERROR', name='toolcallstatus'), nullable=False),
+    sa.Column('execution_time_ms', sa.Integer(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['conversation_id'], ['conversations.id'], ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['message_id'], ['messages.id'], ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_tool_call_logs_conversation_id'), 'tool_call_logs', ['conversation_id'], unique=False)
+    op.create_index(op.f('ix_tool_call_logs_created_at'), 'tool_call_logs', ['created_at'], unique=False)
+    op.create_index(op.f('ix_tool_call_logs_tool_name'), 'tool_call_logs', ['tool_name'], unique=False)
+    op.create_index(op.f('ix_tool_call_logs_user_id'), 'tool_call_logs', ['user_id'], unique=False)
+    op.add_column('messages', sa.Column('sequence_number', sa.Integer(), nullable=False))
+    op.create_index(op.f('ix_messages_sequence_number'), 'messages', ['sequence_number'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_messages_sequence_number'), table_name='messages')
+    op.drop_column('messages', 'sequence_number')
+    op.drop_index(op.f('ix_tool_call_logs_user_id'), table_name='tool_call_logs')
+    op.drop_index(op.f('ix_tool_call_logs_tool_name'), table_name='tool_call_logs')
+    op.drop_index(op.f('ix_tool_call_logs_created_at'), table_name='tool_call_logs')
+    op.drop_index(op.f('ix_tool_call_logs_conversation_id'), table_name='tool_call_logs')
+    op.drop_table('tool_call_logs')
+    # ### end Alembic commands ###

alembic/versions/f00ef5a9ad43_add_conversations_and_messages_tables.py

@@ -0,0 +1,68 @@
+"""Add conversations and messages tables
+
+Revision ID: f00ef5a9ad43
+Revises:
+Create Date: 2026-02-03 11:50:29.285248
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'f00ef5a9ad43'
+down_revision: Union[str, Sequence[str], None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('conversations',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('title', sqlmodel.sql.sqltypes.AutoString(length=200), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.Column('deleted_at', sa.DateTime(), nullable=True),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_conversations_created_at'), 'conversations', ['created_at'], unique=False)
+    op.create_index(op.f('ix_conversations_deleted_at'), 'conversations', ['deleted_at'], unique=False)
+    op.create_index(op.f('ix_conversations_updated_at'), 'conversations', ['updated_at'], unique=False)
+    op.create_index(op.f('ix_conversations_user_id'), 'conversations', ['user_id'], unique=False)
+    op.create_table('messages',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('conversation_id', sa.Integer(), nullable=False),
+    sa.Column('role', sa.Enum('USER', 'ASSISTANT', name='messagerole'), nullable=False),
+    sa.Column('content', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('tool_calls', sa.JSON(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('deleted_at', sa.DateTime(), nullable=True),
+    sa.ForeignKeyConstraint(['conversation_id'], ['conversations.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_messages_conversation_id'), 'messages', ['conversation_id'], unique=False)
+    op.create_index(op.f('ix_messages_created_at'), 'messages', ['created_at'], unique=False)
+    op.create_index(op.f('ix_messages_deleted_at'), 'messages', ['deleted_at'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_messages_deleted_at'), table_name='messages')
+    op.drop_index(op.f('ix_messages_created_at'), table_name='messages')
+    op.drop_index(op.f('ix_messages_conversation_id'), table_name='messages')
+    op.drop_table('messages')
+    op.drop_index(op.f('ix_conversations_user_id'), table_name='conversations')
+    op.drop_index(op.f('ix_conversations_updated_at'), table_name='conversations')
+    op.drop_index(op.f('ix_conversations_deleted_at'), table_name='conversations')
+    op.drop_index(op.f('ix_conversations_created_at'), table_name='conversations')
+    op.drop_table('conversations')
+    # ### end Alembic commands ###

requirements.txt

@@ -0,0 +1,12 @@
+fastapi
+uvicorn[standard]
+sqlmodel
+psycopg2-binary
+python-jose[cryptography]
+passlib[bcrypt]
+python-dotenv
+pydantic-settings
+alembic
+cohere
+mcp
+sqlalchemy

src/agents/__init__.py

@@ -0,0 +1,10 @@
+"""
+Agents package for AI-powered task management.
+
+This package contains the TaskAgent class and configuration for
+handling natural language task management conversations.
+"""
+from .task_agent import TaskAgent
+from .agent_config import TASK_AGENT_SYSTEM_PROMPT, AGENT_CONFIG, TOOL_CONFIG
+
+__all__ = ["TaskAgent", "TASK_AGENT_SYSTEM_PROMPT", "AGENT_CONFIG", "TOOL_CONFIG"]

src/agents/agent_config.py

@@ -0,0 +1,83 @@
+"""
+Agent configuration including system prompts and behavior settings.
+
+This module defines the AI agent's personality, capabilities, and instructions.
+"""
+
+# System prompt for the task management agent
+TASK_AGENT_SYSTEM_PROMPT = """You are a helpful task management assistant for KIro Todo application.
+
+Your role is to help users manage their tasks through natural language conversation. You have access to the following tools:
+
+1. **list_tasks** - View all tasks (with optional filtering by completion status)
+2. **create_task** - Create a new task with title and optional description
+3. **update_task** - Modify an existing task's title or description
+4. **delete_task** - Permanently remove a task
+5. **get_task** - Retrieve details of a specific task by ID
+6. **mark_complete** - Toggle task completion status or set to specific value
+
+## Guidelines:
+
+### Communication Style
+- Be friendly, concise, and helpful
+- Use natural conversational language
+- Confirm actions clearly (e.g., "I've created the task 'Buy groceries'")
+- Ask for clarification when user intent is ambiguous
+
+### Task Operations
+- When creating tasks, extract the title from the user's message
+- Include descriptions if the user provides additional details
+- For updates and deletions, you may need to list tasks first to find the correct task ID
+- Always confirm destructive operations (like delete) with clear feedback
+- Present task lists in a readable format
+
+### Error Handling
+- If a tool call fails, explain the issue in user-friendly terms
+- Suggest alternatives when operations cannot be completed
+- Never expose technical details or error codes to users
+
+### User Privacy
+- You can only access tasks belonging to the authenticated user
+- Never mention or reference other users' data
+- All operations are automatically scoped to the current user
+
+### Examples:
+
+**User**: "Show me my tasks"
+**You**: Use list_tasks tool, then present results like:
+"Here are your tasks:
+1. Buy groceries (incomplete)
+2. Call mom (incomplete)
+3. Finish report (completed)"
+
+**User**: "Add a task to buy milk"
+**You**: Use create_task with title="Buy milk", then confirm:
+"I've created the task 'Buy milk' for you."
+
+**User**: "Mark task 1 as done"
+**You**: Use mark_complete with task_id=1, completed=true, then confirm:
+"Great! I've marked 'Buy groceries' as complete."
+
+**User**: "Delete the milk task"
+**You**: Use list_tasks to find the task ID, then delete_task, then confirm:
+"I've deleted the task 'Buy milk'."
+
+Remember: Always be helpful, clear, and confirm your actions!
+"""
+
+# Agent configuration settings
+AGENT_CONFIG = {
+    "model": None,  # Will be set from settings.OPENAI_MODEL
+    "temperature": 0.7,  # Balanced between creativity and consistency
+    "max_tokens": 500,  # Reasonable response length
+    "top_p": 1.0,
+    "frequency_penalty": 0.0,
+    "presence_penalty": 0.0,
+}
+
+# Tool execution settings
+TOOL_CONFIG = {
+    "max_retries": 2,  # Retry failed tool calls up to 2 times
+    "timeout_seconds": 10,  # Tool execution timeout
+    "log_all_calls": True,  # Log all tool invocations for audit
+}

src/agents/task_agent.py

@@ -0,0 +1,203 @@
+"""
+TaskAgent class for handling AI-powered task management conversations.
+
+This module implements the core agent that processes user messages and
+executes task operations through MCP tools.
+"""
+from openai import AsyncOpenAI
+from typing import List, Dict, Any, Optional
+from ..config import settings
+from .agent_config import TASK_AGENT_SYSTEM_PROMPT, AGENT_CONFIG
+
+
+class TaskAgent:
+    """
+    AI agent for task management conversations.
+
+    This agent uses OpenAI's API (or OpenRouter) with function calling to process natural
+    language requests and execute task operations through MCP tools.
+    """
+
+    def __init__(self):
+        """
+        Initialize the TaskAgent with OpenAI client.
+
+        The agent is configured with:
+        - OpenAI API key from settings (can be OpenRouter key)
+        - System prompt defining agent behavior
+        - Model configuration (temperature, max_tokens, etc.)
+        - Empty tools list (tools registered later via register_tools)
+        """
+        # Configure client for OpenRouter if base URL is provided
+        client_kwargs = {"api_key": settings.OPENAI_API_KEY}
+        if hasattr(settings, 'OPENAI_BASE_URL') and settings.OPENAI_BASE_URL:
+            client_kwargs["base_url"] = settings.OPENAI_BASE_URL
+
+        self.client = AsyncOpenAI(**client_kwargs)
+        self.model = settings.OPENAI_MODEL
+        self.system_prompt = TASK_AGENT_SYSTEM_PROMPT
+        self.temperature = AGENT_CONFIG["temperature"]
+        self.max_tokens = AGENT_CONFIG["max_tokens"]
+        self.tools: List[Dict[str, Any]] = []
+
+    def register_tools(self, tools: List[Dict[str, Any]]) -> None:
+        """
+        Register MCP tools with the agent.
+
+        Tools should be in OpenAI function calling format:
+        {
+            "type": "function",
+            "function": {
+                "name": "tool_name",
+                "description": "Tool description",
+                "parameters": {...}
+            }
+        }
+
+        Args:
+            tools: List of tool definitions in OpenAI format
+        """
+        self.tools = tools
+
+    async def process_message(
+        self,
+        message: str,
+        conversation_history: List[Dict[str, str]],
+        tool_executor: Optional[Any] = None
+    ) -> Dict[str, Any]:
+        """
+        Process a user message and generate a response.
+
+        This method:
+        1. Constructs the full message history with system prompt
+        2. Calls OpenAI API with tool definitions
+        3. Handles tool calls if the agent decides to use them
+        4. Returns the final response with any tool call metadata
+
+        Args:
+            message: The user's message to process
+            conversation_history: Previous messages in the conversation
+                Format: [{"role": "user"|"assistant", "content": "..."}]
+            tool_executor: Optional callable to execute tool calls
+                Should accept (tool_name, arguments) and return result
+
+        Returns:
+            Dict containing:
+                - content: The assistant's response text
+                - tool_calls: List of tool calls made (if any)
+                - finish_reason: Why the model stopped generating
+
+        Raises:
+            Exception: If OpenAI API call fails
+        """
+        # Build messages array with system prompt
+        messages = [
+            {"role": "system", "content": self.system_prompt}
+        ]
+
+        # Add conversation history
+        messages.extend(conversation_history)
+
+        # Add current user message
+        messages.append({"role": "user", "content": message})
+
+        # Call OpenAI API
+        response = await self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            tools=self.tools if self.tools else None,
+            temperature=self.temperature,
+            max_tokens=self.max_tokens
+        )
+
+        # Extract response
+        assistant_message = response.choices[0].message
+
+        # Handle tool calls if present
+        tool_calls_data = []
+        if assistant_message.tool_calls and tool_executor:
+            for tool_call in assistant_message.tool_calls:
+                tool_name = tool_call.function.name
+                tool_args = tool_call.function.arguments
+
+                # Execute tool
+                try:
+                    import json
+                    args_dict = json.loads(tool_args)
+                    result = await tool_executor(tool_name, args_dict)
+
+                    tool_calls_data.append({
+                        "id": tool_call.id,
+                        "name": tool_name,
+                        "arguments": args_dict,
+                        "result": result
+                    })
+                except Exception as e:
+                    tool_calls_data.append({
+                        "id": tool_call.id,
+                        "name": tool_name,
+                        "arguments": tool_args,
+                        "error": str(e)
+                    })
+
+            # If tools were called, make another API call with tool results
+            # to get the final response
+            messages.append({
+                "role": "assistant",
+                "content": assistant_message.content,
+                "tool_calls": [
+                    {
+                        "id": tc["id"],
+                        "type": "function",
+                        "function": {
+                            "name": tc["name"],
+                            "arguments": json.dumps(tc["arguments"])
+                        }
+                    }
+                    for tc in tool_calls_data
+                ]
+            })
+
+            # Add tool results
+            for tc in tool_calls_data:
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tc["id"],
+                    "content": json.dumps(tc.get("result", {"error": tc.get("error")}))
+                })
+
+            # Get final response
+            final_response = await self.client.chat.completions.create(
+                model=self.model,
+                messages=messages,
+                temperature=self.temperature,
+                max_tokens=self.max_tokens
+            )
+
+            final_message = final_response.choices[0].message
+
+            return {
+                "content": final_message.content,
+                "tool_calls": tool_calls_data,
+                "finish_reason": final_response.choices[0].finish_reason
+            }
+
+        # No tool calls - return direct response
+        return {
+            "content": assistant_message.content,
+            "tool_calls": [],
+            "finish_reason": response.choices[0].finish_reason
+        }
+
+    async def health_check(self) -> bool:
+        """
+        Verify the agent can communicate with OpenAI API.
+
+        Returns:
+            True if API is accessible, False otherwise
+        """
+        try:
+            await self.client.models.retrieve(self.model)
+            return True
+        except Exception:
+            return False

src/api/__init__.py

@@ -0,0 +1,6 @@
+"""API routers package."""
+from .tasks import router as tasks_router
+from .auth import router as auth_router
+from .chat import router as chat_router
+
+__all__ = ["tasks_router", "auth_router", "chat_router"]

src/api/auth.py

@@ -0,0 +1,140 @@
+from fastapi import APIRouter, HTTPException, status, Depends
+from pydantic import BaseModel, EmailStr
+from sqlmodel import Session, select
+from passlib.context import CryptContext
+from jose import jwt
+from datetime import datetime, timedelta
+from ..models.user import User
+from ..database import get_session
+from ..config import settings
+
+router = APIRouter(prefix="/api/auth", tags=["Authentication"])
+
+# Password hashing
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+class SignupRequest(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class SigninRequest(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class AuthResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+    user: dict
+
+
+def hash_password(password: str) -> str:
+    """Hash a password using bcrypt."""
+    return pwd_context.hash(password)
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash."""
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def create_access_token(user_id: int, email: str) -> str:
+    """Create a JWT access token."""
+    expire = datetime.utcnow() + timedelta(hours=settings.JWT_EXPIRATION_HOURS)
+    to_encode = {
+        "sub": str(user_id),
+        "email": email,
+        "exp": expire
+    }
+    encoded_jwt = jwt.encode(to_encode, settings.JWT_SECRET, algorithm=settings.JWT_ALGORITHM)
+    return encoded_jwt
+
+
+@router.post("/signup", response_model=AuthResponse)
+async def signup(
+    request: SignupRequest,
+    session: Session = Depends(get_session)
+):
+    """
+    Register a new user.
+
+    - Validates email uniqueness
+    - Hashes password
+    - Creates user in database
+    - Returns JWT token
+    """
+    # Check if user already exists
+    existing_user = session.exec(
+        select(User).where(User.email == request.email)
+    ).first()
+
+    if existing_user:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Email already registered"
+        )
+
+    # Create new user
+    hashed_password = hash_password(request.password)
+    new_user = User(
+        email=request.email,
+        password_hash=hashed_password
+    )
+
+    session.add(new_user)
+    session.commit()
+    session.refresh(new_user)
+
+    # Create access token
+    access_token = create_access_token(new_user.id, new_user.email)
+
+    return AuthResponse(
+        access_token=access_token,
+        user={
+            "id": new_user.id,
+            "email": new_user.email
+        }
+    )
+
+
+@router.post("/signin", response_model=AuthResponse)
+async def signin(
+    request: SigninRequest,
+    session: Session = Depends(get_session)
+):
+    """
+    Authenticate a user.
+
+    - Validates credentials
+    - Returns JWT token
+    """
+    # Find user by email
+    user = session.exec(
+        select(User).where(User.email == request.email)
+    ).first()
+
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid email or password"
+        )
+
+    # Verify password
+    if not verify_password(request.password, user.password_hash):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid email or password"
+        )
+
+    # Create access token
+    access_token = create_access_token(user.id, user.email)
+
+    return AuthResponse(
+        access_token=access_token,
+        user={
+            "id": user.id,
+            "email": user.email
+        }
+    )

src/api/chat.py

@@ -0,0 +1,563 @@
+"""
+Chat API Router
+
+Provides conversational task management through natural language.
+Users send messages, and the AI agent responds with task operations via MCP tools.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, status, Request, Response
+from fastapi.responses import StreamingResponse
+from sqlmodel import Session, select
+from typing import Dict, AsyncGenerator
+from datetime import datetime
+import json
+import logging
+
+from ..database import get_session
+from ..middleware.auth import get_current_user
+from ..middleware.rate_limit import rate_limit_middleware
+from ..models.conversation import Conversation
+from ..models.message import Message, MessageRole
+from ..schemas.chat import ChatRequest, ChatResponse
+from ..services.agent_service import AgentService
+
+
+# Configure logger
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api", tags=["Chat"])
+
+
+@router.post("/{user_id}/chat", response_model=ChatResponse, status_code=status.HTTP_200_OK)
+async def chat(
+    user_id: int,
+    chat_request: ChatRequest,
+    http_request: Request,
+    response: Response,
+    session: Session = Depends(get_session),
+    current_user: Dict = Depends(get_current_user)
+):
+    """
+    Process conversational task management request.
+
+    This endpoint:
+    1. Verifies JWT authentication and user_id match
+    2. Loads or creates conversation
+    3. Saves user message to database
+    4. Processes message with AI agent
+    5. Saves assistant response to database
+    6. Returns response with tool call metadata
+
+    Args:
+        user_id: User identifier from URL (must match JWT)
+        request: ChatRequest with message and optional conversation_id
+        session: Database session dependency
+        current_user: Authenticated user from JWT token
+
+    Returns:
+        ChatResponse with conversation_id, message_id, assistant_message, and tool_calls
+
+    Raises:
+        HTTPException 400: Invalid message format
+        HTTPException 401: Missing or invalid JWT token
+        HTTPException 403: User_id mismatch or unauthorized conversation access
+        HTTPException 404: Conversation not found
+        HTTPException 500: Agent processing failure
+    """
+    # Log incoming chat request
+    logger.info(
+        f"Chat request received - user_id={user_id}, "
+        f"conversation_id={chat_request.conversation_id}, "
+        f"message_length={len(chat_request.message)}"
+    )
+
+    # Apply rate limiting
+    await rate_limit_middleware(http_request, user_id)
+
+    # Verify user_id matches JWT token
+    if current_user["user_id"] != user_id:
+        logger.warning(
+            f"Authorization failed - URL user_id={user_id} does not match "
+            f"JWT user_id={current_user['user_id']}"
+        )
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Permission denied",
+            headers={"X-Error-Details": "URL user_id does not match authenticated user"}
+        )
+
+    # Validate and sanitize message content
+    try:
+        from ..utils.validation import sanitize_message_content, validate_conversation_id
+        sanitized_message = sanitize_message_content(chat_request.message)
+        validated_conversation_id = validate_conversation_id(chat_request.conversation_id)
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+    # Load or create conversation
+    conversation = None
+    if chat_request.conversation_id:
+        # Load existing conversation
+        logger.debug(f"Loading existing conversation_id={chat_request.conversation_id}")
+        conversation = session.get(Conversation, chat_request.conversation_id)
+
+        # Verify conversation exists
+        if not conversation:
+            logger.warning(f"Conversation not found - conversation_id={chat_request.conversation_id}")
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Conversation not found",
+                headers={"X-Error-Details": f"conversation_id {chat_request.conversation_id} does not exist"}
+            )
+
+        # Verify conversation belongs to authenticated user
+        if conversation.user_id != user_id:
+            logger.warning(
+                f"Unauthorized conversation access - conversation_id={chat_request.conversation_id}, "
+                f"owner_id={conversation.user_id}, requester_id={user_id}"
+            )
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Permission denied",
+                headers={"X-Error-Details": "Conversation belongs to different user"}
+            )
+
+        # Check if conversation is soft-deleted
+        if conversation.deleted_at is not None:
+            logger.warning(f"Attempted access to deleted conversation_id={chat_request.conversation_id}")
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Conversation not found",
+                headers={"X-Error-Details": "Conversation was deleted"}
+            )
+
+        logger.info(f"Loaded existing conversation_id={conversation.id}")
+    else:
+        # Create new conversation
+        logger.info(f"Creating new conversation for user_id={user_id}")
+        conversation = Conversation(
+            user_id=user_id,
+            title=None,  # Can be auto-generated from first message later
+            created_at=datetime.utcnow(),
+            updated_at=datetime.utcnow()
+        )
+        session.add(conversation)
+        session.commit()
+        session.refresh(conversation)
+        logger.info(f"Created new conversation_id={conversation.id}")
+
+    # Calculate sequence number for the new message
+    message_count_stmt = select(Message).where(
+        Message.conversation_id == conversation.id,
+        Message.deleted_at.is_(None)
+    )
+    existing_message_count = len(session.exec(message_count_stmt).all())
+    next_sequence_number = existing_message_count + 1
+
+    # Save user message to database (before agent processing)
+    logger.debug(f"Persisting user message to conversation_id={conversation.id}, sequence={next_sequence_number}")
+    user_message = Message(
+        conversation_id=conversation.id,
+        role=MessageRole.USER,
+        content=chat_request.message,
+        tool_calls=None,
+        sequence_number=next_sequence_number,
+        created_at=datetime.utcnow()
+    )
+    session.add(user_message)
+    session.commit()
+    session.refresh(user_message)
+    logger.debug(f"User message persisted - message_id={user_message.id}")
+
+    # Load conversation history for agent context (last 20 messages for performance)
+    statement = (
+        select(Message)
+        .where(Message.conversation_id == conversation.id)
+        .where(Message.deleted_at.is_(None))
+        .order_by(Message.created_at.desc())
+        .limit(20)
+    )
+    history_messages = session.exec(statement).all()
+
+    # Reverse to get chronological order (oldest to newest)
+    history_messages = list(reversed(history_messages))
+
+    # Initialize agent service with user_id
+    agent_service = AgentService(user_id=user_id)
+
+    # Format conversation history for agent
+    conversation_history = agent_service.format_conversation_history(history_messages)
+
+    # Process message with agent (with timeout)
+    import asyncio
+    logger.info(
+        f"Processing message with agent - conversation_id={conversation.id}, "
+        f"history_length={len(conversation_history)}"
+    )
+
+    try:
+        agent_response = await asyncio.wait_for(
+            agent_service.process_message(
+                message=sanitized_message,
+                conversation_history=conversation_history[:-1]  # Exclude the just-added user message
+            ),
+            timeout=30.0  # 30 second timeout
+        )
+
+        logger.info(
+            f"Agent processing completed - conversation_id={conversation.id}, "
+            f"tool_calls={len(agent_response.get('tool_calls', []) or [])}"
+        )
+
+    except asyncio.TimeoutError:
+        logger.error(
+            f"Agent processing timeout - conversation_id={conversation.id}, "
+            f"exceeded 30 second limit"
+        )
+        raise HTTPException(
+            status_code=status.HTTP_504_GATEWAY_TIMEOUT,
+            detail="Agent processing timeout - request took longer than 30 seconds"
+        )
+    except Exception as e:
+        # Log error and return 500 with user-friendly message
+        logger.error(
+            f"Agent processing error - conversation_id={conversation.id}, "
+            f"error={str(e)}",
+            exc_info=True
+        )
+
+        # User-friendly error messages for common OpenAI API failures
+        error_message = "Agent processing failed"
+        if "rate_limit" in str(e).lower():
+            error_message = "AI service is currently busy. Please try again in a moment."
+        elif "api_key" in str(e).lower() or "authentication" in str(e).lower():
+            error_message = "AI service configuration error. Please contact support."
+        elif "timeout" in str(e).lower():
+            error_message = "AI service is taking too long to respond. Please try again."
+        elif "connection" in str(e).lower():
+            error_message = "Unable to connect to AI service. Please try again."
+
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=error_message,
+            headers={"X-Error-Details": str(e)}
+        )
+
+    # Calculate sequence number for assistant response
+    assistant_sequence_number = next_sequence_number + 1
+
+    # Save assistant response to database (after agent processing)
+    logger.debug(f"Persisting assistant response to conversation_id={conversation.id}, sequence={assistant_sequence_number}")
+    assistant_message = Message(
+        conversation_id=conversation.id,
+        role=MessageRole.ASSISTANT,
+        content=agent_response.get("content", ""),
+        tool_calls=agent_response.get("tool_calls"),
+        sequence_number=assistant_sequence_number,
+        created_at=datetime.utcnow()
+    )
+    session.add(assistant_message)
+
+    # Update conversation timestamp
+    conversation.updated_at = datetime.utcnow()
+    session.add(conversation)
+
+    session.commit()
+    session.refresh(assistant_message)
+    logger.debug(f"Assistant response persisted - message_id={assistant_message.id}")
+
+    # Add rate limit headers to response
+    if hasattr(http_request, 'state') and hasattr(http_request.state, 'rate_limit_headers'):
+        for header_name, header_value in http_request.state.rate_limit_headers.items():
+            response.headers[header_name] = header_value
+
+    # Build response
+    logger.info(
+        f"Chat request completed successfully - conversation_id={conversation.id}, "
+        f"message_id={assistant_message.id}, user_id={user_id}"
+    )
+
+    return ChatResponse(
+        conversation_id=conversation.id,
+        message_id=assistant_message.id,
+        assistant_message=agent_response.get("content", ""),
+        tool_calls=agent_response.get("tool_calls"),
+        timestamp=assistant_message.created_at
+    )
+
+
+@router.post("/{user_id}/chat/stream")
+async def chat_stream(
+    user_id: int,
+    request: ChatRequest,
+    session: Session = Depends(get_session),
+    current_user: Dict = Depends(get_current_user)
+):
+    """
+    Stream chat response with Server-Sent Events (SSE).
+
+    Provides progressive response rendering for better user experience.
+    Streams agent response in chunks as it's generated.
+
+    Args:
+        user_id: User identifier from URL (must match JWT)
+        request: Chat request with message and optional conversation_id
+        session: Database session dependency
+        current_user: Authenticated user from JWT token
+
+    Returns:
+        StreamingResponse with text/event-stream content type
+
+    Raises:
+        HTTPException 400: Invalid message format
+        HTTPException 401: Missing or invalid JWT token
+        HTTPException 403: User_id mismatch or unauthorized conversation access
+        HTTPException 404: Conversation not found
+        HTTPException 500: Agent processing failure
+    """
+    # Verify user_id matches JWT token
+    if current_user["user_id"] != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Permission denied"
+        )
+
+    async def event_generator() -> AsyncGenerator[str, None]:
+        """Generate SSE events for streaming response."""
+        try:
+            # Load or create conversation (same logic as non-streaming endpoint)
+            conversation = None
+            if request.conversation_id:
+                conversation = session.get(Conversation, request.conversation_id)
+                if not conversation or conversation.user_id != user_id:
+                    yield f"data: {json.dumps({'error': 'Conversation not found', 'done': True})}\n\n"
+                    return
+                if conversation.deleted_at is not None:
+                    yield f"data: {json.dumps({'error': 'Conversation was deleted', 'done': True})}\n\n"
+                    return
+            else:
+                conversation = Conversation(
+                    user_id=user_id,
+                    title=None,
+                    created_at=datetime.utcnow(),
+                    updated_at=datetime.utcnow()
+                )
+                session.add(conversation)
+                session.commit()
+                session.refresh(conversation)
+
+            # Calculate sequence number
+            message_count_stmt = select(Message).where(
+                Message.conversation_id == conversation.id,
+                Message.deleted_at.is_(None)
+            )
+            existing_message_count = len(session.exec(message_count_stmt).all())
+            user_seq = existing_message_count + 1
+
+            # Save user message
+            user_message = Message(
+                conversation_id=conversation.id,
+                role=MessageRole.USER,
+                content=request.message,
+                tool_calls=None,
+                sequence_number=user_seq,
+                created_at=datetime.utcnow()
+            )
+            session.add(user_message)
+            session.commit()
+
+            # Load conversation history
+            statement = (
+                select(Message)
+                .where(Message.conversation_id == conversation.id)
+                .where(Message.deleted_at.is_(None))
+                .order_by(Message.created_at.desc())
+                .limit(20)
+            )
+            history_messages = session.exec(statement).all()
+            history_messages = list(reversed(history_messages))
+
+            # Initialize agent service
+            agent_service = CohereAgentService(user_id=user_id)
+            conversation_history = agent_service.format_conversation_history(history_messages)
+
+            # Process message with agent
+            agent_response = await agent_service.process_message(
+                message=request.message,
+                conversation_history=conversation_history[:-1]
+            )
+
+            # Stream response content in chunks
+            content = agent_response.get("content", "")
+            chunk_size = 10  # Characters per chunk
+
+            for i in range(0, len(content), chunk_size):
+                chunk = content[i:i + chunk_size]
+                yield f"data: {json.dumps({'content': chunk, 'done': False})}\n\n"
+
+            # Save assistant response
+            assistant_message = Message(
+                conversation_id=conversation.id,
+                role=MessageRole.ASSISTANT,
+                content=content,
+                tool_calls=agent_response.get("tool_calls"),
+                sequence_number=user_seq + 1,
+                created_at=datetime.utcnow()
+            )
+            session.add(assistant_message)
+
+            # Update conversation timestamp
+            conversation.updated_at = datetime.utcnow()
+            session.add(conversation)
+            session.commit()
+            session.refresh(assistant_message)
+
+            # Send final event with metadata
+            final_data = {
+                "done": True,
+                "conversation_id": conversation.id,
+                "message_id": assistant_message.id,
+                "tool_calls": agent_response.get("tool_calls"),
+                "timestamp": assistant_message.created_at.isoformat()
+            }
+            yield f"data: {json.dumps(final_data)}\n\n"
+
+        except Exception as e:
+            # Stream error event
+            error_data = {
+                "error": str(e),
+                "done": True
+            }
+            yield f"data: {json.dumps(error_data)}\n\n"
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",  # Disable nginx buffering
+        }
+    )
+
+
+@router.get("/{user_id}/conversations", status_code=status.HTTP_200_OK)
+async def list_conversations(
+    user_id: int,
+    session: Session = Depends(get_session),
+    current_user: Dict = Depends(get_current_user)
+):
+    """
+    List all conversations for authenticated user.
+
+    Returns conversations ordered by most recently updated.
+    Excludes soft-deleted conversations.
+
+    Args:
+        user_id: User identifier from URL (must match JWT)
+        session: Database session dependency
+        current_user: Authenticated user from JWT token
+
+    Returns:
+        List of conversations with metadata
+
+    Raises:
+        HTTPException 403: User_id mismatch
+    """
+    # Verify user_id matches JWT token
+    if current_user["user_id"] != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Permission denied"
+        )
+
+    # Query conversations for user
+    statement = (
+        select(Conversation)
+        .where(Conversation.user_id == user_id)
+        .where(Conversation.deleted_at.is_(None))
+        .order_by(Conversation.updated_at.desc())
+    )
+    conversations = session.exec(statement).all()
+
+    return {
+        "conversations": [
+            {
+                "id": conv.id,
+                "title": conv.title,
+                "created_at": conv.created_at,
+                "updated_at": conv.updated_at
+            }
+            for conv in conversations
+        ],
+        "total": len(conversations)
+    }
+
+
+@router.get("/{user_id}/conversations/{conversation_id}/messages", status_code=status.HTTP_200_OK)
+async def get_conversation_messages(
+    user_id: int,
+    conversation_id: int,
+    session: Session = Depends(get_session),
+    current_user: Dict = Depends(get_current_user)
+):
+    """
+    Get all messages in a conversation.
+
+    Returns messages ordered chronologically.
+    Excludes soft-deleted messages.
+
+    Args:
+        user_id: User identifier from URL (must match JWT)
+        conversation_id: Conversation identifier
+        session: Database session dependency
+        current_user: Authenticated user from JWT token
+
+    Returns:
+        List of messages with metadata
+
+    Raises:
+        HTTPException 403: User_id mismatch or unauthorized conversation access
+        HTTPException 404: Conversation not found
+    """
+    # Verify user_id matches JWT token
+    if current_user["user_id"] != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Permission denied"
+        )
+
+    # Load conversation and verify ownership
+    conversation = session.get(Conversation, conversation_id)
+    if not conversation or conversation.user_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Conversation not found"
+        )
+
+    # Query messages
+    statement = (
+        select(Message)
+        .where(Message.conversation_id == conversation_id)
+        .where(Message.deleted_at.is_(None))
+        .order_by(Message.created_at.asc())
+    )
+    messages = session.exec(statement).all()
+
+    return {
+        "conversation_id": conversation_id,
+        "messages": [
+            {
+                "id": msg.id,
+                "role": msg.role.value,
+                "content": msg.content,
+                "tool_calls": msg.tool_calls,
+                "created_at": msg.created_at
+            }
+            for msg in messages
+        ],
+        "total": len(messages)
+    }

src/api/dependencies.py

@@ -0,0 +1,81 @@
+"""
+FastAPI dependencies for authentication and authorization.
+
+This module provides reusable dependency functions for route handlers.
+"""
+from fastapi import Depends, HTTPException, status
+from sqlmodel import Session, select
+from typing import Dict
+from ..middleware.auth import get_current_user
+from ..models.user import User
+from ..database import get_session
+
+
+async def verify_jwt(
+    current_user: Dict[str, any] = Depends(get_current_user)
+) -> Dict[str, any]:
+    """
+    Verify JWT token and return authenticated user information.
+
+    This dependency can be injected into route handlers to ensure
+    the request is authenticated. It extracts user_id and email
+    from the verified JWT token.
+
+    Usage:
+        @app.get("/api/protected")
+        async def protected_route(user: Dict = Depends(verify_jwt)):
+            user_id = user["user_id"]
+            email = user["email"]
+            # ... route logic
+
+    Args:
+        current_user: User info from JWT token (injected by get_current_user)
+
+    Returns:
+        Dict containing user_id and email from token payload
+
+    Raises:
+        HTTPException: 401 if token is invalid or expired
+    """
+    return current_user
+
+
+async def get_current_user_from_db(
+    current_user: Dict[str, any] = Depends(get_current_user),
+    session: Session = Depends(get_session)
+) -> User:
+    """
+    Verify JWT token and fetch full User model from database.
+
+    This dependency verifies the JWT token and then fetches the
+    complete User object from the database. Use this when you need
+    access to the full user model with relationships.
+
+    Usage:
+        @app.get("/api/profile")
+        async def get_profile(user: User = Depends(get_current_user_from_db)):
+            return {"email": user.email, "created_at": user.created_at}
+
+    Args:
+        current_user: User info from JWT token (injected by get_current_user)
+        session: Database session
+
+    Returns:
+        User model instance from database
+
+    Raises:
+        HTTPException: 401 if token is invalid or 404 if user not found
+    """
+    user_id = current_user["user_id"]
+
+    # Fetch user from database
+    statement = select(User).where(User.id == user_id)
+    user = session.exec(statement).first()
+
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+
+    return user

src/api/tasks.py

@@ -0,0 +1,240 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlmodel import Session, select
+from typing import List, Dict
+from datetime import datetime
+
+from ..database import get_session
+from ..middleware.auth import get_current_user
+from ..models.task import Task
+from ..schemas.task import TaskCreate, TaskUpdate, TaskResponse
+
+
+router = APIRouter(prefix="/api/tasks", tags=["Tasks"])
+
+
+@router.get("", response_model=List[TaskResponse], status_code=status.HTTP_200_OK)
+async def list_tasks(
+    session: Session = Depends(get_session),
+    current_user: Dict = Depends(get_current_user)
+):
+    """
+    List all tasks for authenticated user.
+
+    Returns all tasks owned by the authenticated user, ordered by creation date (newest first).
+    User identity is extracted from JWT token.
+    """
+    user_id = current_user["user_id"]
+
+    # Query tasks filtered by authenticated user_id
+    statement = select(Task).where(Task.user_id == user_id).order_by(Task.created_at.desc())
+    tasks = session.exec(statement).all()
+
+    return tasks
+
+
+@router.post("", response_model=TaskResponse, status_code=status.HTTP_201_CREATED)
+async def create_task(
+    task_data: TaskCreate,
+    session: Session = Depends(get_session),
+    current_user: Dict = Depends(get_current_user)
+):
+    """
+    Create a new task for authenticated user.
+
+    User ID is extracted from JWT token, never from client input.
+    Task starts with completed=False by default.
+    """
+    user_id = current_user["user_id"]
+
+    # Validate title is not empty (Pydantic handles this, but double-check)
+    if not task_data.title or task_data.title.strip() == "":
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Title is required and cannot be empty"
+        )
+
+    # Create task with user_id from JWT (never from client)
+    task = Task(
+        title=task_data.title,
+        description=task_data.description,
+        completed=False,  # Always start as incomplete
+        user_id=user_id,  # Set from JWT token
+        created_at=datetime.utcnow(),
+        updated_at=datetime.utcnow()
+    )
+
+    session.add(task)
+    session.commit()
+    session.refresh(task)
+
+    return task
+
+
+@router.get("/{task_id}", response_model=TaskResponse, status_code=status.HTTP_200_OK)
+async def get_task(
+    task_id: int,
+    session: Session = Depends(get_session),
+    current_user: Dict = Depends(get_current_user)
+):
+    """
+    Get a specific task by ID.
+
+    User must own the task. Returns 403 if task belongs to another user.
+    Returns 404 if task doesn't exist.
+    """
+    user_id = current_user["user_id"]
+
+    # Fetch task by ID
+    task = session.get(Task, task_id)
+
+    # Return 404 if task not found
+    if not task:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Task not found"
+        )
+
+    # Verify ownership - return 403 if user doesn't own this task
+    if task.user_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not have permission to access this task"
+        )
+
+    return task
+
+
+@router.put("/{task_id}", response_model=TaskResponse, status_code=status.HTTP_200_OK)
+async def update_task(
+    task_id: int,
+    task_data: TaskUpdate,
+    session: Session = Depends(get_session),
+    current_user: Dict = Depends(get_current_user)
+):
+    """
+    Update an existing task.
+
+    User must own the task. Only provided fields are updated.
+    Updates the updated_at timestamp automatically.
+    """
+    user_id = current_user["user_id"]
+
+    # Fetch task by ID
+    task = session.get(Task, task_id)
+
+    # Return 404 if task not found
+    if not task:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Task not found"
+        )
+
+    # Verify ownership - return 403 if user doesn't own this task
+    if task.user_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not have permission to update this task"
+        )
+
+    # Update only provided fields
+    update_data = task_data.model_dump(exclude_unset=True)
+
+    # Validate title if provided
+    if "title" in update_data and (not update_data["title"] or update_data["title"].strip() == ""):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Title cannot be empty"
+        )
+
+    for field, value in update_data.items():
+        setattr(task, field, value)
+
+    # Update timestamp
+    task.updated_at = datetime.utcnow()
+
+    session.add(task)
+    session.commit()
+    session.refresh(task)
+
+    return task
+
+
+@router.delete("/{task_id}", status_code=status.HTTP_200_OK)
+async def delete_task(
+    task_id: int,
+    session: Session = Depends(get_session),
+    current_user: Dict = Depends(get_current_user)
+):
+    """
+    Delete a task permanently.
+
+    User must own the task. Returns success message on deletion.
+    """
+    user_id = current_user["user_id"]
+
+    # Fetch task by ID
+    task = session.get(Task, task_id)
+
+    # Return 404 if task not found
+    if not task:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Task not found"
+        )
+
+    # Verify ownership - return 403 if user doesn't own this task
+    if task.user_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not have permission to delete this task"
+        )
+
+    # Delete task
+    session.delete(task)
+    session.commit()
+
+    return {"message": "Task deleted successfully"}
+
+
+@router.patch("/{task_id}/complete", response_model=TaskResponse, status_code=status.HTTP_200_OK)
+async def toggle_task_completion(
+    task_id: int,
+    session: Session = Depends(get_session),
+    current_user: Dict = Depends(get_current_user)
+):
+    """
+    Toggle task completion status.
+
+    Flips the completed boolean (True -> False or False -> True).
+    User must own the task.
+    """
+    user_id = current_user["user_id"]
+
+    # Fetch task by ID
+    task = session.get(Task, task_id)
+
+    # Return 404 if task not found
+    if not task:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Task not found"
+        )
+
+    # Verify ownership - return 403 if user doesn't own this task
+    if task.user_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not have permission to modify this task"
+        )
+
+    # Toggle completion status
+    task.completed = not task.completed
+
+    # Update timestamp
+    task.updated_at = datetime.utcnow()
+
+    session.add(task)
+    session.commit()
+    session.refresh(task)
+
+    return task

src/config.py

@@ -0,0 +1,46 @@
+from pydantic_settings import BaseSettings
+from typing import List
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    # Database
+    DATABASE_URL: str
+
+    # JWT Configuration
+    JWT_SECRET: str
+    JWT_ALGORITHM: str = "HS256"
+    JWT_EXPIRATION_HOURS: int = 168  # 7 days
+
+    # Better Auth Secret (must match frontend)
+    BETTER_AUTH_SECRET: str
+
+    # CORS Configuration
+    CORS_ORIGINS: str = "http://localhost:3000"
+
+    # OpenAI Configuration (supports OpenRouter)
+    OPENAI_API_KEY: str
+    OPENAI_MODEL: str = "gpt-4o-mini"
+    OPENAI_BASE_URL: str = ""
+
+    # MCP Server Configuration
+    MCP_SERVER_PORT: int = 8001
+    MCP_SERVER_HOST: str = "localhost"
+
+    # Environment
+    ENVIRONMENT: str = "development"
+    DEBUG: bool = True
+
+    @property
+    def cors_origins_list(self) -> List[str]:
+        """Parse CORS_ORIGINS string into list."""
+        return [origin.strip() for origin in self.CORS_ORIGINS.split(",")]
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+
+# Global settings instance
+settings = Settings()

src/database.py

@@ -0,0 +1,29 @@
+from sqlmodel import SQLModel, create_engine, Session
+from sqlalchemy.pool import NullPool
+from .config import settings
+
+# Import models to register them with SQLModel metadata
+from .models.user import User  # noqa: F401
+from .models.task import Task  # noqa: F401
+from .models.conversation import Conversation  # noqa: F401
+from .models.message import Message  # noqa: F401
+
+
+# Create engine with appropriate pooling for serverless
+engine = create_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,
+    poolclass=NullPool  # Let Neon handle connection pooling
+)
+
+
+def init_db():
+    """Initialize database by creating all tables."""
+    SQLModel.metadata.create_all(engine)
+    print("Database tables created successfully")
+
+
+def get_session():
+    """Dependency for getting database session."""
+    with Session(engine) as session:
+        yield session

src/jobs/cleanup_conversations.py

@@ -0,0 +1,157 @@
+"""
+Conversation Cleanup Job
+
+Implements 90-day retention policy for conversations and messages.
+Permanently deletes soft-deleted conversations older than 90 days.
+"""
+
+from sqlmodel import Session, select
+from datetime import datetime, timedelta
+from ..database import engine
+from ..models.conversation import Conversation
+from ..models.message import Message
+from ..utils.logging import StructuredLogger
+
+logger = StructuredLogger("cleanup")
+
+
+def cleanup_old_conversations(dry_run: bool = False) -> dict:
+    """
+    Delete conversations and messages older than 90 days.
+
+    This function implements the 90-day retention policy by:
+    1. Finding conversations soft-deleted more than 90 days ago
+    2. Deleting associated messages
+    3. Permanently deleting the conversations
+
+    Args:
+        dry_run: If True, only count records without deleting
+
+    Returns:
+        Dict with cleanup statistics
+    """
+    cutoff_date = datetime.utcnow() - timedelta(days=90)
+
+    with Session(engine) as session:
+        # Find conversations to delete
+        statement = select(Conversation).where(
+            Conversation.deleted_at.is_not(None),
+            Conversation.deleted_at < cutoff_date
+        )
+        conversations_to_delete = session.exec(statement).all()
+
+        conversation_count = len(conversations_to_delete)
+        message_count = 0
+
+        if not dry_run:
+            for conversation in conversations_to_delete:
+                # Delete associated messages
+                message_statement = select(Message).where(
+                    Message.conversation_id == conversation.id
+                )
+                messages = session.exec(message_statement).all()
+                message_count += len(messages)
+
+                for message in messages:
+                    session.delete(message)
+
+                # Delete conversation
+                session.delete(conversation)
+
+            session.commit()
+
+            logger.info(
+                "cleanup_completed",
+                conversations_deleted=conversation_count,
+                messages_deleted=message_count,
+                cutoff_date=cutoff_date.isoformat()
+            )
+        else:
+            # Count messages without deleting
+            for conversation in conversations_to_delete:
+                message_statement = select(Message).where(
+                    Message.conversation_id == conversation.id
+                )
+                messages = session.exec(message_statement).all()
+                message_count += len(messages)
+
+            logger.info(
+                "cleanup_dry_run",
+                conversations_to_delete=conversation_count,
+                messages_to_delete=message_count,
+                cutoff_date=cutoff_date.isoformat()
+            )
+
+    return {
+        "conversations_deleted": conversation_count,
+        "messages_deleted": message_count,
+        "cutoff_date": cutoff_date.isoformat(),
+        "dry_run": dry_run
+    }
+
+
+def cleanup_orphaned_messages() -> dict:
+    """
+    Delete messages that belong to deleted conversations.
+
+    This is a safety cleanup for any orphaned messages.
+
+    Returns:
+        Dict with cleanup statistics
+    """
+    with Session(engine) as session:
+        # Find messages with no parent conversation
+        statement = select(Message).where(
+            ~Message.conversation_id.in_(
+                select(Conversation.id)
+            )
+        )
+        orphaned_messages = session.exec(statement).all()
+
+        count = len(orphaned_messages)
+
+        for message in orphaned_messages:
+            session.delete(message)
+
+        session.commit()
+
+        logger.info(
+            "orphaned_messages_cleanup",
+            messages_deleted=count
+        )
+
+    return {
+        "orphaned_messages_deleted": count
+    }
+
+
+if __name__ == "__main__":
+    """
+    Run cleanup job from command line.
+
+    Usage:
+        python -m backend.src.jobs.cleanup_conversations
+        python -m backend.src.jobs.cleanup_conversations --dry-run
+    """
+    import sys
+
+    dry_run = "--dry-run" in sys.argv
+
+    print("Starting conversation cleanup job...")
+    print(f"Dry run: {dry_run}")
+    print(f"Cutoff date: {(datetime.utcnow() - timedelta(days=90)).isoformat()}")
+    print()
+
+    # Run main cleanup
+    result = cleanup_old_conversations(dry_run=dry_run)
+    print(f"Conversations deleted: {result['conversations_deleted']}")
+    print(f"Messages deleted: {result['messages_deleted']}")
+    print()
+
+    # Run orphaned messages cleanup
+    if not dry_run:
+        orphaned_result = cleanup_orphaned_messages()
+        print(f"Orphaned messages deleted: {orphaned_result['orphaned_messages_deleted']}")
+        print()
+
+    print("Cleanup job completed!")

src/main.py

@@ -0,0 +1,121 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from .config import settings
+from .schemas.error import ErrorResponse
+from .api import tasks_router, auth_router, chat_router
+from .agents import TaskAgent
+
+
+# Initialize FastAPI application
+app = FastAPI(
+    title="KIro Todo API",
+    description="RESTful API for multi-user todo application with JWT authentication and Cohere AI agent",
+    version="1.0.0"
+)
+
+
+# Global agent instance (initialized at startup)
+task_agent: TaskAgent = None
+
+
+@app.on_event("startup")
+async def startup_event():
+    """
+    Initialize application components at startup.
+
+    This includes:
+    - Creating the TaskAgent instance
+    - Verifying OpenAI/OpenRouter API connectivity
+    """
+    global task_agent
+
+    # Initialize the task agent
+    task_agent = TaskAgent()
+
+    # Verify agent can connect to API
+    is_healthy = await task_agent.health_check()
+    if is_healthy:
+        print(f"[OK] TaskAgent initialized successfully with model: {task_agent.model}")
+    else:
+        print(f"[WARNING] TaskAgent initialized but API health check failed")
+
+
+def get_task_agent() -> TaskAgent:
+    """
+    Get the global TaskAgent instance.
+
+    This function can be used as a dependency in route handlers.
+
+    Returns:
+        TaskAgent: The initialized agent instance
+
+    Raises:
+        RuntimeError: If agent is not initialized
+    """
+    if task_agent is None:
+        raise RuntimeError("TaskAgent not initialized. Application startup may have failed.")
+    return task_agent
+
+
+# Configure CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Include API routers
+app.include_router(auth_router)
+app.include_router(tasks_router)
+app.include_router(chat_router)
+
+
+# Global exception handler for HTTPException
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request, exc: HTTPException):
+    """Handle HTTP exceptions with consistent error response format."""
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": exc.detail,
+            "message": get_user_friendly_message(exc.status_code),
+            "details": getattr(exc, "details", None)
+        }
+    )
+
+
+def get_user_friendly_message(status_code: int) -> str:
+    """Get user-friendly message for HTTP status code."""
+    messages = {
+        400: "The request contains invalid data",
+        401: "Authentication is required to access this resource",
+        403: "You do not have permission to access this resource",
+        404: "The requested resource was not found",
+        500: "An internal server error occurred"
+    }
+    return messages.get(status_code, "An error occurred")
+
+
+# Health check endpoint
+@app.get("/health", tags=["Health"])
+async def health_check():
+    """Health check endpoint to verify API is running."""
+    return {
+        "status": "healthy",
+        "environment": settings.ENVIRONMENT
+    }
+
+
+# Root endpoint
+@app.get("/", tags=["Root"])
+async def root():
+    """Root endpoint with API information."""
+    return {
+        "message": "KIro Todo API",
+        "version": "1.0.0",
+        "docs": "/docs"
+    }

src/middleware/__init__.py

@@ -0,0 +1 @@
+# Middleware package

src/middleware/auth.py

@@ -0,0 +1,62 @@
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from jose import jwt, JWTError
+from typing import Dict
+from ..config import settings
+
+
+# HTTP Bearer security scheme
+security = HTTPBearer()
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security)
+) -> Dict[str, any]:
+    """
+    Verify JWT token and extract user identity.
+
+    This dependency extracts and validates the JWT token from the Authorization header.
+    User identity is extracted from the token payload, never from client input.
+
+    Args:
+        credentials: HTTP Bearer credentials containing JWT token
+
+    Returns:
+        Dict containing user_id and email from token payload
+
+    Raises:
+        HTTPException: 401 if token is missing, invalid, or expired
+    """
+    try:
+        # Decode and verify JWT token
+        payload = jwt.decode(
+            credentials.credentials,
+            settings.JWT_SECRET,
+            algorithms=[settings.JWT_ALGORITHM]
+        )
+
+        # Extract user ID from token payload
+        user_id = payload.get("sub")
+        email = payload.get("email")
+
+        if user_id is None:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid token: missing user ID"
+            )
+
+        return {
+            "user_id": int(user_id),
+            "email": email
+        }
+
+    except JWTError as e:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Invalid token: {str(e)}"
+        )
+    except ValueError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token: malformed user ID"
+        )

src/middleware/rate_limit.py

@@ -0,0 +1,161 @@
+"""
+Rate Limiting Middleware
+
+Implements token bucket algorithm for rate limiting API requests.
+Limits: 60 requests per minute per user.
+"""
+
+from fastapi import Request, HTTPException, status
+from typing import Dict
+import time
+from collections import defaultdict
+import threading
+
+
+class TokenBucket:
+    """
+    Token bucket implementation for rate limiting.
+
+    Each user gets a bucket with tokens that refill over time.
+    Each request consumes one token.
+    """
+
+    def __init__(self, capacity: int, refill_rate: float):
+        """
+        Initialize token bucket.
+
+        Args:
+            capacity: Maximum number of tokens (burst size)
+            refill_rate: Tokens added per second
+        """
+        self.capacity = capacity
+        self.refill_rate = refill_rate
+        self.tokens = capacity
+        self.last_refill = time.time()
+        self.lock = threading.Lock()
+
+    def consume(self, tokens: int = 1) -> bool:
+        """
+        Try to consume tokens from bucket.
+
+        Args:
+            tokens: Number of tokens to consume
+
+        Returns:
+            True if tokens were consumed, False if insufficient tokens
+        """
+        with self.lock:
+            # Refill tokens based on time elapsed
+            now = time.time()
+            elapsed = now - self.last_refill
+            self.tokens = min(
+                self.capacity,
+                self.tokens + (elapsed * self.refill_rate)
+            )
+            self.last_refill = now
+
+            # Try to consume tokens
+            if self.tokens >= tokens:
+                self.tokens -= tokens
+                return True
+            return False
+
+    def get_remaining(self) -> int:
+        """Get number of tokens remaining."""
+        with self.lock:
+            return int(self.tokens)
+
+    def get_reset_time(self) -> int:
+        """Get timestamp when bucket will be full."""
+        with self.lock:
+            if self.tokens >= self.capacity:
+                return int(time.time())
+
+            tokens_needed = self.capacity - self.tokens
+            seconds_to_full = tokens_needed / self.refill_rate
+            return int(time.time() + seconds_to_full)
+
+
+class RateLimiter:
+    """
+    Rate limiter using token bucket algorithm.
+
+    Tracks rate limits per user_id.
+    """
+
+    def __init__(
+        self,
+        requests_per_minute: int = 60,
+        burst_size: int = 10
+    ):
+        """
+        Initialize rate limiter.
+
+        Args:
+            requests_per_minute: Maximum requests per minute per user
+            burst_size: Maximum burst size (extra tokens beyond rate)
+        """
+        self.requests_per_minute = requests_per_minute
+        self.capacity = requests_per_minute + burst_size
+        self.refill_rate = requests_per_minute / 60.0  # Tokens per second
+        self.buckets: Dict[int, TokenBucket] = defaultdict(
+            lambda: TokenBucket(self.capacity, self.refill_rate)
+        )
+        self.lock = threading.Lock()
+
+    def check_rate_limit(self, user_id: int) -> tuple[bool, int, int]:
+        """
+        Check if request is within rate limit.
+
+        Args:
+            user_id: User identifier
+
+        Returns:
+            Tuple of (allowed, remaining, reset_time)
+        """
+        with self.lock:
+            bucket = self.buckets[user_id]
+
+        allowed = bucket.consume(1)
+        remaining = bucket.get_remaining()
+        reset_time = bucket.get_reset_time()
+
+        return allowed, remaining, reset_time
+
+
+# Global rate limiter instance
+rate_limiter = RateLimiter(requests_per_minute=60, burst_size=10)
+
+
+async def rate_limit_middleware(request: Request, user_id: int):
+    """
+    Rate limiting middleware for API endpoints.
+
+    Args:
+        request: FastAPI request object
+        user_id: Authenticated user ID
+
+    Raises:
+        HTTPException 429: Rate limit exceeded
+    """
+    allowed, remaining, reset_time = rate_limiter.check_rate_limit(user_id)
+
+    # Add rate limit headers to response
+    request.state.rate_limit_headers = {
+        "X-RateLimit-Limit": str(rate_limiter.requests_per_minute),
+        "X-RateLimit-Remaining": str(remaining),
+        "X-RateLimit-Reset": str(reset_time)
+    }
+
+    if not allowed:
+        retry_after = reset_time - int(time.time())
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Rate limit exceeded",
+            headers={
+                "X-RateLimit-Limit": str(rate_limiter.requests_per_minute),
+                "X-RateLimit-Remaining": "0",
+                "X-RateLimit-Reset": str(reset_time),
+                "Retry-After": str(max(1, retry_after))
+            }
+        )

src/models/__init__.py

@@ -0,0 +1,8 @@
+# Models package
+from .user import User
+from .task import Task
+from .conversation import Conversation
+from .message import Message, MessageRole
+from .tool_call_log import ToolCallLog, ToolCallStatus
+
+__all__ = ["User", "Task", "Conversation", "Message", "MessageRole", "ToolCallLog", "ToolCallStatus"]

src/models/conversation.py

@@ -0,0 +1,28 @@
+from sqlmodel import Field, SQLModel, Relationship
+from typing import Optional, List, TYPE_CHECKING
+from datetime import datetime
+
+if TYPE_CHECKING:
+    from .user import User
+    from .message import Message
+
+
+class Conversation(SQLModel, table=True):
+    """Conversation model representing a chat session between a user and the AI agent."""
+
+    __tablename__ = "conversations"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    user_id: int = Field(foreign_key="users.id", index=True)
+    title: Optional[str] = Field(default=None, max_length=200)
+    created_at: datetime = Field(default_factory=datetime.utcnow, index=True)
+    updated_at: datetime = Field(default_factory=datetime.utcnow, index=True)
+    deleted_at: Optional[datetime] = Field(default=None, index=True)
+
+    # Relationships
+    owner: "User" = Relationship(back_populates="conversations")
+    messages: List["Message"] = Relationship(
+        back_populates="conversation",
+        cascade_delete=True,
+        sa_relationship_kwargs={"order_by": "Message.created_at"}
+    )

src/models/message.py

@@ -0,0 +1,37 @@
+from sqlmodel import Field, SQLModel, Relationship, Column, JSON
+from typing import Optional, Dict, Any, TYPE_CHECKING
+from datetime import datetime
+from enum import Enum
+
+if TYPE_CHECKING:
+    from .conversation import Conversation
+
+
+class MessageRole(str, Enum):
+    """Enum representing the role of a message sender."""
+    USER = "user"
+    ASSISTANT = "assistant"
+
+
+class Message(SQLModel, table=True):
+    """Message model representing a single exchange in a conversation."""
+
+    __tablename__ = "messages"
+    __table_args__ = (
+        {"sqlite_autoincrement": True},
+    )
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    conversation_id: int = Field(foreign_key="conversations.id", index=True)
+    role: MessageRole = Field(sa_column_kwargs={"nullable": False})
+    content: str = Field(sa_column_kwargs={"nullable": False})
+    tool_calls: Optional[Dict[str, Any]] = Field(
+        default=None,
+        sa_column=Column(JSON)
+    )
+    sequence_number: int = Field(index=True)
+    created_at: datetime = Field(default_factory=datetime.utcnow, index=True)
+    deleted_at: Optional[datetime] = Field(default=None, index=True)
+
+    # Relationships
+    conversation: "Conversation" = Relationship(back_populates="messages")

src/models/task.py

@@ -0,0 +1,23 @@
+from sqlmodel import Field, SQLModel, Relationship
+from typing import Optional, TYPE_CHECKING
+from datetime import datetime
+
+if TYPE_CHECKING:
+    from .user import User
+
+
+class Task(SQLModel, table=True):
+    """Task model representing a todo item belonging to a specific user."""
+
+    __tablename__ = "tasks"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    title: str = Field(max_length=200, min_length=1)
+    description: Optional[str] = Field(default=None, max_length=2000)
+    completed: bool = Field(default=False)
+    user_id: int = Field(foreign_key="users.id", index=True)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+    # Relationships
+    owner: "User" = Relationship(back_populates="tasks")

src/models/tool_call_log.py

@@ -0,0 +1,45 @@
+from sqlmodel import Field, SQLModel, Relationship, Column, JSON
+from sqlalchemy import ForeignKey, Integer
+from typing import Optional, Dict, Any, TYPE_CHECKING
+from datetime import datetime
+from enum import Enum
+
+if TYPE_CHECKING:
+    from .message import Message
+    from .conversation import Conversation
+    from .user import User
+
+
+class ToolCallStatus(str, Enum):
+    """Enum representing the status of a tool call."""
+    SUCCESS = "success"
+    ERROR = "error"
+
+
+class ToolCallLog(SQLModel, table=True):
+    """ToolCallLog model for auditing MCP tool invocations."""
+
+    __tablename__ = "tool_call_logs"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    message_id: Optional[int] = Field(
+        default=None,
+        sa_column=Column(Integer, ForeignKey("messages.id", ondelete="SET NULL"))
+    )
+    conversation_id: int = Field(
+        sa_column=Column(Integer, ForeignKey("conversations.id", ondelete="CASCADE"), index=True, nullable=False)
+    )
+    user_id: int = Field(
+        sa_column=Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), index=True, nullable=False)
+    )
+    tool_name: str = Field(max_length=50, index=True)
+    arguments: Dict[str, Any] = Field(sa_column=Column(JSON))
+    result: Dict[str, Any] = Field(sa_column=Column(JSON))
+    status: ToolCallStatus = Field(sa_column_kwargs={"nullable": False})
+    execution_time_ms: int = Field(default=0)
+    created_at: datetime = Field(default_factory=datetime.utcnow, index=True)
+
+    # Relationships
+    message: Optional["Message"] = Relationship()
+    conversation: "Conversation" = Relationship()
+    user: "User" = Relationship()

src/models/user.py

@@ -0,0 +1,22 @@
+from sqlmodel import Field, SQLModel, Relationship
+from typing import Optional, List, TYPE_CHECKING
+from datetime import datetime
+
+if TYPE_CHECKING:
+    from .task import Task
+    from .conversation import Conversation
+
+
+class User(SQLModel, table=True):
+    """User model representing a person with an account in the system."""
+
+    __tablename__ = "users"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    email: str = Field(unique=True, index=True, max_length=255)
+    password_hash: str = Field(max_length=255)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+    # Relationships
+    tasks: List["Task"] = Relationship(back_populates="owner", cascade_delete=True)
+    conversations: List["Conversation"] = Relationship(back_populates="owner", cascade_delete=True)

src/schemas/__init__.py

@@ -0,0 +1 @@
+# Schemas package

src/schemas/chat.py

@@ -0,0 +1,78 @@
+"""
+Chat API Schemas
+
+Request and response models for the chat endpoint.
+"""
+
+from pydantic import BaseModel, Field, field_validator
+from typing import Optional, List, Dict, Any
+from datetime import datetime
+
+
+class ChatRequest(BaseModel):
+    """Request model for chat endpoint."""
+
+    message: str = Field(
+        ...,
+        min_length=1,
+        max_length=2000,
+        description="User's natural language message"
+    )
+    conversation_id: Optional[int] = Field(
+        default=None,
+        description="Existing conversation ID to continue (omit for new conversation)"
+    )
+
+    @field_validator('message')
+    @classmethod
+    def validate_message(cls, v: str) -> str:
+        """Validate message is not empty or whitespace-only."""
+        if not v or v.strip() == "":
+            raise ValueError("Message cannot be empty or whitespace-only")
+        return v.strip()
+
+
+class ToolCallResult(BaseModel):
+    """Tool call result metadata."""
+
+    tool: str = Field(..., description="Tool name")
+    parameters: Dict[str, Any] = Field(..., description="Tool parameters")
+    result: Dict[str, Any] = Field(..., description="Tool execution result")
+    duration_ms: Optional[int] = Field(None, description="Execution time in milliseconds")
+
+
+class ChatResponse(BaseModel):
+    """Response model for chat endpoint."""
+
+    conversation_id: int = Field(..., description="Conversation identifier")
+    message_id: int = Field(..., description="Assistant message ID")
+    assistant_message: str = Field(..., description="Natural language response from agent")
+    tool_calls: Optional[List[ToolCallResult]] = Field(
+        default=None,
+        description="List of MCP tool invocations (empty if no tools used)"
+    )
+    timestamp: datetime = Field(..., description="Response generation timestamp")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "conversation_id": 456,
+                "message_id": 789,
+                "assistant_message": "I've added 'Buy groceries tomorrow' to your tasks. Task created successfully!",
+                "tool_calls": [
+                    {
+                        "tool": "create_task",
+                        "parameters": {
+                            "title": "Buy groceries tomorrow",
+                            "description": ""
+                        },
+                        "result": {
+                            "task_id": 101,
+                            "status": "success"
+                        },
+                        "duration_ms": 45
+                    }
+                ],
+                "timestamp": "2026-02-03T10:30:00Z"
+            }
+        }

src/schemas/error.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel
+from typing import Optional, Dict, Any
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response format."""
+
+    error: str
+    message: str
+    details: Optional[Dict[str, Any]] = None
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "error": "Validation error",
+                "message": "The provided data is invalid",
+                "details": {
+                    "field": "title",
+                    "constraint": "minLength"
+                }
+            }
+        }

src/schemas/task.py

@@ -0,0 +1,61 @@
+from pydantic import BaseModel, Field
+from typing import Optional
+from datetime import datetime
+
+
+class TaskCreate(BaseModel):
+    """Schema for creating a new task."""
+
+    title: str = Field(..., min_length=1, max_length=200, description="Task title (required)")
+    description: Optional[str] = Field(None, max_length=2000, description="Optional detailed description")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "title": "Buy groceries",
+                "description": "Milk, eggs, bread, and vegetables"
+            }
+        }
+
+
+class TaskUpdate(BaseModel):
+    """Schema for updating an existing task."""
+
+    title: Optional[str] = Field(None, min_length=1, max_length=200, description="Updated task title")
+    description: Optional[str] = Field(None, max_length=2000, description="Updated description")
+    completed: Optional[bool] = Field(None, description="Updated completion status")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "title": "Buy groceries and cook dinner",
+                "description": "Updated shopping list",
+                "completed": True
+            }
+        }
+
+
+class TaskResponse(BaseModel):
+    """Schema for task response."""
+
+    id: int = Field(..., description="Unique task identifier")
+    title: str = Field(..., description="Task title")
+    description: Optional[str] = Field(None, description="Task description")
+    completed: bool = Field(..., description="Whether task is marked as complete")
+    user_id: int = Field(..., description="ID of user who owns this task")
+    created_at: datetime = Field(..., description="Timestamp when task was created")
+    updated_at: datetime = Field(..., description="Timestamp when task was last modified")
+
+    class Config:
+        from_attributes = True
+        json_schema_extra = {
+            "example": {
+                "id": 1,
+                "title": "Buy groceries",
+                "description": "Milk, eggs, bread",
+                "completed": False,
+                "user_id": 42,
+                "created_at": "2026-02-02T10:30:00Z",
+                "updated_at": "2026-02-02T10:30:00Z"
+            }
+        }

src/services/__init__.py

@@ -0,0 +1,5 @@
+"""Services package."""
+
+from .agent_service import AgentService
+
+__all__ = ["AgentService"]

src/services/agent_service.py

@@ -0,0 +1,374 @@
+"""
+Agent Service Module
+
+This module provides the AgentService class that orchestrates AI agent interactions.
+The service wraps MCP tools with user_id pre-bound for security and data isolation.
+"""
+
+from typing import List, Dict, Any, Optional
+import json
+import time
+from openai import OpenAI
+from ..config import settings
+from ..tools.mcp_server import mcp_server, MCPContext
+from ..tools import (
+    get_list_tasks_definition,
+    get_create_task_definition,
+    get_mark_complete_definition,
+    get_update_task_definition,
+    get_delete_task_definition,
+    get_get_task_definition
+)
+from ..database import engine
+
+
+class AgentService:
+    """
+    Agent Service for processing conversational task management requests.
+
+    This service:
+    1. Initializes OpenAI client with configured API key
+    2. Wraps MCP tools with user_id pre-bound for security
+    3. Processes user messages with conversation history
+    4. Returns agent responses with tool call metadata
+    """
+
+    def __init__(self, user_id: int):
+        """
+        Initialize AgentService for a specific user.
+
+        Args:
+            user_id: Authenticated user ID for data scoping
+        """
+        self.user_id = user_id
+
+        # Configure client for OpenRouter if base URL is provided
+        client_kwargs = {"api_key": settings.OPENAI_API_KEY}
+        if hasattr(settings, 'OPENAI_BASE_URL') and settings.OPENAI_BASE_URL:
+            client_kwargs["base_url"] = settings.OPENAI_BASE_URL
+
+        self.client = OpenAI(**client_kwargs)
+        self.model = settings.OPENAI_MODEL
+        self.mcp_context = mcp_server.create_context(user_id=user_id)
+
+    def create_user_scoped_tools(self) -> List[Dict[str, Any]]:
+        """
+        Create user-scoped tool definitions for OpenAI function calling.
+
+        This method wraps internal MCP tools with user_id pre-bound,
+        ensuring the agent can only access the authenticated user's data.
+
+        Returns:
+            List of tool definitions in OpenAI function calling format
+        """
+        tools = [
+            get_list_tasks_definition(),
+            get_create_task_definition(),
+            get_mark_complete_definition(),
+            get_update_task_definition(),
+            get_delete_task_definition(),
+            get_get_task_definition()
+        ]
+
+        return tools
+
+    async def execute_tool(self, tool_name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute an MCP tool with the given arguments.
+
+        Args:
+            tool_name: Name of the tool to execute
+            arguments: Tool arguments (user_id is pre-bound from context)
+
+        Returns:
+            Tool execution result
+
+        Raises:
+            ValueError: If tool not found
+        """
+        # Get tool function from MCP server
+        tool_func = mcp_server.get_tool(tool_name)
+
+        if not tool_func:
+            raise ValueError(f"Tool '{tool_name}' not found")
+
+        # Execute tool with user-scoped context
+        try:
+            result = await tool_func(self.mcp_context, **arguments)
+            return result
+        except Exception as e:
+            print(f"Error executing tool '{tool_name}': {str(e)}")
+            return {
+                "status": "error",
+                "error": str(e)
+            }
+
+    async def process_message(
+        self,
+        message: str,
+        conversation_history: List[Dict[str, str]]
+    ) -> Dict[str, Any]:
+        """
+        Process user message with conversation history and return agent response.
+
+        This method implements the full OpenAI function calling workflow:
+        1. Send message with tool definitions to OpenAI
+        2. If model calls tools, execute them
+        3. Send tool results back to model
+        4. Return final natural language response
+
+        Args:
+            message: User's natural language input
+            conversation_history: List of previous messages in conversation
+
+        Returns:
+            Dict containing:
+                - content: Agent's natural language response
+                - tool_calls: List of tool invocations with results (if any)
+                - model: Model used for generation
+
+        Raises:
+            Exception: If OpenAI API call fails
+        """
+        # Build messages array for OpenAI API
+        messages = []
+
+        # Add system message for agent behavior
+        system_prompt = (
+            "You are a helpful task management assistant. "
+            "You help users manage their tasks through natural conversation.\n\n"
+
+            "**Task Creation Intent Recognition:**\n"
+            "When users express intent to create a task, use the create_task tool. Examples:\n"
+            "- 'remind me to X' → create_task(title='X')\n"
+            "- 'add task X' → create_task(title='X')\n"
+            "- 'I need to X' → create_task(title='X')\n"
+            "- 'create a task for X' → create_task(title='X')\n"
+            "- 'don't let me forget to X' → create_task(title='X')\n\n"
+
+            "**Task Listing Intent Recognition:**\n"
+            "When users want to see their tasks, use the list_tasks tool. Examples:\n"
+            "- 'show my tasks' → list_tasks()\n"
+            "- 'what do I need to do' → list_tasks()\n"
+            "- 'list my todos' → list_tasks()\n"
+            "- 'what are my tasks' → list_tasks()\n"
+            "- 'show me my task list' → list_tasks()\n\n"
+
+            "**Task Completion Intent Recognition:**\n"
+            "When users indicate they finished a task, use mark_complete tool. Examples:\n"
+            "- 'I finished X' → list_tasks() to find task, then mark_complete(task_id)\n"
+            "- 'mark X as done' → list_tasks() to find task, then mark_complete(task_id)\n"
+            "- 'I completed the groceries task' → list_tasks() to find task, then mark_complete(task_id)\n"
+            "- 'done with X' → list_tasks() to find task, then mark_complete(task_id)\n\n"
+
+            "**Task Update Intent Recognition:**\n"
+            "When users want to modify a task, use update_task tool. Examples:\n"
+            "- 'change X to Y' → list_tasks() to find task, then update_task(task_id, title='Y')\n"
+            "- 'update task X' → list_tasks() to find task, then update_task(task_id, ...)\n"
+            "- 'rename X to Y' → list_tasks() to find task, then update_task(task_id, title='Y')\n"
+            "- 'add details to X' → list_tasks() to find task, then update_task(task_id, description='...')\n\n"
+
+            "**Task Deletion Intent Recognition:**\n"
+            "When users want to remove a task, use delete_task tool. Examples:\n"
+            "- 'delete X' → list_tasks() to find task, then delete_task(task_id)\n"
+            "- 'remove the task' → list_tasks() to find task, then delete_task(task_id)\n"
+            "- 'cancel X' → list_tasks() to find task, then delete_task(task_id)\n"
+            "- 'get rid of X' → list_tasks() to find task, then delete_task(task_id)\n\n"
+
+            "**Multi-Step Operations:**\n"
+            "For operations that reference tasks by title or description (not ID):\n"
+            "1. First call list_tasks() to get all tasks\n"
+            "2. Identify the matching task from the list\n"
+            "3. Use the task's ID for the operation (mark_complete, update_task, delete_task)\n"
+            "4. If multiple tasks match, ask the user to clarify which one\n"
+            "5. If no tasks match, inform the user the task wasn't found\n\n"
+
+            "**Context Awareness:**\n"
+            "- Remember previous messages in the conversation\n"
+            "- When users say 'the first task', 'the second one', 'that task', refer to recently listed tasks\n"
+            "- Maintain context across multiple turns\n"
+            "- If context is unclear, ask clarifying questions\n\n"
+
+            "**Response Guidelines:**\n"
+            "- Always confirm actions taken (e.g., 'I've added X to your tasks')\n"
+            "- Format task lists in a readable way (use bullet points or numbered lists)\n"
+            "- Show completed vs incomplete tasks clearly\n"
+            "- Be concise, friendly, and conversational\n"
+            "- If no tasks exist, provide an encouraging message\n"
+            "- If a request is ambiguous, ask clarifying questions\n"
+            "- When multiple tasks match a reference, list them and ask which one\n"
+            "- Provide helpful error messages when operations fail"
+        )
+
+        messages.append({
+            "role": "system",
+            "content": system_prompt
+        })
+
+        # Add conversation history
+        for msg in conversation_history:
+            messages.append({
+                "role": msg.get("role", "user"),
+                "content": msg.get("content", "")
+            })
+
+        # Add current user message
+        messages.append({
+            "role": "user",
+            "content": message
+        })
+
+        # Get user-scoped tools
+        tools = self.create_user_scoped_tools()
+
+        # Track tool calls for response metadata
+        executed_tool_calls = []
+
+        # Call OpenAI API with retry logic
+        max_retries = 3
+        retry_delay = 1  # seconds
+
+        try:
+            if tools:
+                # First API call with tools (with retry)
+                for attempt in range(max_retries):
+                    try:
+                        response = self.client.chat.completions.create(
+                            model=self.model,
+                            messages=messages,
+                            tools=tools,
+                            temperature=0.3,
+                            max_tokens=500
+                        )
+                        break  # Success, exit retry loop
+                    except Exception as api_error:
+                        if attempt < max_retries - 1:
+                            # Retry on transient errors
+                            error_str = str(api_error).lower()
+                            if any(keyword in error_str for keyword in ['timeout', 'connection', 'rate_limit', '429', '503', '502']):
+                                print(f"OpenAI API error (attempt {attempt + 1}/{max_retries}): {api_error}. Retrying in {retry_delay}s...")
+                                time.sleep(retry_delay)
+                                retry_delay *= 2  # Exponential backoff
+                                continue
+                        # Non-retryable error or max retries reached
+                        raise
+
+                assistant_message = response.choices[0].message
+
+                # Check if model wants to call tools
+                if assistant_message.tool_calls:
+                    # Execute each tool call
+                    for tool_call in assistant_message.tool_calls:
+                        tool_name = tool_call.function.name
+
+                        # Handle None or empty arguments from OpenRouter
+                        tool_args_str = tool_call.function.arguments
+                        if tool_args_str is None or tool_args_str == "":
+                            tool_args = {}
+                        else:
+                            tool_args = json.loads(tool_args_str)
+
+                        # Execute tool and track timing
+                        start_time = time.time()
+                        tool_result = await self.execute_tool(tool_name, tool_args)
+                        duration_ms = int((time.time() - start_time) * 1000)
+
+                        # Store tool call metadata
+                        executed_tool_calls.append({
+                            "tool": tool_name,
+                            "parameters": tool_args,
+                            "result": tool_result,
+                            "duration_ms": duration_ms
+                        })
+
+                        # Add tool call and result to messages for next API call
+                        messages.append({
+                            "role": "assistant",
+                            "content": None,
+                            "tool_calls": [{
+                                "id": tool_call.id,
+                                "type": "function",
+                                "function": {
+                                    "name": tool_name,
+                                    "arguments": tool_call.function.arguments
+                                }
+                            }]
+                        })
+
+                        messages.append({
+                            "role": "tool",
+                            "tool_call_id": tool_call.id,
+                            "content": json.dumps(tool_result)
+                        })
+
+                    # Second API call to get natural language response
+                    final_response = self.client.chat.completions.create(
+                        model=self.model,
+                        messages=messages,
+                        temperature=0.3,
+                        max_tokens=500
+                    )
+
+                    final_content = final_response.choices[0].message.content or ""
+
+                    return {
+                        "content": final_content,
+                        "tool_calls": executed_tool_calls if executed_tool_calls else None,
+                        "model": self.model,
+                        "finish_reason": final_response.choices[0].finish_reason
+                    }
+
+                else:
+                    # No tool calls, return direct response
+                    content = assistant_message.content or ""
+
+                    return {
+                        "content": content,
+                        "tool_calls": None,
+                        "model": self.model,
+                        "finish_reason": response.choices[0].finish_reason
+                    }
+
+            else:
+                # No tools available, call without tools
+                response = self.client.chat.completions.create(
+                    model=self.model,
+                    messages=messages,
+                    temperature=0.3,
+                    max_tokens=500
+                )
+
+                content = response.choices[0].message.content or ""
+
+                return {
+                    "content": content,
+                    "tool_calls": None,
+                    "model": self.model,
+                    "finish_reason": response.choices[0].finish_reason
+                }
+
+        except Exception as e:
+            # Log error and re-raise
+            print(f"Error processing message with OpenAI: {str(e)}")
+            raise
+
+    def format_conversation_history(
+        self,
+        messages: List[Any]
+    ) -> List[Dict[str, str]]:
+        """
+        Format database messages into OpenAI conversation history format.
+
+        Args:
+            messages: List of Message model instances from database
+
+        Returns:
+            List of message dicts in OpenAI format
+        """
+        history = []
+        for msg in messages:
+            history.append({
+                "role": msg.role.value if hasattr(msg.role, 'value') else msg.role,
+                "content": msg.content
+            })
+        return history

src/services/cohere_agent_service.py

@@ -0,0 +1,221 @@
+"""
+Cohere Agent Service Module
+
+This module provides the CohereAgentService class that uses Cohere API for chat.
+"""
+
+from typing import List, Dict, Any
+import json
+import time
+import cohere
+from ..config import settings
+from ..tools.mcp_server import mcp_server
+from ..tools import (
+    get_list_tasks_definition,
+    get_create_task_definition,
+    get_mark_complete_definition,
+    get_update_task_definition,
+    get_delete_task_definition,
+    get_get_task_definition
+)
+from ..database import engine
+
+
+class CohereAgentService:
+    """
+    Cohere Agent Service for processing conversational task management requests.
+    """
+
+    def __init__(self, user_id: int):
+        """
+        Initialize CohereAgentService for a specific user.
+
+        Args:
+            user_id: Authenticated user ID for data scoping
+        """
+        self.user_id = user_id
+        self.client = cohere.Client(api_key=settings.COHERE_API_KEY)
+        self.model = settings.COHERE_MODEL
+        self.mcp_context = mcp_server.create_context(user_id=user_id)
+
+    def create_user_scoped_tools(self) -> List[Dict[str, Any]]:
+        """
+        Create user-scoped tool definitions for Cohere function calling.
+
+        Converts OpenAI-style tool definitions to Cohere format.
+        """
+        openai_tools = [
+            get_list_tasks_definition(),
+            get_create_task_definition(),
+            get_mark_complete_definition(),
+            get_update_task_definition(),
+            get_delete_task_definition(),
+            get_get_task_definition()
+        ]
+
+        # Convert OpenAI format to Cohere format
+        cohere_tools = []
+        for tool in openai_tools:
+            func = tool["function"]
+            cohere_tool = {
+                "name": func["name"],
+                "description": func["description"],
+                "parameter_definitions": {}
+            }
+
+            # Convert parameters
+            if "parameters" in func and "properties" in func["parameters"]:
+                for param_name, param_info in func["parameters"]["properties"].items():
+                    cohere_tool["parameter_definitions"][param_name] = {
+                        "description": param_info.get("description", ""),
+                        "type": param_info.get("type", "string"),
+                        "required": param_name in func["parameters"].get("required", [])
+                    }
+
+            cohere_tools.append(cohere_tool)
+
+        return cohere_tools
+
+    async def execute_tool(self, tool_name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute a tool with the given arguments.
+        """
+        try:
+            # Get the tool handler from MCP server
+            tool_handler = mcp_server.get_tool(tool_name)
+
+            if not tool_handler:
+                return {"error": f"Tool '{tool_name}' not found"}
+
+            # Execute with user context
+            result = await tool_handler(self.mcp_context, **arguments)
+
+            return result
+
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def process_message(
+        self,
+        message: str,
+        conversation_history: List[Dict[str, str]]
+    ) -> Dict[str, Any]:
+        """
+        Process a user message using Cohere API.
+        """
+        try:
+            # Get tools
+            tools = self.create_user_scoped_tools()
+
+            # Convert conversation history to Cohere format
+            chat_history = []
+            for msg in conversation_history:
+                if msg["role"] == "user":
+                    chat_history.append({
+                        "role": "USER",
+                        "message": msg["content"]
+                    })
+                elif msg["role"] == "assistant":
+                    chat_history.append({
+                        "role": "CHATBOT",
+                        "message": msg["content"]
+                    })
+
+            # System message (preamble in Cohere)
+            preamble = """You are a helpful task management assistant for KIro Todo application.
+
+Your role is to help users manage their tasks through natural language conversation. You have access to tools for:
+- Listing tasks
+- Creating new tasks
+- Updating tasks
+- Deleting tasks
+- Marking tasks as complete/incomplete
+
+Be friendly, concise, and helpful. Always confirm actions clearly."""
+
+            # Call Cohere API with tools
+            response = self.client.chat(
+                model=self.model,
+                message=message,
+                chat_history=chat_history,
+                tools=tools,
+                preamble=preamble,
+                temperature=0.7
+            )
+
+            executed_tool_calls = []
+
+            # Check if model wants to use tools
+            if response.tool_calls:
+                # Execute each tool call
+                for tool_call in response.tool_calls:
+                    tool_name = tool_call.name
+                    tool_args = tool_call.parameters
+
+                    # Execute tool
+                    start_time = time.time()
+                    tool_result = await self.execute_tool(tool_name, tool_args)
+                    duration_ms = int((time.time() - start_time) * 1000)
+
+                    executed_tool_calls.append({
+                        "tool": tool_name,
+                        "parameters": tool_args,
+                        "result": tool_result,
+                        "duration_ms": duration_ms
+                    })
+
+                # Make second call with tool results
+                tool_results = [
+                    {
+                        "call": {
+                            "name": tc["tool"],
+                            "parameters": tc["parameters"]
+                        },
+                        "outputs": [tc["result"]]
+                    }
+                    for tc in executed_tool_calls
+                ]
+
+                final_response = self.client.chat(
+                    model=self.model,
+                    message=message,
+                    chat_history=chat_history,
+                    tools=tools,
+                    tool_results=tool_results,
+                    preamble=preamble,
+                    temperature=0.7
+                )
+
+                return {
+                    "content": final_response.text,
+                    "tool_calls": executed_tool_calls if executed_tool_calls else None,
+                    "model": self.model,
+                    "finish_reason": "complete"
+                }
+            else:
+                # No tool calls
+                return {
+                    "content": response.text,
+                    "tool_calls": None,
+                    "model": self.model,
+                    "finish_reason": "complete"
+                }
+
+        except Exception as e:
+            print(f"Error processing message with Cohere: {str(e)}")
+            raise
+
+    def format_conversation_history(
+        self,
+        messages: List[Any]
+    ) -> List[Dict[str, str]]:
+        """
+        Format database messages for Cohere API.
+        """
+        formatted = []
+        for msg in messages:
+            formatted.append({
+                "role": msg.role.value,
+                "content": msg.content
+            })
+        return formatted

src/services/conversation_service.py

@@ -0,0 +1,330 @@
+"""
+ConversationService for managing chat conversations and messages.
+
+This service handles CRUD operations for conversations, message creation
+with sequence numbering, and conversation history retrieval.
+"""
+from sqlmodel import Session, select, func
+from typing import List, Optional, Dict, Any
+from datetime import datetime
+from ..models.conversation import Conversation
+from ..models.message import Message, MessageRole
+
+
+class ConversationService:
+    """
+    Service for managing conversations and messages.
+
+    This service provides:
+    - Conversation CRUD operations
+    - Message creation with automatic sequence numbering
+    - Conversation history retrieval
+    - User-scoped data access
+    """
+
+    def __init__(self, session: Session):
+        """
+        Initialize the ConversationService.
+
+        Args:
+            session: SQLModel database session
+        """
+        self.session = session
+
+    def create_conversation(self, user_id: int) -> Conversation:
+        """
+        Create a new conversation for a user.
+
+        Args:
+            user_id: ID of the user creating the conversation
+
+        Returns:
+            Conversation: The newly created conversation
+
+        Raises:
+            Exception: If database operation fails
+        """
+        conversation = Conversation(
+            user_id=user_id,
+            created_at=datetime.utcnow(),
+            updated_at=datetime.utcnow()
+        )
+
+        self.session.add(conversation)
+        self.session.commit()
+        self.session.refresh(conversation)
+
+        return conversation
+
+    def get_conversation(
+        self,
+        conversation_id: int,
+        user_id: int
+    ) -> Optional[Conversation]:
+        """
+        Retrieve a specific conversation by ID.
+
+        This method enforces user_id scoping - users can only access
+        their own conversations.
+
+        Args:
+            conversation_id: ID of the conversation to retrieve
+            user_id: ID of the authenticated user
+
+        Returns:
+            Conversation if found and belongs to user, None otherwise
+        """
+        statement = select(Conversation).where(
+            Conversation.id == conversation_id,
+            Conversation.user_id == user_id
+        )
+        return self.session.exec(statement).first()
+
+    def list_conversations(
+        self,
+        user_id: int,
+        limit: int = 50,
+        offset: int = 0
+    ) -> List[Conversation]:
+        """
+        List all conversations for a user.
+
+        Conversations are returned in reverse chronological order
+        (most recent first).
+
+        Args:
+            user_id: ID of the authenticated user
+            limit: Maximum number of conversations to return (default: 50)
+            offset: Number of conversations to skip (default: 0)
+
+        Returns:
+            List of conversations belonging to the user
+        """
+        statement = (
+            select(Conversation)
+            .where(Conversation.user_id == user_id)
+            .order_by(Conversation.updated_at.desc())
+            .limit(limit)
+            .offset(offset)
+        )
+        return list(self.session.exec(statement).all())
+
+    def delete_conversation(
+        self,
+        conversation_id: int,
+        user_id: int
+    ) -> bool:
+        """
+        Delete a conversation and all its messages.
+
+        This method enforces user_id scoping - users can only delete
+        their own conversations.
+
+        Args:
+            conversation_id: ID of the conversation to delete
+            user_id: ID of the authenticated user
+
+        Returns:
+            True if conversation was deleted, False if not found
+        """
+        conversation = self.get_conversation(conversation_id, user_id)
+        if not conversation:
+            return False
+
+        self.session.delete(conversation)
+        self.session.commit()
+        return True
+
+    def create_message(
+        self,
+        conversation_id: int,
+        user_id: int,
+        role: MessageRole,
+        content: str,
+        tool_calls: Optional[Dict[str, Any]] = None
+    ) -> Optional[Message]:
+        """
+        Create a new message in a conversation with automatic sequence numbering.
+
+        This method:
+        1. Verifies the conversation exists and belongs to the user
+        2. Calculates the next sequence number
+        3. Creates the message with proper sequencing
+        4. Updates the conversation's updated_at timestamp
+
+        Args:
+            conversation_id: ID of the conversation
+            user_id: ID of the authenticated user
+            role: Message role (USER or ASSISTANT)
+            content: Message content
+            tool_calls: Optional tool call metadata
+
+        Returns:
+            Message if created successfully, None if conversation not found
+
+        Raises:
+            Exception: If database operation fails
+        """
+        # Verify conversation exists and belongs to user
+        conversation = self.get_conversation(conversation_id, user_id)
+        if not conversation:
+            return None
+
+        # Get next sequence number
+        sequence_number = self._get_next_sequence_number(conversation_id)
+
+        # Create message
+        message = Message(
+            conversation_id=conversation_id,
+            role=role,
+            content=content,
+            tool_calls=tool_calls,
+            sequence_number=sequence_number,
+            created_at=datetime.utcnow()
+        )
+
+        self.session.add(message)
+
+        # Update conversation timestamp
+        conversation.updated_at = datetime.utcnow()
+        self.session.add(conversation)
+
+        self.session.commit()
+        self.session.refresh(message)
+
+        return message
+
+    def get_conversation_history(
+        self,
+        conversation_id: int,
+        user_id: int,
+        include_deleted: bool = False
+    ) -> List[Message]:
+        """
+        Retrieve all messages in a conversation in chronological order.
+
+        This method enforces user_id scoping - users can only access
+        messages from their own conversations.
+
+        Args:
+            conversation_id: ID of the conversation
+            user_id: ID of the authenticated user
+            include_deleted: Whether to include soft-deleted messages (default: False)
+
+        Returns:
+            List of messages ordered by sequence_number (oldest first)
+            Empty list if conversation not found or doesn't belong to user
+        """
+        # Verify conversation exists and belongs to user
+        conversation = self.get_conversation(conversation_id, user_id)
+        if not conversation:
+            return []
+
+        # Build query
+        statement = (
+            select(Message)
+            .where(Message.conversation_id == conversation_id)
+            .order_by(Message.sequence_number.asc())
+        )
+
+        # Filter out deleted messages unless requested
+        if not include_deleted:
+            statement = statement.where(Message.deleted_at.is_(None))
+
+        return list(self.session.exec(statement).all())
+
+    def get_message_count(
+        self,
+        conversation_id: int,
+        user_id: int
+    ) -> int:
+        """
+        Get the total number of messages in a conversation.
+
+        Args:
+            conversation_id: ID of the conversation
+            user_id: ID of the authenticated user
+
+        Returns:
+            Number of messages (excluding deleted), 0 if conversation not found
+        """
+        # Verify conversation exists and belongs to user
+        conversation = self.get_conversation(conversation_id, user_id)
+        if not conversation:
+            return 0
+
+        statement = (
+            select(func.count(Message.id))
+            .where(
+                Message.conversation_id == conversation_id,
+                Message.deleted_at.is_(None)
+            )
+        )
+        return self.session.exec(statement).one()
+
+    def _get_next_sequence_number(self, conversation_id: int) -> int:
+        """
+        Calculate the next sequence number for a message in a conversation.
+
+        This method finds the highest existing sequence number and adds 1.
+        If no messages exist, returns 1.
+
+        Args:
+            conversation_id: ID of the conversation
+
+        Returns:
+            Next sequence number to use
+        """
+        statement = (
+            select(func.max(Message.sequence_number))
+            .where(Message.conversation_id == conversation_id)
+        )
+        max_sequence = self.session.exec(statement).one()
+
+        # If no messages exist, start at 1
+        if max_sequence is None:
+            return 1
+
+        return max_sequence + 1
+
+    def soft_delete_message(
+        self,
+        message_id: int,
+        conversation_id: int,
+        user_id: int
+    ) -> bool:
+        """
+        Soft delete a message (set deleted_at timestamp).
+
+        This method enforces user_id scoping - users can only delete
+        messages from their own conversations.
+
+        Args:
+            message_id: ID of the message to delete
+            conversation_id: ID of the conversation
+            user_id: ID of the authenticated user
+
+        Returns:
+            True if message was deleted, False if not found
+        """
+        # Verify conversation belongs to user
+        conversation = self.get_conversation(conversation_id, user_id)
+        if not conversation:
+            return False
+
+        # Find message
+        statement = select(Message).where(
+            Message.id == message_id,
+            Message.conversation_id == conversation_id
+        )
+        message = self.session.exec(statement).first()
+
+        if not message:
+            return False
+
+        # Soft delete
+        message.deleted_at = datetime.utcnow()
+        self.session.add(message)
+        self.session.commit()
+
+        return True

src/tools/__init__.py

@@ -0,0 +1,40 @@
+"""
+MCP Tools Package
+
+This package contains all MCP tools for the AI agent.
+Tools are user-scoped and enforce data isolation.
+"""
+
+from .mcp_server import MCPServer, MCPContext, mcp_server
+from .list_tasks import list_tasks_internal, get_tool_definition as get_list_tasks_definition
+from .create_task import create_task_internal, get_tool_definition as get_create_task_definition
+from .mark_complete import mark_complete_internal, get_tool_definition as get_mark_complete_definition
+from .update_task import update_task_internal, get_tool_definition as get_update_task_definition
+from .delete_task import delete_task_internal, get_tool_definition as get_delete_task_definition
+from .get_task import get_task_internal, get_tool_definition as get_get_task_definition
+
+# Register tools with MCP server
+mcp_server.register_tool("list_tasks", list_tasks_internal)
+mcp_server.register_tool("create_task", create_task_internal)
+mcp_server.register_tool("mark_complete", mark_complete_internal)
+mcp_server.register_tool("update_task", update_task_internal)
+mcp_server.register_tool("delete_task", delete_task_internal)
+mcp_server.register_tool("get_task", get_task_internal)
+
+__all__ = [
+    "MCPServer",
+    "MCPContext",
+    "mcp_server",
+    "list_tasks_internal",
+    "create_task_internal",
+    "mark_complete_internal",
+    "update_task_internal",
+    "delete_task_internal",
+    "get_task_internal",
+    "get_list_tasks_definition",
+    "get_create_task_definition",
+    "get_mark_complete_definition",
+    "get_update_task_definition",
+    "get_delete_task_definition",
+    "get_get_task_definition",
+]

src/tools/create_task.py

@@ -0,0 +1,133 @@
+"""
+Create Task MCP Tool
+
+This tool enables the AI agent to create new tasks for the authenticated user.
+Enforces user_id scoping and validates input parameters.
+"""
+
+from typing import Dict, Any
+from sqlmodel import Session
+from datetime import datetime
+from ..models.task import Task
+from .mcp_server import MCPContext
+
+
+async def create_task_internal(
+    ctx: MCPContext,
+    title: str,
+    description: str = ""
+) -> Dict[str, Any]:
+    """
+    Internal MCP tool for creating a new task.
+
+    This function is called by the AgentService with user_id pre-bound.
+    It creates a task in the database and returns structured result.
+
+    Args:
+        ctx: MCP context containing db_engine and user_id
+        title: Task title (required, 1-200 chars)
+        description: Task description (optional, max 2000 chars)
+
+    Returns:
+        Dict containing:
+            - task: Created task details (id, title, description, completed, timestamps)
+            - status: "success" or "error"
+            - error: Error message (only if status is "error")
+
+    Error Cases:
+        - Empty title: Returns error "Title is required"
+        - Title too long: Returns error "Title exceeds 200 characters"
+        - Database error: Returns error with message
+    """
+    try:
+        # Validate title
+        if not title or title.strip() == "":
+            return {
+                "status": "error",
+                "error": "Title is required"
+            }
+
+        title = title.strip()
+
+        if len(title) > 200:
+            return {
+                "status": "error",
+                "error": "Title exceeds 200 characters"
+            }
+
+        # Validate description length
+        if description and len(description) > 2000:
+            return {
+                "status": "error",
+                "error": "Description exceeds 2000 characters"
+            }
+
+        # Create task in database
+        with ctx.get_session() as session:
+            task = Task(
+                title=title,
+                description=description if description else None,
+                completed=False,
+                user_id=ctx.user_id,
+                created_at=datetime.utcnow(),
+                updated_at=datetime.utcnow()
+            )
+
+            session.add(task)
+            session.commit()
+            session.refresh(task)
+
+            # Return structured result
+            return {
+                "status": "success",
+                "task": {
+                    "id": task.id,
+                    "title": task.title,
+                    "description": task.description,
+                    "completed": task.completed,
+                    "created_at": task.created_at.isoformat(),
+                    "updated_at": task.updated_at.isoformat()
+                }
+            }
+
+    except Exception as e:
+        # Log error and return structured error response
+        print(f"Error creating task: {str(e)}")
+        return {
+            "status": "error",
+            "error": f"Database error: {str(e)}"
+        }
+
+
+def get_tool_definition() -> Dict[str, Any]:
+    """
+    Get OpenAI function calling definition for create_task tool.
+
+    Returns:
+        Tool definition in OpenAI function calling format
+    """
+    return {
+        "type": "function",
+        "function": {
+            "name": "create_task",
+            "description": (
+                "Create a new task for the user. "
+                "Use this when the user wants to add a task, reminder, or todo item. "
+                "Examples: 'remind me to X', 'add task X', 'I need to X', 'create a task for X'."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "title": {
+                        "type": "string",
+                        "description": "The task title or main description (required, 1-200 characters)"
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Additional details or notes about the task (optional, max 2000 characters)"
+                    }
+                },
+                "required": ["title"]
+            }
+        }
+    }

src/tools/delete_task.py

@@ -0,0 +1,106 @@
+"""
+Delete Task MCP Tool
+
+This tool enables the AI agent to permanently delete tasks.
+Enforces user_id scoping for security.
+"""
+
+from typing import Dict, Any
+from sqlmodel import Session, select
+from ..models.task import Task
+from .mcp_server import MCPContext
+
+
+async def delete_task_internal(
+    ctx: MCPContext,
+    task_id: int
+) -> Dict[str, Any]:
+    """
+    Internal MCP tool for deleting a task.
+
+    This function is called by the AgentService with user_id pre-bound.
+    It permanently removes the task from the database.
+
+    Args:
+        ctx: MCP context containing db_engine and user_id
+        task_id: ID of the task to delete
+
+    Returns:
+        Dict containing:
+            - status: "success" or "error"
+            - message: Confirmation message
+            - deleted_task_id: ID of the deleted task
+            - error: Error message (only if status is "error")
+
+    Error Cases:
+        - Task not found: Returns error "Task not found"
+        - Task belongs to different user: Returns error "Task not found" (security)
+        - Database error: Returns error with message
+    """
+    try:
+        # Query task with user_id scoping for security
+        with ctx.get_session() as session:
+            statement = select(Task).where(
+                Task.id == task_id,
+                Task.user_id == ctx.user_id
+            )
+            task = session.exec(statement).first()
+
+            if not task:
+                return {
+                    "status": "error",
+                    "error": "Task not found"
+                }
+
+            # Store task title for confirmation message
+            task_title = task.title
+
+            # Delete task
+            session.delete(task)
+            session.commit()
+
+            # Return structured result
+            return {
+                "status": "success",
+                "message": f"Task '{task_title}' deleted successfully",
+                "deleted_task_id": task_id
+            }
+
+    except Exception as e:
+        # Log error and return structured error response
+        print(f"Error deleting task: {str(e)}")
+        return {
+            "status": "error",
+            "error": f"Database error: {str(e)}"
+        }
+
+
+def get_tool_definition() -> Dict[str, Any]:
+    """
+    Get OpenAI function calling definition for delete_task tool.
+
+    Returns:
+        Tool definition in OpenAI function calling format
+    """
+    return {
+        "type": "function",
+        "function": {
+            "name": "delete_task",
+            "description": (
+                "Permanently delete a task. "
+                "Use this when the user wants to remove, delete, or cancel a task. "
+                "Examples: 'delete X', 'remove the task', 'cancel task 3', "
+                "'get rid of X', 'delete my first task'."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task_id": {
+                        "type": "integer",
+                        "description": "The ID of the task to delete"
+                    }
+                },
+                "required": ["task_id"]
+            }
+        }
+    }

src/tools/get_task.py

@@ -0,0 +1,112 @@
+"""
+Get Task MCP Tool
+
+This tool enables the AI agent to retrieve details of a specific task by ID.
+Useful for multi-step operations and context-aware task references.
+"""
+
+from typing import Dict, Any
+from sqlmodel import Session, select
+from ..models.task import Task
+from .mcp_server import MCPContext
+
+
+async def get_task_internal(
+    ctx: MCPContext,
+    task_id: int
+) -> Dict[str, Any]:
+    """
+    Internal MCP tool for retrieving a specific task by ID.
+
+    This function is called by the AgentService with user_id pre-bound.
+    It retrieves detailed information about a single task.
+
+    Args:
+        ctx: MCP context containing db_engine and user_id
+        task_id: ID of the task to retrieve
+
+    Returns:
+        Dict containing:
+            - task: Task details (id, title, description, completed, timestamps)
+            - status: "success" or "error"
+            - error: Error message (only if status is "error")
+
+    Error Cases:
+        - Task not found: Returns error "Task not found"
+        - Task belongs to different user: Returns error "Task not found" (security)
+        - Invalid task_id: Returns error "Invalid task ID"
+        - Database error: Returns error with message
+    """
+    try:
+        # Validate task_id
+        if not isinstance(task_id, int) or task_id <= 0:
+            return {
+                "status": "error",
+                "error": "Invalid task ID"
+            }
+
+        # Query task with user_id scoping for security
+        with ctx.get_session() as session:
+            statement = select(Task).where(
+                Task.id == task_id,
+                Task.user_id == ctx.user_id
+            )
+            task = session.exec(statement).first()
+
+            if not task:
+                return {
+                    "status": "error",
+                    "error": "Task not found"
+                }
+
+            # Return structured result
+            return {
+                "status": "success",
+                "task": {
+                    "id": task.id,
+                    "title": task.title,
+                    "description": task.description,
+                    "completed": task.completed,
+                    "created_at": task.created_at.isoformat(),
+                    "updated_at": task.updated_at.isoformat()
+                }
+            }
+
+    except Exception as e:
+        # Log error and return structured error response
+        print(f"Error getting task: {str(e)}")
+        return {
+            "status": "error",
+            "error": f"Database error: {str(e)}"
+        }
+
+
+def get_tool_definition() -> Dict[str, Any]:
+    """
+    Get OpenAI function calling definition for get_task tool.
+
+    Returns:
+        Tool definition in OpenAI function calling format
+    """
+    return {
+        "type": "function",
+        "function": {
+            "name": "get_task",
+            "description": (
+                "Retrieve detailed information about a specific task by its ID. "
+                "Use this when the user asks for details about a particular task. "
+                "Examples: 'show me task 5', 'what's in task 3', 'details of the first task', "
+                "'tell me about task 10'."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task_id": {
+                        "type": "integer",
+                        "description": "The ID of the task to retrieve"
+                    }
+                },
+                "required": ["task_id"]
+            }
+        }
+    }

src/tools/list_tasks.py

@@ -0,0 +1,101 @@
+"""
+List Tasks MCP Tool
+
+This tool enables the AI agent to retrieve all tasks for the authenticated user.
+Returns task list with completion status and counts.
+"""
+
+from typing import Dict, Any, List
+from sqlmodel import Session, select
+from ..models.task import Task
+from .mcp_server import MCPContext
+
+
+async def list_tasks_internal(ctx: MCPContext) -> Dict[str, Any]:
+    """
+    Internal MCP tool for listing all tasks for the authenticated user.
+
+    This function is called by the AgentService with user_id pre-bound.
+    It retrieves all tasks from the database and returns structured result.
+
+    Args:
+        ctx: MCP context containing db_engine and user_id
+
+    Returns:
+        Dict containing:
+            - tasks: List of task objects with all fields
+            - total: Total number of tasks
+            - completed_count: Number of completed tasks
+            - pending_count: Number of incomplete tasks
+
+    Error Cases:
+        - Database connection failure: Returns error with message
+        - No tasks found: Returns empty array (not an error)
+    """
+    try:
+        # Query tasks for user
+        with ctx.get_session() as session:
+            statement = select(Task).where(Task.user_id == ctx.user_id)
+            tasks = session.exec(statement).all()
+
+            # Convert tasks to dict format
+            task_list = []
+            for task in tasks:
+                task_list.append({
+                    "id": task.id,
+                    "title": task.title,
+                    "description": task.description,
+                    "completed": task.completed,
+                    "created_at": task.created_at.isoformat(),
+                    "updated_at": task.updated_at.isoformat()
+                })
+
+            # Calculate counts
+            completed_count = sum(1 for t in tasks if t.completed)
+            pending_count = sum(1 for t in tasks if not t.completed)
+
+            return {
+                "tasks": task_list,
+                "total": len(tasks),
+                "completed_count": completed_count,
+                "pending_count": pending_count
+            }
+
+    except Exception as e:
+        # Log error and return structured error response
+        print(f"Error listing tasks: {str(e)}")
+        return {
+            "status": "error",
+            "error": f"Database error: {str(e)}",
+            "tasks": [],
+            "total": 0,
+            "completed_count": 0,
+            "pending_count": 0
+        }
+
+
+def get_tool_definition() -> Dict[str, Any]:
+    """
+    Get OpenAI function calling definition for list_tasks tool.
+
+    Returns:
+        Tool definition in OpenAI function calling format
+    """
+    return {
+        "type": "function",
+        "function": {
+            "name": "list_tasks",
+            "description": (
+                "Retrieve all tasks for the user with their completion status. "
+                "Use this when the user wants to see their tasks, check what they need to do, "
+                "or inquire about their task list. "
+                "Examples: 'show my tasks', 'what do I need to do', 'list my todos', "
+                "'what are my tasks', 'show me my task list'."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {},
+                "required": []
+            }
+        }
+    }

src/tools/mark_complete.py

@@ -0,0 +1,115 @@
+"""
+Mark Complete MCP Tool
+
+This tool enables the AI agent to toggle task completion status.
+Supports marking tasks as complete or incomplete.
+"""
+
+from typing import Dict, Any
+from sqlmodel import Session, select
+from datetime import datetime
+from ..models.task import Task
+from .mcp_server import MCPContext
+
+
+async def mark_complete_internal(
+    ctx: MCPContext,
+    task_id: int
+) -> Dict[str, Any]:
+    """
+    Internal MCP tool for toggling task completion status.
+
+    This function is called by the AgentService with user_id pre-bound.
+    It finds the task and toggles its completed status.
+
+    Args:
+        ctx: MCP context containing db_engine and user_id
+        task_id: ID of the task to mark complete/incomplete
+
+    Returns:
+        Dict containing:
+            - task: Updated task details
+            - status: "success" or "error"
+            - action: "marked_complete" or "marked_incomplete"
+            - error: Error message (only if status is "error")
+
+    Error Cases:
+        - Task not found: Returns error "Task not found"
+        - Task belongs to different user: Returns error "Task not found" (security)
+        - Database error: Returns error with message
+    """
+    try:
+        # Query task with user_id scoping for security
+        with ctx.get_session() as session:
+            statement = select(Task).where(
+                Task.id == task_id,
+                Task.user_id == ctx.user_id
+            )
+            task = session.exec(statement).first()
+
+            if not task:
+                return {
+                    "status": "error",
+                    "error": "Task not found"
+                }
+
+            # Toggle completion status
+            task.completed = not task.completed
+            task.updated_at = datetime.utcnow()
+
+            session.add(task)
+            session.commit()
+            session.refresh(task)
+
+            # Return structured result
+            return {
+                "status": "success",
+                "action": "marked_complete" if task.completed else "marked_incomplete",
+                "task": {
+                    "id": task.id,
+                    "title": task.title,
+                    "description": task.description,
+                    "completed": task.completed,
+                    "created_at": task.created_at.isoformat(),
+                    "updated_at": task.updated_at.isoformat()
+                }
+            }
+
+    except Exception as e:
+        # Log error and return structured error response
+        print(f"Error marking task complete: {str(e)}")
+        return {
+            "status": "error",
+            "error": f"Database error: {str(e)}"
+        }
+
+
+def get_tool_definition() -> Dict[str, Any]:
+    """
+    Get OpenAI function calling definition for mark_complete tool.
+
+    Returns:
+        Tool definition in OpenAI function calling format
+    """
+    return {
+        "type": "function",
+        "function": {
+            "name": "mark_complete",
+            "description": (
+                "Toggle the completion status of a task (mark as complete or incomplete). "
+                "Use this when the user indicates they finished a task or wants to mark it as done. "
+                "Examples: 'I finished X', 'mark X as done', 'complete the task', "
+                "'I completed X', 'mark task 5 as complete'."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task_id": {
+                        "type": "integer",
+                        "description": "The ID of the task to mark as complete/incomplete"
+                    }
+                },
+                "required": ["task_id"]
+            }
+        }
+    }

src/tools/mcp_server.py

@@ -0,0 +1,113 @@
+"""
+MCP Server Setup Module
+
+This module provides the MCP server configuration and context setup for the AI agent.
+MCP tools are embedded in the FastAPI process for security and performance.
+"""
+
+from typing import Dict, Any, Optional
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlmodel import Session
+from ..database import engine
+
+
+class MCPContext:
+    """
+    MCP Context configuration containing shared resources for MCP tools.
+
+    This context is passed to all MCP tools to provide access to:
+    - Database engine for query execution
+    - User ID for data isolation
+    - Configuration settings
+    """
+
+    def __init__(
+        self,
+        db_engine: AsyncEngine,
+        user_id: int,
+        config: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Initialize MCP context.
+
+        Args:
+            db_engine: SQLAlchemy async engine for database operations
+            user_id: Authenticated user ID for data scoping
+            config: Optional configuration dictionary
+        """
+        self.db_engine = db_engine
+        self.user_id = user_id
+        self.config = config or {}
+
+    def get_session(self) -> Session:
+        """
+        Create a new database session.
+
+        Returns:
+            SQLModel Session instance
+        """
+        return Session(self.db_engine)
+
+
+class MCPServer:
+    """
+    MCP Server setup and configuration.
+
+    This class manages the MCP server lifecycle and tool registration.
+    In embedded mode, tools are registered directly in the FastAPI process.
+    """
+
+    def __init__(self):
+        """Initialize MCP server."""
+        self.tools = {}
+        self.db_engine = engine
+
+    def register_tool(self, name: str, tool_func: callable):
+        """
+        Register an MCP tool.
+
+        Args:
+            name: Tool name (e.g., "list_tasks")
+            tool_func: Tool function to execute
+        """
+        self.tools[name] = tool_func
+
+    def create_context(self, user_id: int) -> MCPContext:
+        """
+        Create a user-scoped MCP context.
+
+        Args:
+            user_id: Authenticated user ID
+
+        Returns:
+            MCPContext instance with user_id pre-bound
+        """
+        return MCPContext(
+            db_engine=self.db_engine,
+            user_id=user_id
+        )
+
+    def get_tool(self, name: str) -> Optional[callable]:
+        """
+        Get a registered tool by name.
+
+        Args:
+            name: Tool name
+
+        Returns:
+            Tool function or None if not found
+        """
+        return self.tools.get(name)
+
+    def list_tools(self) -> list[str]:
+        """
+        List all registered tool names.
+
+        Returns:
+            List of tool names
+        """
+        return list(self.tools.keys())
+
+
+# Global MCP server instance
+mcp_server = MCPServer()

src/tools/update_task.py

@@ -0,0 +1,160 @@
+"""
+Update Task MCP Tool
+
+This tool enables the AI agent to update existing task details.
+Supports updating title and/or description.
+"""
+
+from typing import Dict, Any, Optional
+from sqlmodel import Session, select
+from datetime import datetime
+from ..models.task import Task
+from .mcp_server import MCPContext
+
+
+async def update_task_internal(
+    ctx: MCPContext,
+    task_id: int,
+    title: Optional[str] = None,
+    description: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Internal MCP tool for updating a task's details.
+
+    This function is called by the AgentService with user_id pre-bound.
+    It updates the task's title and/or description.
+
+    Args:
+        ctx: MCP context containing db_engine and user_id
+        task_id: ID of the task to update
+        title: New task title (optional, 1-200 chars)
+        description: New task description (optional, max 2000 chars)
+
+    Returns:
+        Dict containing:
+            - task: Updated task details
+            - status: "success" or "error"
+            - error: Error message (only if status is "error")
+
+    Error Cases:
+        - Task not found: Returns error "Task not found"
+        - Task belongs to different user: Returns error "Task not found" (security)
+        - Empty title: Returns error "Title cannot be empty"
+        - Title too long: Returns error "Title exceeds 200 characters"
+        - No fields to update: Returns error "No fields provided to update"
+        - Database error: Returns error with message
+    """
+    try:
+        # Validate that at least one field is provided
+        if title is None and description is None:
+            return {
+                "status": "error",
+                "error": "No fields provided to update"
+            }
+
+        # Validate title if provided
+        if title is not None:
+            title = title.strip()
+            if not title:
+                return {
+                    "status": "error",
+                    "error": "Title cannot be empty"
+                }
+            if len(title) > 200:
+                return {
+                    "status": "error",
+                    "error": "Title exceeds 200 characters"
+                }
+
+        # Validate description length if provided
+        if description is not None and len(description) > 2000:
+            return {
+                "status": "error",
+                "error": "Description exceeds 2000 characters"
+            }
+
+        # Query task with user_id scoping for security
+        with ctx.get_session() as session:
+            statement = select(Task).where(
+                Task.id == task_id,
+                Task.user_id == ctx.user_id
+            )
+            task = session.exec(statement).first()
+
+            if not task:
+                return {
+                    "status": "error",
+                    "error": "Task not found"
+                }
+
+            # Update fields
+            if title is not None:
+                task.title = title
+            if description is not None:
+                task.description = description
+
+            task.updated_at = datetime.utcnow()
+
+            session.add(task)
+            session.commit()
+            session.refresh(task)
+
+            # Return structured result
+            return {
+                "status": "success",
+                "task": {
+                    "id": task.id,
+                    "title": task.title,
+                    "description": task.description,
+                    "completed": task.completed,
+                    "created_at": task.created_at.isoformat(),
+                    "updated_at": task.updated_at.isoformat()
+                }
+            }
+
+    except Exception as e:
+        # Log error and return structured error response
+        print(f"Error updating task: {str(e)}")
+        return {
+            "status": "error",
+            "error": f"Database error: {str(e)}"
+        }
+
+
+def get_tool_definition() -> Dict[str, Any]:
+    """
+    Get OpenAI function calling definition for update_task tool.
+
+    Returns:
+        Tool definition in OpenAI function calling format
+    """
+    return {
+        "type": "function",
+        "function": {
+            "name": "update_task",
+            "description": (
+                "Update an existing task's title or description. "
+                "Use this when the user wants to modify, change, or edit a task. "
+                "Examples: 'change X to Y', 'update the task', 'edit task 3', "
+                "'rename X to Y', 'add details to the task'."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task_id": {
+                        "type": "integer",
+                        "description": "The ID of the task to update"
+                    },
+                    "title": {
+                        "type": "string",
+                        "description": "New task title (optional, 1-200 characters)"
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "New task description (optional, max 2000 characters)"
+                    }
+                },
+                "required": ["task_id"]
+            }
+        }
+    }

src/utils/logging.py

@@ -0,0 +1,193 @@
+"""
+Structured Logging Utility
+
+Provides structured logging for agent operations, tool invocations, and errors.
+Enables better debugging and monitoring in production.
+"""
+
+import logging
+import json
+from datetime import datetime
+from typing import Dict, Any, Optional
+import sys
+
+
+class StructuredLogger:
+    """
+    Structured logger for application events.
+
+    Logs events in JSON format for easy parsing and analysis.
+    """
+
+    def __init__(self, name: str, level: int = logging.INFO):
+        """
+        Initialize structured logger.
+
+        Args:
+            name: Logger name (typically module name)
+            level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        """
+        self.logger = logging.getLogger(name)
+        self.logger.setLevel(level)
+
+        # Create console handler with JSON formatter
+        if not self.logger.handlers:
+            handler = logging.StreamHandler(sys.stdout)
+            handler.setLevel(level)
+            self.logger.addHandler(handler)
+
+    def _log(
+        self,
+        level: int,
+        event: str,
+        **kwargs: Any
+    ):
+        """
+        Log structured event.
+
+        Args:
+            level: Logging level
+            event: Event name/description
+            **kwargs: Additional context fields
+        """
+        log_entry = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "event": event,
+            **kwargs
+        }
+
+        self.logger.log(level, json.dumps(log_entry))
+
+    def info(self, event: str, **kwargs: Any):
+        """Log info level event."""
+        self._log(logging.INFO, event, **kwargs)
+
+    def warning(self, event: str, **kwargs: Any):
+        """Log warning level event."""
+        self._log(logging.WARNING, event, **kwargs)
+
+    def error(self, event: str, error: Optional[Exception] = None, **kwargs: Any):
+        """Log error level event."""
+        if error:
+            kwargs["error_type"] = type(error).__name__
+            kwargs["error_message"] = str(error)
+        self._log(logging.ERROR, event, **kwargs)
+
+    def debug(self, event: str, **kwargs: Any):
+        """Log debug level event."""
+        self._log(logging.DEBUG, event, **kwargs)
+
+    def agent_operation(
+        self,
+        user_id: int,
+        conversation_id: int,
+        message: str,
+        response: str,
+        tool_calls: Optional[list] = None,
+        duration_ms: Optional[int] = None
+    ):
+        """
+        Log agent operation with full context.
+
+        Args:
+            user_id: User identifier
+            conversation_id: Conversation identifier
+            message: User message
+            response: Agent response
+            tool_calls: List of tool invocations
+            duration_ms: Operation duration in milliseconds
+        """
+        self.info(
+            "agent_operation",
+            user_id=user_id,
+            conversation_id=conversation_id,
+            message_length=len(message),
+            response_length=len(response),
+            tool_calls_count=len(tool_calls) if tool_calls else 0,
+            tools_used=[tc.get("tool") for tc in tool_calls] if tool_calls else [],
+            duration_ms=duration_ms
+        )
+
+    def tool_invocation(
+        self,
+        user_id: int,
+        tool_name: str,
+        parameters: Dict[str, Any],
+        result: Dict[str, Any],
+        duration_ms: int
+    ):
+        """
+        Log MCP tool invocation.
+
+        Args:
+            user_id: User identifier
+            tool_name: Name of the tool
+            parameters: Tool parameters
+            result: Tool result
+            duration_ms: Execution duration in milliseconds
+        """
+        self.info(
+            "tool_invocation",
+            user_id=user_id,
+            tool=tool_name,
+            parameters=parameters,
+            status=result.get("status", "unknown"),
+            duration_ms=duration_ms
+        )
+
+    def api_request(
+        self,
+        method: str,
+        path: str,
+        user_id: Optional[int] = None,
+        status_code: Optional[int] = None,
+        duration_ms: Optional[int] = None
+    ):
+        """
+        Log API request.
+
+        Args:
+            method: HTTP method
+            path: Request path
+            user_id: User identifier (if authenticated)
+            status_code: Response status code
+            duration_ms: Request duration in milliseconds
+        """
+        self.info(
+            "api_request",
+            method=method,
+            path=path,
+            user_id=user_id,
+            status_code=status_code,
+            duration_ms=duration_ms
+        )
+
+    def rate_limit_exceeded(
+        self,
+        user_id: int,
+        endpoint: str,
+        limit: int,
+        reset_time: int
+    ):
+        """
+        Log rate limit exceeded event.
+
+        Args:
+            user_id: User identifier
+            endpoint: API endpoint
+            limit: Rate limit threshold
+            reset_time: When limit resets (unix timestamp)
+        """
+        self.warning(
+            "rate_limit_exceeded",
+            user_id=user_id,
+            endpoint=endpoint,
+            limit=limit,
+            reset_time=reset_time
+        )
+
+
+# Global logger instances
+agent_logger = StructuredLogger("agent", level=logging.INFO)
+api_logger = StructuredLogger("api", level=logging.INFO)
+tool_logger = StructuredLogger("tools", level=logging.INFO)

src/utils/validation.py

@@ -0,0 +1,149 @@
+"""
+Input Sanitization and Validation Utilities
+
+Provides utilities for sanitizing and validating user input.
+Prevents injection attacks and ensures data integrity.
+"""
+
+import re
+from typing import Optional
+import html
+
+
+def sanitize_message_content(content: str, max_length: int = 2000) -> str:
+    """
+    Sanitize user message content.
+
+    Args:
+        content: Raw user input
+        max_length: Maximum allowed length
+
+    Returns:
+        Sanitized content
+
+    Raises:
+        ValueError: If content is invalid
+    """
+    if not content or not isinstance(content, str):
+        raise ValueError("Message content must be a non-empty string")
+
+    # Strip whitespace
+    content = content.strip()
+
+    if not content:
+        raise ValueError("Message content cannot be empty")
+
+    # Check length
+    if len(content) > max_length:
+        raise ValueError(f"Message content exceeds {max_length} characters")
+
+    # HTML escape to prevent XSS
+    content = html.escape(content)
+
+    # Remove null bytes
+    content = content.replace('\x00', '')
+
+    # Normalize whitespace (replace multiple spaces with single space)
+    content = re.sub(r'\s+', ' ', content)
+
+    return content
+
+
+def validate_conversation_id(conversation_id: Optional[int]) -> Optional[int]:
+    """
+    Validate conversation ID.
+
+    Args:
+        conversation_id: Conversation ID to validate
+
+    Returns:
+        Validated conversation ID or None
+
+    Raises:
+        ValueError: If conversation_id is invalid
+    """
+    if conversation_id is None:
+        return None
+
+    if not isinstance(conversation_id, int):
+        raise ValueError("Conversation ID must be an integer")
+
+    if conversation_id <= 0:
+        raise ValueError("Conversation ID must be positive")
+
+    return conversation_id
+
+
+def validate_task_title(title: str, max_length: int = 200) -> str:
+    """
+    Validate and sanitize task title.
+
+    Args:
+        title: Task title
+        max_length: Maximum allowed length
+
+    Returns:
+        Sanitized title
+
+    Raises:
+        ValueError: If title is invalid
+    """
+    if not title or not isinstance(title, str):
+        raise ValueError("Title must be a non-empty string")
+
+    # Strip whitespace
+    title = title.strip()
+
+    if not title:
+        raise ValueError("Title cannot be empty")
+
+    # Check length
+    if len(title) > max_length:
+        raise ValueError(f"Title exceeds {max_length} characters")
+
+    # HTML escape
+    title = html.escape(title)
+
+    # Remove null bytes
+    title = title.replace('\x00', '')
+
+    return title
+
+
+def validate_task_description(description: Optional[str], max_length: int = 2000) -> Optional[str]:
+    """
+    Validate and sanitize task description.
+
+    Args:
+        description: Task description
+        max_length: Maximum allowed length
+
+    Returns:
+        Sanitized description or None
+
+    Raises:
+        ValueError: If description is invalid
+    """
+    if description is None or description == "":
+        return None
+
+    if not isinstance(description, str):
+        raise ValueError("Description must be a string")
+
+    # Strip whitespace
+    description = description.strip()
+
+    if not description:
+        return None
+
+    # Check length
+    if len(description) > max_length:
+        raise ValueError(f"Description exceeds {max_length} characters")
+
+    # HTML escape
+    description = html.escape(description)
+
+    # Remove null bytes
+    description = description.replace('\x00', '')
+
+    return description