api_specification.yaml

openapi: 3.0.3
info:
  title: LLM Optimization Platform API
  description: |
    Comprehensive API for the LLM Fine-Tuning & Prompt Optimization Platform.
    
    This platform provides endpoints for:
    - Fine-tuned and commercial model text generation
    - Model management and information
    - Prompt evaluation and comparison
    - Cost tracking and budget management
    - Human feedback collection
    - System monitoring and health checks
    
    ## Authentication
    
    Currently, the API uses API key authentication. Include your API key in the `Authorization` header:
    ```
    Authorization: Bearer YOUR_API_KEY
    ```
    
    ## Rate Limits
    
    - Text generation: 100 requests per minute
    - Batch operations: 10 requests per minute
    - Other endpoints: 1000 requests per minute
    
    ## Error Handling
    
    All endpoints return standardized error responses with the following structure:
    ```json
    {
      "error": "error_code",
      "message": "Human readable error message",
      "details": "Additional error details (optional)",
      "timestamp": "2024-01-01T00:00:00Z"
    }
    ```
    
  version: 1.0.0
  contact:
    name: LLM Optimization Platform
    email: support@llm-optimization.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:5000/api/v1
    description: Development server
  - url: https://api.llm-optimization.com/v1
    description: Production server

security:
  - ApiKeyAuth: []

