docs/ERGONOMICS_IMPROVEMENTS.md

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:

# 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:

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:

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:

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

from ylff.config import settings

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

Development Mode

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

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

API Documentation

# 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