1. Overview
2. Serialization Architecture
3. Native .evo Format
4. Public Serialization API
5. Saving a Model
6. Loading a Model
7. State Dictionaries
8. Architecture Reconstruction
9. Metadata and Manifests
10. Archive Inspection
11. Model Checkpointing
12. Restoring Training
13. Model Version Compatibility
14. Artifact Integrity
15. Security Considerations
16. ONNX Export
17. ONNX Compatibility
18. Model Deployment
19. Complete Serialization Example
20. Testing and Verification
21. Troubleshooting
22. Best Practices
23. Developer References
24. Next Steps

Model serialization converts a trained model into a persistent artifact that can be stored, transferred, inspected, and restored.

EveryO provides a native model format designed to preserve model architecture, parameters, registered buffers, and metadata.

• Preserve trained model parameters.
• Reconstruct supported model architectures.
• Store model metadata.
• Support checkpointing.
• Verify model restoration.
• Enable model portability.
• Avoid Python pickle-based model loading.

                  EveryO Model
                       |
                       v
                 Model.state_dict()
                       |
                       v
                Parameter Arrays
                       |
                       +------------------+
                       |                  |
                       v                  v
               Model Architecture     Model Metadata
                       |                  |
                       +---------+--------+
                                 |
                                 v
                          .evo Archive
                                 |
                                 v
                          Persistent File

                    .evo Archive
                         |
                         v
                    Read Manifest
                         |
                         v
                 Validate Format Version
                         |
                         v
                 Load NumPy Parameters
                         |
                         v
                 Reconstruct Architecture
                         |
                         v
                    Restore State
                         |
                         v
                    Evaluation Mode
                         |
                         v
                     Ready Model

EveryO uses .evo as its native model archive suffix.

The archive is ZIP-based and contains two members:

model.evo
│
├── manifest.json
│
└── parameters.npz

The inspected implementation defines:

FORMAT_VERSION = 1

MANIFEST_NAME = "manifest.json"

PARAMETERS_NAME = "parameters.npz"

DEFAULT_SUFFIX = ".evo"

• Structured metadata.
• NumPy numerical storage.
• Architecture reconstruction through registered classes.
• No Python pickle required.
• Versioned archive format.

import everyo as eo

eo.save
eo.load
eo.build_manifest
eo.load_manifest
eo.inspect_archive

save(
    model,
    path,
    *,
    metadata=None,
    overwrite=True
)

load(
    path,
    *,
    model=None,
    strict=True
)

from pathlib import Path
import everyo as eo

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

path = eo.save(
    model,
    "artifacts/model.evo"
)

print("Saved:", path)

When the destination has no suffix, EveryO appends .evo.

eo.save(model, "artifacts/model")

The resulting file is:

artifacts/model.evo

eo.save(
    model,
    "artifacts/model.evo",
    metadata={
        "experiment": "classification-v1",
        "epoch": 20,
        "validation_accuracy": 0.92,
        "dataset_version": "2026-10"
    }
)

The metric value above is illustrative, not a measured EveryO result.

eo.save(
    model,
    "artifacts/model.evo",
    overwrite=False
)

If the destination already exists, the implementation raises a serialization error.

import everyo as eo

model = eo.load(
    "artifacts/model.evo"
)

print(type(model).__name__)

model = eo.Sequential(
    eo.Linear(4, 8, seed=10),
    eo.ReLU(),
    eo.Linear(8, 2, seed=11)
)

restored = eo.load(
    "artifacts/model.evo",
    model=model
)

When model is supplied, the loader uses the existing architecture and restores its state.

restored = eo.load(
    "artifacts/model.evo",
    strict=True
)

Strict loading requires matching state names.

Shape compatibility must also be satisfied.

The inspected load() implementation calls:

model.eval()

before returning the model.

To continue training, switch back to training mode:

model.train()

A state dictionary maps parameter and buffer names to NumPy arrays.

state = model.state_dict()

for name, array in state.items():
    print(name, array.shape)

model.load_state_dict(
    state,
    strict=True
)

The inspected Module.state_dict() implementation includes:

• Named parameters.
• Registered persistent buffers.

Buffers may include running statistics used by certain layers.

A model with normalization layers may require running statistics to reproduce inference behavior.

Restoring weights without those buffers can change predictions.

EveryO reconstructs model classes using a registry.

Manifest Class Name
        |
        v
   Module Registry
        |
        v
 Registered Module Class
        |
        v
     from_config()
        |
        v
 Reconstructed Model

The base module supports:

model.get_config()

and:

ModelClass.from_config(config)

Custom module types must be registered and provide sufficient configuration information for reconstruction.

The source provides a registration decorator:

from everyo.nn.module import register_module

A custom module cannot necessarily be reconstructed automatically unless:

• Its class is registered.
• Its configuration can recreate the architecture.
• The required class implementation is available.
• Its saved state matches the reconstructed module.

