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:

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

Incorrect:

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

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

Correct:

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

Incorrect:

from ylff.model_loader import JobResponse  # ❌ Wrong module

3. Services

Correct:

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

4. Utils

Correct:

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:

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

# 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

# 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

# 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