LifeRPG_v2.0/modern/backend/api_docs.py

"""
OpenAPI/Swagger documentation configuration for LifeRPG API.
Provides comprehensive API documentation including AI endpoints.
"""

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

def custom_openapi_schema(app: FastAPI):
    """Generate custom OpenAPI schema with comprehensive AI documentation."""
    if app.openapi_schema:
        return app.openapi_schema

    openapi_schema = get_openapi(
        title="LifeRPG API - AI-Powered Habit Management",
        version="3.0.0",
        description="""
        ## 🧙‍♂️ The AI-Powered Habit Management Platform

        LifeRPG transforms daily habits into magical achievements using cutting-edge AI.
        
        ### 🤖 AI Features
        - **Natural Language Processing**: Create habits using plain English
        - **Predictive Analytics**: AI forecasts habit success probability  
        - **Voice & Image Input**: Multimodal interaction capabilities
        - **Smart Suggestions**: Personalized recommendations
        - **Local Processing**: 100% privacy-focused AI (no external APIs)

        ### 🔒 Authentication
        Most endpoints require JWT authentication. Get your token from `/auth/login`.

        ### 📊 Rate Limits
        - AI endpoints: 60 requests per minute
        - Standard endpoints: 100 requests per minute
        - Authenticated users get higher limits

        ### 🚀 Getting Started
        1. Register: `POST /auth/register`
        2. Login: `POST /auth/login` 
        3. Create habits: `POST /ai/habits/create-natural`
        4. Get predictions: `GET /ai/habits/predict-success/{habit_id}`

        ### 💡 Examples
        **Natural Language Habit Creation:**
        ```json
        {
          "text": "I want to drink 8 glasses of water every day"
        }
        ```
        
        **Response:**
        ```json
        {
          "name": "Drink Water",
          "frequency": "daily",
          "target": 8,
          "unit": "glasses",
          "category": "health"
        }
        ```
        """,
        routes=app.routes,
        tags=[
            {
                "name": "Authentication",
                "description": "User registration, login, and token management"
            },
            {
                "name": "Habits",
                "description": "Core habit CRUD operations"
            },
            {
                "name": "AI Habits",
                "description": "🤖 AI-powered habit management features",
                "externalDocs": {
                    "description": "AI Documentation",
                    "url": "https://git.churchofmalware.org/Diablo_Rain/LifeRPG/blob/master/PHASE_3_AI_README.md"
                }
            },
            {
                "name": "Analytics", 
                "description": "📊 Habit analytics and insights"
            },
            {
                "name": "Social",
                "description": "👥 Social features and leaderboards"
            },
            {
                "name": "Gamification",
                "description": "🎮 XP, levels, achievements, and RPG features"
            },
            {
                "name": "Health",
                "description": "🏥 Health checks and system status"
            }
        ]
    )

    # Add AI-specific schema components
    openapi_schema["components"]["schemas"].update({
        "HabitParseRequest": {
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "description": "Natural language description of the habit",
                    "example": "I want to exercise for 30 minutes every morning"
                }
            },
            "required": ["text"]
        },
        "HabitParseResponse": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Extracted habit name",
                    "example": "Morning Exercise"
                },
                "frequency": {
                    "type": "string",
                    "enum": ["daily", "weekly", "monthly", "custom"],
                    "description": "How often to perform the habit"
                },
                "category": {
                    "type": "string",
                    "description": "AI-determined category",
                    "example": "fitness"
                },
                "target": {
                    "type": "integer", 
                    "description": "Target amount (if applicable)",
                    "example": 30
                },
                "unit": {
                    "type": "string",
                    "description": "Unit of measurement",
                    "example": "minutes"
                },
                "confidence": {
                    "type": "number",
                    "format": "float",
                    "description": "AI confidence in parsing (0.0-1.0)",
                    "example": 0.92
                },
                "suggestions": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "AI suggestions for improvement"
                }
            }
        },
        "AISuccessPrediction": {
            "type": "object", 
            "properties": {
                "probability": {
                    "type": "number",
                    "format": "float",
                    "description": "Success probability (0.0-1.0)",
                    "example": 0.78
                },
                "confidence": {
                    "type": "number",
                    "format": "float", 
                    "description": "Prediction confidence",
                    "example": 0.85
                },
                "factors": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "Key factors influencing prediction"
                },
                "recommendations": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "AI recommendations to improve success"
                }
            }
        },
        "AISuggestion": {
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "description": "Suggestion text",
                    "example": "Try adding a 5-minute warm-up routine"
                },
                "category": {
                    "type": "string",
                    "description": "Suggestion category",
                    "example": "fitness"
                },
                "confidence": {
                    "type": "number",
                    "format": "float",
                    "description": "AI confidence in suggestion",
                    "example": 0.89
                },
                "priority": {
                    "type": "string",
                    "enum": ["low", "medium", "high"],
                    "description": "Suggested priority level"
                }
            }
        },
        "VoiceCommandRequest": {
            "type": "object",
            "properties": {
                "audio_data": {
                    "type": "string",
                    "format": "base64",
                    "description": "Base64 encoded audio data"
                },
                "format": {
                    "type": "string",
                    "enum": ["wav", "mp3", "webm"],
                    "description": "Audio format"
                }
            },
            "required": ["audio_data", "format"]
        },
        "ImageCheckinRequest": {
            "type": "object",
            "properties": {
                "image_data": {
                    "type": "string",
                    "format": "base64", 
                    "description": "Base64 encoded image data"
                },
                "habit_id": {
                    "type": "integer",
                    "description": "Optional habit ID to match against"
                }
            },
            "required": ["image_data"]
        },
        "PatternAnalysis": {
            "type": "object",
            "properties": {
                "patterns": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "Identified behavioral patterns"
                },
                "trends": {
                    "type": "object",
                    "description": "Statistical trends in habit completion"
                },
                "insights": {
                    "type": "array", 
                    "items": {"type": "string"},
                    "description": "AI-generated insights"
                },
                "recommendations": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "Personalized recommendations"
                }
            }
        }
    })

    # Add security schemes
    openapi_schema["components"]["securitySchemes"] = {
        "BearerAuth": {
            "type": "http",
            "scheme": "bearer",
            "bearerFormat": "JWT",
            "description": "JWT token obtained from /auth/login"
        }
    }

    # Add AI endpoints documentation examples
    openapi_schema["paths"]["/api/v1/ai/habits/create-natural"] = {
        "post": {
            "tags": ["AI Habits"],
            "summary": "🤖 Create habit from natural language",
            "description": """
            Parse natural language text into a structured habit using AI.
            
            **Examples:**
            - "I want to drink water every morning"
            - "Exercise for 30 minutes 3 times a week"  
            - "Read 20 pages before bed daily"
            
            The AI will extract:
            - Habit name and description
            - Frequency and timing
            - Target amounts and units
            - Appropriate category
            """,
            "requestBody": {
                "required": True,
                "content": {
                    "application/json": {
                        "schema": {"$ref": "#/components/schemas/HabitParseRequest"}
                    }
                }
            },
            "responses": {
                "200": {
                    "description": "Successfully parsed habit",
                    "content": {
                        "application/json": {
                            "schema": {"$ref": "#/components/schemas/HabitParseResponse"}
                        }
                    }
                },
                "400": {
                    "description": "Invalid input text"
                },
                "429": {
                    "description": "Rate limit exceeded"
                },
                "503": {
                    "description": "AI service unavailable"
                }
            },
            "security": [{"BearerAuth": []}]
        }
    }

    app.openapi_schema = openapi_schema
    return app.openapi_schema


def setup_api_docs(app: FastAPI):
    """Set up comprehensive API documentation."""
    
    # Custom OpenAPI schema
    app.openapi = lambda: custom_openapi_schema(app)
    
    # Add metadata
    app.title = "LifeRPG API"
    app.description = "🧙‍♂️ AI-Powered Habit Management Platform"
    app.version = "3.0.0"
    app.terms_of_service = "https://liferpg.com/terms"
    app.contact = {
        "name": "LifeRPG Support",
        "url": "https://git.churchofmalware.org/Diablo_Rain/LifeRPG",
        "email": "support@liferpg.com"
    }
    app.license_info = {
        "name": "MIT License",
        "url": "https://git.churchofmalware.org/Diablo_Rain/LifeRPG/blob/master/LICENSE"
    }
    
    return app


# Add this to your main app.py file:
# from api_docs import setup_api_docs
# app = setup_api_docs(app)