The manifest describes the saved model.

A representative structure is:

{
  "format_version": 1,
  "everyo_version": "0.2.0",
  "created_at": "2026-10-15T00:00:00+00:00",
  "architecture": {
    "class_name": "Sequential",
    "config": {}
  },
  "parameters": {
    "parameter_name": {
      "shape": [4, 8],
      "dtype": "float32"
    }
  },
  "num_parameters": 58,
  "metadata": {
    "experiment": "classification-v1"
  }
}

This is a structural illustration, not an exact manifest generated from a particular model.

manifest = eo.build_manifest(
    model,
    metadata={
        "project": "EveryO",
        "stage": "evaluation"
    }
)

print(manifest)

manifest = eo.load_manifest(
    "artifacts/model.evo"
)

print(manifest["format_version"])
print(manifest["architecture"])

Metadata must be JSON-serializable.

Use:

• Strings.
• Numbers.
• Booleans.
• Lists.
• Dictionaries.
• Null values.

Convert unsupported objects before saving.

EveryO provides an inspection function that reads model metadata without reconstructing the model.

import everyo as eo

information = eo.inspect_archive(
    "artifacts/model.evo"
)

print(information)

The inspected implementation returns:

info = eo.inspect_archive(
    "artifacts/model.evo"
)

print("Class:", info["class_name"])
print("Parameters:", info["num_parameters"])
print("Version:", info["everyo_version"])

Checkpointing saves a model during training.

The inspected constructor is:

ModelCheckpoint(
    path,
    *,
    monitor="val_loss",
    mode="min",
    save_best_only=True
)

checkpoint = eo.ModelCheckpoint(
    "checkpoints/best-model.evo",
    monitor="val_loss",
    mode="min",
    save_best_only=True
)

history = trainer.fit(
    train_loader,
    epochs=50,
    validation_loader=val_loader,
    callbacks=[checkpoint]
)

This example assumes the model, trainer, and loaders have already been configured.

With save_best_only=True, the callback saves when the monitored metric improves.

With save_best_only=False, it saves at every epoch to the configured destination, replacing the previous file.

The callback includes the epoch and available training metrics in the saved metadata.

Restoring a model for inference is different from resuming training exactly.

model = eo.load(
    "checkpoints/best-model.evo"
)

model.train()

The native model archive preserves model state and metadata, but the inspected save() implementation does not serialize the optimizer's internal state.

Therefore, loading a model and creating a new optimizer is not necessarily equivalent to resuming the original optimization process.

A fully resumable training checkpoint may require:

• Model state.
• Optimizer state.
• Scheduler state.
• Epoch and step counters.
• Random generator state.
• DataLoader progression.
• Training configuration.

Do not assume that a native .evo model archive contains all of these components.

The archive stores a format version and the saving EveryO version.

The inspected format version is:

FORMAT_VERSION = 1

The loader rejects archives whose format version is newer than the implementation supports.

• Framework version.
• Archive format version.
• Registered module availability.
• Architecture configuration.
• Parameter names.
• Parameter shapes.
• Numerical dtype compatibility.

For production artifacts:

1. Record the framework version.
2. Record the source commit.
3. Retain a compatible runtime environment.
4. Test restoration before deployment.
5. Validate predictions after upgrades.

Artifact integrity checks detect unintended changes or corruption.

A SHA-256 digest can identify whether a file's bytes have changed.

import hashlib
from pathlib import Path

def sha256_file(path):
    digest = hashlib.sha256()

    with Path(path).open("rb") as handle:
        for chunk in iter(
            lambda: handle.read(1024 * 1024),
            b""
        ):
            digest.update(chunk)

    return digest.hexdigest()

print(
    sha256_file("artifacts/model.evo")
)

A hash detects changes when compared with a trusted expected hash.

It does not establish who created the artifact.

• Trusted artifact storage.
• Access controls.
• Versioned releases.
• Integrity verification.
• Backups.
• Audit records.

EveryO's native serialization avoids Python pickle-based model reconstruction.

The inspected implementation:

• Stores architecture descriptions as JSON.
• Uses NumPy arrays for state.
• Loads NumPy data with allow_pickle=False.
• Resolves model classes through a registration mechanism.
• Rejects unsupported future format versions.

Avoiding pickle reduces arbitrary code-execution risks associated with deserialization.

It does not eliminate all risks associated with malicious files, including oversized archives, excessive resource consumption, or vulnerabilities in dependencies.

• Accept models only from trusted sources.
• Verify artifact integrity.
• Enforce file size limits.
• Keep dependencies updated.
• Use isolated environments for untrusted artifacts.
• Restrict artifact write permissions.
• Avoid storing credentials in metadata.

EveryO includes ONNX interoperability utilities.

eo.export_onnx
eo.export_onnx_traced
eo.onnx_available
eo.run_onnx

import everyo as eo

