docs/API_MODELS.md

# API Models Documentation

This document describes the Pydantic models used throughout the YLFF API. All models are rigorously defined with comprehensive validation, documentation, and examples.

## Overview

All API request/response models are defined in `ylff/api_models.py` with:

- **Comprehensive field validation** (ranges, types, constraints)
- **Detailed descriptions** for all fields
- **Examples** for every field and model
- **Type safety** with enums where appropriate
- **Custom validators** for complex validation logic
- **JSON schema generation** support

## Model Organization

Models are organized into:

- **Enums**: Type-safe enumerations for common values
- **Request Models**: Input validation for API endpoints
- **Response Models**: Structured response data

## Enums

### `JobStatus`

Job execution status values:

- `queued`: Job is queued for execution
- `running`: Job is currently executing
- `completed`: Job completed successfully
- `failed`: Job failed
- `cancelled`: Job was cancelled

### `DeviceType`

Device type for model inference/training:

- `cpu`: CPU execution
- `cuda`: CUDA GPU execution
- `mps`: Apple Metal Performance Shaders

### `UseCase`

Use case for model selection:

- `ba_validation`: Bundle Adjustment validation
- `mono_depth`: Monocular depth estimation
- `multi_view`: Multi-view depth estimation
- `pose_conditioned`: Pose-conditioned depth
- `training`: Training use case
- `inference`: General inference

## Request Models

### `ValidateSequenceRequest`

Request model for sequence validation endpoint.

**Fields:**

- `sequence_dir` (str, required): Directory containing image sequence
- `model_name` (str, optional): DA3 model name (default: auto-select)
- `use_case` (UseCase): Use case for model selection (default: `ba_validation`)
- `accept_threshold` (float): Accept threshold in degrees (default: 2.0, range: 0-180)
- `reject_threshold` (float): Reject threshold in degrees (default: 30.0, range: 0-180)
- `output` (str, optional): Output JSON path for results

**Validation:**

- `reject_threshold` must be greater than `accept_threshold`
- `sequence_dir` cannot be empty

**Example:**

```json
{
  "sequence_dir": "data/sequences/sequence_001",
  "model_name": "depth-anything/DA3-LARGE",
  "use_case": "ba_validation",
  "accept_threshold": 2.0,
  "reject_threshold": 30.0,
  "output": "data/results/validation.json"
}
```

### `ValidateARKitRequest`

Request model for ARKit validation endpoint.

**Fields:**

- `arkit_dir` (str, required): Directory containing ARKit video and JSON metadata
- `output_dir` (str): Output directory (default: `"data/arkit_validation"`)
- `model_name` (str, optional): DA3 model name
- `max_frames` (int, optional): Maximum frames to process (≥1)
- `frame_interval` (int): Extract every Nth frame (default: 1, ≥1)
- `device` (DeviceType): Device for DA3 inference (default: `cpu`)
- `gui` (bool): Show real-time GUI visualization (default: `False`)

**Validation:**

- `arkit_dir` cannot be empty

### `BuildDatasetRequest`

Request model for building training dataset.

**Fields:**

- `sequences_dir` (str, required): Directory containing sequence directories
- `output_dir` (str): Output directory (default: `"data/training"`)
- `model_name` (str, optional): DA3 model name for validation
- `max_samples` (int, optional): Maximum training samples (≥1)
- `accept_threshold` (float): Accept threshold in degrees (default: 2.0)
- `reject_threshold` (float): Reject threshold in degrees (default: 30.0)
- `use_wandb` (bool): Enable W&B logging (default: `True`)
- `wandb_project` (str): W&B project name (default: `"ylff"`)
- `wandb_name` (str, optional): W&B run name

**Validation:**

- `reject_threshold` must be greater than `accept_threshold`

### `TrainRequest`

Request model for model fine-tuning.

**Fields:**

- `training_data_dir` (str, required): Directory containing training samples
- `model_name` (str, optional): DA3 model name to fine-tune
- `epochs` (int): Number of epochs (default: 10, range: 1-1000)
- `lr` (float): Learning rate (default: 1e-5, >0)
- `batch_size` (int): Batch size (default: 1, ≥1)
- `checkpoint_dir` (str): Checkpoint directory (default: `"checkpoints"`)
- `device` (DeviceType): Device for training (default: `cuda`)
- `use_wandb` (bool): Enable W&B logging (default: `True`)
- `wandb_project` (str): W&B project name (default: `"ylff"`)
- `wandb_name` (str, optional): W&B run name

### `PretrainRequest`

Request model for model pre-training on ARKit sequences.

**Fields:**

