README.md

metadata

title: TaskFlow API
emoji: ✅
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
license: mit

TaskFlow Backend API

FastAPI backend for TaskFlow task management application with AI chatbot integration.

Features

• 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 .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

pip install -r requirements.txt

2. Configure Environment

Create a .env file in the backend/ directory:

# 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

alembic upgrade head

4. Start the Server

uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000

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

{
  "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

{
  "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

pytest

Database Migrations

Create a new migration:

alembic revision -m "description"

Apply migrations:

alembic upgrade head

Rollback migration:

alembic downgrade -1

License

MIT License