How kefirchk/animatica-ml-engine works
Project Type and Purpose
• This is a hybrid ML-inference engine plus REST API service.
• It provides both a CLI entry point for training/reconstruction/animation (run_model.py) and an HTTP server (FastAPI via run_server.py).
File Structure
• Top-level “app” directory contains:
• data/configs & data/checkpoints (model checkpoints & YAML configs)
• src/ml – core ML modules, datasets, augmentation, runners, and services
• src/server – FastAPI app, routers, config, exceptions
• Dockerfile, requirements, entrypoints run_model.py & run_server.py
• Outside “app”: test notebook, docs, CI config, license, pyproject, .gitignore.
Main Components
a. External Actors
• CLI User (invokes run_model.py)
• HTTP Client (browser or other service hitting API endpoints)
• External Model Store (Google Drive / Yandex-Disk for pretrained checkpoints)
b. Container / Deployment Unit
• Docker Container (or local venv) hosting the engine
c. Subsystems Inside the Container
1. Configuration Loader
• YAML configs under app/data/configs
• Environment variables (ML_ENGINE_KEY, API_MODE, LOG_LEVEL)
2. Data Layer
• Checkpoints directory under app/data/checkpoints
3. ML Core
• Datasets & Augmentations (app/src/ml/datasets)
• Network Blocks (encoder, decoder, dense_motion, discriminator, generator, keypoint_detector under app/src/ml/modules)
• Runners (training, reconstruction, animation under app/src/ml/runners)
• Services (model I/O, training loop orchestration, video_animation, logging, visualization under app/src/ml/services)
4. REST API Layer (app/src/server)
• Routers exposing /api/fomm/video
• Exception handlers, configuration
5. HTTP Server
• Uvicorn running FastAPI application
6. CLI Layer
• run_model.py entrypoint invoking appropriate runner
Relationships and Data Flow
• CLI Flow:
User → run_model.py → Config Loader → Selected Runner (train/reconstruction/animation) → Services → Modules → Output (logs, model checkpoints, generated videos)
• REST Flow:
HTTP Client → Uvicorn FastAPI → Router (/api/fomm/video) → Service Layer (animation service) → ML Modules pipeline → Video Writer → HTTP Response
Architectural Patterns & Design Principles
• Layered architecture (CLI/API at top, then services, then core ML modules, then data)
• Separation of concerns:
• Runners orchestrate workflows
• Services wrap module calls and I/O
• Modules implement pure neural-network building blocks
• Configs drive behavior, no hard-coded paths
• Modularity for easy extension (e.g., adding new augmentations, models, runners)
Technologies & Frameworks to Annotate
• Python 3.x
• PyTorch (in modules)
• FastAPI + Uvicorn (in server)
• Docker + Dockerfile + docker-compose
• YAML for configs
• pre-commit, pytest or Jupyter for testing