1. Overview
2. Engineering Principles
3. Python Compatibility
4. Formatting and Linting
5. Naming Conventions
6. Module Organization
7. Type Annotations
8. Docstring Standards
9. Public API Design
10. Error Handling
11. Tensor Operations
12. Automatic Differentiation
13. Neural Network Modules
14. Numerical Precision and Stability
15. Memory and Performance
16. Data Pipeline Standards
17. Backend Independence
18. CUDA Coding Standards
19. Security and Input Validation
20. Testing Standards
21. Documentation Standards
22. Logging and Diagnostics
23. Dependency Management
24. Git and Commit Practices
25. Code Review Standards
26. Quality Checklist
27. Official References
28. Next Steps

Coding standards provide a consistent engineering foundation for EveryO.

They help contributors implement new features while preserving the framework's architecture, mathematical behavior, and public interfaces.

• Improve source readability.
• Reduce defects.
• Preserve numerical correctness.
• Maintain API consistency.
• Support multiple contributors.
• Improve testability.
• Prevent unnecessary dependencies.
• Simplify long-term maintenance.

EveryO is a readable neural computing framework.

Its engineering philosophy prioritizes correctness and clarity over unnecessary complexity.

1. Correctness before optimization.
2. Readability before cleverness.
3. Explicit behavior before hidden assumptions.
4. Tests before unsupported claims.
5. Stable APIs before unnecessary changes.
6. Minimal dependencies.
7. CPU functionality as the baseline.
8. Documentation aligned with implementation.

The core framework must not require:

• GPU hardware.
• CUDA.
• TensorFlow.
• API credentials.
• Network access.
• External AI services.

Optimization is encouraged when it provides measurable value.

However, a performance improvement that substantially reduces maintainability should be evaluated carefully.

Contributors must not fabricate benchmarks or claim unverified acceleration.

EveryO declares:

requires-python = ">=3.9"

The inspected project CI explicitly tests Python 3.9 through 3.12.

New core code should remain compatible with Python 3.9 unless an approved change modifies the supported baseline.

Prefer syntax supported by the minimum Python version.

For example:

from typing import Optional

def normalize(
    values: list[float],
    epsilon: Optional[float] = None,
) -> list[float]:
    ...

Avoid introducing syntax requiring a newer interpreter without an approved compatibility change.

Run the relevant tests on the supported Python versions, using CI to identify version-specific failures.

EveryO uses Ruff.

The inspected pyproject.toml specifies:

[tool.ruff]
line-length = 100
target-version = "py39"
exclude = [".venv", "build", "dist"]

[tool.ruff.lint]
select = [
    "E",
    "F",
    "W",
    "I",
    "UP",
    "B",
    "C4",
    "SIM",
    "RET",
]

These cover areas including style, potential errors, import ordering, Python modernization, common bugs, and simplification.

ruff check .

ruff format --check .

ruff format .

./scripts/lint.sh

Automatic fixes:

./scripts/lint.sh --fix

The development dependencies pin:

ruff==0.17.0

Use the repository-defined version to minimize differences between local development and CI.

Consistent naming improves readability and discoverability.

Preferred:

learning_rate = 0.001
batch_size = 32

Avoid:

lr2 = 0.001
bsx = 32

Short mathematical variables such as x, y, and w are acceptable when their meaning is clear.

Prefer names that communicate a condition:

is_training = True
requires_grad = False
has_bias = True

Modules should have focused responsibilities.

everyo/
│
├── core/
│   ├── tensor.py
│   ├── operations.py
│   └── device.py
│
├── nn/
│   ├── module.py
│   ├── layers.py
│   └── losses.py
│
├── optim/
├── data/
├── training/
├── serialization/
└── cuda/

This is an illustrative selection of repository modules.

A module should have one clear responsibility.

Avoid mixing unrelated functions such as:

• Dataset parsing.
• Neural network initialization.
• Model serialization.
• CLI output.

The contribution guide recommends splitting files that grow beyond a few hundred lines when doing so improves clarity.

This is a design guideline rather than a strict line-count limit.

Avoid circular imports.

Keep dependencies flowing toward foundational modules rather than making the core depend on higher-level training or visualization features.

EveryO requires type hints on public functions and methods.

