# Ergonomic Improvements for YLFF

## Current Pain Points Identified

### 1. **Naming Conflict: `models.py` vs `models/`** ⚠️ HIGH PRIORITY

- **Issue**: `ylff/models.py` (ML model utilities) conflicts with `ylff/models/` (Pydantic API models)
- **Impact**: Confusing imports, requires workarounds like `importlib.util.spec_from_file_location`
- **Current Workaround**: Complex import logic in `routers/models.py`
- **Solution**: Rename `models.py` → `model_loader.py` or `ml_models.py`

### 2. **No API Documentation** ✅ FIXED

- **Issue**: No automatic OpenAPI/Swagger docs
- **Impact**: Hard to discover endpoints, test API
- **Solution**: Enabled FastAPI's automatic docs at `/docs` and `/redoc`

### 3. **No Configuration Management** ✅ FIXED

- **Issue**: Hardcoded values, no centralized config
- **Impact**: Hard to change settings, no environment-based config
- **Solution**: Added `config.py` with environment variable support

### 4. **Limited Development Experience**

- **Issue**: No hot reload, debug mode, or dev utilities
- **Impact**: Slower development cycle
- **Solution**: Added `--dev` flag for hot reload

### 5. **Import Path Confusion**

- **Issue**: Mixed import styles (`from ..models`, `from .models`, direct imports)
- **Impact**: Hard to know where things come from
- **Solution**: Standardize import paths, add clear documentation

### 6. **Limited Type Hints**

- **Issue**: Some functions lack proper type hints
- **Impact**: Poor IDE support, harder to catch errors
- **Solution**: Add comprehensive type hints throughout

### 7. **No User-Friendly Error Messages**

- **Issue**: Generic error messages, no helpful suggestions
- **Impact**: Hard to debug issues
- **Solution**: Custom exception classes with helpful messages

## Implemented Improvements

### ✅ 1. API Documentation (OpenAPI/Swagger)

**Enabled automatic API documentation:**

- **Swagger UI**: `http://localhost:8000/docs`
- **ReDoc**: `http://localhost:8000/redoc`
- **OpenAPI Schema**: `http://localhost:8000/openapi.json`

**Benefits:**

- Interactive API testing
- Automatic documentation from code
- Client SDK generation support

### ✅ 2. Configuration Management

**Created `ylff/config.py` with:**

- Environment variable support (YLFF\_ prefix)
- `.env` file support for local development
- Type-safe settings with Pydantic
- Sensible defaults

**Usage:**

```bash
# Environment variables
export YLFF_API_PORT=9000
export YLFF_LOG_LEVEL=DEBUG
export YLFF_PROFILING_ENABLED=true

# Or use .env file
YLFF_API_PORT=9000
YLFF_LOG_LEVEL=DEBUG
```

**Available Settings:**

- `YLFF_API_HOST`, `YLFF_API_PORT`, `YLFF_API_WORKERS`
- `YLFF_LOG_LEVEL`, `YLFF_LOG_FORMAT` (text/json)
- `YLFF_PROFILING_ENABLED`
- `YLFF_DEFAULT_MODEL`, `YLFF_DEFAULT_DEVICE`
- `YLFF_WANDB_ENTITY`, `YLFF_WANDB_PROJECT`
- And more...

### ✅ 3. Development Mode

**Added `--dev` flag for hot reload:**

```bash
python -m ylff --api --dev
# or
uvicorn ylff.app:api_app --reload
```

**Features:**

- Automatic code reload on changes
- Better for development workflow

### ✅ 4. Improved Logging

**Added JSON logging support:**

```bash
export YLFF_LOG_FORMAT=json
```

**Benefits:**

- Structured logs for log aggregation
- Better for production monitoring
- Still supports text format for development

## Recommended Next Steps

### Priority 1: Fix Naming Conflict

**Rename `models.py` → `model_loader.py`**

This will:

- Eliminate import confusion
- Remove need for `importlib.util` workarounds
- Improve IDE autocomplete
- Make codebase more maintainable

**Migration:**

1. Rename file: `ylff/models.py` → `ylff/model_loader.py`
2. Update all imports: `from ..models import` → `from ..model_loader import`
3. Update `__init__.py` if needed

### Priority 2: Standardize Imports

**Create import guidelines:**

- Use absolute imports: `from ylff.services import BAValidator`
- Or relative from package root: `from ..services import BAValidator`
- Document preferred patterns

### Priority 3: Add Type Hints

**Improve type coverage:**

- Add return type hints to all functions
- Use `typing.Protocol` for interfaces
- Use `TypedDict` for complex dict structures
- Enable `mypy` for type checking

### Priority 4: Custom Exceptions

**Create domain-specific exceptions:**

```python
class YLFFError(Exception):
    """Base exception for YLFF."""
    pass

class ModelNotFoundError(YLFFError):
    """Raised when model cannot be found."""
    pass

class ValidationError(YLFFError):
    """Raised when validation fails."""
    pass
```

### Priority 5: API Client Generation

**Generate client SDKs:**

- Use OpenAPI schema to generate Python client
- Generate TypeScript client for web apps
- Create CLI tool for API interaction

## Usage Examples

### Configuration

```python
from ylff.config import settings

# Access settings
print(settings.api_port)  # 8000
print(settings.default_model)  # "depth-anything/DA3-LARGE"
```

### Development Mode

```bash
# Start API with hot reload
python -m ylff --api --dev

# Or with custom port
python -m ylff --api --dev --port 9000
```

### API Documentation

```bash
# Start server
uvicorn ylff.app:api_app --host 0.0.0.0 --port 8000

# Visit in browser:
# - Swagger UI: http://localhost:8000/docs
# - ReDoc: http://localhost:8000/redoc
```

## Benefits Summary

1. **Better Developer Experience**

   - Hot reload for faster iteration
   - Interactive API docs
   - Clear configuration management

2. **Better Production Experience**

   - Environment-based configuration
   - JSON logging for aggregation
   - Type-safe settings

3. **Better Maintainability**
   - Centralized configuration
   - Clear import patterns
   - Comprehensive documentation