seedfile 1.0.0

A simple, portable bundle format for ML models and their metadata

🌱 SEED

A portable bundle format for machine learning models.

SEED packages a model's weights, config, tokenizer, and any other artifacts into a single .seed file — a self-contained zip with a structured manifest. Built with language models in mind, generic enough for anything.

No more juggling separate .pth, .json, and custom pickle files. One file, everything inside.

---

Author

Artheme Gauthier-Villars ([e-mail])

Install

pip install seedfile

---

Quickstart

from seedfile import sd

# Save everything in one shot
sd.save("my_model.seed", {
    "model":     model.state_dict(),   # PyTorch state dict
    "config":    CONFIG,               # dict, dataclass, or custom object
    "tokenizer": tokenizer,            # any Python object
})

# Load it back anywhere
data = sd.load("my_model.seed")

model.load_state_dict(data.get("model"))
CONFIG    = data.get("config")
tokenizer = data.get("tokenizer")

The bundle knows what it contains:

print(data)
# SeedBundle(version=v1.0.0, components=['model', 'config', 'tokenizer'])

"model" in data   # True
len(data)         # 3

---

Why SEED?

Training a language model produces a lot of artifacts that belong together:

Artifact	Typical format	Problem
Model weights	.pth	Detached from the config it was trained with
Tokenizer	custom class / HF files	Separate directory, easy to lose
Generation config	.json	No guarantee it matches the weights
Training history	dict / CSV	Usually just forgotten

SEED bundles all of it. When you share or archive a .seed file, everything travels together.

---

Serialisation

SEED picks the right format automatically — no configuration needed:

Object type	Saved as
PyTorch state_dict	.pth via torch.save
torch.Tensor	.pth
numpy.ndarray	.npy via np.save
dict, list, primitives	.json
Custom objects	.json (via __dict__) → pickle fallback

---

Custom serialisers

For objects that need special handling, pass a serializers dict:

def save_tokenizer(obj, tmp_dir):
    path = tmp_dir / "tokenizer.model"
    obj.save(str(path))
    return "tokenizer.model"

sd.save("my_model.seed", {"model": model.state_dict(), "tokenizer": tokenizer},
        serializers={"tokenizer": save_tokenizer})

---

Updating a single component

sd.update("my_model.seed", "config", new_config)

---

Manifest

Every .seed file contains a manifest.json:

{
  "format_version": "v1.0.0",
  "metadata": {
    "created_at": "2026-05-12T10:30:00+00:00",
    "python_version": "3.10.4"
  },
  "components": {
    "model":     "model.pth",
    "config":    "config.json",
    "tokenizer": "tokenizer.pkl"
  }
}

SEED warns on load if the format version or Python version differs from what was used at save time.

---

Zero hard dependencies

SEED has no required dependencies. torch and numpy are used only if already present in your environment.

---

License

MIT