Repository navigation
Support and Troubleshooting
Diagnose · Understand · Resolve · Verify
A comprehensive guide to diagnosing EveryO problems, resolving common errors, and requesting effective community support.
Home · Installation · Development Setup · Testing and Quality Assurance
Official Support Policy: SUPPORT.md
Maintainer: @krishanth7
Important
Support Availability
EveryO is maintained as an open-source project. Support is provided publicly on a best-effort basis.
There is no guaranteed response time for ordinary support requests, no contractual service-level agreement, and no entitlement to custom development.
Please use public GitHub channels for routine questions. Security vulnerabilities must be reported privately.
- Support Overview
- Where to Get Help
- Before Requesting Support
- System Requirements
- Installation Troubleshooting
- Python Environment Problems
- Import and Dependency Errors
- EveryO Diagnostic Commands
- Tensor Errors
- Automatic Differentiation Problems
- Neural Network Errors
- Training and Optimization Problems
- Data Pipeline Problems
- CUDA Troubleshooting
- TensorFlow Troubleshooting
- ONNX Troubleshooting
- Model Serialization Problems
- Distributed Training Problems
- Performance Problems
- Testing and CI Failures
- Error Diagnosis Workflow
- Submitting a Bug Report
- Requesting a Feature
- Security Reporting
- Support Scope and Limitations
- Troubleshooting Reference Table
- Frequently Asked Questions
- Official Resources
- Next Steps
EveryO provides a readable neural computing framework implemented primarily with Python and NumPy.
Users may encounter problems involving:
- Installation.
- Python environments.
- Dependency compatibility.
- Tensor shapes.
- Gradient computation.
- Neural network architecture.
- Model training.
- Optional acceleration.
- Model export.
- Serialization.
- Distributed execution.
This guide explains how to isolate these problems systematically.
A successful troubleshooting process should:
- Identify the failing component.
- Reproduce the problem.
- Collect relevant environment details.
- Determine the likely cause.
- Apply a targeted correction.
- Verify the result.
- Document unresolved problems.
Fix the underlying cause rather than suppressing error messages or disabling validation.
EveryO provides separate channels for different types of requests.
| Request Type | Recommended Channel |
|---|---|
| Reproducible bug | GitHub Bug Report |
| Feature proposal | GitHub Feature Request |
| Architecture question | GitHub Discussions |
| General usage question | GitHub Discussions |
| Contribution question | GitHub Discussions or relevant PR |
| Security vulnerability | Private Vulnerability Reporting |
Warning
Do not publish security exploit details in public issues or discussions.
Collect enough information for someone else to reproduce the problem.
Include:
- EveryO version.
- Python version.
- Operating system.
- Relevant hardware.
- Installation method.
- Minimal reproducible example.
- Complete error message.
- Optional backend availability.
- Commands already attempted.
python --version
python -m pip --version
python -m pip show everyo
everyo info
everyo doctorpython -c "import sys; print(sys.executable)"python -c "import everyo; print(everyo.__file__)"Remove:
- Access tokens.
- Passwords.
- Personal directory names.
- Private file paths.
- Confidential datasets.
- Internal network information.
Never upload secrets as part of a bug report.
EveryO declares support for Python 3.9 and newer.
The repository CI explicitly exercises Python 3.9–3.12.
For versions beyond the tested CI matrix, verify compatibility before relying on them.
The package declares:
- NumPy.
- Matplotlib.
| Capability | Dependency |
|---|---|
| Development | pytest, pytest-cov, Ruff, PyYAML |
| TensorFlow backend | TensorFlow |
| CUDA build | pybind11 and CUDA toolchain |
| ONNX interoperability | ONNX, ONNX Runtime |
| YAML functionality | PyYAML |
Use a dedicated virtual environment for each project.
Avoid mixing system packages with project-specific dependencies.
Clone the repository:
git clone https://github.com/krishanth7/EveryO.git
cd EveryOCreate a virtual environment:
python -m venv .venvActivate it on Linux or macOS:
source .venv/bin/activateActivate it in Windows PowerShell:
.venv\Scripts\Activate.ps1Install EveryO:
python -m pip install -e .Verify:
everyo info
everyo doctorTry:
python -m pip --versionIf pip is missing, check the Python installation.
Use a virtual environment rather than installing into protected system directories.
First upgrade the environment's packaging tools:
python -m pip install --upgrade pip setuptools wheelThen retry installation.
If the error continues, preserve the complete output.
Confirm that the imported package points to the expected checkout:
python -c "import everyo; print(everyo.__file__)"A common problem is installing EveryO into one Python environment and running code in another.
Check:
python -c "import sys; print(sys.executable)"And:
python -m pip show everyoPowerShell may restrict script execution.
If activation is blocked, use the environment's Python executable directly:
.venv\Scripts\python.exe -m pip install -e .
.venv\Scripts\python.exe -m everyo infoA notebook kernel may use a different Python environment.
Inside the notebook:
import sys
print(sys.executable)Compare that path with the interpreter used to install EveryO.
Use the same interpreter for:
- Package installation.
- Running scripts.
- Testing.
- Debugging.
Likely causes:
- EveryO was not installed.
- The wrong Python environment is active.
- The installation failed.
Resolution:
python -m pip install -e .
python -c "import everyo; print('Import successful')"Install or repair the required dependency:
python -m pip install numpyInstall:
python -m pip install matplotlibInstall only the required extra.
TensorFlow:
python -m pip install -e ".[tensorflow]"ONNX:
python -m pip install -e ".[onnx]"CUDA build bindings:
python -m pip install -e ".[cuda]"Installing the CUDA Python extra does not install an NVIDIA GPU, GPU driver, or CUDA toolkit.
EveryO provides built-in diagnostics.
everyo infoReports information such as:
- EveryO version.
- Python version.
- Platform.
- NumPy version.
- Matplotlib availability.
- TensorFlow availability.
- CUDA availability.
- Default device.
everyo doctorThe diagnostic command checks core components and runs an actual autograd calculation.
everyo info --jsonIf optional TensorFlow or CUDA components are unavailable, the CPU core may still operate normally.
An unavailable optional backend is not automatically a core installation failure.
import everyo as eo
x = eo.tensor(
[2.0],
requires_grad=True,
)
y = x * x
y.backward()
print(x.grad)Expected:
[4.]
If this fails, capture the complete traceback and environment information.
Matrix multiplication requires compatible inner dimensions.
For example:
import everyo as eo
a = eo.tensor([[1.0, 2.0]])
b = eo.tensor([[3.0], [4.0]])
result = eo.matmul(a, b)
print(result.shape)Expected:
(1, 1)
- Incorrect input feature count.
- Unexpected batch dimension.
- Incompatible matrix dimensions.
- Invalid broadcasting.
- Incorrect reshape.
print("Input shape:", a.shape)
print("Weight shape:", b.shape)Check:
print(a.dtype)Avoid silently mixing incompatible data representations.
Check:
print(a.device)When debugging, begin with CPU execution if the problem does not specifically require CUDA.
Confirm that the input requires gradients:
x = eo.tensor(
[3.0],
requires_grad=True,
)Gradients are computed through:
loss.backward()Code executed inside no_grad() does not build the usual gradient graph.
with eo.no_grad():
predictions = model(features)Use this for inference rather than training.
When a backward operation requires an explicit upstream gradient, reduce the result to a scalar or supply the appropriate gradient according to the API.
Compare analytical gradients with central finite differences.
For a scalar function:
f'(x) ≈ [f(x + h) - f(x - h)] / (2h)
Where:
-
his a small perturbation. - The approximation should be compared using appropriate tolerances.
- Floating-point precision affects accuracy.
Report reproducible disagreement between analytical and numerical gradients with:
- Input values.
- Dtype.
- Operation.
- Expected gradient.
- Actual gradient.
- Tolerance.
A linear layer expects an input feature dimension matching its constructor.
model = eo.Linear(
4,
16,
)The final dimension of the input should contain four features.
Ensure the final layer produces the required number of outputs.
For a three-class classification problem:
model = eo.Sequential(
eo.Linear(4, 16),
eo.ReLU(),
eo.Linear(16, 3),
)EveryO uses NHWC image tensors:
(batch, height, width, channels)
For example:
(32, 28, 28, 1)
This is different from the NCHW layout used by some other frameworks.
Use training mode during training and evaluation mode for inference where layers such as dropout or batch normalization depend on mode.
- Print input shapes.
- Inspect layer configuration.
- Check output dimensions.
- Verify activation placement.
- Confirm the loss function.
- Run a small batch.
Possible causes:
- Incorrect labels.
- Learning rate too high.
- Learning rate too low.
- Incorrect model output dimension.
- Data preprocessing problems.
- Gradient computation errors.
- Model capacity limitations.
import everyo as eo
model = eo.Sequential(
eo.Linear(4, 16),
eo.ReLU(),
eo.Linear(16, 3),
)Check:
- Optimizer.
- Learning rate.
- Loss function.
- Batch size.
- Number of epochs.
- Input dimensions.
- Label encoding.
Possible causes:
- Excessive learning rate.
- Invalid inputs.
- Numerical overflow.
- Unstable intermediate operations.
- Invalid loss configuration.
- Check input arrays for NaN or infinity.
- Reduce learning rate.
- Test a small batch.
- Use float32 or float64 where appropriate.
- Examine intermediate values.
- Verify gradients.
If training performance improves while validation performance worsens, consider:
- Regularization.
- Dropout.
- Early stopping.
- More representative data.
- Model simplification.
Features and labels must contain compatible sample counts.
Classification labels and numerical features may require different representations.
A DataLoader may produce a smaller final batch when the dataset size is not divisible by the batch size.
Use deterministic seeds where supported.
Ensure validation and test samples are not accidentally included in training data.
- Verify sample count.
- Verify feature dimensions.
- Verify labels.
- Verify normalization.
- Verify train/test separation.
- Inspect a single batch.
CUDA is optional.
Possible causes:
- No compatible NVIDIA GPU.
- Missing driver.
- Missing CUDA toolkit.
- Native extension not built.
- Incompatible build environment.
import everyo as eo
print(eo.cuda.is_available())python -m pip install -e ".[cuda]"On a supported system with the required toolchain:
./scripts/build_cuda.shOn systems with NVIDIA drivers:
nvidia-smiEveryO supports CPU operation without CUDA.
Where supported by the device API, strict CUDA selection raises an error instead of silently falling back.
The repository documents CUDA tests that skip without GPU hardware.
A successful CPU test run does not establish native CUDA correctness.
TensorFlow is an optional integration.
Install:
python -m pip install -e ".[tensorflow]"python -c "import tensorflow as tf; print(tf.__version__)"TensorFlow availability depends on:
- Python version.
- Operating system.
- Architecture.
- Installed TensorFlow distribution.
- Hardware configuration.
EveryO's NumPy-based core does not require TensorFlow.
When comparing frameworks, check:
- Input dtype.
- Tensor layout.
- Weight initialization.
- Reduction conventions.
- Floating-point tolerance.
ONNX interoperability is optional.
python -m pip install -e ".[onnx]"import everyo as eo
model = eo.Sequential(
eo.Linear(4, 8),
eo.ReLU(),
eo.Linear(8, 2),
)
model.eval()
eo.export_onnx(
model,
"model.onnx",
input_shape=(1, 4),
)The layer-based exporter supports a defined set of layers.
If an architecture is unsupported, consider the tracing exporter.
A traced model may preserve the shapes and control-flow path of its example input.
Do not assume that every traced architecture supports arbitrary batch sizes.
Compare exported-model outputs against EveryO using the same inputs.
- Unsupported operator.
- Incompatible opset.
- Runtime version mismatch.
- Unexpected tensor layout.
- Fixed traced dimensions.
- Numerical differences.
EveryO uses .evo archives.
The repository documents:
model.evo
|
+-- manifest.json
|
+-- parameters.npz
import everyo as eo
model = eo.Sequential(
eo.Linear(4, 8),
eo.ReLU(),
eo.Linear(8, 2),
)
eo.save(
model,
"model.evo",
)restored = eo.load("model.evo")- File not found.
- Corrupt archive.
- Unsupported model configuration.
- Unregistered custom module.
- Parameter shape mismatch.
- Version incompatibility.
Custom module classes should follow the registration and serialization requirements documented in the contributor guide.
EveryO's model loader uses pickle-free serialization.
However, untrusted archives should still be handled carefully.
Verify:
- Process count.
- Rank.
- World size.
- Rendezvous configuration.
- Network connectivity.
Possible causes:
- Missing worker.
- Incorrect rank configuration.
- Different collective call order.
- Worker crash.
- Network interruption.
Multiple workers do not guarantee faster execution.
Thread oversubscription can reduce performance.
On Linux/macOS:
OMP_NUM_THREADS=1 python examples/distributed_training.pyThe README documents testing across separate processes on one host, but not completed validation across two physical machines.
The documented TCP implementation assumes a trusted network and does not provide encrypted transport.
Do not expose the rendezvous service to untrusted networks.
- Large tensor allocations.
- Python execution overhead.
- Inefficient model architecture.
- Repeated device transfers.
- Thread oversubscription.
- Excessive logging.
- Small workloads with high coordination overhead.
everyo benchmark --sizes 128 256 512 1024with eo.profile() as run:
model(batch)
run.summary()Array-in/array-out CUDA calls may transfer data for each operation.
GPU-resident tensors are intended to reduce repeated transfers.
EveryO's documented int8 quantization is not a guaranteed speed optimization.
Record:
- Hardware.
- Input size.
- Dtype.
- Python version.
- EveryO version.
- Repetitions.
- Warm-up behavior.
python -m pip install -e ".[dev]"python -m pytest -qpython -m pytest tests/test_autograd.py -qruff check .ruff format --check .- Formatting violations.
- Lint errors.
- Missing dependencies.
- Failing assertions.
- Platform-specific behavior.
- Incorrect doctests.
- Unhandled numerical warnings.
Tests requiring unavailable hardware or optional dependencies may be skipped.
Do not interpret skipped tests as successful hardware validation.
Use a structured process.
Problem Detected
|
v
Collect Error Output
|
v
Run EveryO Doctor
|
v
Check Python Environment
|
v
Create Minimal Reproduction
|
v
Identify Component
|
+--------+--------+
| |
v v
Known Issue Unknown Issue
| |
v v
Apply Fix Open Bug Report
| |
+--------+--------+
|
v
Verify Result
- Reproduce the problem.
- Record the environment.
- Reduce the example.
- Check documentation.
- Test the suspected fix.
- Re-run validation.
- Report unresolved defects.
Use the official issue template.
# Bug: Short Description
## Summary
Describe the problem.
## Environment
- EveryO version:
- Python version:
- Operating system:
- Hardware:
- Installation method:
- CUDA available:
- TensorFlow available:
## Steps to Reproduce
1.
2.
3.
## Minimal Reproduction
```python
# Reproducible codeDescribe the expected result.
Describe the observed result.
Paste the sanitized traceback.
Include relevant everyo info and
everyo doctor output.
Describe attempted fixes.
## 22.2 Minimal Reproduction
A minimal reproduction should:
- Run independently.
- Avoid private datasets.
- Use small inputs.
- Include required imports.
- Demonstrate one specific problem.
## 22.3 Reporting Numerical Bugs
Include actual and expected values and the comparison tolerance.
---
# 23. Requesting a Feature
Feature requests are welcome but are not guaranteed to be implemented.
## 23.1 Feature Request Channel
[Open Feature Request](https://github.com/krishanth7/EveryO/issues/new?template=feature_request.yml)
## 23.2 Recommended Content
- Problem statement.
- Proposed functionality.
- Intended users.
- Example API.
- Alternatives.
- Compatibility implications.
- Testing requirements.
- Maintenance considerations.
## 23.3 Architectural Changes
Large architectural changes should begin with a discussion or design issue.
## 23.4 Approval
The maintainer makes final decisions under the project governance policy.
---
# 24. Security Reporting
Security vulnerabilities require private reporting.
## 24.1 Report Privately
[Report a Vulnerability](https://github.com/krishanth7/EveryO/security/advisories/new)
## 24.2 Do Not Publish
Do not publish:
- Exploit code.
- Confidential vulnerability details.
- Attack instructions.
- Sensitive affected-system information.
## 24.3 Security Response Targets
The official Security Policy lists:
| Stage | Target |
|:---|:---|
| Acknowledgement | Within 7 days |
| Initial assessment | Within 14 days |
| Fix or mitigation plan | Communicated after assessment |
These are best-effort targets, not contractual guarantees.
## 24.4 Security Policy
[SECURITY.md](https://github.com/krishanth7/EveryO/blob/main/SECURITY.md)
---
# 25. Support Scope and Limitations
The official support policy defines the scope of community assistance.
## 25.1 In Scope
- Installation.
- Documented APIs.
- Reproducible defects.
- Examples.
- Contribution questions.
## 25.2 Not Guaranteed
- Private consulting.
- Custom model development.
- Debugging unrelated applications.
- Hardware support.
- Specific response times.
- Implementation of requested features.
## 25.3 Public Support
Routine questions should use public channels.
Public discussions help create searchable solutions for future users.
---
# 26. Troubleshooting Reference Table
| Problem | Likely Cause | First Action |
|:---|:---|:---|
| Cannot import EveryO | Wrong environment | Check interpreter and installation |
| CLI not found | Environment not active | Activate environment |
| NumPy missing | Dependency unavailable | Install package dependencies |
| Autograd gradient missing | Graph not tracked | Check `requires_grad` |
| Matrix shape error | Incompatible dimensions | Print tensor shapes |
| Loss becomes NaN | Numerical instability | Check data and learning rate |
| CUDA unavailable | Missing hardware/toolchain | Run diagnostics |
| TensorFlow unavailable | Optional extra missing | Check installation |
| ONNX export fails | Unsupported operation | Check exporter coverage |
| Model load fails | Archive or module issue | Inspect serialization requirements |
| Distributed job hangs | Worker or network mismatch | Verify ranks and rendezvous |
| Training is slow | Execution overhead | Profile and benchmark |
| CI fails | Test or formatting issue | Run local checks |
| Security concern | Potential vulnerability | Report privately |
---
# 27. Frequently Asked Questions
<details>
<summary><strong>Does EveryO require an NVIDIA GPU?</strong></summary>
No. The core framework runs on CPU. CUDA acceleration is optional.
</details>
<details>
<summary><strong>Does EveryO require TensorFlow?</strong></summary>
No. TensorFlow is an optional integration and reference backend.
</details>
<details>
<summary><strong>Can EveryO work without an API key?</strong></summary>
Yes. EveryO does not require API keys or user accounts for core operation.
</details>
<details>
<summary><strong>Why is CUDA marked unavailable?</strong></summary>
The required GPU, driver, toolkit, or compiled extension may be unavailable.
Run `everyo doctor` for diagnostics.
</details>
<details>
<summary><strong>Why is my gradient missing?</strong></summary>
Check whether the input requires gradients, whether the computation was tracked, and whether backward was called.
</details>
<details>
<summary><strong>Why does my model train slowly?</strong></summary>
EveryO prioritizes readable and verifiable implementations. Use benchmarks and profiling to identify bottlenecks.
</details>
<details>
<summary><strong>Can I report a bug publicly?</strong></summary>
Yes, for ordinary reproducible defects.
Security vulnerabilities must be reported privately.
</details>
<details>
<summary><strong>Is technical support guaranteed?</strong></summary>
No. Routine support is provided publicly on a best-effort basis.
</details>
---
# 28. Official Resources
| Resource | Link |
|:---|:---|
| Repository | [EveryO](https://github.com/krishanth7/EveryO) |
| Support Policy | [SUPPORT.md](https://github.com/krishanth7/EveryO/blob/main/SUPPORT.md) |
| Installation Guide | [Getting Started](https://github.com/krishanth7/EveryO/blob/main/docs/getting-started.md) |
| API Reference | [API Documentation](https://github.com/krishanth7/EveryO/blob/main/docs/api-reference.md) |
| CUDA Guide | [CUDA Documentation](https://github.com/krishanth7/EveryO/blob/main/docs/cuda.md) |
| Scaling Guide | [Scaling Documentation](https://github.com/krishanth7/EveryO/blob/main/docs/scaling.md) |
| Contributing | [CONTRIBUTING.md](https://github.com/krishanth7/EveryO/blob/main/CONTRIBUTING.md) |
| Security Policy | [SECURITY.md](https://github.com/krishanth7/EveryO/blob/main/SECURITY.md) |
| Bug Reports | [New Bug Report](https://github.com/krishanth7/EveryO/issues/new?template=bug_report.yml) |
| Feature Requests | [New Feature Request](https://github.com/krishanth7/EveryO/issues/new?template=feature_request.yml) |
| Discussions | [GitHub Discussions](https://github.com/krishanth7/EveryO/discussions) |
| CI | [GitHub Actions](https://github.com/krishanth7/EveryO/actions) |
| Maintainer | [@krishanth7](https://github.com/krishanth7) |
---
# 29. Next Steps
Explore related documentation:
| Wiki Page | Purpose |
|:---|:---|
| [Frequently Asked Questions](Frequently-Asked-Questions) | Common questions and answers |
| [Installation](Installation) | Installation instructions |
| [Development Setup](Development-Setup) | Contributor environment |
| [Testing and Quality Assurance](Testing-and-Quality-Assurance) | Testing methodology |
| [Roadmap](Roadmap) | Development status |
| [Project Governance](Project-Governance) | Project decision-making |
*Wiki links become active after their corresponding pages are created.*
---
<div align="center">
### Support and Troubleshooting — Documentation Prepared
**Next Recommended Page: [Frequently Asked Questions →](Frequently-Asked-Questions)**
[Home](Home) · [Installation](Installation) · [Roadmap](Roadmap)
---
**EveryO — Open Machine Learning. Built for Developers.**
**Project Maintainer:** [@krishanth7](https://github.com/krishanth7)
*Open Source · MIT Licensed · Community Driven*
**© 2026 EveryO Contributors**
</div>