docs/IMPORT_GUIDELINES.md

# Import Guidelines for YLFF

## Overview

This document provides clear guidelines for importing modules in the YLFF codebase to ensure consistency and avoid confusion.

## Directory Structure

```
ylff/
├── model_loader.py      # ML model loading utilities (renamed from models.py)
├── models/              # Pydantic API models (package)
│   └── api_models.py
├── services/            # Business logic
├── utils/               # Utility functions
└── routers/             # API route handlers
```

## Import Patterns

### 1. ML Model Utilities (`model_loader.py`)

**Correct:**

```python
from ylff.model_loader import load_da3_model, get_recommended_model
from ..model_loader import load_da3_model  # In submodules
```

**Incorrect:**

```python
from ylff.models import load_da3_model  # ❌ This imports from models/ package
```

### 2. Pydantic API Models (`models/api_models.py`)

**Correct:**

```python
from ylff.models import JobResponse, ValidateSequenceRequest
from ..models import JobResponse  # In submodules
```

**Incorrect:**

```python
from ylff.model_loader import JobResponse  # ❌ Wrong module
```

### 3. Services

**Correct:**

```python
from ylff.services import BAValidator, ARKitProcessor
from ylff.services.ba_validator import BAValidator
from ..services import BAValidator  # In submodules
```

### 4. Utils

**Correct:**

```python
from ylff.utils.profiler import Profiler, profile
from ylff.utils.coordinate_utils import convert_arkit_to_opencv
from ..utils.profiler import Profiler  # In submodules
```

### 5. Routers

**Correct:**

```python
from ylff.routers import health_router, validation_router
from ..routers import health_router  # In submodules
```

## Naming Convention Summary

| Module                 | Import Path                         | Purpose                              |
| ---------------------- | ----------------------------------- | ------------------------------------ |
| `model_loader.py`      | `from ylff.model_loader import ...` | ML model loading utilities           |
| `models/api_models.py` | `from ylff.models import ...`       | Pydantic API request/response models |
| `services/*.py`        | `from ylff.services import ...`     | Business logic                       |
| `utils/*.py`           | `from ylff.utils import ...`        | Utility functions                    |
| `routers/*.py`         | `from ylff.routers import ...`      | API route handlers                   |

## Common Mistakes to Avoid

### ❌ Mistake 1: Confusing `model_loader` and `models`

```python
# WRONG - This will fail or import wrong thing
from ylff.models import load_da3_model  # ❌

# CORRECT
from ylff.model_loader import load_da3_model  # ✅
```

### ❌ Mistake 2: Using `importlib.util` workarounds

```python
# WRONG - Complex workaround
import importlib.util
spec = importlib.util.spec_from_file_location(...)

# CORRECT - Direct import
from ylff.model_loader import get_recommended_model  # ✅
```

### ❌ Mistake 3: Inconsistent relative imports

```python
# WRONG - Mixing styles
from .models import ...  # Sometimes
from ..models import ...  # Other times

# CORRECT - Consistent relative imports
from ..model_loader import ...  # In submodules
from ylff.model_loader import ...  # At package level
```

## Best Practices

1. **Use absolute imports at package level**: `from ylff.services import BAValidator`
2. **Use relative imports in submodules**: `from ..services import BAValidator`
3. **Be explicit about source**: Import from the specific module, not a parent package
4. **Avoid circular imports**: Services shouldn't import from routers, etc.

## Migration Notes

After renaming `models.py` → `model_loader.py`:

- ✅ All imports updated to use `model_loader`
- ✅ No more `importlib.util` workarounds
- ✅ Clear separation: `model_loader` = ML utilities, `models/` = API models
- ✅ Better IDE autocomplete and type checking