Repository navigation
Development Setup
Clone · Configure · Build · Test · Contribute
A comprehensive guide to setting up, understanding, testing, debugging, and contributing to the EveryO development environment.
Home · Getting Started · Framework Architecture · Testing and Quality Assurance
Maintained By & Owner: EveryO Contributors & @krishanth7
Important
Development Philosophy
EveryO is designed to be a readable, reproducible neural computing framework. The core must remain usable without requiring a GPU, TensorFlow, network access during execution, or API credentials.
Contributors should prioritize mathematical correctness, clear implementation, appropriate tests, and honest documentation of limitations.
- Overview
- System Requirements
- Required Development Tools
- Clone the Repository
- Configure Python Environment
- Install Development Dependencies
- Verify Installation
- Repository Architecture
- Development Workflow
- Running Tests
- Linting and Formatting
- Debugging EveryO
- Developing Tensor Operations
- Developing Neural Network Layers
- Optional Backends
- CUDA Development
- Documentation Development
- Git Branching Workflow
- Commit Guidelines
- Pull Request Preparation
- Continuous Integration
- Environment Troubleshooting
- Development Best Practices
- Contributor Readiness Checklist
- Developer References
- Next Steps
The EveryO development environment enables contributors to inspect, modify, test, and extend the framework.
It supports development across:
- Tensor computation.
- Automatic differentiation.
- Neural network architectures.
- Loss functions.
- Optimization algorithms.
- Dataset processing.
- Model training.
- Serialization.
- Backend integration.
- Performance profiling.
- Documentation.
A correctly configured environment should allow developers to:
- Import EveryO.
- Execute tensor operations.
- Run automatic differentiation.
- Run unit and integration tests.
- Apply code formatting.
- Debug framework components.
- Create a development branch.
- Submit a pull request.
EveryO declares Python 3.9 or newer in its package metadata.
The inspected project documentation and CI matrix explicitly cover:
| Python Version | CI Coverage |
|---|---|
| Python 3.9 | Ubuntu |
| Python 3.10 | Ubuntu |
| Python 3.11 | Ubuntu |
| Python 3.12 | Ubuntu, Windows, macOS |
Newer Python versions are not included in the inspected CI matrix and should be validated separately.
- Linux.
- Windows.
- macOS.
| Package | Declared Requirement |
|---|---|
| NumPy | >=1.22 |
| Matplotlib | >=3.5 |
| Package | Purpose |
|---|---|
| pytest | Automated testing |
| pytest-cov | Coverage reporting |
| Ruff | Linting and formatting |
| PyYAML | YAML support |
Check Git installation:
git --versionpython --versionOn systems using python3:
python3 --versionpython -m pip --versionVisual Studio Code is a suitable development environment.
Recommended editor capabilities include:
- Python syntax support.
- Code completion.
- Integrated terminal.
- Git integration.
- Test discovery.
- Debugging.
- Ruff integration.
An editor is a developer preference, not an EveryO runtime requirement.
git clone https://github.com/krishanth7/EveryO.gitcd EveryOgit statusgit branch --show-currentgit remote -vExpected repository origin:
https://github.com/krishanth7/EveryO.git
The displayed URL format may differ when SSH authentication is used.
Use a dedicated virtual environment to isolate development dependencies.
python -m venv .venvsource .venv/bin/activate.venv\Scripts\Activate.ps1.venv\Scripts\activate.batpython -c "import sys; print(sys.executable)"The executable should point to the virtual environment.
python -m pip install --upgrade pippython -m pip install -e ".[dev]"Editable installation allows source changes to be reflected without reinstalling the package after each modification.
EveryO's contributing guide also documents:
./scripts/setup.shThis is intended for a compatible shell environment.
Windows contributors can use the manual Python commands instead.
python -m pip install -e ".[dev,tensorflow]"python -m pip install -e ".[dev,onnx]"python -m pip install -e ".[dev,cuda]"python -m pip install -e ".[dev,yaml]"Note
Installing the CUDA extra provides declared Python build dependencies. It does not automatically guarantee that the native CUDA extension is built or usable.
python -c "import everyo; print('EveryO import successful')"python -m everyo infopython -m everyo doctorimport everyo as eo
x = eo.tensor(
[2.0],
requires_grad=True
)
y = x * x
y.backward()
print(x.grad)Expected numerical gradient:
[4.]
- Package imports successfully.
- CLI diagnostics complete.
- Tensor operations execute.
- Backpropagation produces the expected gradient.
EveryO/
│
├── everyo/
│ ├── core/
│ ├── nn/
│ ├── optim/
│ ├── data/
│ ├── training/
│ ├── serialization/
│ ├── cuda/
│ └── ...
│
├── cuda/
│
├── tests/
│
├── examples/
│
├── docs/
│
├── scripts/
│
├── .github/
│ └── workflows/
│
├── pyproject.toml
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
└── LICENSE
This is a simplified architectural view rather than an exhaustive file tree.
| Component | Responsibility |
|---|---|
core |
Tensors, operations, autograd |
nn |
Neural network modules |
optim |
Optimization algorithms |
data |
Datasets and loading |
training |
Training engine and callbacks |
serialization |
Model persistence and ONNX |
cuda |
Optional CUDA interfaces |
tests |
Automated validation |
examples |
Executable demonstrations |
docs |
Project documentation |
scripts |
Development automation |
The core numerical implementation should remain independent of heavyweight optional backends.
Contributors should avoid introducing unnecessary dependencies into the core layer.
Identify Issue
|
v
Read Existing Implementation
|
v
Create Development Branch
|
v
Implement Change
|
v
Add or Update Tests
|
v
Run Quality Checks
|
v
Update Documentation
|
v
Open Pull Request
|
v
Review and Revision
|
v
Merge After Approval
- Keep changes focused.
- Prefer understandable implementations.
- Add regression tests for bug fixes.
- Preserve public API compatibility where practical.
- Explain behavior changes.
- Avoid unrelated refactoring.
EveryO uses pytest.
python -m pytest -qpython -m pytest tests/test_autograd.py -vpython -m pytest -k gradientpython -m pytest -m "not slow"python -m pytest \
--cov=everyo \
--cov-report=term-missingThe contributing guide documents:
./scripts/test.shFast mode:
./scripts/test.sh --fastCoverage mode:
./scripts/test.sh --coverageEveryO uses Ruff.
ruff check .ruff format --check .ruff format ../scripts/lint.shAutomatic fixes:
./scripts/lint.sh --fixThe inspected configuration specifies:
[tool.ruff]
line-length = 100
target-version = "py39"The development dependencies pin Ruff to version 0.17.0.
Use the repository-defined version to avoid formatter differences between local development and CI.
Debugging is essential for numerical frameworks.
- Tensor shapes.
- Gradient values.
- Computation graph behavior.
- Parameter updates.
- Numerical instability.
- Backend selection.
breakpoint()import everyo as eo
x = eo.tensor(
[2.0],
requires_grad=True
)
y = x * x
breakpoint()
y.backward()Inspect the tensor, output, and gradient behavior.
- Reproduce the problem.
- Reduce it to the smallest failing case.
- Inspect intermediate values.
- Compare against NumPy.
- Verify gradient calculations.
- Add a regression test.
- Confirm the fix.
New differentiable operations require both forward and backward implementations.
everyo/core/operations.py
- Implement forward computation.
- Implement the backward function.
- Handle shape and broadcasting behavior.
- Add numerical gradient tests.
- Export the public operation.
- Update documentation.
For a scalar function:
[ f(x) ]
use the central-difference approximation:
[ f'(x)\approx \frac{f(x+\epsilon)-f(x-\epsilon)} {2\epsilon} ]
- Correct forward values.
- Correct gradient values.
- Appropriate dtype behavior.
- Predictable shape handling.
- Meaningful exceptions.
- Tests for boundary cases.
New layers should integrate with EveryO's module system.
from everyo.nn import Modulefrom everyo.nn.module import register_module- Forward computation.
- Parameters.
- Gradient propagation.
- Training and evaluation behavior.
- Configuration serialization.
- Public exports.
- Unit tests.
For layers with constructor arguments, implement sufficient configuration support for reconstruction.
Include:
- Forward shape tests.
- Parameter tests.
- Gradient tests.
- Serialization round-trip tests.
- Invalid-input tests.
EveryO's core runs on NumPy.
Additional functionality may depend on optional packages or native extensions.
| Backend | Role |
|---|---|
| NumPy | Core numerical computation |
| TensorFlow | Optional interoperability and validation |
| CUDA | Optional acceleration |
| ONNX | Model export and interoperability |
- Preserve CPU functionality.
- Handle missing optional dependencies.
- Provide informative errors.
- Avoid unnecessary runtime requirements.
- Verify numerical compatibility.
Backend-specific tests should skip appropriately when prerequisites are unavailable.
CUDA contributions require additional tooling and hardware validation.
The contributing guide identifies:
cuda/src/
cuda/include/everyo_cuda.h
cuda/bindings/bindings.cpp
everyo/cuda/interface.py
- Check memory bounds.
- Validate CUDA calls.
- Check kernel launches.
- Manage device memory safely.
- Provide appropriate CPU fallback behavior.
- Test numerical correctness.
The project documents:
EVERYO_CUDA_CHECK(...)and:
EVERYO_CUDA_CHECK_KERNEL()./scripts/build_cuda.shpython -m pytest tests/test_devices.py -vCUDA pull requests should specify:
- GPU model.
- CUDA toolkit version.
- Driver environment.
- Tests executed.
- Known limitations.
Do not claim GPU validation when only CPU fallback tests were performed.
Documentation must remain aligned with implemented functionality.
README.md
CONTRIBUTING.md
CHANGELOG.md
docs/
GitHub Wiki
- Correct API names.
- Valid code examples.
- Accurate expected outputs.
- Clear prerequisites.
- Supported version information.
- Explicit limitations.
When modifying public behavior:
- Update relevant documentation.
- Add or revise examples.
- Update tests.
- Record the change in
CHANGELOG.md. - Confirm links remain valid.
Do not present planned functionality as implemented.
Distinguish:
- Available.
- Experimental.
- Planned.
Contributors should develop changes on dedicated branches.
Create a fork using GitHub's Fork action.
git clone https://github.com/YOUR_USERNAME/EveryO.gitgit remote add upstream \
https://github.com/krishanth7/EveryO.gitgit fetch upstream
git switch main
git merge --ff-only upstream/maingit switch -c feature/new-operationfeature/new-operation
fix/gradient-broadcasting
docs/development-guide
test/serialization-regression
refactor/tensor-validation
These are recommended conventions, not strictly enforced branch names.
Commits should communicate changes clearly.
type(scope): concise description
feat(core): add tensor operation
fix(autograd): correct broadcast gradient
test(nn): cover layer serialization
docs(wiki): add development setup guide
refactor(data): simplify batching logic
| Type | Purpose |
|---|---|
feat |
New functionality |
fix |
Bug correction |
docs |
Documentation |
test |
Tests |
refactor |
Internal restructuring |
perf |
Performance improvement |
chore |
Maintenance |
These are proposed commit conventions, not a claim that the repository enforces Conventional Commits.
Run:
python -m pytest -qruff check .ruff format --check .A professional PR should include:
- Problem statement.
- Proposed solution.
- Implementation details.
- Testing performed.
- Compatibility considerations.
- Documentation changes.
- Related issues.
## Summary
Describe the change.
## Motivation
Explain the problem being solved.
## Implementation
Describe the technical approach.
## Testing
- [ ] Unit tests
- [ ] Integration tests
- [ ] Numerical validation
- [ ] Lint and formatting
## Compatibility
Describe any API or behavioral changes.
## Related Issues
Closes #ISSUE_NUMBEREveryO uses GitHub Actions.
.github/workflows/tests.yml
.github/workflows/cuda-build.yml
| Job | Purpose |
|---|---|
| Tests | Python test matrix |
| Lint | Ruff validation |
| TensorFlow | Optional backend tests |
| Examples | Executable examples |
| ONNX | Export and runtime validation |
| Build | Distribution validation |
The inspected test workflow runs on:
- Push.
- Pull request.
- Manual dispatch.
Contributors should review failed checks and fix problems before requesting merge.
A successful local run does not guarantee that all platform-specific CI jobs will pass.
Python command not found
Verify Python installation and PATH configuration.
Try python3 or the Windows Python launcher where appropriate.
Virtual environment activation fails
Confirm the environment exists and use the activation command appropriate to your operating system and shell.
On Windows, PowerShell execution policies may affect script activation.
ModuleNotFoundError: everyo
Confirm the correct virtual environment is active.
Run:
python -m pip install -e ".[dev]"pytest command unavailable
Use:
python -m pytestConfirm development dependencies were installed.
Ruff formatting differs from CI
Reinstall the repository's development dependencies and verify the Ruff version.
CUDA extension unavailable
Verify the CUDA toolkit, compiler, hardware, extension build, and supported environment.
CPU functionality should remain available without CUDA.
Git push permission denied
Verify GitHub authentication and repository permissions.
For external contributions, push to your fork and open a pull request against the upstream repository.
- Keep functions focused.
- Prefer explicit behavior.
- Use meaningful names.
- Add type hints to public interfaces.
- Write clear docstrings.
- Use project-specific exceptions.
- Validate operations against reference calculations.
- Use finite-difference gradient tests.
- Test broadcasting.
- Check numerical stability.
- Document precision limitations.
- Avoid unnecessary dependencies.
- Preserve architectural boundaries.
- Keep changes reviewable.
- Add regression tests.
- Update relevant documentation.
- Never commit credentials.
- Avoid unsafe deserialization.
- Validate external inputs.
- Keep dependencies updated.
- Report vulnerabilities responsibly.
- Git installed.
- Compatible Python installed.
- Repository cloned.
- Virtual environment created.
- Development dependencies installed.
- EveryO imports successfully.
- CLI diagnostics run.
- Tensor operations execute.
- Automatic differentiation works.
- Relevant tests pass.
- Repository architecture understood.
- Feature branch created.
- Code conventions reviewed.
- Test requirements understood.
- Documentation guidelines reviewed.
- Change implemented.
- Tests added or updated.
- Lint checks pass.
- Formatting checks pass.
- Documentation updated.
- Pull request prepared.
| Resource | Link |
|---|---|
| EveryO Repository | GitHub |
| README | README.md |
| Contribution Guide | CONTRIBUTING.md |
| Project Configuration | pyproject.toml |
| Source Code | everyo/ |
| Test Suite | tests/ |
| Examples | examples/ |
| Development Scripts | scripts/ |
| CI Workflow | tests.yml |
| Changelog | CHANGELOG.md |
| Issues | GitHub Issues |
| Pull Requests | GitHub Pull Requests |
Continue with the EveryO contributor documentation.
| Page | Focus |
|---|---|
| Contributing | Contribution workflow and community participation |
| Coding Standards | Source conventions and maintainability |
| Pull Request Guidelines | Review and submission standards |
| Testing and Quality Assurance | Test strategy and CI |
| Release Process | Versioning, packaging, and releases |
Wiki links become active after their corresponding pages are created.
Next Recommended Page: Contributing →
Home · Getting Started · Framework Architecture · Testing and Quality Assurance
EveryO — Open Machine Learning. Built for Developers.
Maintained By & Owner:
EveryO Contributors & @krishanth7
Open Source · MIT Licensed · Community Driven
© 2026 EveryO Contributors