How mart1t1/synergie works
Project Overview and Key Components
• This is an AI/ML project that handles dataset generation, model training, inference, and provides an API. The overall process starts with the generation of annotated IMU data sessions, passes through the training of deep learning models, and finally serves inference requests via FastAPI.
• CLI/Main Driver (main.py): Acts as the entry point for both training (-t) and dataset/dataset generation (-p) modes.
• Data Generation Module: Encapsulated under the data_generation directory. It handles exporting and aligning data from IMU CSV files, using defined constants (from constants.py) to map sessions.
• Training Module: Located in the training directory. This includes data augmentation, hyperparameter settings, loading routines, and the training pipeline.
• Model Module: In the model directory. Contains the logic and definition of the figure skating jump recognition model.
• Inference Module: Found in the inference directory. Uses the trained model structure to perform predictions.
• API Component: Under the api directory (api/api.py). Built with FastAPI to expose at least one endpoint for integration or real-time inference.
• Saved Models: The saved_models directory holds checkpoints and model files used for both inference and, potentially, restarting training.
• Utility Functions: Distributed across utils for plotting, jump detection logic (‘jump.py’), and signal resampling routines.
• Testing: Includes tests folder for API and possibly for other modules.
Analyzing Relationships and Data Flow
• Data Generation Component reads paths and settings from the constants files and retrieves session CSV files. Its output (processed data) is then used for model training.
• The Training Module (with hyperparameters, data augmentation, and data loading) consumes the data and feeds it to the Model Module to train and generate checkpoints.
• The Inference Module, using the saved model artifacts that are stored in the saved_models checkpoint structure, is responsible for performing predictions. It typically uses the same model structure as training.
• The API component is integrated with the Inference Module to expose jump recognition functionality via HTTP endpoints.
• Underlying Utilities are shared components helping plotting, signal processing, etc., to facilitate data quality, visualization, or preprocessing.
Important Architectural Patterns & Principles
• Modularization: Notice that the project is divided by function (data_generation, training, inference, api) so that each area is self-contained.
• Separation of Concerns: The CLI triggers modules without tightly coupling their functionality, and the API module only exposes what’s necessary (inference endpoint).
• Reusability: Utilities and shared constants enable code reuse.
• Integration Points: There’s a clear division between offline (training, data generation) and online (API/inference) components.