Add comprehensive FastAPI + SQLModel example with sheppy for background tasks

[Copilot]

This PR adds a complete, production-ready example demonstrating how to integrate sheppy with FastAPI and SQLModel for background task processing with database operations.

Overview

The new example is located at examples/fastapi-integration/with-sqlmodel/ and showcases a real-world user management API with comprehensive audit logging capabilities.

What's Included

📦 Application Structure

A fully-featured FastAPI application with:

• User Management API: Create, read, update users with proper validation
• Audit Logging System: Automatic tracking of all user actions in background tasks
• Background Task Processing: Four different task types demonstrating various database operation patterns
• SQLModel Integration: Type-safe database models with SQLite (easily switchable to PostgreSQL)

🎯 Key Features Demonstrated

1. FastAPI + Sheppy Integration

@app.post("/users/{user_id}/toggle-status")
async def toggle_user_status(
    user_id: int,
    is_active: bool,
    queue: Queue = Depends(get_queue),
):
    task = update_user_activity(user_id=user_id, is_active=is_active)
    await queue.add(task)
    return {"message": "Task queued", "task_id": task.id}

2. Dependency Injection in Tasks

@task
async def create_audit_log(
    user_id: int,
    action: str,
    description: str,
    session: Session = Depends(get_session),  # FastAPI's Depends works!
) -> TaskStatus:
    audit_log = AuditLog(...)
    session.add(audit_log)
    session.commit()
    return TaskStatus(success=True, ...)

3. Database Operations

• Writing: Creating audit logs, updating user status, bulk updates
• Reading: Querying inactive users for cleanup tasks
• Transactions: Proper rollback on errors

4. Real-World Use Cases

• Audit trail for compliance and debugging
• Bulk user updates without blocking API responses
• Scheduled maintenance tasks (cleanup inactive users)

📝 Complete Documentation

The example includes:

• Comprehensive README with setup instructions
• API endpoint documentation with curl examples
• Interactive demo script showing all features
• Production deployment considerations
• Troubleshooting guide

🧪 Testing

15 test cases covering:

• All API endpoints
• Background task execution
• Error handling
• Database operations
• Edge cases

📊 Statistics

• 1,422 lines added across 12 files
• 0 linting errors (passes ruff)
• 0 security vulnerabilities (CodeQL verified)
• 15 comprehensive tests

Why This Example Matters

1. Shows Real Integration: Not just print statements—actual database reads/writes
2. Production Patterns: Demonstrates audit logging, a common enterprise requirement
3. Best Practices: Proper error handling, transactions, dependency injection
4. Easy to Adapt: Clear structure makes it easy to build upon for real projects

Quick Start

# Start Redis
docker run -d -p 6379:6379 redis:latest

# Install dependencies
pip install fastapi uvicorn sqlmodel sheppy redis httpx

# Run the app
cd examples/fastapi-integration/with-sqlmodel
fastapi dev app/main.py

# In another terminal, start the worker
sheppy work

# Try the demo
python demo.py

Closes #[issue-number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add examples with FastAPI apps</issue_title>
<issue_description>we need to:

• add example of full fastapi app with sqlmodel using sheppy for background tasks.
• it should represent how sheppy integrates with fastapi, so it should demonstrate using Depends, and nice integration with fastapi itself
• at least one of the route should focus on using sheppy to queue a task which will use database - reading, and most importantly writing into it. Could be something like updating users, and/or creating some records, perhaps audit records that something happened, or something else that's cool. Be creative</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #8

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.