TaskFlow API

A simple task management REST API built with FastAPI.

Features

CRUD Operations: Create, Read, Update, Delete tasks
Task Filtering: Filter tasks by status
Pagination: List tasks with page and limit parameters
Validation: Pydantic models with field validation
Auto-generated API Docs: Swagger UI at /docs

Setup

Prerequisites

Python 3.11 or higher
pip

Installation

Clone the repository (or navigate to project directory):

cd taskflow

Create and activate virtual environment:

# Create venv
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Activate (Unix/MacOS)
source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Running the API

Start the server:

python main.py

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

API Documentation (Swagger UI): http://localhost:8000/docs

API Endpoints

Create Task

POST /tasks/
Content-Type: application/json

{
  "title": "My task",
  "description": "Optional description",
  "status": "pending"
}

List Tasks

GET /tasks/
GET /tasks/?status_filter=pending
GET /tasks/?page=1&limit=10

Get Single Task

GET /tasks/{task_id}

Update Task

PUT /tasks/{task_id}
Content-Type: application/json

{
  "status": "completed"
}

Delete Task

DELETE /tasks/{task_id}

Task Model

id (UUID): Auto-generated unique identifier
title (string, max 140 chars): Task title (required)
description (string, optional): Task description
status (string): Task status (pending, in_progress, completed, unknown)
created_at (datetime): Auto-generated creation timestamp
updated_at (datetime): Auto-updated modification timestamp

Status Values

Valid status values:

pending - Task not started
in_progress - Task being worked on
completed - Task finished
unknown - Invalid status values are normalized to 'unknown'

Examples

Using cURL

Create a task:

curl -X POST "http://localhost:8000/tasks/" \
  -H "Content-Type: application/json" \
  -d '{"title": "Buy groceries", "status": "pending"}'

List all tasks:

curl "http://localhost:8000/tasks/"

Get specific task:

curl "http://localhost:8000/tasks/{task_id}"

Update task:

curl -X PUT "http://localhost:8000/tasks/{task_id}" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'

Delete task:

curl -X DELETE "http://localhost:8000/tasks/{task_id}"

Using Python requests

import requests

base_url = "http://localhost:8000"

# Create task
response = requests.post(f"{base_url}/tasks/", json={
    "title": "Test task",
    "description": "Testing the API",
    "status": "pending"
})
task = response.json()
task_id = task["id"]

# Get task
task = requests.get(f"{base_url}/tasks/{task_id}").json()
print(task)

# Update task
updated = requests.put(f"{base_url}/tasks/{task_id}", json={
    "status": "completed"
}).json()
print(updated)

# Delete task
requests.delete(f"{base_url}/tasks/{task_id}")

Running Tests

Run the test suite:

pytest ai-state/regressions/backend/ -v

Troubleshooting

Port already in use

If you see "Address already in use" error:

# Windows: Find and kill process on port 8000
netstat -ano | findstr :8000
taskkill /PID <PID> /F

# Unix/MacOS: Find and kill process
lsof -ti:8000 | xargs kill

ModuleNotFoundError

Make sure you've activated the virtual environment and installed dependencies:

# Activate venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Unix/MacOS

# Install dependencies
pip install -r requirements.txt

Tests failing with import errors

Tests are organized in ai-state/regressions/backend/ and include path setup. Run from project root:

pytest ai-state/regressions/backend/ -v

Project Structure

taskflow/
├── main.py                  # FastAPI app and startup
├── models.py                # Pydantic models
├── storage.py               # In-memory storage
├── routes/
│   ├── __init__.py
│   └── tasks.py             # Task endpoints
├── requirements.txt         # Dependencies
├── README.md               # This file
└── ai-state/
    └── regressions/
        └── backend/        # Test files

Development Workflow

This project uses the Khujta Sphere Framework for structured development.

Core Workflow (5 Steps)

1. /core:brainstorm      → Refine requirements
2. /core:write-plan      → Create tasks.yaml
3. /core:analyze-tasks   → Generate config files
4. /core:prepare-standards → Create implementation standards
5. /core:execute-tasks   → Implement systematically

For detailed workflow documentation, see .claude/docs/CORE-WORKFLOW.md

Skills Available

brainstorm - Socratic requirement refinement
write-plan - Phase-appropriate task planning
task-analyzer - Auto-identify config opportunities
config-generator - Master config file creation
standards-creator - Latest docs-based standards
execute-tasks - Guided implementation

See .claude/skills/INDEX.md for all available skills.

Development Notes

Storage: Uses in-memory storage (data lost on restart)
Authentication: None (prototype phase)
Persistence: No database (use for testing/prototyping only)
Framework: Khujta Sphere for structured AI-assisted development

Tech Stack

FastAPI 0.104+: Modern web framework
Pydantic v2: Data validation
Uvicorn: ASGI server
Python 3.11+

License

Prototype project - no license specified.

Name	execute-tasks
Description	This skill should be used when executing tasks from ai-state/active/tasks.yaml sequentially. It loads tasks, gathers context, implements features with phase-appropriate testing, updates task status in tasks.yaml, organizes tests into ai-state/regressions/ folders, and logs all operations to operations.log. Use after write-plan creates tasks.yaml or when resuming development work.

execute-tasks

SKILL.md