modssc 0.2.4__tar.gz → 0.3__tar.gz

{modssc-0.2.4 → modssc-0.3}/.gitignore

@@ -44,3 +44,6 @@ log/
 coverage.xml
 analysis/
 dev_wip/
+bench/configs/experiments/article/README.md
+bench/configs/experiments/best/
+bench/configs/experiments/smoke/

{modssc-0.2.4 → modssc-0.3}/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on "Keep a Changelog", and this project adheres to Semantic Versioning.
 
+## 0.3
+- Refactored modules to reduce redundancy, centralize shared functions, and improve maintainability and test coverage.
+
+## 0.2.5
+- Added env var passthrough for dataset, preprocess, and runs cache directories in benchmarks.
+
 ## 0.2.4
 - Improved torch container and device handling in inductive benchmarks.
 - Added LSTM embedding support and hidden_size alias in inductive bundles.

{modssc-0.2.4 → modssc-0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modssc
-Version: 0.2.4
+Version: 0.3
 Summary: ModSSC: a modular framework for semi-supervised classification on heterogeneous data
 Project-URL: Homepage, https://github.com/ModSSC/ModSSC
 Project-URL: Repository, https://github.com/ModSSC/ModSSC
@@ -188,6 +188,8 @@ Pick the path that fits your goal: learn the concepts, run examples, or dive int
 - **Getting started**: [install and first run](https://modssc.github.io/ModSSC/getting-started/installation).
 - **CLI and API reference**: [full command and API list](https://modssc.github.io/ModSSC/reference/cli).
 
+If you use benchmark configs with environment placeholders, set `MODSSC_OUTPUT_DIR`, `MODSSC_DATASET_CACHE_DIR`, and `MODSSC_PREPROCESS_CACHE_DIR` before running. See the [Configuration reference](https://modssc.github.io/ModSSC/reference/configuration) for examples.
+
 ### Examples
 
 - **Examples**: small scripts in [examples/](examples/).

{modssc-0.2.4 → modssc-0.3}/README.md

@@ -22,6 +22,8 @@ Pick the path that fits your goal: learn the concepts, run examples, or dive int
 - **Getting started**: [install and first run](https://modssc.github.io/ModSSC/getting-started/installation).
 - **CLI and API reference**: [full command and API list](https://modssc.github.io/ModSSC/reference/cli).
 
+If you use benchmark configs with environment placeholders, set `MODSSC_OUTPUT_DIR`, `MODSSC_DATASET_CACHE_DIR`, and `MODSSC_PREPROCESS_CACHE_DIR` before running. See the [Configuration reference](https://modssc.github.io/ModSSC/reference/configuration) for examples.
+
 ### Examples
 
 - **Examples**: small scripts in [examples/](examples/).

{modssc-0.2.4 → modssc-0.3}/docs/getting-started/quickstart.md

@@ -12,6 +12,20 @@ Run the benchmark runner with the toy inductive config:
 python -m bench.main --config bench/configs/experiments/toy_inductive.yaml
 ```
 
+If your config uses environment placeholders (like `${MODSSC_OUTPUT_DIR}`), export them first:
+
+```bash
+export MODSSC_OUTPUT_DIR=/tmp/modssc_runs
+export MODSSC_DATASET_CACHE_DIR=/tmp/modssc_cache/datasets
+export MODSSC_PREPROCESS_CACHE_DIR=/tmp/modssc_cache/preprocess
+```
+
+Or set one global cache root for all runtime caches:
+
+```bash
+export MODSSC_CACHE_ROOT=/tmp/modssc_cache
+```
+
 Run a quick Python API pass with the dataset loader and sampling plan:
 
 ```python

{modssc-0.2.4 → modssc-0.3}/docs/how-to/datasets.md

@@ -54,7 +54,7 @@ _ = download_dataset("toy")
 
 
 !!! tip
-    Override the dataset cache directory with `MODSSC_CACHE_DIR` if you want to store datasets outside the repo or default user cache. <sup class="cite"><a href="#source-3">[3]</a></sup>
+  Override the dataset cache directory with `MODSSC_CACHE_DIR` if you want to store datasets outside the repo or default user cache. For a single root across caches, you can set `MODSSC_CACHE_ROOT`. For bench YAML configs, you can also set `MODSSC_DATASET_CACHE_DIR` and reference it in `dataset.cache_dir`. <sup class="cite"><a href="#source-3">[3]</a></sup>
 
 
 ## Related links

{modssc-0.2.4 → modssc-0.3}/docs/how-to/views.md

@@ -78,7 +78,7 @@ The view plan schema is defined in [`src/modssc/views/plan.py`](https://github.c
   <li id="source-3"><a href="https://github.com/ModSSC/ModSSC/blob/main/src/modssc/inductive/methods/co_training.py"><code>src/modssc/inductive/methods/co_training.py</code></a></li>
   <li id="source-4"><a href="https://github.com/ModSSC/ModSSC/blob/main/src/modssc/inductive/types.py"><code>src/modssc/inductive/types.py</code></a></li>
   <li id="source-5"><a href="https://github.com/ModSSC/ModSSC/blob/main/src/modssc/preprocess/plan.py"><code>src/modssc/preprocess/plan.py</code></a></li>
-  <li id="source-6"><a href="https://github.com/ModSSC/ModSSC/blob/main/bench/configs/experiments/best/inductive/co_training/text/imdb.yaml"><code>bench/configs/experiments/best/inductive/co_training/text/imdb.yaml</code></a></li>
+  <li id="source-6"><a href="https://github.com/ModSSC/ModSSC/blob/main/bench/configs/experiments/minimal/inductive/co_training/text/imdb.yaml"><code>bench/configs/experiments/minimal/inductive/co_training/text/imdb.yaml</code></a></li>
   <li id="source-7"><a href="https://github.com/ModSSC/ModSSC/blob/main/bench/schema.py"><code>bench/schema.py</code></a></li>
 </ol>
 </details>

{modssc-0.2.4 → modssc-0.3}/docs/index.md

@@ -33,7 +33,7 @@ ModSSC is a modular framework for semi-supervised classification across heteroge
 - [Transductive tutorial](tutorials/transductive-toy.md)
 
 ## Version
-Current version is `0.2.4`, sourced from [`src/modssc/__about__.py`](https://github.com/ModSSC/ModSSC/blob/main/src/modssc/__about__.py) and referenced by the Hatch version config in [`pyproject.toml`](https://github.com/ModSSC/ModSSC/blob/main/pyproject.toml). <sup class="cite"><a href="#source-18">[18]</a><a href="#source-2">[2]</a></sup>
+Current version is `0.3`, sourced from [`src/modssc/__about__.py`](https://github.com/ModSSC/ModSSC/blob/main/src/modssc/__about__.py) and referenced by the Hatch version config in [`pyproject.toml`](https://github.com/ModSSC/ModSSC/blob/main/pyproject.toml). <sup class="cite"><a href="#source-18">[18]</a><a href="#source-2">[2]</a></sup>
 
 
 ## Project status and support

{modssc-0.2.4 → modssc-0.3}/docs/reference/benchmarks.md

@@ -13,18 +13,97 @@ python -m bench.main --config bench/configs/experiments/toy_inductive.yaml
 python -m bench.main --config bench/configs/experiments/toy_transductive.yaml
 ```
 
+If you are using environment variable placeholders in configs (like `${MODSSC_OUTPUT_DIR}`), set them once before running:
+
+```bash
+export MODSSC_OUTPUT_DIR=/tmp/modssc_runs
+export MODSSC_DATASET_CACHE_DIR=/tmp/modssc_cache/datasets
+export MODSSC_PREPROCESS_CACHE_DIR=/tmp/modssc_cache/preprocess
+```
+
+If one of these placeholders is missing at runtime, config loading fails fast with an explicit error.
+
+You can also set one global cache root for runtime caches (dataset, preprocess, split, graph):
+
+```bash
+export MODSSC_CACHE_ROOT=/tmp/modssc_cache
+```
+
+Optional graph-specific overrides:
+
+```bash
+export MODSSC_GRAPH_CACHE_DIR=/tmp/modssc_cache/graphs
+export MODSSC_GRAPH_VIEWS_CACHE_DIR=/tmp/modssc_cache/graph_views
+```
+
 Enable verbose logging for a run:
 
 ```bash
 python -m bench.main --config bench/configs/experiments/toy_inductive.yaml --log-level detailed
 ```
 
+Run the same config on multiple seeds:
+
+```yaml
+run:
+  name: toy_pseudo_label
+  seed: 0
+  seeds: [1, 2, 3, 4, 5]
+```
+
+In sweep mode, the runner executes one run per seed and auto-suffixes `run.name` with `-seed<N>`. For each run, `run.seed` and section seeds (`sampling`, `preprocess`, `views`, `graph`, `augmentation`, `search`) are aligned to that seed.
+
+Or sweep by run count from the CLI:
+
+```bash
+# Uses run.seed as base and runs seeds [seed, seed+1, ..., seed+N-1]
+python -m bench.main --config bench/configs/experiments/toy_inductive.yaml --num-runs 5
+```
+
+`--num-runs` follows the same seed-sweep logic and overrides `run.seeds` when both are present.
+
 The `--log-level` flag is defined on the bench CLI entry point. <sup class="cite"><a href="#source-1">[1]</a></sup>
 
 
 The bench entry point and example configs are in [`bench/main.py`](https://github.com/ModSSC/ModSSC/blob/main/bench/main.py) and [`bench/configs/experiments/`](https://github.com/ModSSC/ModSSC/tree/main/bench/configs/experiments). <sup class="cite"><a href="#source-1">[1]</a><a href="#source-2">[2]</a></sup>
 
 
+## Cache behavior in multi-seed runs
+For multi-seed sweeps, keep one shared cache root and let fingerprints isolate seed-dependent artifacts:
+
+```bash
+export MODSSC_CACHE_ROOT=/tmp/modssc_cache
+```
+
+Use separate `MODSSC_CACHE_ROOT` values only when you explicitly need hard isolation (for example strict clean-room comparisons across branches/commits).
+
+When you run 5 seeds, you should expect 5 distinct split/preprocess/graph fingerprints (one per seed), while dataset artifacts are shared.
+
+- Dataset cache (`datasets/`):
+Reused across seeds when dataset identity is unchanged (provider, dataset id, version, resolved options). Usually do not recompute.
+
+- Sampling split cache (`splits/`):
+Conceptually seed-dependent (different split fingerprint per seed), so each seed maps to a different split entry.
+Current bench orchestration computes sampling in-memory (`save=False`) and does not persist split cache entries.
+
+- Preprocess cache (`preprocess/`):
+Seed-dependent. Fingerprint includes dataset fingerprint, resolved plan fingerprint, fit fingerprint, and seed.
+In a 5-seed sweep, expect 5 preprocess entries. Reuse only happens when rerunning the same seed + same plan + same fit inputs.
+
+- Graph cache (`graphs/`):
+Seed-dependent. Fingerprint includes dataset fingerprint, preprocess fingerprint, graph spec, and seed.
+In a 5-seed sweep, expect 5 graph entries (unless graph is dataset-provided and not rebuilt).
+
+- Method training/inference:
+Not cached by the benchmark runner. Model fit/eval is recomputed every run.
+
+Practical rules:
+- Keep the same cache root for speed when rerunning identical experiments.
+- Do not reuse cache for "strict from-scratch" comparisons; use a new cache root.
+- If you change dataset options, preprocessing steps/params, `fit_on`, graph spec, or seeds, expect recomputation for impacted stages.
+- If preprocessing or graph implementation changes in code while config stays the same, clear impacted cache folders to avoid stale artifacts.
+
+
 ## How outputs are stored
 Each run writes a timestamped directory under [`runs/`](https://github.com/ModSSC/ModSSC/tree/main/runs) with:
 - `config.yaml` (copied config)

{modssc-0.2.4 → modssc-0.3}/docs/reference/configuration.md

@@ -14,6 +14,12 @@ Start with where files live, then how they are loaded, then the schema blocks yo
 ## How configs are loaded
 - Bench configs are read from YAML with `bench.utils.io.load_yaml` and validated via `ExperimentConfig.from_dict`. <sup class="cite"><a href="#source-3">[3]</a><a href="#source-2">[2]</a></sup>
 
+- Bench configs support environment variable expansion in string values (for example `${MODSSC_OUTPUT_DIR}` or `$MODSSC_OUTPUT_DIR`). This is useful for `run.output_dir`, `dataset.cache_dir`, and `preprocess.cache_dir` placeholders in YAML. <sup class="cite"><a href="#source-3">[3]</a></sup>
+
+- Unresolved placeholders now fail fast with an explicit error (key path + missing variable names) instead of being kept as literal strings.
+
+- Runtime cache env vars (outside YAML placeholders): `MODSSC_CACHE_ROOT` (global root), `MODSSC_CACHE_DIR` (dataset cache), `MODSSC_PREPROCESS_CACHE_DIR` (preprocess cache), `MODSSC_SPLIT_CACHE_DIR` (sampling split cache), `MODSSC_GRAPH_CACHE_DIR` (graph cache), `MODSSC_GRAPH_VIEWS_CACHE_DIR` (graph views cache).
+
 - CLI plan/spec files use `load_yaml_or_json` and are validated with their respective `from_dict` methods. <sup class="cite"><a href="#source-4">[4]</a><a href="#source-5">[5]</a><a href="#source-6">[6]</a></sup>
 
 - Preprocess plans are loaded from YAML with `modssc.preprocess.plan.load_plan`. <sup class="cite"><a href="#source-7">[7]</a></sup>
@@ -28,6 +34,23 @@ Run a bench config:
 python -m bench.main --config bench/configs/experiments/toy_inductive.yaml
 ```
 
+Run a bench config with environment variable placeholders:
+
+```bash
+MODSSC_OUTPUT_DIR=/tmp/modssc_runs \
+MODSSC_DATASET_CACHE_DIR=/tmp/modssc_cache/datasets \
+MODSSC_PREPROCESS_CACHE_DIR=/tmp/modssc_cache/preprocess \
+python -m bench.main --config bench/configs/experiments/toy_inductive.yaml
+```
+
+Or export them once per shell session:
+
+```bash
+export MODSSC_OUTPUT_DIR=/tmp/modssc_runs
+export MODSSC_DATASET_CACHE_DIR=/tmp/modssc_cache/datasets
+export MODSSC_PREPROCESS_CACHE_DIR=/tmp/modssc_cache/preprocess
+```
+
 Load and inspect a config in Python:
 
 ```python
@@ -44,7 +67,7 @@ The bench entry point, schema, and YAML loader are in [`bench/main.py`](https://
 ## Experiment config schema (bench)
 Top-level keys and their required fields are defined in [`bench/schema.py`](https://github.com/ModSSC/ModSSC/blob/main/bench/schema.py):
 
-- `run`: `name`, `seed`, `output_dir`, `fail_fast`, optional `log_level`. <sup class="cite"><a href="#source-2">[2]</a></sup>
+- `run`: `name`, `seed`, `output_dir`, `fail_fast`, optional `log_level`, optional `seeds` (list of run seeds for a sweep). <sup class="cite"><a href="#source-2">[2]</a></sup>
 
 - `dataset`: `id`, optional `options`, `download`, `cache_dir`. <sup class="cite"><a href="#source-2">[2]</a></sup>
 
@@ -398,6 +421,6 @@ evaluation:
   <li id="source-23"><a href="https://github.com/ModSSC/ModSSC/blob/main/src/modssc/hpo/samplers.py"><code>src/modssc/hpo/samplers.py</code></a></li>
   <li id="source-24"><a href="https://github.com/ModSSC/ModSSC/blob/main/bench/configs/experiments/toy_inductive.yaml"><code>bench/configs/experiments/toy_inductive.yaml</code></a></li>
   <li id="source-25"><a href="https://github.com/ModSSC/ModSSC/blob/main/bench/configs/experiments/toy_transductive.yaml"><code>bench/configs/experiments/toy_transductive.yaml</code></a></li>
-  <li id="source-26"><a href="https://github.com/ModSSC/ModSSC/blob/main/bench/configs/experiments/best/inductive/softmatch/text/ag_news.yaml"><code>bench/configs/experiments/best/inductive/softmatch/text/ag_news.yaml</code></a></li>
+  <li id="source-26"><a href="https://github.com/ModSSC/ModSSC/blob/main/bench/configs/experiments/minimal/inductive/pseudo_label/text/imdb.yaml"><code>bench/configs/experiments/minimal/inductive/pseudo_label/text/imdb.yaml</code></a></li>
 </ol>
 </details>

{modssc-0.2.4 → modssc-0.3}/src/modssc/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2024-present ModSSC contributors
 #
 # SPDX-License-Identifier: MIT
-__version__ = "0.2.4"
+__version__ = "0.3"

{modssc-0.2.4 → modssc-0.3}/src/modssc/data_augmentation/ops/audio.py

@@ -9,6 +9,7 @@ from ..registry import register_op
 from ..types import AugmentationContext, Modality
 from ..utils import is_torch_tensor
 from .base import AugmentationOp
+from .common import apply_gaussian_noise
 
 
 @register_op("audio.add_noise")
@@ -21,22 +22,12 @@ class AddNoise(AugmentationOp):
     std: float = 0.005
 
     def apply(self, x: Any, *, rng: np.random.Generator, ctx: AugmentationContext) -> Any:  # noqa: ARG002
-        std = float(self.std)
-        if std < 0:
-            raise ValueError("std must be >= 0")
-        if std == 0:
-            return x
-        if is_torch_tensor(x):
-            import importlib
-
-            torch = importlib.import_module("torch")
-            seed = int(rng.integers(0, 1 << 31))
-            gen = torch.Generator(device=x.device).manual_seed(seed)
-            noise = torch.randn(x.shape, generator=gen, device=x.device, dtype=x.dtype) * std
-            return x + noise
-        arr = np.asarray(x)
-        noise = rng.normal(0.0, std, size=arr.shape).astype(arr.dtype, copy=False)
-        return arr + noise
+        return apply_gaussian_noise(
+            x,
+            std=float(self.std),
+            rng=rng,
+            is_torch_tensor_fn=is_torch_tensor,
+        )
 
 
 @register_op("audio.time_shift")

modssc-0.3/src/modssc/data_augmentation/ops/common.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+
+def apply_gaussian_noise(
+    x: Any,
+    *,
+    std: float,
+    rng: np.random.Generator,
+    is_torch_tensor_fn: Any,
+) -> Any:
+    std = float(std)
+    if std < 0:
+        raise ValueError("std must be >= 0")
+    if std == 0:
+        return x
+    if is_torch_tensor_fn(x):
+        import importlib
+
+        torch = importlib.import_module("torch")
+        seed = int(rng.integers(0, 1 << 31))
+        gen = torch.Generator(device=x.device).manual_seed(seed)
+        noise = torch.randn(x.shape, generator=gen, device=x.device, dtype=x.dtype) * std
+        return x + noise
+    arr = np.asarray(x)
+    noise = rng.normal(0.0, std, size=arr.shape).astype(arr.dtype, copy=False)
+    return arr + noise

{modssc-0.2.4 → modssc-0.3}/src/modssc/data_augmentation/ops/tabular.py

@@ -9,6 +9,7 @@ from ..registry import register_op
 from ..types import AugmentationContext, Modality
 from ..utils import is_torch_tensor
 from .base import AugmentationOp
+from .common import apply_gaussian_noise
 
 
 @register_op("tabular.gaussian_noise")
@@ -21,22 +22,12 @@ class GaussianNoise(AugmentationOp):
     std: float = 0.1
 
     def apply(self, x: Any, *, rng: np.random.Generator, ctx: AugmentationContext) -> Any:  # noqa: ARG002
-        std = float(self.std)
-        if std < 0:
-            raise ValueError("std must be >= 0")
-        if std == 0:
-            return x
-        if is_torch_tensor(x):
-            import importlib
-
-            torch = importlib.import_module("torch")
-            seed = int(rng.integers(0, 1 << 31))
-            gen = torch.Generator(device=x.device).manual_seed(seed)
-            noise = torch.randn(x.shape, generator=gen, device=x.device, dtype=x.dtype) * std
-            return x + noise
-        arr = np.asarray(x)
-        noise = rng.normal(0.0, std, size=arr.shape).astype(arr.dtype, copy=False)
-        return arr + noise
+        return apply_gaussian_noise(
+            x,
+            std=self.std,
+            rng=rng,
+            is_torch_tensor_fn=is_torch_tensor,
+        )
 
 
 @register_op("tabular.feature_dropout")

{modssc-0.2.4 → modssc-0.3}/src/modssc/data_augmentation/ops/text.py

@@ -32,9 +32,19 @@ class Lowercase(AugmentationOp):
         return out if many else out[0]
 
 
+class _PerItemTextOp(AugmentationOp):
+    def _apply_one(self, s: str, *, rng: np.random.Generator) -> str:
+        raise NotImplementedError
+
+    def apply(self, x: Any, *, rng: np.random.Generator, ctx: AugmentationContext) -> Any:  # noqa: ARG002
+        items, many = _as_list(x)
+        out = [self._apply_one(s, rng=rng) for s in items]
+        return out if many else out[0]
+
+
 @register_op("text.word_dropout")
 @dataclass
-class WordDropout(AugmentationOp):
+class WordDropout(_PerItemTextOp):
     """Randomly drop words from whitespace-tokenized text."""
 
     op_id: str = "text.word_dropout"
@@ -53,15 +63,10 @@ class WordDropout(AugmentationOp):
             keep = [tokens[int(rng.integers(0, len(tokens)))]]
         return " ".join(keep)
 
-    def apply(self, x: Any, *, rng: np.random.Generator, ctx: AugmentationContext) -> Any:  # noqa: ARG002
-        items, many = _as_list(x)
-        out = [self._apply_one(s, rng=rng) for s in items]
-        return out if many else out[0]
-
 
 @register_op("text.random_swap")
 @dataclass
-class RandomSwap(AugmentationOp):
+class RandomSwap(_PerItemTextOp):
     """Randomly swap two words N times."""
 
     op_id: str = "text.random_swap"
@@ -79,8 +84,3 @@ class RandomSwap(AugmentationOp):
             j = int(j)
             tokens[i], tokens[j] = tokens[j], tokens[i]
         return " ".join(tokens)
-
-    def apply(self, x: Any, *, rng: np.random.Generator, ctx: AugmentationContext) -> Any:  # noqa: ARG002
-        items, many = _as_list(x)
-        out = [self._apply_one(s, rng=rng) for s in items]
-        return out if many else out[0]

{modssc-0.2.4 → modssc-0.3}/src/modssc/data_augmentation/utils.py

@@ -5,6 +5,8 @@ from typing import Any
 
 import numpy as np
 
+from modssc.numpy_utils import to_numpy
+
 from .types import Backend
 
 
@@ -20,19 +22,6 @@ def is_torch_tensor(x: Any) -> bool:
     return hasattr(x, "shape") and hasattr(x, "dtype") and hasattr(x, "device")
 
 
-def to_numpy(x: Any) -> np.ndarray:
-    """Best-effort conversion to numpy (detaches torch tensors)."""
-    if isinstance(x, np.ndarray):
-        return x
-    if hasattr(x, "detach"):
-        x = x.detach()
-    if hasattr(x, "cpu"):
-        x = x.cpu()
-    if hasattr(x, "numpy"):
-        return x.numpy()
-    return np.asarray(x)
-
-
 def _u64_from_bytes(b: bytes) -> int:
     return int.from_bytes(b[:8], "little", signed=False)
 

{modssc-0.2.4 → modssc-0.3}/src/modssc/data_loader/cache.py

@@ -4,7 +4,6 @@ import contextlib
 import os
 import shutil
 import sqlite3
-import tempfile
 from collections.abc import Iterable, Iterator
 from contextlib import contextmanager
 from dataclasses import dataclass
@@ -15,8 +14,10 @@ from platformdirs import user_cache_dir
 
 from modssc.data_loader.errors import ManifestError
 from modssc.data_loader.manifest import Manifest, read_manifest
+from modssc.io_utils import atomic_write_text as _atomic_write_text
 
 CACHE_ENV = "MODSSC_CACHE_DIR"
+CACHE_ROOT_ENV = "MODSSC_CACHE_ROOT"
 
 
 def default_cache_dir() -> Path:
@@ -24,6 +25,10 @@ def default_cache_dir() -> Path:
     if override:
         return Path(override).expanduser().resolve()
 
+    root_override = os.environ.get(CACHE_ROOT_ENV)
+    if root_override:
+        return Path(root_override).expanduser().resolve() / "datasets"
+
     # Heuristic: if running in a dev repo (pyproject.toml exists in parents),
     # default to a local "cache" folder at the repo root.
     current = Path.cwd()
@@ -118,15 +123,7 @@ def read_cached_manifest(layout: CacheLayout, fingerprint: str) -> Manifest:
 
 
 def atomic_write_text(path: Path, text: str) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with tempfile.NamedTemporaryFile(
-        "w", delete=False, dir=str(path.parent), encoding="utf-8"
-    ) as tmp:
-        tmp.write(text)
-        tmp.flush()
-        os.fsync(tmp.fileno())
-        tmp_path = Path(tmp.name)
-    tmp_path.replace(path)
+    _atomic_write_text(path, text)
 
 
 def dir_size_bytes(path: Path) -> int:

{modssc-0.2.4 → modssc-0.3}/src/modssc/data_loader/errors.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from modssc.dependency_errors import MissingExtraErrorMessageMixin
+
 
 class DataLoaderError(RuntimeError):
     """Base error for modssc.data_loader."""
@@ -23,19 +25,12 @@ class ProviderNotFoundError(DataLoaderError):
 
 
 @dataclass(frozen=True)
-class OptionalDependencyError(DataLoaderError):
+class OptionalDependencyError(MissingExtraErrorMessageMixin, DataLoaderError):
     """Raised when an optional dependency (extra) required by a provider is missing."""
 
     extra: str
     purpose: str | None = None
 
-    def __str__(self) -> str:
-        msg = f"Missing optional dependency extra: {self.extra!r}."
-        if self.purpose:
-            msg += f" Required for: {self.purpose}."
-        msg += f' Install with: pip install "modssc[{self.extra}]"'
-        return msg
-
 
 class DatasetNotCachedError(DataLoaderError):
     def __init__(self, dataset_id: str) -> None:

modssc-0.3/src/modssc/data_loader/json_utils.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+
+def to_jsonable(obj: Any) -> Any:
+    if obj is None:
+        return None
+    if isinstance(obj, (bool, int, float, str)):
+        return obj
+    if isinstance(obj, Path):
+        return str(obj)
+    if isinstance(obj, np.ndarray):
+        return {"__type__": "ndarray", "shape": list(obj.shape), "dtype": str(obj.dtype)}
+    if hasattr(obj, "shape") and hasattr(obj, "dtype"):
+        try:
+            shape = list(obj.shape)
+        except Exception:
+            shape = None
+        return {
+            "__type__": type(obj).__name__,
+            "shape": shape,
+            "dtype": str(getattr(obj, "dtype", "")),
+        }
+    if isinstance(obj, Mapping):
+        return {str(k): to_jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        if len(obj) > 50:
+            return {"__type__": type(obj).__name__, "len": len(obj)}
+        return [to_jsonable(v) for v in obj]
+    return {"__type__": type(obj).__name__}
+
+
+def mapping_to_jsonable(meta: Mapping[str, Any]) -> dict[str, Any]:
+    return {str(k): to_jsonable(v) for k, v in meta.items()}

{modssc-0.2.4 → modssc-0.3}/src/modssc/data_loader/manifest.py

@@ -9,8 +9,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-import numpy as np
-
+from modssc.data_loader.json_utils import to_jsonable as _jsonable
 from modssc.data_loader.types import DatasetIdentity, LoadedDataset
 
 
@@ -22,34 +21,6 @@ def python_version() -> str:
     return sys.version.split()[0]
 
 
-def _jsonable(obj: Any) -> Any:
-    if obj is None:
-        return None
-    if isinstance(obj, (bool, int, float, str)):
-        return obj
-    if isinstance(obj, Path):
-        return str(obj)
-    if isinstance(obj, np.ndarray):
-        return {"__type__": "ndarray", "shape": list(obj.shape), "dtype": str(obj.dtype)}
-    if hasattr(obj, "shape") and hasattr(obj, "dtype"):
-        try:
-            shape = list(obj.shape)
-        except Exception:
-            shape = None
-        return {
-            "__type__": type(obj).__name__,
-            "shape": shape,
-            "dtype": str(getattr(obj, "dtype", "")),
-        }
-    if isinstance(obj, Mapping):
-        return {str(k): _jsonable(v) for k, v in obj.items()}
-    if isinstance(obj, (list, tuple)):
-        if len(obj) > 50:
-            return {"__type__": type(obj).__name__, "len": len(obj)}
-        return [_jsonable(v) for v in obj]
-    return {"__type__": type(obj).__name__}
-
-
 def dataset_summary(ds: LoadedDataset) -> dict[str, Any]:
     def shape_dtype(x: Any) -> dict[str, Any]:
         if x is None: