How vitthalhumbe/myalgo works
1. Overall shape
- This is a Python package named myalgo that implements two machine-learning algorithms from scratch: Linear Regression and a feed-forward Artificial Neural Network.
- The repo is organized as a layered system: a Python-facing API on top, a C++ numerical backend underneath, and tests/CI/release tooling around it.
2. Public package boundary
- The installable code lives under src/myalgo, which is the main package boundary.
- src/myalgo/__init__.py exposes the package namespace, while the algorithm entry points are split into linear_regression.py and ann.py.
3. Linear Regression subsystem
- src/myalgo/linear_regression.py is the user-facing implementation for regression.
- The README indicates it supports multiple training methods: Normal Equation, Gradient Descent, and Stochastic Gradient Descent, plus regularization modes: Lasso, Ridge, and Elastic Net.
- This module is the main orchestration layer for model fitting, prediction, and configuration.
4. ANN subsystem
- src/myalgo/ann.py is the high-level neural network module.
- The README shows a compositional model API built from layer objects such as Flatten and Dense, with activations like ReLU, sigmoid, tanh, and softmax.
- It also manages training concerns such as loss selection, learning rate, epochs, and batch size.
5. Neural-network building blocks
- src/myalgo/neuron.py suggests a lower-level implementation of neuron/layer primitives used by the ANN stack.
- Architecturally, this sits between the high-level network API and the numerical backend, likely encapsulating forward/backward behavior for dense computation.
6. C++ performance backend
- The directory src/myalgo/_cpp contains ann.cpp and linear_regression.cpp.
- This is the computational core for numeric-heavy work, and the README explicitly says C++ is used as the high-performance backend for numerical calculations.
- The architecture boundary is clear: Python manages API and model flow; C++ handles performance-sensitive math.
7. Python-to-native integration
- The repo is packaged with setup.py and pyproject.toml, which indicates the build/install path is likely responsible for compiling and exposing the C++ code as part of the Python package.
- For an architecture diagram, it is important to show this as a cross-language boundary between the Python modules and the compiled backend.
8. Training and inference data flow
- Typical flow for both algorithms is: user code imports myalgo, constructs a model, calls fit/train, and then calls predict.
- For ANN, data flows through layer composition, activation/loss evaluation, and iterative optimization.
- For linear regression, data flows through the chosen optimization method or closed-form solution, then into prediction.
9. Test coverage boundary
- tests/test_linear_regression.py and tests/test_ann.py provide algorithm-level verification.
- These tests imply the repo validates both the public API and the core model behavior, likely covering training and prediction paths.
10. Documentation and examples
- README.md provides the primary usage documentation and feature summary.
- docs/MyAlgo.pdf appears to be the fuller project documentation, while results/MNIST loss vs Accuracy.png is a saved experiment artifact rather than runtime code.
11. CI and release pipeline
- .github/workflows/ci.yml suggests automated testing/validation on changes.
- .github/workflows/publish.yml suggests a release workflow for packaging and publishing the library, likely to PyPI given the README badge and install instructions.
12. Key architectural boundaries to show in a diagram
- User application boundary: external Python code calling the package.
- Python API layer: ann.py, linear_regression.py, neuron.py.
- Native compute boundary: src/myalgo/_cpp/*.cpp.
- Quality/release boundary: tests and GitHub Actions.
- This separation is the most important structural feature of the repository.
13. Notable implementation intent
- The project is intentionally “from scratch” and does not depend on high-level ML frameworks like TensorFlow, PyTorch, or scikit-learn.
- That means the architecture is self-contained and centered on its own algorithm implementations rather than external ML services or frameworks.
Main entry points: ann.py Neural network · setup.py Build config · linear_regression.py Linear regression · __init__.py Package init
Components 16
Python API
Installable package boundary and user-facing modules.
- Package init · Exposes the myalgo namespace.
src/myalgo/__init__.py - Linear regression · High-level regression training and prediction API.
src/myalgo/linear_regression.py - Neural network · High-level ANN construction and training API.
src/myalgo/ann.py - Neuron core · Lower-level neuron and layer behavior used by the ANN stack.
src/myalgo/neuron.py
C++ backend
Performance-sensitive numerical core compiled into the package.
- ANN compute · C++ numerical backend for ANN operations.
src/myalgo/_cpp/ann.cpp - Regression compute · C++ numerical backend for linear regression operations.
src/myalgo/_cpp/linear_regression.cpp
Quality & release
Tests and CI/release automation around the package.
- ANN tests · Algorithm-level verification for neural network behavior.
tests/test_ann.py - Regression tests · Algorithm-level verification for linear regression behavior.
tests/test_linear_regression.py - CI workflow · Automated validation on changes.
.github/workflows/ci.yml - Publish workflow · Release and publishing pipeline for packaged builds.
.github/workflows/publish.yml
Docs & assets
Documentation and experiment artifacts.
- README · Primary usage guide and feature summary.
README.md - Project docs · Full project documentation artifact.
docs/MyAlgo.pdf - Experiment plot · Saved result from model experimentation.
Other components
- User code · External Python application using the package.
- Build config · Python packaging and native extension build entry points.
setup.py - Project meta · Build system and project metadata.
pyproject.toml
Connections 18
- User code → Package init: imports · User code imports the package namespace.
- Package init → Linear regression: exposes · Namespace surfaces regression API.
- Package init → Neural network: exposes · Namespace surfaces ANN API.
- Linear regression → Regression compute: uses · Regression delegates numerical work to C++ backend.
- Neural network → Neuron core: composes · ANN builds models from lower-level primitives.
- Neural network → ANN compute: uses · ANN delegates compute-heavy operations to C++ backend.
- Neuron core → ANN compute: bridges · Layer primitives sit between Python API and native compute.
- Build config → ANN compute: builds · Packaging compiles and exposes native ANN code.
- Build config → Regression compute: builds · Packaging compiles and exposes native regression code.
- Project meta → Build config: describes · Project metadata supports the build/install path.
- ANN tests → Neural network: verifies · Tests exercise ANN public behavior.
- Regression tests → Linear regression: verifies · Tests exercise regression public behavior.
- CI workflow → ANN tests: runs · CI executes ANN tests.
- CI workflow → Regression tests: runs · CI executes regression tests.
- Publish workflow → Build config: packages · Release workflow produces distributable builds.
- README → Linear regression: documents · README describes regression usage and options.
- README → Neural network: documents · README describes ANN layers and training.
- Project docs → README: extends · PDF documentation expands on the README.