- `arkit_sequences_dir` (str, required): Directory containing ARKit sequence directories
- `model_name` (str, optional): DA3 model name to pre-train
- `epochs` (int): Number of epochs (default: 10, range: 1-1000)
- `lr` (float): Learning rate (default: 1e-4, >0)
- `batch_size` (int): Batch size (default: 1, ≥1)
- `checkpoint_dir` (str): Checkpoint directory (default: `"checkpoints/pretrain"`)
- `device` (DeviceType): Device for training (default: `cuda`)
- `max_sequences` (int, optional): Maximum sequences to process (≥1)
- `max_frames_per_sequence` (int, optional): Maximum frames per sequence (≥1)
- `frame_interval` (int): Extract every Nth frame (default: 1, ≥1)
- `use_lidar` (bool): Use ARKit LiDAR depth as supervision (default: `False`)
- `use_ba_depth` (bool): Use BA depth maps as supervision (default: `False`)
- `min_ba_quality` (float): Minimum BA quality threshold (default: 0.0, range: 0.0-1.0)
- `use_wandb` (bool): Enable W&B logging (default: `True`)
- `wandb_project` (str): W&B project name (default: `"ylff"`)
- `wandb_name` (str, optional): W&B run name

### `EvaluateBAAgreementRequest`

Request model for BA agreement evaluation.

**Fields:**

- `test_data_dir` (str, required): Directory containing test sequences
- `model_name` (str): DA3 model name (default: `"depth-anything/DA3-LARGE"`)
- `checkpoint` (str, optional): Path to model checkpoint
- `threshold` (float): Agreement threshold in degrees (default: 2.0, range: 0-180)
- `device` (DeviceType): Device for inference (default: `cuda`)
- `use_wandb` (bool): Enable W&B logging (default: `True`)
- `wandb_project` (str): W&B project name (default: `"ylff"`)
- `wandb_name` (str, optional): W&B run name

### `VisualizeRequest`

Request model for result visualization.

**Fields:**

- `results_dir` (str, required): Directory containing validation results
- `output_dir` (str, optional): Output directory for visualizations
- `use_plotly` (bool): Use Plotly for interactive plots (default: `True`)

## Response Models

### `JobResponse`

Standard response for job-based endpoints.

**Fields:**

- `job_id` (str, required): Unique job identifier
- `status` (JobStatus, required): Current job status
- `message` (str, optional): Status message or error description
- `result` (dict, optional): Job result data (only when completed/failed)

### `ValidationStats`

Statistics from BA validation.

**Fields:**

- `total_frames` (int): Total frames processed (≥0)
- `accepted` (int): Accepted frames count (≥0)
- `rejected_learnable` (int): Rejected-learnable frames count (≥0)
- `rejected_outlier` (int): Rejected-outlier frames count (≥0)
- `accepted_percentage` (float): Percentage accepted (0-100)
- `rejected_learnable_percentage` (float): Percentage rejected-learnable (0-100)
- `rejected_outlier_percentage` (float): Percentage rejected-outlier (0-100)
- `ba_status` (str, optional): BA validation status
- `max_error_deg` (float, optional): Maximum rotation error in degrees (≥0)

### `HealthResponse`

Health check response.

**Fields:**

- `status` (str): Health status (`"healthy"`, `"degraded"`, `"unhealthy"`)
- `timestamp` (float): Unix timestamp
- `request_id` (str): Request ID
- `profiling` (dict, optional): Profiling status if available

### `ModelsResponse`

Response for models list endpoint.

**Fields:**

- `models` (dict): Dictionary of available models with metadata
- `recommended` (str, optional): Recommended model for requested use case

### `ErrorResponse`

Standard error response.

**Fields:**

- `error` (str): Error type/name
- `message` (str): Human-readable error message
- `request_id` (str): Request ID for log correlation
- `details` (dict, optional): Additional error details
- `endpoint` (str, optional): Endpoint where error occurred

## Validation Features

### Field Validators

1. **Range Validation**: Numeric fields have `ge` (≥), `le` (≤), `gt` (>), `lt` (<) constraints
2. **String Validation**: String fields have `min_length` constraints
3. **Custom Validators**:
   - `reject_threshold > accept_threshold` validation
   - Path format validation
   - Non-empty string validation

### Type Safety

- Enums for status values, device types, and use cases
- Optional fields clearly marked with `Optional[Type]`
- Required fields use `...` in Field definition

### Examples

All models include `model_config` with JSON schema examples for:

- API documentation generation
- Client SDK generation
- Testing and validation

## Usage

### In API Endpoints

```python
from .api_models import ValidateSequenceRequest, JobResponse

@app.post("/api/v1/validate/sequence", response_model=JobResponse)
async def validate_sequence(request: ValidateSequenceRequest):
    # request is automatically validated
    # Invalid requests return 422 with detailed error messages
    ...
```

### Model Validation

Pydantic automatically validates:

- Type checking
- Range constraints
- Custom validators
- Required fields
- Enum values

### Error Handling

Validation errors are automatically handled by FastAPI and return:

```json
{
  "error": "ValidationError",
  "message": "Invalid request data",
  "details": [
    {
      "field": "reject_threshold",
      "error": "reject_threshold (20.0) must be greater than accept_threshold (30.0)"
    }
  ],
  "request_id": "..."
}
```

## Benefits

1. **Type Safety**: Catch errors at request time, not runtime
2. **Documentation**: Auto-generated API docs with examples
3. **Validation**: Comprehensive input validation before processing
4. **Consistency**: Standardized request/response formats
5. **Maintainability**: Centralized model definitions
6. **Developer Experience**: Clear error messages and examples