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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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`