How jhackisneros/vision_artificial works
Project Type and Purpose
• This is an end-to-end machine learning system with two major facets:
a) An ML research and experimentation pipeline (data preprocessing, model training, hyperparameter tuning, evaluation, explainability, robustness testing, pruning/quantization, ensemble methods).
b) A deployed inference service (a Flask-based web application packaged in Docker with user authentication via Firebase).
• The goal is to build, evaluate and optimize CNN/MLP models for a computer-vision task (likely image classification), produce lightweight TFLite models, and host a user-facing dashboard that serves real-time predictions.
File Structure Analysis
• Top-level directories:
• notebooks/ → Jupyter notebooks illustrating each stage of the ML workflow.
• experiments/ → JSON/CSV artifacts from hyperparameter trials, ensemble results, robustness scores.
• models/ → Trained model artifacts: .keras, .tflite, and ensemble sub-models.
• src/ → Production-quality Python modules: data ingestion, model definitions, training, evaluation, tuning, explainability, robustness, pruning/quantization, utilities.
• scripts/ → Automation entry-points: converting to TFLite, exporting metrics, initializing Firebase, orchestrating full training runs.
• deployment/ → Dockerfile + Flask app: REST endpoints, static assets (HTML, CSS, JS), Firebase config, utility modules for auth, prediction, theming.
• Configuration:
• requirements.txt & deployment/flask_app/requirements-deploy.txt for dependency management.
• deployment/run_flask.sh to launch the service in container.
Key Components
A. Data Layer
• Raw dataset (images + labels) → src/data.py → persists to local/remote storage.
B. Preprocessing & Augmentation
• Notebook “02_preprocessing” & src/module(s) handle resizing, normalization, augmentation (18 configurations in notebooks).
C. Model Training & Tuning
• src/model_cnn.py / model_mlp.py define architectures.
• src/train.py launches training loops.
• src/tuning.py & hyperparam_trials.json drive Bayesian/grid search.
D. Model Evaluation & Analysis
• src/evaluate.py, src/robustness.py, src/explainability.py produce metrics, GradCAM heatmaps.
• experiments/*.json, *.csv store results.
E. Model Optimization
• src/pruning_quant.py applies pruning and quantization.
• scripts/convert_to_tflite.py exports .tflite.
F. Ensemble Construction
• src/ensemble.py builds ensemble from multiple .keras sub-models.
G. Artifact Storage
• models/ directory holds final .keras, .tflite, ensemble models.
H. Deployment Service
• Docker container running Flask app (deployment/flask_app/app.py).
• Loads TFLite or Keras model at startup.
• Exposes endpoints for user login, registration, prediction, profile, password reset.
• UI templates (HTML/CSS/JS) for dashboard, notifications, theming.
• Firebase for user authentication and data persistence.
I. Automation Scripts
• scripts/reproduce_experiment.sh & run_all_training.sh orchestrate full pipelines.
Relationships & Data Flows
• Data Layer → Preprocessing → Training/Tuning → Evaluation → Optimization → Model Artifacts.
• Artifacts → Deployment Service (via volume mount or image build).
• Deployment Service ↔ Firebase (auth & user data).
• Frontend (browser) ↔ Flask API (prediction requests, user management).
• Optionally, scripts can trigger end-to-end workflows and populate the experiments folder.
Architectural Patterns & Design Principles
• Modular separation of concerns: src modules strictly separated by functionality (data, model, evaluation, utils).
• Reproducibility: deterministic scripts, config file (src/utils/config.py), experiment logs.
• Layered architecture for the web app: Templates, Static assets, Business logic (Flask views), Utilities (auth, prediction).
• ML/DevOps convergence: clear boundary between research notebooks and production code.
Technologies & Frameworks
• Python 3.x, TensorFlow/Keras, TensorFlow Lite, Flask, Docker, Firebase (Auth & Firestore), Jupyter, shell scripting.
• Logging & config via JSON (experiments), Python modules (src/utils/config.py).