def calculate_batch_count(
    sample_count: int,
    batch_size: int,
) -> int:
    if batch_size <= 0:
        raise ValueError("batch_size must be positive")

    return (sample_count + batch_size - 1) // batch_size

• Annotate parameters.
• Annotate return values.
• Use meaningful types.
• Avoid unnecessary Any.
• Preserve Python 3.9 compatibility.
• Keep public interfaces understandable.

from typing import Optional

def create_label(
    name: Optional[str] = None,
) -> str:
    return name or "unnamed"

Type annotations do not replace runtime validation.

Tensor shapes, numerical dtypes, and device availability may still require explicit checks.

Public modules, classes, and functions require docstrings.

A public function docstring should explain:

• Purpose.
• Parameters.
• Return value.
• Exceptions.
• Important numerical behavior.
• Usage examples where useful.

def calculate_batch_count(
    sample_count: int,
    batch_size: int,
) -> int:
    """Calculate the number of batches including the final partial batch.

    Args:
        sample_count: Total number of samples.
        batch_size: Number of samples per batch.

    Returns:
        Number of batches.

    Raises:
        ValueError: If sample_count is negative or batch_size is not positive.
    """
    if sample_count < 0:
        raise ValueError("sample_count must be non-negative")

    if batch_size <= 0:
        raise ValueError("batch_size must be positive")

    return (sample_count + batch_size - 1) // batch_size

When implementing numerical operations, document the relevant formula and shape behavior.

For example:

[ Y=XW+b ]

Explain input, parameter, and output dimensions.

Public APIs should be predictable and consistent.

• Use descriptive names.
• Keep signatures focused.
• Provide sensible defaults.
• Validate invalid arguments.
• Document side effects.
• Avoid unexpected global state.
• Preserve backward compatibility where practical.

import everyo as eo

layer = eo.Linear(
    4,
    8,
    bias=True,
    seed=42,
)

When introducing a public operation, update the relevant package exports.

For core operations:

everyo/__init__.py

For neural network layers:

everyo/nn/__init__.py
everyo/__init__.py

Proposals that alter existing signatures or behavior should document:

• Motivation.
• Compatibility impact.
• Migration approach.
• Required tests.
• Release implications.

EveryO defines framework-specific exception classes.

• EveryOError
• EveryOShapeError
• EveryODTypeError
• EveryODeviceError
• EveryOGradientError
• EveryOSerializationError

Error messages should identify the relevant values and explain the problem.

Preferred:

Cannot multiply matrices with shapes
(32, 64) and (128, 10).

Avoid ambiguous messages such as:

Invalid input.

def validate_matrix_dimensions(
    left_shape: tuple[int, int],
    right_shape: tuple[int, int],
) -> None:
    if left_shape[1] != right_shape[0]:
        raise ValueError(
            "Incompatible matrix shapes: "
            f"{left_shape} and {right_shape}"
        )

This example demonstrates error-message quality; production EveryO code should use the appropriate framework exception where applicable.

Avoid broad exception handling that hides programming errors.

When wrapping an exception, preserve useful diagnostic information.

Tensor operations must preserve mathematical and shape correctness.

• Validate input shapes.
• Handle broadcasting correctly.
• Preserve expected dtype behavior.
• Implement correct forward computation.
• Implement backward computation when differentiable.
• Test edge cases.

For compatible dimensions, broadcasting expands operands conceptually without changing the mathematical meaning of the operation.

Gradient implementations must reduce contributions along broadcast dimensions appropriately.

For:

[ A\in\mathbb{R}^{m\times k} ]

and:

[ B\in\mathbb{R}^{k\times n} ]

the output has shape:

[ AB\in\mathbb{R}^{m\times n} ]

import numpy as np
import everyo as eo

def test_matmul_shape():
    a = eo.ones(3, 4)
    b = eo.ones(4, 5)

    result = eo.matmul(a, b)

    assert result.shape == (3, 5)

    np.testing.assert_allclose(
        result.numpy(),
        np.full((3, 5), 4.0),
    )

Automatic differentiation is a correctness-critical subsystem.

Every new differentiable operation must have appropriate gradient tests.

The contribution guide specifically requires finite-difference verification.

[ \frac{\partial f}{\partial x_i} \approx \frac{f(x_i+\epsilon)-f(x_i-\epsilon)} {2\epsilon} ]

For:

[ f(x)=x^2 ]

the derivative is:

[ f'(x)=2x ]

import numpy as np
import everyo as eo

def test_square_gradient():
    x = eo.tensor(
        [2.0],
        requires_grad=True,
    )

    y = x * x
    y.backward()

    np.testing.assert_allclose(
        x.grad,
        [4.0],
    )

• Scalar inputs.
• Vector inputs.
• Matrix inputs.
• Broadcasting.
• Reused tensors.
• Gradient accumulation.
• Chain-rule composition.
• Invalid gradient shapes.

Use tolerances appropriate to the dtype, operation, and numerical conditions.

Do not impose one universal tolerance on all computations.

New layers should follow EveryO's Module architecture.

• Subclass Module.
• Register the layer appropriately.
• Implement forward().
• Register trainable parameters.
• Support applicable backward computation.
• Provide configuration for serialization.
• Add tests.

import everyo as eo

model = eo.Sequential(
    eo.Linear(4, 16, seed=0),
    eo.ReLU(),
    eo.Linear(16, 2, seed=1),
)

output = model(eo.zeros(8, 4))

assert output.shape == (8, 2)

Layers with constructor arguments should implement get_config() when necessary for reconstruction.

Include save/load round-trip tests.

Modules with training-dependent behavior should correctly support the framework's training and evaluation modes.

Machine learning computations are affected by floating-point limitations.

• Overflow.
• Underflow.
• Cancellation.
• Division by zero.
• Loss of precision.
• Unstable exponentiation.

For logits (z_i), a numerically stable softmax subtracts the maximum logit:

[ softmax(z_i)= \frac{e^{z_i-m}} {\sum_j e^{z_j-m}} ]

where:

[ m=\max_j z_j ]

• Use stable formulations.
• Avoid unnecessary precision conversions.
• Test extreme input values.
• Compare against trusted numerical references.
• Document known limitations.

import numpy as np

np.testing.assert_allclose(
    actual,
    expected,
    rtol=1e-5,
    atol=1e-7,
)

The example tolerances are illustrative and must be chosen for the specific computation.

Performance improvements must preserve correctness and readability.

• Prefer vectorized operations.
• Avoid unnecessary copies.
• Reduce redundant computation.
• Profile before optimizing.
• Benchmark representative workloads.
• Record numerical differences.

For a dense array:

[ Memory=Elements\times BytesPerElement ]

Performance claims should include:

• Hardware.
• Python version.
• EveryO version or commit.
• Input dimensions.
• Dtype.
• Number of repetitions.
• Timing methodology.
• Baseline results.

A performance change should explain why the improvement justifies any added complexity.

Data processing must preserve sample integrity and reproducibility.

• Validate feature-target alignment.
• Handle empty datasets.
• Validate batch sizes.
• Avoid unintended dtype conversions.
• Document shuffling behavior.
• Preserve deterministic behavior when seeded.

import numpy as np
import everyo as eo

features = np.zeros(
    (100, 4),
    dtype=np.float32,
)

targets = np.zeros(
    100,
    dtype=np.int64,
)

dataset = eo.ArrayDataset(
    features,
    targets,
)

loader = eo.DataLoader(
    dataset,
    batch_size=16,
    shuffle=True,
    seed=42,
)

Fit preprocessing parameters on training data only.

Apply the fitted transformation to validation and test data.

Seeded workflows should be tested for repeatability where the API promises deterministic behavior.

EveryO's core must remain usable without optional acceleration or interoperability packages.

The core numerical implementation uses NumPy.

• Optional imports must not break core imports.
• CPU-only testing must remain possible.
• Unsupported devices should produce meaningful behavior or errors.
• Backend-specific tests should skip appropriately.

Do not make everyo.core depend on higher-level modules or heavyweight optional frameworks.

CUDA development requires additional safety and correctness controls.

cuda/src/
cuda/include/everyo_cuda.h
cuda/bindings/bindings.cpp
everyo/cuda/interface.py

• Bounds-check memory access.
• Validate CUDA calls.
• Check kernel launches.
• Use safe device-memory ownership.
• Provide NumPy fallback behavior.
• Compare results with CPU references.

Use the repository's CUDA error-checking facilities:

EVERYO_CUDA_CHECK(...)

EVERYO_CUDA_CHECK_KERNEL()

Use the project's detail::DeviceBuffer abstraction where required to ensure device memory is released safely.

./scripts/build_cuda.sh

python -m pytest tests/test_devices.py -v

CUDA pull requests should document the actual hardware tested.

Security is part of code quality.

Do not introduce:

• Credential harvesting.
• Undisclosed telemetry.
• Unauthorized network activity.
• Malicious code.
• Unsafe execution of model-file contents.
• Secrets committed to the repository.

Validate relevant:

• Tensor shapes.
• Dtypes.
• Array dimensions.
• Configuration values.
• File formats.
• Serialization metadata.

EveryO's security policy describes pickle-free model loading.

Changes must preserve the intended safe-loading architecture.

Report vulnerabilities privately:

GitHub Private Vulnerability Reporting

Do not publish exploit details in a public issue.

Behavioral changes require appropriate tests.

python -m pytest -q

python -m pytest tests/test_autograd.py -v

Tests requiring CUDA or TensorFlow should skip appropriately when the required environment is unavailable.

Tests should be:

• Deterministic where practical.
• Focused.
• Readable.
• Independent.
• Meaningful.
• Sensitive to actual defects.

Avoid assertions that merely confirm execution without checking relevant behavior.

Documentation must describe implemented functionality accurately.

When public behavior changes, update relevant:

• API documentation.
• Tutorials.
• Examples.
• Changelog entries.
• README content where appropriate.

Distinguish:

Do not fabricate:

• Benchmarks.
• Test results.
• Compatibility claims.
• Citations.
• Contributors.
• Adoption metrics.

Documentation examples should:

• Use valid imports.
• Match current signatures.
• Explain prerequisites.
• Avoid nonexistent APIs.
• Include correct expected behavior.

Diagnostic information should help developers understand failures.

• Use meaningful messages.
• Avoid unnecessary output.
• Do not log credentials.
• Do not expose private datasets.
• Preserve useful exception context.

Use the framework's existing logging utilities where appropriate instead of introducing a competing logging system.

Bug reports should include:

python -m everyo info

Along with a minimal reproduction and relevant traceback.

Dependencies affect installation size, compatibility, security, and maintenance.

The inspected package metadata declares:

numpy>=1.22
matplotlib>=3.5

tensorflow
cuda
onnx
yaml
dev

Before adding a dependency, consider:

1. Is it necessary?
2. Can the feature be implemented using existing dependencies?
3. Is it compatible with supported Python versions?
4. Does it introduce security concerns?
5. Should it be optional?
6. Does it increase installation complexity?

The everyo.core layer must remain dependency-free beyond NumPy under the current contribution rules.

Contributions should be submitted through focused branches and reviewed pull requests.

fix/gradient-broadcasting
feature/new-layer
docs/api-reference
test/optimizer-regression
refactor/tensor-validation

type(scope): description

Examples:

feat(nn): add activation layer
fix(core): correct tensor broadcasting
test(autograd): add finite-difference coverage
docs(wiki): improve coding standards

These commit conventions are recommended rather than currently enforced.

• Keep commits focused.
• Explain changes clearly.
• Avoid unrelated files.
• Never commit credentials.
• Preserve reviewable history.

EveryO's repository rules require technically sound, maintainable contributions.

A pull request should explain:

• Problem.
• Solution.
• Alternatives.
• Testing performed.
• Compatibility implications.
• Relevant documentation.

Passing CI does not guarantee merge approval.

Maintainers may request changes, defer work, or reject contributions that do not align with the project's direction.

• Understand the relevant architecture.
• Review existing implementation patterns.
• Confirm Python compatibility.
• Identify tests that should be updated.

• Follow naming conventions.
• Add type hints to public APIs.
• Add public docstrings.
• Validate inputs.
• Use appropriate exceptions.
• Preserve dependency boundaries.
• Keep modules focused.

• Forward results are correct.
• Gradients are correct.
• Broadcasting is tested.
• Edge cases are covered.
• Numerical tolerances are justified.

• Tests pass.
• Ruff lint passes.
• Ruff formatting passes.
• Documentation is updated.
• Changelog is updated where relevant.
• No credentials are included.
• Performance claims are measured.
• Compatibility impacts are documented.

python -m pytest -q

ruff check .

ruff format --check .

python -m compileall -q everyo

Continue with EveryO's contribution and release documentation.

Wiki links become active after the corresponding pages are created.