paths:
  # Health and Status Endpoints
  /health:
    get:
      tags:
        - Health
      summary: Basic health check
      description: Returns basic health status of the API service
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: "healthy"
                timestamp: "2024-01-01T00:00:00Z"
                version: "1.0.0"

  /status:
    get:
      tags:
        - Health
      summary: Detailed system status
      description: Returns detailed system information including resource usage
      responses:
        '200':
          description: Detailed system status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedStatusResponse'
        '500':
          description: System unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /ready:
    get:
      tags:
        - Health
      summary: Readiness check
      description: Kubernetes/container readiness probe endpoint
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessResponse'
        '503':
          description: Service not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessResponse'

  # Model Management Endpoints
  /models:
    get:
      tags:
        - Models
      summary: List available models
      description: Returns a list of all available models (fine-tuned and commercial)
      responses:
        '200':
          description: List of available models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsListResponse'
              example:
                models:
                  - id: "gpt-4"
                    name: "GPT-4"
                    type: "commercial"
                    provider: "openai"
                    status: "available"
                  - id: "my-fine-tuned-model"
                    name: "my-fine-tuned-model"
                    type: "fine-tuned"
                    provider: "local"
                    status: "available"
                count: 2
                timestamp: "2024-01-01T00:00:00Z"
        '500':
          description: Error listing models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /models/{model_id}:
    get:
      tags:
        - Models
      summary: Get model information
      description: Returns detailed information about a specific model
      parameters:
        - name: model_id
          in: path
          required: true
          description: Model identifier
          schema:
            type: string
          example: "gpt-4"
      responses:
        '200':
          description: Model information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelInfoResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error getting model info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # Text Generation Endpoints
  /generate:
    post:
      tags:
        - Generation
      summary: Generate text
      description: Generate text using a specified model (fine-tuned or commercial)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
            example:
              prompt: "Write a short story about AI"
              model_id: "gpt-4"
              max_tokens: 100
              temperature: 0.7
              top_p: 1.0
      responses:
        '200':
          description: Text generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
              example:
                text: "Once upon a time, in a world where artificial intelligence..."
                model_id: "gpt-4"
                prompt: "Write a short story about AI"
                parameters:
                  max_tokens: 100
                  temperature: 0.7
                  top_p: 1.0
                metrics:
                  latency_ms: 1500
                  input_tokens: 8
                  output_tokens: 95
                  total_tokens: 103
                timestamp: "2024-01-01T00:00:00Z"
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Generation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /generate/batch:
    post:
      tags:
        - Generation
      summary: Batch text generation
      description: Generate text for multiple prompts using a specified model
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchGenerateRequest'
            example:
              prompts: 
                - "What is AI?"
                - "Explain machine learning"
              model_id: "gpt-4"
              max_tokens: 50
              temperature: 0.7
      responses:
        '200':
          description: Batch generation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGenerateResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Batch generation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key authentication. Use "Bearer YOUR_API_KEY"

  schemas:
    # Common Schemas
    ErrorResponse:
      type: object
      required:
        - error
        - message
        - timestamp
      properties:
        error:
          type: string
          description: Error code
          example: "validation_error"
        message:
          type: string
          description: Human readable error message
          example: "Invalid request parameters"
        details:
          type: string
          description: Additional error details
          example: "max_tokens must be between 1 and 2048"
        timestamp:
          type: string
          format: date-time
          description: Error timestamp in ISO 8601 format
          example: "2024-01-01T00:00:00Z"

    # Health Schemas
    HealthResponse:
      type: object
      required:
        - status
        - timestamp
        - version
      properties:
        status:
          type: string
          enum: [healthy, unhealthy]
          example: "healthy"
        timestamp:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
        version:
          type: string
          example: "1.0.0"

    DetailedStatusResponse:
      type: object
      required:
        - status
        - timestamp
        - version
        - system
        - environment
      properties:
        status:
          type: string
          enum: [healthy, degraded, unhealthy]
        timestamp:
          type: string
          format: date-time
        version:
          type: string
        system:
          type: object
          properties:
            memory:
              type: object
              properties:
                total:
                  type: integer
                available:
                  type: integer
                percent:
                  type: number
                used:
                  type: integer
            disk:
              type: object
              properties:
                total:
                  type: integer
                free:
                  type: integer
                used:
                  type: integer
                percent:
                  type: number
            cpu:
              type: object
              properties:
                percent:
                  type: number
                count:
                  type: integer
        environment:
          type: object
          properties:
            python_version:
              type: string
            platform:
              type: string
        warnings:
          type: array
          items:
            type: string

    ReadinessResponse:
      type: object
      required:
        - ready
        - timestamp
        - checks
      properties:
        ready:
          type: boolean
        timestamp:
          type: string
          format: date-time
        checks:
          type: object
          properties:
            memory_available:
              type: boolean
            disk_available:
              type: boolean

    # Model Schemas
    Model:
      type: object
      required:
        - id
        - name
        - type
        - provider
        - status
      properties:
        id:
          type: string
          description: Unique model identifier
          example: "gpt-4"
        name:
          type: string
          description: Human readable model name
          example: "GPT-4"
        type:
          type: string
          enum: [commercial, fine-tuned]
          description: Model type
        provider:
          type: string
          description: Model provider
          example: "openai"
        description:
          type: string
          description: Model description
        status:
          type: string
          enum: [available, unavailable]
          description: Model availability status
        capabilities:
          type: array
          items:
            type: string
          description: Model capabilities
          example: ["text-generation", "chat"]
        context_length:
          type: integer
          description: Maximum context length in tokens
          example: 8192

    ModelsListResponse:
      type: object
      required:
        - models
        - count
        - timestamp
      properties:
        models:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        count:
          type: integer
          description: Total number of models
        timestamp:
          type: string
          format: date-time

    ModelInfoResponse:
      type: object
      required:
        - model
        - timestamp
      properties:
        model:
          $ref: '#/components/schemas/Model'
        timestamp:
          type: string
          format: date-time

    # Generation Schemas
    GenerateRequest:
      type: object
      required:
        - prompt
        - model_id
      properties:
        prompt:
          type: string
          description: Input prompt for text generation
          minLength: 1
          maxLength: 10000
          example: "Write a short story about AI"
        model_id:
          type: string
          description: Model identifier to use for generation
          example: "gpt-4"
        max_tokens:
          type: integer
          description: Maximum number of tokens to generate
          minimum: 1
          maximum: 2048
          default: 100
        temperature:
          type: number
          description: Sampling temperature (0.0 to 2.0)
          minimum: 0.0
          maximum: 2.0
          default: 0.7
        top_p:
          type: number
          description: Nucleus sampling parameter
          minimum: 0.0
          maximum: 1.0
          default: 1.0

    GenerateResponse:
      type: object
      required:
        - text
        - model_id
        - prompt
        - parameters
        - metrics
        - timestamp
      properties:
        text:
          type: string
          description: Generated text
        model_id:
          type: string
          description: Model used for generation
        prompt:
          type: string
          description: Original input prompt
        parameters:
          type: object
          description: Generation parameters used
          properties:
            max_tokens:
              type: integer
            temperature:
              type: number
            top_p:
              type: number
        metrics:
          type: object
          description: Generation metrics
          properties:
            latency_ms:
              type: integer
              description: Generation latency in milliseconds
            input_tokens:
              type: integer
              description: Number of input tokens
            output_tokens:
              type: integer
              description: Number of output tokens
            total_tokens:
              type: integer
              description: Total tokens (input + output)
        metadata:
          type: object
          description: Additional metadata from the model
        timestamp:
          type: string
          format: date-time

    BatchGenerateRequest:
      type: object
      required:
        - prompts
        - model_id
      properties:
        prompts:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 10
          description: List of prompts for batch generation
        model_id:
          type: string
          description: Model identifier to use for generation
        max_tokens:
          type: integer
          minimum: 1
          maximum: 2048
          default: 100
        temperature:
          type: number
          minimum: 0.0
          maximum: 2.0
          default: 0.7
        top_p:
          type: number
          minimum: 0.0
          maximum: 1.0
          default: 1.0

    BatchGenerateResponse:
      type: object
      required:
        - results
        - model_id
        - parameters
        - metrics
        - timestamp
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              prompt:
                type: string
              text:
                type: string
                nullable: true
              success:
                type: boolean
              error:
                type: string
                nullable: true
              metadata:
                type: object
        model_id:
          type: string
        parameters:
          type: object
        metrics:
          type: object
          properties:
            total_latency_ms:
              type: integer
            successful_generations:
              type: integer
            failed_generations:
              type: integer
            average_latency_ms:
              type: integer
        timestamp:
          type: string
          format: date-time

tags:
  - name: Health
    description: Health check and system status endpoints
  - name: Models
    description: Model management and information endpoints
  - name: Generation
    description: Text generation endpoints