docs/APP_UNIFICATION.md

App Unification Summary

Overview

Unified CLI and API into a single app.py entry point that can run in either mode depending on context.

Structure

ylff/app.py

• CLI Application: Imports Typer CLI from cli.py (lazy import)
• API Application: FastAPI app with all routers
• Main Entry Point: Detects context and runs appropriate mode

Entry Points

CLI Mode (Default)

# Via module
python -m ylff validate sequence /path/to/sequence
python -m ylff train start /path/to/data

# Via command (if installed)
ylff validate sequence /path/to/sequence
ylff train start /path/to/data

API Mode

# Via module with --api flag
python -m ylff --api [--host 0.0.0.0] [--port 8000]

# Via uvicorn (recommended for production)
uvicorn ylff.app:api_app --host 0.0.0.0 --port 8000

# Via gunicorn
gunicorn ylff.app:api_app -w 4 -k uvicorn.workers.UvicornWorker

Context Detection

The main() function detects the mode based on:

1. --api flag in command line arguments
2. uvicorn or gunicorn in sys.argv[0]
3. Default: CLI mode

Backward Compatibility

• ylff/cli.py - Still exists, contains all CLI commands
• ylff/api.py - Still exists for backward compatibility (imports from app.py)
• ylff/__main__.py - Updated to use unified main() function
• Dockerfile - Updated to use ylff.app:api_app

Benefits

1. Single Entry Point: One place to manage both CLI and API
2. Context-Aware: Automatically detects which mode to run
3. Flexible: Can run CLI or API from same codebase
4. Backward Compatible: Existing scripts and Docker configs still work

Usage Examples

CLI Commands

# Validation
python -m ylff validate sequence data/sequences/seq001
python -m ylff validate arkit data/arkit_recording

# Dataset building
python -m ylff dataset build data/raw_sequences --output-dir data/training

# Training
python -m ylff train start data/training --epochs 10
python -m ylff train pretrain data/arkit_sequences --epochs 5

# Evaluation
python -m ylff eval ba-agreement data/test --threshold 2.0

# Visualization
python -m ylff visualize data/validation_results

API Server

# Development
python -m ylff --api

# Production
uvicorn ylff.app:api_app --host 0.0.0.0 --port 8000 --workers 4

Files Changed

1. ylff/app.py: Unified entry point with CLI and API
2. ylff/main.py: Updated to use main() from app.py
3. ylff/cli.py: Updated imports to use new structure
4. Dockerfile: Updated CMD to use ylff.app:api_app