print(
    "ONNX available:",
    eo.onnx_available()
)

python -m pip install "everyo[onnx]"

Inspect the installed exporter before using it:

import inspect
import everyo as eo

print(
    inspect.signature(eo.export_onnx)
)

EveryO provides two export approaches:

The appropriate exporter depends on the model architecture and supported operations.

The inspected layer-based ONNX exporter supports these layer types:

• AvgPool2D
• BatchNorm1D
• BatchNorm2D
• Conv2D
• Dropout
• Flatten
• LayerNorm
• Linear
• LogSoftmax
• MaxPool2D
• ReLU
• Sequential
• Sigmoid
• Softmax
• Tanh

The inspected default opset is:

DEFAULT_OPSET = 17

EveryO uses NHWC image layout for relevant operations.

ONNX convolution and pooling operators use NCHW conventions.

The exporter handles required layout conversions for supported layers.

Not every EveryO model can be exported using the layer-based exporter.

Recurrent, attention, and transformer architectures may require operation tracing.

Successful export does not guarantee identical behavior on every downstream runtime.

Compare predictions between:

• The original EveryO model.
• The exported ONNX model.
• The target inference runtime.

Use numerical tolerances appropriate to the model and precision.

A deployment-ready artifact should include more than model weights.

model-release/
│
├── model.evo
├── manifest.json
├── preprocessing.json
├── metrics.json
├── requirements.txt
├── checksums.sha256
└── README.md

This is a recommended external release structure, not the internal layout of an .evo archive.

• Compatible runtime.
• Validated model artifact.
• Input schema.
• Preprocessing configuration.
• Output schema.
• Performance requirements.
• Error handling.
• Monitoring.

Document:

• Model purpose.
• Supported inputs.
• Expected outputs.
• Known limitations.
• Validation results.
• Resource requirements.
• Rollback procedure.

This example saves a model, inspects its archive, reloads it, and verifies output consistency.

from pathlib import Path

import numpy as np
import everyo as eo

# ---------------------------------
# 1. Create a model
# ---------------------------------

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

# ---------------------------------
# 2. Create input data
# ---------------------------------

x = eo.tensor([
    [0.2, 0.4, 0.6, 0.8]
])

# ---------------------------------
# 3. Generate reference output
# ---------------------------------

model.eval()

with eo.no_grad():
    original_output = model(x).numpy()

# ---------------------------------
# 4. Save model
# ---------------------------------

artifact_path = Path(
    "artifacts/classifier.evo"
)

eo.save(
    model,
    artifact_path,
    metadata={
        "project": "EveryO",
        "purpose": "serialization-demo",
        "version": 1
    }
)

# ---------------------------------
# 5. Inspect archive
# ---------------------------------

info = eo.inspect_archive(
    artifact_path
)

print("Model class:", info["class_name"])
print("Parameter count:", info["num_parameters"])

# ---------------------------------
# 6. Restore model
# ---------------------------------

restored_model = eo.load(
    artifact_path
)

# ---------------------------------
# 7. Generate restored output
# ---------------------------------

with eo.no_grad():
    restored_output = restored_model(x).numpy()

# ---------------------------------
# 8. Verify results
# ---------------------------------

np.testing.assert_allclose(
    original_output,
    restored_output,
    rtol=1e-6,
    atol=1e-7
)

print("Serialization round-trip verified.")

The example should:

1. Create a model.
2. Produce a reference prediction.
3. Save an .evo archive.
4. Read archive metadata.
5. Restore the architecture and parameters.
6. Compare predictions.

The final verification message should appear if the round-trip outputs satisfy the specified numerical tolerances.

python -m pytest

• Save and load a linear model.
• Save and load a sequential model.
• Preserve parameter values.
• Preserve registered buffers.
• Preserve supported metadata.
• Reject malformed archives.
• Reject unsupported format versions.
• Reject unregistered architecture classes.
• Verify strict state loading.
• Compare inference results before and after restoration.

import numpy as np

original_state = model.state_dict()
restored_state = restored_model.state_dict()

assert original_state.keys() == restored_state.keys()

for name in original_state:
    np.testing.assert_allclose(
        original_state[name],
        restored_state[name]
    )

• Save the correct model state.
• Include useful metadata.
• Record the framework version.
• Record model configuration.
• Validate the archive.
• Verify restored predictions.
• Store preprocessing configuration.
• Maintain artifact checksums.
• Restrict access to production artifacts.
• Test compatibility after upgrades.

project-model-version.evo

Example:

everyo-classifier-v1.evo

For each model release:

1. Complete training.
2. Evaluate the model.
3. Save the artifact.
4. Inspect metadata.
5. Verify restoration.
6. Run inference regression tests.
7. Record a trusted checksum.
8. Publish to controlled artifact storage.
9. Monitor deployment behavior.

Continue exploring EveryO's advanced engineering documentation.

Wiki links become active after the corresponding pages are created.