chatbot

.dockerignore

@@ -43,3 +43,21 @@ alembic/versions/*.pyc
 
 # Documentation
 docs/_build/
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Environment
+.env
+
+# Alembic cache
+alembic/versions/__pycache__/
+
+# Node
+node_modules/
+package-lock.json
+
+# Temp / AI tools
+tmpclaude-*

.env

@@ -2,6 +2,7 @@
 # For local PostgreSQL: postgresql://user:password@localhost:5432/todo_db
 # For Neon: Use your Neon connection string from the dashboard
 DATABASE_URL=postgresql://neondb_owner:npg_MmFvJBHT8Y0k@ep-silent-thunder-ab0rbvrp-pooler.eu-west-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require
+
 # Application Settings
 APP_NAME=Task CRUD API
 DEBUG=True
@@ -11,3 +12,18 @@ CORS_ORIGINS=http://localhost:3000
 BETTER_AUTH_SECRET=zMdW1P03wJvWJnLKzQ8YYO26vHeinqmR
 JWT_ALGORITHM=HS256
 JWT_EXPIRATION_DAYS=7
+
+# LLM Provider Configuration
+LLM_PROVIDER=gemini
+# FALLBACK_PROVIDER=openrouter
+GEMINI_API_KEY=AIzaSyCAlcHZxp5ELh1GqJwKqBLQziUNi0vnobU
+# OPENROUTER_API_KEY=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
+COHERE_API_KEY=
+
+# Agent Configuration
+AGENT_TEMPERATURE=0.7
+AGENT_MAX_TOKENS=500
+
+# Conversation Settings
+CONVERSATION_MAX_MESSAGES=20
+CONVERSATION_MAX_TOKENS=2000

.env.example

@@ -6,7 +6,32 @@ APP_NAME=Task CRUD API
 DEBUG=True
 CORS_ORIGINS=http://localhost:3000
 
-# Authentication (Placeholder for Spec 2)
-# JWT_SECRET=your-secret-key-here
-# JWT_ALGORITHM=HS256
-# JWT_EXPIRATION_MINUTES=1440
+# Authentication
+BETTER_AUTH_SECRET=your-secret-key-here-min-32-characters
+JWT_ALGORITHM=HS256
+JWT_EXPIRATION_DAYS=7
+
+# LLM Provider Configuration
+# Primary provider: gemini, openrouter, cohere
+LLM_PROVIDER=gemini
+
+# Optional fallback provider (recommended for production)
+FALLBACK_PROVIDER=openrouter
+
+# API Keys (provide at least one for your primary provider)
+GEMINI_API_KEY=your-gemini-api-key-here
+OPENROUTER_API_KEY=your-openrouter-api-key-here
+COHERE_API_KEY=your-cohere-api-key-here
+
+# Agent Configuration
+AGENT_TEMPERATURE=0.7
+AGENT_MAX_TOKENS=8192
+
+# Conversation Settings (for free-tier constraints)
+CONVERSATION_MAX_MESSAGES=20
+CONVERSATION_MAX_TOKENS=8000
+
+# How to get API keys:
+# - Gemini: https://makersuite.google.com/app/apikey (free, no credit card required)
+# - OpenRouter: https://openrouter.ai/ (free models available)
+# - Cohere: https://cohere.com/ (trial only, not recommended for production)

README.md

@@ -10,24 +10,227 @@ license: mit
 
 # TaskFlow Backend API
 
-FastAPI backend for TaskFlow task management application.
+FastAPI backend for TaskFlow task management application with AI chatbot integration.
 
 ## Features
 
-- User authentication with JWT
+- User authentication with JWT and Better Auth
 - Task CRUD operations
+- **AI Chatbot Assistant** - Conversational AI for task management
 - PostgreSQL database with SQLModel ORM
 - RESTful API design
+- Multi-turn conversation support with context management
+- Intent recognition for todo-related requests
+
+## Tech Stack
+
+- **Framework**: FastAPI 0.104.1
+- **ORM**: SQLModel 0.0.14
+- **Database**: PostgreSQL (Neon Serverless)
+- **Authentication**: Better Auth + JWT
+- **AI Provider**: Google Gemini (gemini-pro)
+- **Migrations**: Alembic 1.13.0
 
 ## Environment Variables
 
-Configure these in your Space settings:
+Configure these in your `.env` file:
+
+### Database
+- `DATABASE_URL`: PostgreSQL connection string (Neon or local)
+
+### Application
+- `APP_NAME`: Application name (default: "Task CRUD API")
+- `DEBUG`: Debug mode (default: True)
+- `CORS_ORIGINS`: Allowed CORS origins (default: "http://localhost:3000")
+
+### Authentication
+- `BETTER_AUTH_SECRET`: Secret key for Better Auth (required)
+- `JWT_ALGORITHM`: JWT algorithm (default: "HS256")
+- `JWT_EXPIRATION_DAYS`: Token expiration in days (default: 7)
+
+### AI Provider Configuration
+- `AI_PROVIDER`: AI provider to use (default: "gemini")
+- `GEMINI_API_KEY`: Google Gemini API key (required if using Gemini)
+- `OPENROUTER_API_KEY`: OpenRouter API key (optional)
+- `COHERE_API_KEY`: Cohere API key (optional)
+
+### Conversation Settings
+- `MAX_CONVERSATION_MESSAGES`: Maximum messages to keep in history (default: 20)
+- `MAX_CONVERSATION_TOKENS`: Maximum tokens to keep in history (default: 8000)
+
+## Setup Instructions
+
+### 1. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Configure Environment
+
+Create a `.env` file in the `backend/` directory:
 
-- `DATABASE_URL`: PostgreSQL connection string
-- `SECRET_KEY`: JWT secret key (generate a secure random string)
-- `ALGORITHM`: JWT algorithm (default: HS256)
-- `ACCESS_TOKEN_EXPIRE_MINUTES`: Token expiration time (default: 30)
+```env
+# Database
+DATABASE_URL=postgresql://user:password@localhost:5432/todo_db
+
+# Application
+APP_NAME=Task CRUD API
+DEBUG=True
+CORS_ORIGINS=http://localhost:3000
+
+# Authentication
+BETTER_AUTH_SECRET=your_secret_key_here
+JWT_ALGORITHM=HS256
+JWT_EXPIRATION_DAYS=7
+
+# AI Provider
+AI_PROVIDER=gemini
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# Conversation Settings
+MAX_CONVERSATION_MESSAGES=20
+MAX_CONVERSATION_TOKENS=8000
+```
+
+### 3. Run Database Migrations
+
+```bash
+alembic upgrade head
+```
+
+### 4. Start the Server
+
+```bash
+uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+The API will be available at `http://localhost:8000`
 
 ## API Documentation
 
-Once deployed, visit `/docs` for interactive API documentation.
+Once running, visit:
+- **Interactive Docs**: `http://localhost:8000/docs`
+- **ReDoc**: `http://localhost:8000/redoc`
+
+## API Endpoints
+
+### Authentication
+- `POST /api/auth/signup` - Register new user
+- `POST /api/auth/login` - Login user
+
+### Tasks
+- `GET /api/{user_id}/tasks` - Get all tasks for user
+- `POST /api/{user_id}/tasks` - Create new task
+- `GET /api/{user_id}/tasks/{task_id}` - Get specific task
+- `PUT /api/{user_id}/tasks/{task_id}` - Update task
+- `DELETE /api/{user_id}/tasks/{task_id}` - Delete task
+
+### AI Chat (New in Phase 1)
+- `POST /api/{user_id}/chat` - Send message to AI assistant
+
+#### Chat Request Body
+```json
+{
+  "message": "Can you help me organize my tasks?",
+  "conversation_id": 123,  // Optional: null for new conversation
+  "temperature": 0.7       // Optional: 0.0 to 1.0
+}
+```
+
+#### Chat Response
+```json
+{
+  "conversation_id": 123,
+  "message": "I'd be happy to help you organize your tasks!",
+  "role": "assistant",
+  "timestamp": "2026-01-14T10:30:00Z",
+  "token_count": 25,
+  "model": "gemini-pro"
+}
+```
+
+## AI Chatbot Features
+
+### Phase 1 (Current)
+- ✅ Natural conversation with AI assistant
+- ✅ Multi-turn conversations with context retention
+- ✅ Intent recognition for todo-related requests
+- ✅ Conversation history persistence
+- ✅ Automatic history trimming (20 messages / 8000 tokens)
+- ✅ Free-tier AI provider support (Gemini)
+
+### Phase 2 (Coming Soon)
+- 🔄 MCP tools for task CRUD operations
+- 🔄 AI can directly create, update, and delete tasks
+- 🔄 Natural language task management
+
+## Error Handling
+
+The API returns standard HTTP status codes:
+
+- `200 OK` - Request successful
+- `400 Bad Request` - Invalid request data
+- `401 Unauthorized` - Authentication required or failed
+- `404 Not Found` - Resource not found
+- `429 Too Many Requests` - Rate limit exceeded
+- `500 Internal Server Error` - Server error
+
+## Database Schema
+
+### Users Table
+- `id`: Primary key
+- `email`: Unique email address
+- `name`: User's name
+- `password`: Hashed password
+- `created_at`, `updated_at`: Timestamps
+
+### Tasks Table
+- `id`: Primary key
+- `user_id`: Foreign key to users
+- `title`: Task title
+- `description`: Task description
+- `completed`: Boolean status
+- `created_at`, `updated_at`: Timestamps
+
+### Conversation Table (New)
+- `id`: Primary key
+- `user_id`: Foreign key to users
+- `title`: Conversation title
+- `created_at`, `updated_at`: Timestamps
+
+### Message Table (New)
+- `id`: Primary key
+- `conversation_id`: Foreign key to conversation
+- `role`: "user" or "assistant"
+- `content`: Message text
+- `timestamp`: Message timestamp
+- `token_count`: Token count for the message
+
+## Development
+
+### Running Tests
+```bash
+pytest
+```
+
+### Database Migrations
+
+Create a new migration:
+```bash
+alembic revision -m "description"
+```
+
+Apply migrations:
+```bash
+alembic upgrade head
+```
+
+Rollback migration:
+```bash
+alembic downgrade -1
+```
+
+## License
+
+MIT License

alembic/versions/20260114_1044_48b10b49730f_add_conversation_and_message_tables.py

@@ -0,0 +1,59 @@
+"""add_conversation_and_message_tables
+
+Revision ID: 48b10b49730f
+Revises: 002_add_user_password
+Create Date: 2026-01-14 10:44:27.010796
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = '48b10b49730f'
+down_revision = '002_add_user_password'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Create conversation table
+    op.create_table(
+        'conversation',
+        sa.Column('id', sa.Integer(), nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('title', sa.String(length=255), nullable=True),
+        sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+        sa.Column('updated_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index('ix_conversation_user_id', 'conversation', ['user_id'])
+    op.create_index('ix_conversation_created_at', 'conversation', ['created_at'])
+
+    # Create message table
+    op.create_table(
+        'message',
+        sa.Column('id', sa.Integer(), nullable=False),
+        sa.Column('conversation_id', sa.Integer(), nullable=False),
+        sa.Column('role', sa.String(length=50), nullable=False),
+        sa.Column('content', sa.Text(), nullable=False),
+        sa.Column('timestamp', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+        sa.Column('token_count', sa.Integer(), nullable=True),
+        sa.ForeignKeyConstraint(['conversation_id'], ['conversation.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index('ix_message_conversation_id', 'message', ['conversation_id'])
+    op.create_index('ix_message_timestamp', 'message', ['timestamp'])
+
+
+def downgrade() -> None:
+    # Drop message table first (due to foreign key dependency)
+    op.drop_index('ix_message_timestamp', table_name='message')
+    op.drop_index('ix_message_conversation_id', table_name='message')
+    op.drop_table('message')
+
+    # Drop conversation table
+    op.drop_index('ix_conversation_created_at', table_name='conversation')
+    op.drop_index('ix_conversation_user_id', table_name='conversation')
+    op.drop_table('conversation')

alembic/versions/20260114_1115_37ca2e18468d_description.py

@@ -0,0 +1,24 @@
+"""description
+
+Revision ID: 37ca2e18468d
+Revises: 48b10b49730f
+Create Date: 2026-01-14 11:15:03.691055
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = '37ca2e18468d'
+down_revision = '48b10b49730f'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

alembic/versions/20260114_1702_a3c44bf7ddcb_add_metadata_column_to_message_table.py

@@ -0,0 +1,27 @@
+"""add metadata column to message table
+
+Revision ID: a3c44bf7ddcb
+Revises: 37ca2e18468d
+Create Date: 2026-01-14 17:02:51.060200
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+# revision identifiers, used by Alembic.
+revision = 'a3c44bf7ddcb'
+down_revision = '37ca2e18468d'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Add metadata column to message table
+    op.add_column('message', sa.Column('metadata', postgresql.JSON(astext_type=sa.Text()), nullable=True))
+
+
+def downgrade() -> None:
+    # Remove metadata column from message table
+    op.drop_column('message', 'metadata')

alembic/versions/20260114_1712_e8275e6c143c_rename_metadata_to_tool_metadata_in_.py

@@ -0,0 +1,26 @@
+"""rename metadata to tool_metadata in message table
+
+Revision ID: e8275e6c143c
+Revises: a3c44bf7ddcb
+Create Date: 2026-01-14 17:12:53.740315
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = 'e8275e6c143c'
+down_revision = 'a3c44bf7ddcb'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Rename metadata column to tool_metadata
+    op.alter_column('message', 'metadata', new_column_name='tool_metadata')
+
+
+def downgrade() -> None:
+    # Rename tool_metadata column back to metadata
+    op.alter_column('message', 'tool_metadata', new_column_name='metadata')

alembic/versions/20260114_1900_d34db62bd406_add_due_date_and_priority_to_task_table.py

@@ -0,0 +1,28 @@
+"""add due_date and priority to task table
+
+Revision ID: d34db62bd406
+Revises: e8275e6c143c
+Create Date: 2026-01-14 19:00:45.426280
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = 'd34db62bd406'
+down_revision = 'e8275e6c143c'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Add due_date and priority columns to tasks table
+    op.add_column('tasks', sa.Column('due_date', sa.Date(), nullable=True))
+    op.add_column('tasks', sa.Column('priority', sa.String(length=20), nullable=False, server_default='medium'))
+
+
+def downgrade() -> None:
+    # Remove due_date and priority columns from tasks table
+    op.drop_column('tasks', 'priority')
+    op.drop_column('tasks', 'due_date')

alembic/versions/tmpclaude-82e1-cwd

@@ -0,0 +1 @@
+/d/Agentic_ai_learning/hacathoon_2/evolution-of-todo/phase-2-full-stack-web-app/backend/alembic/versions

package-lock.json

@@ -0,0 +1,6 @@
+{
+  "name": "backend",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {}
+}

requirements.txt

@@ -13,4 +13,10 @@ passlib[bcrypt]==1.7.4
 python-multipart==0.0.6
 
 # Add this line (or replace if bcrypt is already listed)
-bcrypt==4.3.0   # Last stable version before the 5.0 break
+bcrypt==4.3.0   # Last stable version before the 5.0 break
+
+# AI Chatbot dependencies
+google-generativeai==0.3.2  # Gemini API client
+tiktoken==0.5.2             # Token counting (optional)
+mcp==1.20.0                 # Official MCP SDK for tool server
+cohere==4.37                # Cohere API client (optional provider)

src/agent/agent_config.py

@@ -0,0 +1,124 @@
+"""
+Agent Configuration
+
+Configuration dataclass for agent behavior and LLM provider settings.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class AgentConfiguration:
+    """
+    Configuration for the AI agent.
+
+    This dataclass defines all configurable parameters for agent behavior,
+    including LLM provider settings, conversation limits, and system prompts.
+    """
+
+    # Provider settings
+    provider: str = "gemini"  # Options: gemini, openrouter, cohere
+    fallback_provider: Optional[str] = None  # Optional fallback provider
+    model: Optional[str] = None  # Model name (provider-specific)
+
+    # API keys (loaded from environment)
+    gemini_api_key: Optional[str] = None
+    openrouter_api_key: Optional[str] = None
+    cohere_api_key: Optional[str] = None
+
+    # Generation parameters
+    temperature: float = 0.7  # Sampling temperature (0.0 to 1.0)
+    max_tokens: int = 8192  # Maximum tokens in response
+
+    # Conversation history limits (for free-tier constraints)
+    max_messages: int = 20  # Maximum messages to keep in history
+    max_conversation_tokens: int = 8000  # Maximum tokens in conversation history
+
+    # System prompt
+    system_prompt: str = """You are a helpful AI assistant for managing tasks.
+You can help users create, view, complete, update, and delete tasks using natural language.
+
+Available tools:
+- add_task: Create a new task
+- list_tasks: View all tasks (with optional filtering)
+- complete_task: Mark a task as completed
+- delete_task: Remove a task
+- update_task: Modify task properties
+
+Always respond in a friendly, conversational manner and confirm actions taken."""
+
+    # Retry settings
+    max_retries: int = 3  # Maximum retries on rate limit errors
+    retry_delay: float = 1.0  # Delay between retries (seconds)
+
+    def get_provider_api_key(self, provider_name: str) -> Optional[str]:
+        """
+        Get API key for a specific provider.
+
+        Args:
+            provider_name: Provider name (gemini, openrouter, cohere)
+
+        Returns:
+            API key or None if not configured
+        """
+        if provider_name == "gemini":
+            return self.gemini_api_key
+        elif provider_name == "openrouter":
+            return self.openrouter_api_key
+        elif provider_name == "cohere":
+            return self.cohere_api_key
+        return None
+
+    def get_provider_model(self, provider_name: str) -> str:
+        """
+        Get default model for a specific provider.
+
+        Args:
+            provider_name: Provider name
+
+        Returns:
+            Model identifier
+        """
+        if self.model:
+            return self.model
+
+        # Default models per provider
+        defaults = {
+            "gemini": "gemini-flash-latest",
+            "openrouter": "google/gemini-flash-1.5",
+            "cohere": "command-r-plus"
+        }
+        return defaults.get(provider_name, "gemini-flash-latest")
+
+    def validate(self) -> bool:
+        """
+        Validate configuration.
+
+        Returns:
+            True if configuration is valid
+
+        Raises:
+            ValueError: If configuration is invalid
+        """
+        # Check primary provider has API key
+        primary_key = self.get_provider_api_key(self.provider)
+        if not primary_key:
+            raise ValueError(f"API key not configured for primary provider: {self.provider}")
+
+        # Validate temperature range
+        if not 0.0 <= self.temperature <= 1.0:
+            raise ValueError(f"Temperature must be between 0.0 and 1.0, got: {self.temperature}")
+
+        # Validate max_tokens
+        if self.max_tokens <= 0:
+            raise ValueError(f"max_tokens must be positive, got: {self.max_tokens}")
+
+        # Validate conversation limits
+        if self.max_messages <= 0:
+            raise ValueError(f"max_messages must be positive, got: {self.max_messages}")
+
+        if self.max_conversation_tokens <= 0:
+            raise ValueError(f"max_conversation_tokens must be positive, got: {self.max_conversation_tokens}")
+
+        return True

src/agent/agent_runner.py

@@ -0,0 +1,281 @@
+"""
+Agent Runner
+
+Core orchestrator for AI agent execution with tool calling support.
+Manages the full request cycle: LLM generation → tool execution → final response.
+"""
+
+import logging
+from typing import List, Dict, Any, Optional
+import asyncio
+
+from .agent_config import AgentConfiguration
+from .providers.base import LLMProvider
+from .providers.gemini import GeminiProvider
+from .providers.openrouter import OpenRouterProvider
+from .providers.cohere import CohereProvider
+from ..mcp.tool_registry import MCPToolRegistry, ToolExecutionResult
+
+logger = logging.getLogger(__name__)
+
+
+class AgentRunner:
+    """
+    Agent execution orchestrator with tool calling support.
+
+    This class manages the full agent request cycle:
+    1. Generate LLM response with tool definitions
+    2. If tool calls requested, execute tools with user context injection
+    3. Generate final response with tool results
+    4. Handle rate limiting with fallback providers
+    """
+
+    def __init__(self, config: AgentConfiguration, tool_registry: MCPToolRegistry):
+        """
+        Initialize the agent runner.
+
+        Args:
+            config: Agent configuration
+            tool_registry: MCP tool registry
+        """
+        self.config = config
+        self.tool_registry = tool_registry
+        self.primary_provider = self._create_provider(config.provider)
+        self.fallback_provider = None
+
+        if config.fallback_provider:
+            self.fallback_provider = self._create_provider(config.fallback_provider)
+
+        logger.info(f"Initialized AgentRunner with provider: {config.provider}")
+
+    def _create_provider(self, provider_name: str) -> LLMProvider:
+        """
+        Create an LLM provider instance.
+
+        Args:
+            provider_name: Provider name (gemini, openrouter, cohere)
+
+        Returns:
+            LLMProvider instance
+
+        Raises:
+            ValueError: If provider is not supported or API key is missing
+        """
+        api_key = self.config.get_provider_api_key(provider_name)
+        if not api_key:
+            raise ValueError(f"API key not configured for provider: {provider_name}")
+
+        model = self.config.get_provider_model(provider_name)
+
+        if provider_name == "gemini":
+            return GeminiProvider(
+                api_key=api_key,
+                model=model,
+                temperature=self.config.temperature,
+                max_tokens=self.config.max_tokens
+            )
+        elif provider_name == "openrouter":
+            return OpenRouterProvider(
+                api_key=api_key,
+                model=model,
+                temperature=self.config.temperature,
+                max_tokens=self.config.max_tokens
+            )
+        elif provider_name == "cohere":
+            return CohereProvider(
+                api_key=api_key,
+                model=model,
+                temperature=self.config.temperature,
+                max_tokens=self.config.max_tokens
+            )
+        else:
+            raise ValueError(f"Unsupported provider: {provider_name}")
+
+    async def execute(
+        self,
+        messages: List[Dict[str, str]],
+        user_id: int,
+        system_prompt: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Execute agent request with tool calling support.
+
+        SECURITY: user_id is injected by backend, never from LLM output.
+
+        Args:
+            messages: Conversation history [{"role": "user", "content": "..."}]
+            user_id: User ID (injected by backend for security)
+            system_prompt: Optional system prompt (uses config default if not provided)
+
+        Returns:
+            Dict with response content and metadata
+        """
+        prompt = system_prompt or self.config.system_prompt
+        provider = self.primary_provider
+
+        try:
+            # Get tool definitions
+            tool_definitions = self.tool_registry.get_tool_definitions()
+
+            logger.info(f"Executing agent for user {user_id} with {len(tool_definitions)} tools")
+
+            # Generate initial response with tool definitions
+            response = await provider.generate_response_with_tools(
+                messages=messages,
+                system_prompt=prompt,
+                tools=tool_definitions
+            )
+
+            # Check if tool calls were requested
+            if response.tool_calls:
+                logger.info(f"Agent requested {len(response.tool_calls)} tool calls")
+
+                # Execute all tool calls
+                tool_results = []
+                for tool_call in response.tool_calls:
+                    result = await self.tool_registry.execute_tool(
+                        tool_name=tool_call["name"],
+                        arguments=tool_call["arguments"],
+                        user_id=user_id  # Inject user context for security
+                    )
+                    tool_results.append(result)
+
+                # Generate final response with tool results
+                final_response = await provider.generate_response_with_tool_results(
+                    messages=messages,
+                    tool_calls=response.tool_calls,
+                    tool_results=tool_results
+                )
+
+                return {
+                    "content": final_response.content,
+                    "tool_calls": response.tool_calls,
+                    "tool_results": tool_results,
+                    "provider": provider.get_provider_name()
+                }
+
+            # No tool calls, return direct response
+            logger.info("Agent generated direct response (no tool calls)")
+            return {
+                "content": response.content,
+                "tool_calls": None,
+                "tool_results": None,
+                "provider": provider.get_provider_name()
+            }
+
+        except Exception as e:
+            logger.error(f"Agent execution failed with primary provider: {str(e)}")
+
+            # Try fallback provider if configured
+            if self.fallback_provider:
+                logger.info("Attempting fallback provider")
+                try:
+                    return await self._execute_with_provider(
+                        provider=self.fallback_provider,
+                        messages=messages,
+                        user_id=user_id,
+                        system_prompt=prompt
+                    )
+                except Exception as fallback_error:
+                    logger.error(f"Fallback provider also failed: {str(fallback_error)}")
+                    raise
+
+            raise
+
+    async def _execute_with_provider(
+        self,
+        provider: LLMProvider,
+        messages: List[Dict[str, str]],
+        user_id: int,
+        system_prompt: str
+    ) -> Dict[str, Any]:
+        """
+        Execute agent request with a specific provider.
+
+        Args:
+            provider: LLM provider to use
+            messages: Conversation history
+            user_id: User ID
+            system_prompt: System prompt
+
+        Returns:
+            Dict with response content and metadata
+        """
+        tool_definitions = self.tool_registry.get_tool_definitions()
+
+        # Generate initial response
+        response = await provider.generate_response_with_tools(
+            messages=messages,
+            system_prompt=system_prompt,
+            tools=tool_definitions
+        )
+
+        # Handle tool calls
+        if response.tool_calls:
+            tool_results = []
+            for tool_call in response.tool_calls:
+                result = await self.tool_registry.execute_tool(
+                    tool_name=tool_call["name"],
+                    arguments=tool_call["arguments"],
+                    user_id=user_id
+                )
+                tool_results.append(result)
+
+            final_response = await provider.generate_response_with_tool_results(
+                messages=messages,
+                tool_calls=response.tool_calls,
+                tool_results=tool_results
+            )
+
+            return {
+                "content": final_response.content,
+                "tool_calls": response.tool_calls,
+                "tool_results": tool_results,
+                "provider": provider.get_provider_name()
+            }
+
+        return {
+            "content": response.content,
+            "tool_calls": None,
+            "tool_results": None,
+            "provider": provider.get_provider_name()
+        }
+
+    async def execute_simple(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: Optional[str] = None
+    ) -> str:
+        """
+        Execute a simple agent request without tool calling.
+
+        Args:
+            messages: Conversation history
+            system_prompt: Optional system prompt
+
+        Returns:
+            Response content as string
+        """
+        prompt = system_prompt or self.config.system_prompt
+        provider = self.primary_provider
+
+        try:
+            response = await provider.generate_simple_response(
+                messages=messages,
+                system_prompt=prompt
+            )
+            return response.content or ""
+
+        except Exception as e:
+            logger.error(f"Simple execution failed: {str(e)}")
+
+            # Try fallback provider
+            if self.fallback_provider:
+                logger.info("Attempting fallback provider for simple execution")
+                response = await self.fallback_provider.generate_simple_response(
+                    messages=messages,
+                    system_prompt=prompt
+                )
+                return response.content or ""
+
+            raise

src/agent/providers/base.py

@@ -0,0 +1,105 @@
+"""
+LLM Provider Base Class
+
+Abstract base class for LLM provider implementations.
+Defines the interface for generating responses with function calling support.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class LLMResponse:
+    """Response from an LLM provider."""
+    content: Optional[str] = None
+    tool_calls: Optional[List[Dict[str, Any]]] = None
+    finish_reason: Optional[str] = None
+    usage: Optional[Dict[str, int]] = None
+
+
+class LLMProvider(ABC):
+    """
+    Abstract base class for LLM providers.
+
+    All provider implementations (Gemini, OpenRouter, Cohere) must
+    implement these methods to support function calling and tool execution.
+    """
+
+    def __init__(self, api_key: str, model: str, temperature: float = 0.7, max_tokens: int = 8192):
+        """
+        Initialize the LLM provider.
+
+        Args:
+            api_key: API key for the provider
+            model: Model identifier (e.g., "gemini-1.5-flash")
+            temperature: Sampling temperature (0.0 to 1.0)
+            max_tokens: Maximum tokens in response
+        """
+        self.api_key = api_key
+        self.model = model
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+
+    @abstractmethod
+    async def generate_response_with_tools(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: str,
+        tools: List[Dict[str, Any]]
+    ) -> LLMResponse:
+        """
+        Generate a response with function calling support.
+
+        Args:
+            messages: Conversation history [{"role": "user", "content": "..."}]
+            system_prompt: System instructions for the agent
+            tools: Tool definitions for function calling
+
+        Returns:
+            LLMResponse with content and/or tool_calls
+        """
+        pass
+
+    @abstractmethod
+    async def generate_response_with_tool_results(
+        self,
+        messages: List[Dict[str, str]],
+        tool_calls: List[Dict[str, Any]],
+        tool_results: List[Dict[str, Any]]
+    ) -> LLMResponse:
+        """
+        Generate a final response after tool execution.
+
+        Args:
+            messages: Original conversation history
+            tool_calls: Tool calls that were made
+            tool_results: Results from tool execution
+
+        Returns:
+            LLMResponse with final content
+        """
+        pass
+
+    @abstractmethod
+    async def generate_simple_response(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: str
+    ) -> LLMResponse:
+        """
+        Generate a simple response without function calling.
+
+        Args:
+            messages: Conversation history
+            system_prompt: System instructions
+
+        Returns:
+            LLMResponse with content
+        """
+        pass
+
+    def get_provider_name(self) -> str:
+        """Get the provider name (e.g., 'gemini', 'openrouter', 'cohere')."""
+        return self.__class__.__name__.replace("Provider", "").lower()

src/agent/providers/cohere.py

@@ -0,0 +1,232 @@
+"""
+Cohere Provider Implementation
+
+Cohere API provider with function calling support.
+Optional provider (trial only, not recommended for production).
+"""
+
+import logging
+from typing import List, Dict, Any
+import cohere
+
+from .base import LLMProvider, LLMResponse
+
+logger = logging.getLogger(__name__)
+
+
+class CohereProvider(LLMProvider):
+    """
+    Cohere API provider implementation.
+
+    Features:
+    - Native function calling support
+    - Trial tier only (not recommended for production)
+    - Model: command-r-plus (best for function calling)
+
+    Note: Cohere requires a paid plan after trial expires.
+    Use Gemini or OpenRouter for free-tier operation.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "command-r-plus",
+        temperature: float = 0.7,
+        max_tokens: int = 8192
+    ):
+        super().__init__(api_key, model, temperature, max_tokens)
+        self.client = cohere.Client(api_key)
+        logger.info(f"Initialized CohereProvider with model: {model}")
+
+    def _convert_tools_to_cohere_format(self, tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Convert MCP tool definitions to Cohere tool format.
+
+        Args:
+            tools: MCP tool definitions
+
+        Returns:
+            List of Cohere-formatted tool definitions
+        """
+        return [
+            {
+                "name": tool["name"],
+                "description": tool["description"],
+                "parameter_definitions": tool["parameters"].get("properties", {})
+            }
+            for tool in tools
+        ]
+
+    async def generate_response_with_tools(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: str,
+        tools: List[Dict[str, Any]]
+    ) -> LLMResponse:
+        """
+        Generate a response with function calling support.
+
+        Args:
+            messages: Conversation history
+            system_prompt: System instructions
+            tools: Tool definitions
+
+        Returns:
+            LLMResponse with content and/or tool_calls
+        """
+        try:
+            # Convert tools to Cohere format
+            cohere_tools = self._convert_tools_to_cohere_format(tools)
+
+            # Format chat history for Cohere
+            chat_history = []
+            for msg in messages[:-1]:  # All except last message
+                chat_history.append({
+                    "role": "USER" if msg["role"] == "user" else "CHATBOT",
+                    "message": msg["content"]
+                })
+
+            # Last message is the current user message
+            current_message = messages[-1]["content"] if messages else ""
+
+            # Generate response with function calling
+            response = self.client.chat(
+                message=current_message,
+                chat_history=chat_history,
+                preamble=system_prompt,
+                model=self.model,
+                temperature=self.temperature,
+                max_tokens=self.max_tokens,
+                tools=cohere_tools
+            )
+
+            # Check for tool calls
+            if response.tool_calls:
+                tool_calls = [
+                    {
+                        "name": tc.name,
+                        "arguments": tc.parameters
+                    }
+                    for tc in response.tool_calls
+                ]
+                logger.info(f"Cohere requested function calls: {[tc['name'] for tc in tool_calls]}")
+                return LLMResponse(
+                    content=None,
+                    tool_calls=tool_calls,
+                    finish_reason="tool_calls"
+                )
+
+            # Regular text response
+            content = response.text
+            logger.info("Cohere generated text response")
+            return LLMResponse(
+                content=content,
+                finish_reason="COMPLETE"
+            )
+
+        except Exception as e:
+            logger.error(f"Cohere API error: {str(e)}")
+            raise
+
+    async def generate_response_with_tool_results(
+        self,
+        messages: List[Dict[str, str]],
+        tool_calls: List[Dict[str, Any]],
+        tool_results: List[Dict[str, Any]]
+    ) -> LLMResponse:
+        """
+        Generate a final response after tool execution.
+
+        Args:
+            messages: Original conversation history
+            tool_calls: Tool calls that were made
+            tool_results: Results from tool execution
+
+        Returns:
+            LLMResponse with final content
+        """
+        try:
+            # Format chat history
+            chat_history = []
+            for msg in messages:
+                chat_history.append({
+                    "role": "USER" if msg["role"] == "user" else "CHATBOT",
+                    "message": msg["content"]
+                })
+
+            # Format tool results for Cohere
+            tool_results_formatted = [
+                {
+                    "call": {"name": call["name"], "parameters": call["arguments"]},
+                    "outputs": [{"result": str(result)}]
+                }
+                for call, result in zip(tool_calls, tool_results)
+            ]
+
+            # Generate final response
+            response = self.client.chat(
+                message="Based on the tool results, provide a natural language response.",
+                chat_history=chat_history,
+                model=self.model,
+                temperature=self.temperature,
+                max_tokens=self.max_tokens,
+                tool_results=tool_results_formatted
+            )
+
+            content = response.text
+            logger.info("Cohere generated final response after tool execution")
+            return LLMResponse(
+                content=content,
+                finish_reason="COMPLETE"
+            )
+
+        except Exception as e:
+            logger.error(f"Cohere API error in tool results: {str(e)}")
+            raise
+
+    async def generate_simple_response(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: str
+    ) -> LLMResponse:
+        """
+        Generate a simple response without function calling.
+
+        Args:
+            messages: Conversation history
+            system_prompt: System instructions
+
+        Returns:
+            LLMResponse with content
+        """
+        try:
+            # Format chat history
+            chat_history = []
+            for msg in messages[:-1]:
+                chat_history.append({
+                    "role": "USER" if msg["role"] == "user" else "CHATBOT",
+                    "message": msg["content"]
+                })
+
+            current_message = messages[-1]["content"] if messages else ""
+
+            # Generate response
+            response = self.client.chat(
+                message=current_message,
+                chat_history=chat_history,
+                preamble=system_prompt,
+                model=self.model,
+                temperature=self.temperature,
+                max_tokens=self.max_tokens
+            )
+
+            content = response.text
+            logger.info("Cohere generated simple response")
+            return LLMResponse(
+                content=content,
+                finish_reason="COMPLETE"
+            )
+
+        except Exception as e:
+            logger.error(f"Cohere API error: {str(e)}")
+            raise

src/agent/providers/gemini.py

@@ -0,0 +1,285 @@
+"""
+Gemini Provider Implementation
+
+Google Gemini API provider with function calling support.
+Primary provider for free-tier operation (15 RPM, 1M token context).
+"""
+
+import logging
+from typing import List, Dict, Any
+import google.generativeai as genai
+from google.generativeai.types import FunctionDeclaration, Tool
+
+from .base import LLMProvider, LLMResponse
+
+logger = logging.getLogger(__name__)
+
+
+class GeminiProvider(LLMProvider):
+    """
+    Google Gemini API provider implementation.
+
+    Features:
+    - Native function calling support
+    - 1M token context window
+    - Free tier: 15 requests/minute
+    - Model: gemini-1.5-flash (recommended for free tier)
+    """
+
+    def __init__(self, api_key: str, model: str = "gemini-flash-latest", temperature: float = 0.7, max_tokens: int = 8192):
+        super().__init__(api_key, model, temperature, max_tokens)
+        genai.configure(api_key=api_key)
+        self.client = genai.GenerativeModel(model)
+        logger.info(f"Initialized GeminiProvider with model: {model}")
+
+    def _sanitize_schema_for_gemini(self, schema: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Sanitize JSON Schema to be Gemini-compatible.
+
+        Gemini only supports a subset of JSON Schema keywords:
+        - Supported: type, description, enum, required, properties, items
+        - NOT supported: maxLength, minLength, pattern, format, minimum, maximum, default, etc.
+
+        Args:
+            schema: Original JSON Schema
+
+        Returns:
+            Gemini-compatible schema with unsupported fields removed
+        """
+        # Fields that Gemini supports
+        ALLOWED_FIELDS = {
+            "type", "description", "enum", "required",
+            "properties", "items"
+        }
+
+        # Create a sanitized copy
+        sanitized = {}
+
+        for key, value in schema.items():
+            if key in ALLOWED_FIELDS:
+                # Recursively sanitize nested objects
+                if key == "properties" and isinstance(value, dict):
+                    sanitized[key] = {
+                        prop_name: self._sanitize_schema_for_gemini(prop_schema)
+                        for prop_name, prop_schema in value.items()
+                    }
+                elif key == "items" and isinstance(value, dict):
+                    sanitized[key] = self._sanitize_schema_for_gemini(value)
+                else:
+                    sanitized[key] = value
+
+        return sanitized
+
+    def _convert_tools_to_gemini_format(self, tools: List[Dict[str, Any]]) -> List[Tool]:
+        """
+        Convert MCP tool definitions to Gemini function declarations.
+
+        Sanitizes schemas to remove unsupported JSON Schema keywords.
+
+        Args:
+            tools: MCP tool definitions
+
+        Returns:
+            List of Gemini Tool objects
+        """
+        function_declarations = []
+        for tool in tools:
+            # Sanitize parameters to remove unsupported fields
+            sanitized_parameters = self._sanitize_schema_for_gemini(tool["parameters"])
+
+            function_declarations.append(
+                FunctionDeclaration(
+                    name=tool["name"],
+                    description=tool["description"],
+                    parameters=sanitized_parameters
+                )
+            )
+
+            logger.debug(f"Sanitized tool schema for Gemini: {tool['name']}")
+
+        return [Tool(function_declarations=function_declarations)]
+
+    def _convert_messages_to_gemini_format(self, messages: List[Dict[str, str]], system_prompt: str) -> List[Dict[str, str]]:
+        """
+        Convert standard message format to Gemini format.
+
+        Args:
+            messages: Standard message format [{"role": "user", "content": "..."}]
+            system_prompt: System instructions
+
+        Returns:
+            Gemini-formatted messages
+        """
+        gemini_messages = []
+
+        # Add system prompt as first user message if provided
+        if system_prompt:
+            gemini_messages.append({
+                "role": "user",
+                "parts": [{"text": system_prompt}]
+            })
+            gemini_messages.append({
+                "role": "model",
+                "parts": [{"text": "Understood. I'll follow these instructions."}]
+            })
+
+        # Convert messages
+        for msg in messages:
+            role = "user" if msg["role"] == "user" else "model"
+            gemini_messages.append({
+                "role": role,
+                "parts": [{"text": msg["content"]}]
+            })
+
+        return gemini_messages
+
+    async def generate_response_with_tools(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: str,
+        tools: List[Dict[str, Any]]
+    ) -> LLMResponse:
+        """
+        Generate a response with function calling support.
+
+        Args:
+            messages: Conversation history
+            system_prompt: System instructions
+            tools: Tool definitions
+
+        Returns:
+            LLMResponse with content and/or tool_calls
+        """
+        try:
+            # Convert tools to Gemini format
+            gemini_tools = self._convert_tools_to_gemini_format(tools)
+
+            # Convert messages to Gemini format
+            gemini_messages = self._convert_messages_to_gemini_format(messages, system_prompt)
+
+            # Generate response with function calling
+            response = self.client.generate_content(
+                gemini_messages,
+                tools=gemini_tools,
+                generation_config={
+                    "temperature": self.temperature,
+                    "max_output_tokens": self.max_tokens
+                }
+            )
+
+            # Check if function calls were made
+            if response.candidates[0].content.parts:
+                first_part = response.candidates[0].content.parts[0]
+
+                # Check for function call
+                if hasattr(first_part, 'function_call') and first_part.function_call:
+                    function_call = first_part.function_call
+                    tool_calls = [{
+                        "name": function_call.name,
+                        "arguments": dict(function_call.args)
+                    }]
+                    logger.info(f"Gemini requested function call: {function_call.name}")
+                    return LLMResponse(
+                        content=None,
+                        tool_calls=tool_calls,
+                        finish_reason="function_call"
+                    )
+
+            # Regular text response
+            content = response.text if hasattr(response, 'text') else None
+            logger.info("Gemini generated text response")
+            return LLMResponse(
+                content=content,
+                finish_reason="stop"
+            )
+
+        except Exception as e:
+            logger.error(f"Gemini API error: {str(e)}")
+            raise
+
+    async def generate_response_with_tool_results(
+        self,
+        messages: List[Dict[str, str]],
+        tool_calls: List[Dict[str, Any]],
+        tool_results: List[Dict[str, Any]]
+    ) -> LLMResponse:
+        """
+        Generate a final response after tool execution.
+
+        Args:
+            messages: Original conversation history
+            tool_calls: Tool calls that were made
+            tool_results: Results from tool execution
+
+        Returns:
+            LLMResponse with final content
+        """
+        try:
+            # Format tool results as a message
+            tool_results_text = "\n\n".join([
+                f"Tool: {call['name']}\nResult: {result}"
+                for call, result in zip(tool_calls, tool_results)
+            ])
+
+            # Add tool results to messages
+            messages_with_results = messages + [
+                {"role": "assistant", "content": f"I called the following tools:\n{tool_results_text}"},
+                {"role": "user", "content": "Based on these tool results, provide a natural language response to the user."}
+            ]
+
+            # Generate final response
+            gemini_messages = self._convert_messages_to_gemini_format(messages_with_results, "")
+            response = self.client.generate_content(
+                gemini_messages,
+                generation_config={
+                    "temperature": self.temperature,
+                    "max_output_tokens": self.max_tokens
+                }
+            )
+
+            content = response.text if hasattr(response, 'text') else None
+            logger.info("Gemini generated final response after tool execution")
+            return LLMResponse(
+                content=content,
+                finish_reason="stop"
+            )
+
+        except Exception as e:
+            logger.error(f"Gemini API error in tool results: {str(e)}")
+            raise
+
+    async def generate_simple_response(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: str
+    ) -> LLMResponse:
+        """
+        Generate a simple response without function calling.
+
+        Args:
+            messages: Conversation history
+            system_prompt: System instructions
+
+        Returns:
+            LLMResponse with content
+        """
+        try:
+            gemini_messages = self._convert_messages_to_gemini_format(messages, system_prompt)
+            response = self.client.generate_content(
+                gemini_messages,
+                generation_config={
+                    "temperature": self.temperature,
+                    "max_output_tokens": self.max_tokens
+                }
+            )
+
+            content = response.text if hasattr(response, 'text') else None
+            logger.info("Gemini generated simple response")
+            return LLMResponse(
+                content=content,
+                finish_reason="stop"
+            )
+
+        except Exception as e:
+            logger.error(f"Gemini API error: {str(e)}")
+            raise

src/agent/providers/openrouter.py

@@ -0,0 +1,264 @@
+"""
+OpenRouter Provider Implementation
+
+OpenRouter API provider with function calling support.
+Fallback provider for when Gemini rate limits are exceeded.
+Uses OpenAI-compatible API format.
+"""
+
+import logging
+from typing import List, Dict, Any
+import httpx
+
+from .base import LLMProvider, LLMResponse
+
+logger = logging.getLogger(__name__)
+
+
+class OpenRouterProvider(LLMProvider):
+    """
+    OpenRouter API provider implementation.
+
+    Features:
+    - OpenAI-compatible API
+    - Access to multiple free models
+    - Function calling support
+    - Recommended free model: google/gemini-flash-1.5
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "google/gemini-flash-1.5",
+        temperature: float = 0.7,
+        max_tokens: int = 8192
+    ):
+        super().__init__(api_key, model, temperature, max_tokens)
+        self.base_url = "https://openrouter.ai/api/v1"
+        self.headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json"
+        }
+        logger.info(f"Initialized OpenRouterProvider with model: {model}")
+
+    def _convert_tools_to_openai_format(self, tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Convert MCP tool definitions to OpenAI function format.
+
+        Args:
+            tools: MCP tool definitions
+
+        Returns:
+            List of OpenAI-formatted function definitions
+        """
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": tool["name"],
+                    "description": tool["description"],
+                    "parameters": tool["parameters"]
+                }
+            }
+            for tool in tools
+        ]
+
+    async def generate_response_with_tools(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: str,
+        tools: List[Dict[str, Any]]
+    ) -> LLMResponse:
+        """
+        Generate a response with function calling support.
+
+        Args:
+            messages: Conversation history
+            system_prompt: System instructions
+            tools: Tool definitions
+
+        Returns:
+            LLMResponse with content and/or tool_calls
+        """
+        try:
+            # Prepare messages with system prompt
+            formatted_messages = [{"role": "system", "content": system_prompt}] + messages
+
+            # Convert tools to OpenAI format
+            openai_tools = self._convert_tools_to_openai_format(tools)
+
+            # Make API request
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.post(
+                    f"{self.base_url}/chat/completions",
+                    headers=self.headers,
+                    json={
+                        "model": self.model,
+                        "messages": formatted_messages,
+                        "tools": openai_tools,
+                        "temperature": self.temperature,
+                        "max_tokens": self.max_tokens
+                    }
+                )
+                response.raise_for_status()
+                data = response.json()
+
+            # Parse response
+            choice = data["choices"][0]
+            message = choice["message"]
+
+            # Check for function calls
+            if "tool_calls" in message and message["tool_calls"]:
+                tool_calls = [
+                    {
+                        "name": tc["function"]["name"],
+                        "arguments": tc["function"]["arguments"]
+                    }
+                    for tc in message["tool_calls"]
+                ]
+                logger.info(f"OpenRouter requested function calls: {[tc['name'] for tc in tool_calls]}")
+                return LLMResponse(
+                    content=None,
+                    tool_calls=tool_calls,
+                    finish_reason=choice.get("finish_reason", "function_call")
+                )
+
+            # Regular text response
+            content = message.get("content")
+            logger.info("OpenRouter generated text response")
+            return LLMResponse(
+                content=content,
+                finish_reason=choice.get("finish_reason", "stop")
+            )
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"OpenRouter API HTTP error: {e.response.status_code} - {e.response.text}")
+            raise
+        except Exception as e:
+            logger.error(f"OpenRouter API error: {str(e)}")
+            raise
+
+    async def generate_response_with_tool_results(
+        self,
+        messages: List[Dict[str, str]],
+        tool_calls: List[Dict[str, Any]],
+        tool_results: List[Dict[str, Any]]
+    ) -> LLMResponse:
+        """
+        Generate a final response after tool execution.
+
+        Args:
+            messages: Original conversation history
+            tool_calls: Tool calls that were made
+            tool_results: Results from tool execution
+
+        Returns:
+            LLMResponse with final content
+        """
+        try:
+            # Format tool results as messages
+            messages_with_results = messages.copy()
+
+            # Add assistant message with tool calls
+            messages_with_results.append({
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": f"call_{i}",
+                        "type": "function",
+                        "function": {
+                            "name": call["name"],
+                            "arguments": str(call["arguments"])
+                        }
+                    }
+                    for i, call in enumerate(tool_calls)
+                ]
+            })
+
+            # Add tool result messages
+            for i, (call, result) in enumerate(zip(tool_calls, tool_results)):
+                messages_with_results.append({
+                    "role": "tool",
+                    "tool_call_id": f"call_{i}",
+                    "content": str(result)
+                })
+
+            # Generate final response
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.post(
+                    f"{self.base_url}/chat/completions",
+                    headers=self.headers,
+                    json={
+                        "model": self.model,
+                        "messages": messages_with_results,
+                        "temperature": self.temperature,
+                        "max_tokens": self.max_tokens
+                    }
+                )
+                response.raise_for_status()
+                data = response.json()
+
+            choice = data["choices"][0]
+            content = choice["message"].get("content")
+            logger.info("OpenRouter generated final response after tool execution")
+            return LLMResponse(
+                content=content,
+                finish_reason=choice.get("finish_reason", "stop")
+            )
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"OpenRouter API HTTP error: {e.response.status_code} - {e.response.text}")
+            raise
+        except Exception as e:
+            logger.error(f"OpenRouter API error in tool results: {str(e)}")
+            raise
+
+    async def generate_simple_response(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: str
+    ) -> LLMResponse:
+        """
+        Generate a simple response without function calling.
+
+        Args:
+            messages: Conversation history
+            system_prompt: System instructions
+
+        Returns:
+            LLMResponse with content
+        """
+        try:
+            # Prepare messages with system prompt
+            formatted_messages = [{"role": "system", "content": system_prompt}] + messages
+
+            # Make API request
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.post(
+                    f"{self.base_url}/chat/completions",
+                    headers=self.headers,
+                    json={
+                        "model": self.model,
+                        "messages": formatted_messages,
+                        "temperature": self.temperature,
+                        "max_tokens": self.max_tokens
+                    }
+                )
+                response.raise_for_status()
+                data = response.json()
+
+            choice = data["choices"][0]
+            content = choice["message"].get("content")
+            logger.info("OpenRouter generated simple response")
+            return LLMResponse(
+                content=content,
+                finish_reason=choice.get("finish_reason", "stop")
+            )
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"OpenRouter API HTTP error: {e.response.status_code} - {e.response.text}")
+            raise
+        except Exception as e:
+            logger.error(f"OpenRouter API error: {str(e)}")
+            raise

src/api/routes/chat.py

@@ -0,0 +1,281 @@
+"""Chat API endpoint for AI chatbot."""
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlmodel import Session
+from typing import Dict, Any
+import logging
+from datetime import datetime
+
+from src.core.database import get_session
+from src.core.security import get_current_user
+from src.core.config import settings
+from src.schemas.chat_request import ChatRequest
+from src.schemas.chat_response import ChatResponse
+from src.services.conversation_service import ConversationService
+from src.agent.agent_config import AgentConfiguration
+from src.agent.agent_runner import AgentRunner
+from src.mcp import tool_registry
+from src.core.exceptions import (
+    classify_ai_error,
+    APIKeyMissingException,
+    APIKeyInvalidException
+)
+
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api", tags=["chat"])
+
+
+def generate_conversation_title(first_user_message: str) -> str:
+    """Generate a conversation title from the first user message.
+
+    Args:
+        first_user_message: The first message from the user
+
+    Returns:
+        A title string (max 50 characters)
+    """
+    # Remove leading/trailing whitespace
+    message = first_user_message.strip()
+
+    # Try to extract the first sentence or first 50 characters
+    # Split by common sentence endings
+    for delimiter in ['. ', '! ', '? ', '\n']:
+        if delimiter in message:
+            title = message.split(delimiter)[0]
+            break
+    else:
+        # No sentence delimiter found, use first 50 chars
+        title = message[:50]
+
+    # If title is too short (less than 10 chars), use timestamp-based default
+    if len(title) < 10:
+        return f"Chat {datetime.now().strftime('%b %d, %I:%M %p')}"
+
+    # Truncate to 50 characters and add ellipsis if needed
+    if len(title) > 50:
+        title = title[:47] + "..."
+
+    return title
+
+
+@router.post("/{user_id}/chat", response_model=ChatResponse)
+async def chat(
+    user_id: int,
+    request: ChatRequest,
+    db: Session = Depends(get_session),
+    current_user: Dict[str, Any] = Depends(get_current_user)
+) -> ChatResponse:
+    """Handle chat messages from users.
+
+    Args:
+        user_id: ID of the user sending the message
+        request: ChatRequest containing the user's message
+        db: Database session
+        current_user: Authenticated user from JWT token
+
+    Returns:
+        ChatResponse containing the AI's response
+
+    Raises:
+        HTTPException 401: If user is not authenticated or user_id doesn't match
+        HTTPException 404: If conversation_id is provided but not found
+        HTTPException 500: If AI provider fails to generate response
+    """
+    # Verify user authorization
+    if current_user["id"] != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authorized to access this user's chat"
+        )
+
+    try:
+        # Validate request message length
+        if not request.message or len(request.message.strip()) == 0:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Message cannot be empty"
+            )
+
+        if len(request.message) > 10000:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Message exceeds maximum length of 10,000 characters"
+            )
+
+        # Initialize services
+        conversation_service = ConversationService(db)
+
+        # Initialize agent configuration from settings
+        try:
+            agent_config = AgentConfiguration(
+                provider=settings.LLM_PROVIDER,
+                fallback_provider=settings.FALLBACK_PROVIDER,
+                gemini_api_key=settings.GEMINI_API_KEY,
+                openrouter_api_key=settings.OPENROUTER_API_KEY,
+                cohere_api_key=settings.COHERE_API_KEY,
+                temperature=settings.AGENT_TEMPERATURE,
+                max_tokens=settings.AGENT_MAX_TOKENS,
+                max_messages=settings.CONVERSATION_MAX_MESSAGES,
+                max_conversation_tokens=settings.CONVERSATION_MAX_TOKENS
+            )
+            agent_config.validate()
+
+            # Create agent runner with tool registry
+            agent_runner = AgentRunner(agent_config, tool_registry)
+        except ValueError as e:
+            logger.error(f"Agent initialization failed: {str(e)}")
+            # Check if it's an API key issue
+            error_msg = str(e).lower()
+            if "api key" in error_msg:
+                if "not found" in error_msg or "missing" in error_msg:
+                    raise APIKeyMissingException(provider=settings.LLM_PROVIDER)
+                elif "invalid" in error_msg:
+                    raise APIKeyInvalidException(provider=settings.LLM_PROVIDER)
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="AI service is not properly configured. Please contact support."
+            )
+
+        # Get or create conversation
+        is_new_conversation = False
+        if request.conversation_id:
+            conversation = conversation_service.get_conversation(
+                request.conversation_id,
+                user_id
+            )
+            if not conversation:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail=f"Conversation {request.conversation_id} not found or you don't have access to it"
+                )
+        else:
+            # Create new conversation with auto-generated title
+            try:
+                # Generate title from first user message
+                title = generate_conversation_title(request.message)
+                conversation = conversation_service.create_conversation(
+                    user_id=user_id,
+                    title=title
+                )
+                is_new_conversation = True
+                logger.info(f"Created new conversation {conversation.id} with title: {title}")
+            except Exception as e:
+                logger.error(f"Failed to create conversation: {str(e)}")
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Failed to create conversation. Please try again."
+                )
+
+        # Add user message to conversation
+        try:
+            user_message = conversation_service.add_message(
+                conversation_id=conversation.id,
+                role="user",
+                content=request.message,
+                token_count=len(request.message) // 4  # Rough token estimate
+            )
+        except Exception as e:
+            logger.error(f"Failed to save user message: {str(e)}")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Failed to save your message. Please try again."
+            )
+
+        # Get conversation history and format for agent
+        history_messages = conversation_service.get_conversation_messages(
+            conversation_id=conversation.id
+        )
+
+        # Format messages for agent with trimming
+        formatted_messages = conversation_service.format_messages_for_agent(
+            messages=history_messages,
+            max_messages=agent_config.max_messages,
+            max_tokens=agent_config.max_conversation_tokens
+        )
+
+        # Generate AI response with tool calling support
+        system_prompt = request.system_prompt or agent_config.system_prompt
+
+        try:
+            agent_result = await agent_runner.execute(
+                messages=formatted_messages,
+                user_id=user_id,  # Inject user context for security
+                system_prompt=system_prompt
+            )
+        except Exception as e:
+            # Use classify_ai_error to determine the appropriate exception
+            logger.error(f"AI service error for user {user_id}: {str(e)}")
+            provider = agent_result.get("provider") if 'agent_result' in locals() else settings.LLM_PROVIDER
+            raise classify_ai_error(e, provider=provider)
+
+        # Add AI response to conversation with tool call metadata
+        try:
+            # Prepare metadata if tools were used
+            tool_metadata = None
+            if agent_result.get("tool_calls"):
+                # Convert ToolExecutionResult objects to dicts for JSON serialization
+                tool_results = agent_result.get("tool_results", [])
+                serializable_results = []
+                for result in tool_results:
+                    if hasattr(result, '__dict__'):
+                        # Convert dataclass/object to dict
+                        serializable_results.append({
+                            "success": result.success,
+                            "data": result.data,
+                            "message": result.message,
+                            "error": result.error
+                        })
+                    else:
+                        # Already a dict
+                        serializable_results.append(result)
+
+                tool_metadata = {
+                    "tool_calls": agent_result["tool_calls"],
+                    "tool_results": serializable_results,
+                    "provider": agent_result.get("provider")
+                }
+
+            assistant_message = conversation_service.add_message(
+                conversation_id=conversation.id,
+                role="assistant",
+                content=agent_result["content"],
+                token_count=len(agent_result["content"]) // 4  # Rough token estimate
+            )
+
+            # Update tool_metadata if tools were used
+            if tool_metadata:
+                assistant_message.tool_metadata = tool_metadata
+                db.add(assistant_message)
+                db.commit()
+        except Exception as e:
+            logger.error(f"Failed to save AI response: {str(e)}")
+            # Still return the response even if saving fails
+            # User gets the response but it won't be in history
+            logger.warning(f"Returning response without saving to database for conversation {conversation.id}")
+
+        # Log tool usage if any
+        if agent_result.get("tool_calls"):
+            logger.info(f"Agent used {len(agent_result['tool_calls'])} tools for user {user_id}")
+
+        # Return response
+        return ChatResponse(
+            conversation_id=conversation.id,
+            message=agent_result["content"],
+            role="assistant",
+            timestamp=assistant_message.timestamp if 'assistant_message' in locals() else user_message.timestamp,
+            token_count=len(agent_result["content"]) // 4,
+            model=agent_result.get("provider")
+        )
+
+    except HTTPException:
+        # Re-raise HTTP exceptions
+        raise
+    except Exception as e:
+        # Catch-all for unexpected errors
+        logger.exception(f"Unexpected error in chat endpoint: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="An unexpected error occurred. Please try again later."
+        )

src/api/routes/conversations.py

@@ -0,0 +1,291 @@
+"""Conversations API endpoints for managing chat conversations."""
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from sqlmodel import Session
+from typing import Dict, Any, List
+import logging
+
+from src.core.database import get_session
+from src.core.security import get_current_user
+from src.services.conversation_service import ConversationService
+from src.schemas.conversation import (
+    ConversationListResponse,
+    ConversationSummary,
+    MessageListResponse,
+    MessageResponse,
+    UpdateConversationRequest,
+    UpdateConversationResponse
+)
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api", tags=["conversations"])
+
+
+@router.get("/{user_id}/conversations", response_model=ConversationListResponse)
+async def list_conversations(
+    user_id: int,
+    limit: int = Query(50, ge=1, le=100, description="Maximum number of conversations to return"),
+    db: Session = Depends(get_session),
+    current_user: Dict[str, Any] = Depends(get_current_user)
+) -> ConversationListResponse:
+    """List all conversations for a user.
+
+    Args:
+        user_id: ID of the user
+        limit: Maximum number of conversations to return (default: 50, max: 100)
+        db: Database session
+        current_user: Authenticated user from JWT token
+
+    Returns:
+        ConversationListResponse with list of conversations
+
+    Raises:
+        HTTPException 401: If user is not authenticated or user_id doesn't match
+    """
+    # Verify user authorization
+    if current_user["id"] != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authorized to access this user's conversations"
+        )
+
+    try:
+        conversation_service = ConversationService(db)
+        conversations = conversation_service.get_user_conversations(user_id, limit=limit)
+
+        # Build conversation summaries with message count and preview
+        summaries: List[ConversationSummary] = []
+        for conv in conversations:
+            # Get messages for this conversation
+            messages = conversation_service.get_conversation_messages(conv.id)
+            message_count = len(messages)
+
+            # Get last message preview
+            last_message_preview = None
+            if messages:
+                last_msg = messages[-1]
+                # Take first 100 characters of the last message
+                last_message_preview = last_msg.content[:100]
+                if len(last_msg.content) > 100:
+                    last_message_preview += "..."
+
+            summaries.append(ConversationSummary(
+                id=conv.id,
+                title=conv.title,
+                created_at=conv.created_at,
+                updated_at=conv.updated_at,
+                message_count=message_count,
+                last_message_preview=last_message_preview
+            ))
+
+        return ConversationListResponse(
+            conversations=summaries,
+            total=len(summaries)
+        )
+
+    except Exception as e:
+        logger.exception(f"Failed to list conversations for user {user_id}: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve conversations. Please try again."
+        )
+
+
+@router.get("/{user_id}/conversations/{conversation_id}/messages", response_model=MessageListResponse)
+async def get_conversation_messages(
+    user_id: int,
+    conversation_id: int,
+    offset: int = Query(0, ge=0, description="Number of messages to skip"),
+    limit: int = Query(50, ge=1, le=200, description="Maximum number of messages to return"),
+    db: Session = Depends(get_session),
+    current_user: Dict[str, Any] = Depends(get_current_user)
+) -> MessageListResponse:
+    """Get message history for a conversation.
+
+    Args:
+        user_id: ID of the user
+        conversation_id: ID of the conversation
+        offset: Number of messages to skip (for pagination)
+        limit: Maximum number of messages to return (default: 50, max: 200)
+        db: Database session
+        current_user: Authenticated user from JWT token
+
+    Returns:
+        MessageListResponse with list of messages
+
+    Raises:
+        HTTPException 401: If user is not authenticated or user_id doesn't match
+        HTTPException 404: If conversation not found or user doesn't have access
+    """
+    # Verify user authorization
+    if current_user["id"] != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authorized to access this user's conversations"
+        )
+
+    try:
+        conversation_service = ConversationService(db)
+
+        # Verify conversation exists and belongs to user
+        conversation = conversation_service.get_conversation(conversation_id, user_id)
+        if not conversation:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Conversation {conversation_id} not found or you don't have access to it"
+            )
+
+        # Get all messages (we'll handle pagination manually)
+        all_messages = conversation_service.get_conversation_messages(conversation_id)
+        total = len(all_messages)
+
+        # Apply pagination
+        paginated_messages = all_messages[offset:offset + limit]
+
+        # Convert to response format
+        message_responses = [
+            MessageResponse(
+                id=msg.id,
+                role=msg.role,
+                content=msg.content,
+                timestamp=msg.timestamp,
+                token_count=msg.token_count
+            )
+            for msg in paginated_messages
+        ]
+
+        return MessageListResponse(
+            conversation_id=conversation_id,
+            messages=message_responses,
+            total=total
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception(f"Failed to get messages for conversation {conversation_id}: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve messages. Please try again."
+        )
+
+
+@router.patch("/{user_id}/conversations/{conversation_id}", response_model=UpdateConversationResponse)
+async def update_conversation(
+    user_id: int,
+    conversation_id: int,
+    request: UpdateConversationRequest,
+    db: Session = Depends(get_session),
+    current_user: Dict[str, Any] = Depends(get_current_user)
+) -> UpdateConversationResponse:
+    """Update a conversation's title.
+
+    Args:
+        user_id: ID of the user
+        conversation_id: ID of the conversation
+        request: UpdateConversationRequest with new title
+        db: Database session
+        current_user: Authenticated user from JWT token
+
+    Returns:
+        UpdateConversationResponse with updated conversation
+
+    Raises:
+        HTTPException 401: If user is not authenticated or user_id doesn't match
+        HTTPException 404: If conversation not found or user doesn't have access
+    """
+    # Verify user authorization
+    if current_user["id"] != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authorized to access this user's conversations"
+        )
+
+    try:
+        conversation_service = ConversationService(db)
+
+        # Verify conversation exists and belongs to user
+        conversation = conversation_service.get_conversation(conversation_id, user_id)
+        if not conversation:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Conversation {conversation_id} not found or you don't have access to it"
+            )
+
+        # Update the title
+        from datetime import datetime
+        conversation.title = request.title
+        conversation.updated_at = datetime.utcnow()
+        db.add(conversation)
+        db.commit()
+        db.refresh(conversation)
+
+        return UpdateConversationResponse(
+            id=conversation.id,
+            title=conversation.title,
+            updated_at=conversation.updated_at
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception(f"Failed to update conversation {conversation_id}: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to update conversation. Please try again."
+        )
+
+
+@router.delete("/{user_id}/conversations/{conversation_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_conversation(
+    user_id: int,
+    conversation_id: int,
+    db: Session = Depends(get_session),
+    current_user: Dict[str, Any] = Depends(get_current_user)
+) -> None:
+    """Delete a conversation and all its messages.
+
+    Args:
+        user_id: ID of the user
+        conversation_id: ID of the conversation
+        db: Database session
+        current_user: Authenticated user from JWT token
+
+    Returns:
+        None (204 No Content)
+
+    Raises:
+        HTTPException 401: If user is not authenticated or user_id doesn't match
+        HTTPException 404: If conversation not found or user doesn't have access
+    """
+    # Verify user authorization
+    if current_user["id"] != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authorized to access this user's conversations"
+        )
+
+    try:
+        conversation_service = ConversationService(db)
+
+        # Delete the conversation (service method handles authorization check)
+        deleted = conversation_service.delete_conversation(conversation_id, user_id)
+
+        if not deleted:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Conversation {conversation_id} not found or you don't have access to it"
+            )
+
+        # Return 204 No Content (no response body)
+        return None
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception(f"Failed to delete conversation {conversation_id}: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to delete conversation. Please try again."
+        )

src/core/config.py

@@ -19,6 +19,21 @@ class Settings(BaseSettings):
     JWT_ALGORITHM: str = "HS256"
     JWT_EXPIRATION_DAYS: int = 7
 
+    # LLM Provider Configuration
+    LLM_PROVIDER: str = "gemini"  # Primary provider: gemini, openrouter, cohere
+    FALLBACK_PROVIDER: str | None = None  # Optional fallback provider
+    GEMINI_API_KEY: str | None = None  # Required if using Gemini
+    OPENROUTER_API_KEY: str | None = None  # Required if using OpenRouter
+    COHERE_API_KEY: str | None = None  # Required if using Cohere
+
+    # Agent Configuration
+    AGENT_TEMPERATURE: float = 0.7  # Sampling temperature (0.0 to 1.0)
+    AGENT_MAX_TOKENS: int = 8192  # Maximum tokens in response
+
+    # Conversation Settings (for free-tier constraints)
+    CONVERSATION_MAX_MESSAGES: int = 20  # Maximum messages to keep in history
+    CONVERSATION_MAX_TOKENS: int = 8000  # Maximum tokens in conversation history
+
     class Config:
         env_file = ".env"
         case_sensitive = True

src/core/exceptions.py

@@ -0,0 +1,125 @@
+"""
+Custom exception classes for structured error handling.
+"""
+
+from typing import Optional
+from fastapi import HTTPException, status
+from src.schemas.error import ErrorCode
+
+
+class AIProviderException(HTTPException):
+    """Base exception for AI provider errors."""
+
+    def __init__(
+        self,
+        error_code: str,
+        detail: str,
+        status_code: int = status.HTTP_500_INTERNAL_SERVER_ERROR,
+        provider: Optional[str] = None
+    ):
+        super().__init__(status_code=status_code, detail=detail)
+        self.error_code = error_code
+        self.source = "AI_PROVIDER"
+        self.provider = provider
+
+
+class RateLimitExceededException(AIProviderException):
+    """Exception raised when AI provider rate limit is exceeded."""
+
+    def __init__(self, provider: Optional[str] = None):
+        super().__init__(
+            error_code=ErrorCode.RATE_LIMIT_EXCEEDED,
+            detail="AI service rate limit exceeded. Please wait a moment and try again.",
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            provider=provider
+        )
+
+
+class APIKeyMissingException(AIProviderException):
+    """Exception raised when API key is not configured."""
+
+    def __init__(self, provider: Optional[str] = None):
+        super().__init__(
+            error_code=ErrorCode.API_KEY_MISSING,
+            detail="AI service is not configured. Please add an API key.",
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            provider=provider
+        )
+
+
+class APIKeyInvalidException(AIProviderException):
+    """Exception raised when API key is invalid or expired."""
+
+    def __init__(self, provider: Optional[str] = None):
+        super().__init__(
+            error_code=ErrorCode.API_KEY_INVALID,
+            detail="Your API key is invalid or expired. Please check your configuration.",
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            provider=provider
+        )
+
+
+class ProviderUnavailableException(AIProviderException):
+    """Exception raised when AI provider is temporarily unavailable."""
+
+    def __init__(self, provider: Optional[str] = None):
+        super().__init__(
+            error_code=ErrorCode.PROVIDER_UNAVAILABLE,
+            detail="AI service is temporarily unavailable. Please try again later.",
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            provider=provider
+        )
+
+
+class ProviderErrorException(AIProviderException):
+    """Exception raised for generic AI provider errors."""
+
+    def __init__(self, detail: str, provider: Optional[str] = None):
+        super().__init__(
+            error_code=ErrorCode.PROVIDER_ERROR,
+            detail=detail,
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            provider=provider
+        )
+
+
+def classify_ai_error(error: Exception, provider: Optional[str] = None) -> AIProviderException:
+    """
+    Classify an AI provider error and return appropriate exception.
+
+    Args:
+        error: The original exception from the AI provider
+        provider: Name of the AI provider (gemini, openrouter, cohere)
+
+    Returns:
+        Appropriate AIProviderException subclass
+    """
+    error_message = str(error).lower()
+
+    # Rate limit errors
+    if any(keyword in error_message for keyword in ["rate limit", "429", "quota exceeded", "too many requests"]):
+        return RateLimitExceededException(provider=provider)
+
+    # API key missing errors
+    if any(keyword in error_message for keyword in ["api key not found", "api key is required", "missing api key"]):
+        return APIKeyMissingException(provider=provider)
+
+    # API key invalid errors
+    if any(keyword in error_message for keyword in [
+        "invalid api key", "api key invalid", "unauthorized", "401",
+        "authentication failed", "invalid credentials", "api key expired"
+    ]):
+        return APIKeyInvalidException(provider=provider)
+
+    # Provider unavailable errors
+    if any(keyword in error_message for keyword in [
+        "503", "service unavailable", "temporarily unavailable",
+        "connection refused", "connection timeout", "timeout"
+    ]):
+        return ProviderUnavailableException(provider=provider)
+
+    # Generic provider error
+    return ProviderErrorException(
+        detail=f"AI service error: {str(error)}",
+        provider=provider
+    )

src/core/security.py

@@ -111,9 +111,13 @@
 import jwt
 from datetime import datetime, timedelta
 from passlib.context import CryptContext
-from fastapi import HTTPException, status
+from fastapi import HTTPException, status, Depends
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from typing import Dict, Any
+from src.core.config import settings
 
 pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+security = HTTPBearer()
 import hashlib
 MAX_BCRYPT_BYTES = 72
 
@@ -165,3 +169,50 @@ def verify_jwt_token(token: str, secret: str) -> dict:
         raise HTTPException(status_code=401, detail="Token expired")
     except jwt.InvalidTokenError:
         raise HTTPException(status_code=401, detail="Invalid token")
+
+
+def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security)
+) -> Dict[str, Any]:
+    """
+    FastAPI dependency to extract and validate JWT token from Authorization header.
+
+    Args:
+        credentials: HTTP Bearer token credentials from request header
+
+    Returns:
+        Dictionary containing user information from token payload:
+        - id: User ID (parsed from 'sub' claim)
+        - email: User email
+        - iat: Token issued at timestamp
+        - exp: Token expiration timestamp
+
+    Raises:
+        HTTPException 401: If token is missing, invalid, or expired
+    """
+    token = credentials.credentials
+
+    try:
+        payload = verify_jwt_token(token, settings.BETTER_AUTH_SECRET)
+
+        # Extract user ID from 'sub' claim and convert to integer
+        user_id = int(payload.get("sub"))
+
+        return {
+            "id": user_id,
+            "email": payload.get("email"),
+            "iat": payload.get("iat"),
+            "exp": payload.get("exp")
+        }
+    except ValueError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid user ID in token",
+            headers={"WWW-Authenticate": "Bearer"}
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Authentication failed: {str(e)}",
+            headers={"WWW-Authenticate": "Bearer"}
+        )

src/main.py

@@ -1,13 +1,76 @@
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+import logging
 from .core.config import settings
-from .api.routes import tasks, auth
+from .api.routes import tasks, auth, chat, conversations
+from .mcp import register_all_tools
+from .core.exceptions import AIProviderException
+from .schemas.error import ErrorResponse
+
+# Configure logging
+logger = logging.getLogger(__name__)
 
 app = FastAPI(
     title=settings.APP_NAME,
     debug=settings.DEBUG
 )
 
+
+# Global exception handler for AIProviderException
+@app.exception_handler(AIProviderException)
+async def ai_provider_exception_handler(request: Request, exc: AIProviderException):
+    """Convert AIProviderException to structured ErrorResponse."""
+    error_response = ErrorResponse(
+        error_code=exc.error_code,
+        detail=exc.detail,
+        source=exc.source,
+        provider=exc.provider
+    )
+    logger.error(
+        f"AI Provider Error: {exc.error_code} - {exc.detail} "
+        f"(Provider: {exc.provider}, Status: {exc.status_code})"
+    )
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=error_response.model_dump()
+    )
+
+
+# Global exception handler for generic HTTPException
+@app.exception_handler(Exception)
+async def generic_exception_handler(request: Request, exc: Exception):
+    """Catch-all exception handler for unexpected errors."""
+    # Log the full exception for debugging
+    logger.exception(f"Unhandled exception: {str(exc)}")
+
+    # Return structured error response
+    error_response = ErrorResponse(
+        error_code="INTERNAL_ERROR",
+        detail="An unexpected error occurred. Please try again later.",
+        source="INTERNAL"
+    )
+    return JSONResponse(
+        status_code=500,
+        content=error_response.model_dump()
+    )
+
+
+@app.on_event("startup")
+async def startup_event():
+    """Initialize application on startup."""
+    logger.info("Starting application initialization...")
+
+    # Register all MCP tools with the tool registry
+    try:
+        register_all_tools()
+        logger.info("MCP tools registered successfully")
+    except Exception as e:
+        logger.error(f"Failed to register MCP tools: {str(e)}")
+        raise
+
+    logger.info("Application initialization complete")
+
 # Configure CORS
 app.add_middleware(
     CORSMiddleware,
@@ -20,6 +83,8 @@ app.add_middleware(
 # Register routes
 app.include_router(auth.router)
 app.include_router(tasks.router)
+app.include_router(chat.router)
+app.include_router(conversations.router)
 
 
 @app.get("/")

src/mcp/__init__.py

@@ -0,0 +1,130 @@
+"""
+MCP Tools Registration
+
+Registers all MCP tools with the global tool registry.
+Each tool is registered with its contract definition (name, description, parameters).
+"""
+
+import json
+import logging
+from pathlib import Path
+
+from .tool_registry import tool_registry
+from .tools.add_task import add_task
+from .tools.list_tasks import list_tasks
+from .tools.complete_task import complete_task
+from .tools.delete_task import delete_task
+from .tools.update_task import update_task
+
+logger = logging.getLogger(__name__)
+
+
+def load_tool_contract(tool_name: str) -> dict:
+    """
+    Load tool contract definition from JSON file.
+
+    Args:
+        tool_name: Name of the tool (e.g., "add_task")
+
+    Returns:
+        Tool contract dictionary
+
+    Raises:
+        FileNotFoundError: If contract file not found
+    """
+    # Get the project root directory
+    current_file = Path(__file__)
+    project_root = current_file.parent.parent.parent  # backend/src/mcp -> backend
+    contract_path = project_root.parent / "specs" / "001-openai-agent-mcp-tools" / "contracts" / f"{tool_name}.json"
+
+    if not contract_path.exists():
+        raise FileNotFoundError(f"Contract file not found: {contract_path}")
+
+    with open(contract_path, "r") as f:
+        return json.load(f)
+
+
+def register_all_tools():
+    """
+    Register all MCP tools with the global tool registry.
+
+    This function should be called during application startup to ensure
+    all tools are available to the agent.
+    """
+    logger.info("Registering MCP tools...")
+
+    # Register add_task tool
+    try:
+        add_task_contract = load_tool_contract("add_task")
+        tool_registry.register_tool(
+            name=add_task_contract["name"],
+            description=add_task_contract["description"],
+            parameters=add_task_contract["parameters"],
+            handler=add_task
+        )
+        logger.info("Registered tool: add_task")
+    except Exception as e:
+        logger.error(f"Failed to register add_task tool: {str(e)}")
+        raise
+
+    # Register list_tasks tool
+    try:
+        list_tasks_contract = load_tool_contract("list_tasks")
+        tool_registry.register_tool(
+            name=list_tasks_contract["name"],
+            description=list_tasks_contract["description"],
+            parameters=list_tasks_contract["parameters"],
+            handler=list_tasks
+        )
+        logger.info("Registered tool: list_tasks")
+    except Exception as e:
+        logger.error(f"Failed to register list_tasks tool: {str(e)}")
+        raise
+
+    # Register complete_task tool
+    try:
+        complete_task_contract = load_tool_contract("complete_task")
+        tool_registry.register_tool(
+            name=complete_task_contract["name"],
+            description=complete_task_contract["description"],
+            parameters=complete_task_contract["parameters"],
+            handler=complete_task
+        )
+        logger.info("Registered tool: complete_task")
+    except Exception as e:
+        logger.error(f"Failed to register complete_task tool: {str(e)}")
+        raise
+
+    # Register delete_task tool
+    try:
+        delete_task_contract = load_tool_contract("delete_task")
+        tool_registry.register_tool(
+            name=delete_task_contract["name"],
+            description=delete_task_contract["description"],
+            parameters=delete_task_contract["parameters"],
+            handler=delete_task
+        )
+        logger.info("Registered tool: delete_task")
+    except Exception as e:
+        logger.error(f"Failed to register delete_task tool: {str(e)}")
+        raise
+
+    # Register update_task tool
+    try:
+        update_task_contract = load_tool_contract("update_task")
+        tool_registry.register_tool(
+            name=update_task_contract["name"],
+            description=update_task_contract["description"],
+            parameters=update_task_contract["parameters"],
+            handler=update_task
+        )
+        logger.info("Registered tool: update_task")
+    except Exception as e:
+        logger.error(f"Failed to register update_task tool: {str(e)}")
+        raise
+
+    logger.info(f"Successfully registered {len(tool_registry.list_tools())} MCP tools")
+
+
+# Export the global registry instance for use in other modules
+__all__ = ["tool_registry", "register_all_tools"]

src/mcp/tool_registry.py

@@ -0,0 +1,140 @@
+"""
+MCP Tool Registry
+
+Manages registration and execution of MCP tools with user context injection.
+Security: user_id is injected by the backend, never trusted from LLM output.
+"""
+
+from typing import Dict, List, Any, Callable, Optional
+from dataclasses import dataclass
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ToolDefinition:
+    """Definition of an MCP tool for LLM function calling."""
+    name: str
+    description: str
+    parameters: Dict[str, Any]
+
+
+@dataclass
+class ToolExecutionResult:
+    """Result of executing an MCP tool."""
+    success: bool
+    data: Optional[Dict[str, Any]] = None
+    message: Optional[str] = None
+    error: Optional[str] = None
+
+
+class MCPToolRegistry:
+    """
+    Registry for MCP tools with user context injection.
+
+    This class manages tool registration and execution, ensuring that
+    user_id is always injected by the backend for security.
+    """
+
+    def __init__(self):
+        self._tools: Dict[str, Callable] = {}
+        self._tool_definitions: Dict[str, ToolDefinition] = {}
+
+    def register_tool(
+        self,
+        name: str,
+        description: str,
+        parameters: Dict[str, Any],
+        handler: Callable
+    ) -> None:
+        """
+        Register an MCP tool with its handler function.
+
+        Args:
+            name: Tool name (e.g., "add_task")
+            description: Tool description for LLM
+            parameters: JSON schema for tool parameters
+            handler: Async function that executes the tool
+        """
+        self._tools[name] = handler
+        self._tool_definitions[name] = ToolDefinition(
+            name=name,
+            description=description,
+            parameters=parameters
+        )
+        logger.info(f"Registered MCP tool: {name}")
+
+    def get_tool_definitions(self) -> List[Dict[str, Any]]:
+        """
+        Get tool definitions in format suitable for LLM function calling.
+
+        Returns:
+            List of tool definitions with name, description, and parameters
+        """
+        return [
+            {
+                "name": tool_def.name,
+                "description": tool_def.description,
+                "parameters": tool_def.parameters
+            }
+            for tool_def in self._tool_definitions.values()
+        ]
+
+    async def execute_tool(
+        self,
+        tool_name: str,
+        arguments: Dict[str, Any],
+        user_id: int
+    ) -> ToolExecutionResult:
+        """
+        Execute an MCP tool with user context injection.
+
+        SECURITY: user_id is injected by the backend, never from LLM output.
+
+        Args:
+            tool_name: Name of the tool to execute
+            arguments: Tool arguments from LLM
+            user_id: User ID (injected by backend, not from LLM)
+
+        Returns:
+            ToolExecutionResult with success status and data/error
+        """
+        if tool_name not in self._tools:
+            logger.error(f"Tool not found: {tool_name}")
+            return ToolExecutionResult(
+                success=False,
+                error=f"Tool '{tool_name}' not found"
+            )
+
+        try:
+            # Inject user_id into arguments for security
+            arguments_with_context = {**arguments, "user_id": user_id}
+
+            logger.info(f"Executing tool: {tool_name} for user: {user_id}")
+
+            # Execute the tool handler
+            handler = self._tools[tool_name]
+            result = await handler(**arguments_with_context)
+
+            logger.info(f"Tool execution successful: {tool_name}")
+            return result
+
+        except Exception as e:
+            logger.error(f"Tool execution failed: {tool_name} - {str(e)}")
+            return ToolExecutionResult(
+                success=False,
+                error=f"Tool execution failed: {str(e)}"
+            )
+
+    def list_tools(self) -> List[str]:
+        """Get list of registered tool names."""
+        return list(self._tools.keys())
+
+    def has_tool(self, tool_name: str) -> bool:
+        """Check if a tool is registered."""
+        return tool_name in self._tools
+
+
+# Global registry instance
+tool_registry = MCPToolRegistry()