Metadata-Version: 2.4
Name: seedfile
Version: 1.0.0
Summary: A simple, portable bundle format for ML models and their metadata
License: MIT
Project-URL: Homepage, https://github.com/ArthGV/SeedFile
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Provides-Extra: numpy
Requires-Dist: numpy; extra == "numpy"
Provides-Extra: all
Requires-Dist: torch; extra == "all"
Requires-Dist: numpy; extra == "all"
Dynamic: license-file

# 🌱 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 (agauthier@ethz.ch)

## Install

```bash
pip install seedfile
```

---

## Quickstart

```python
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:

```python
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:

```python
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

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

---

## Manifest

Every `.seed` file contains a `manifest.json`:

```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
