olaverse-foundry 0.1.0__tar.gz

olaverse_foundry-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: olaverse-foundry
+Version: 0.1.0
+Summary: A toolkit for building model families — seed, grow, fuse, freeze, extend.
+Author-email: Olaverse Labs <hello@olaverse.co.uk>
+License: Apache-2.0
+Project-URL: Homepage, https://olaverse.co.uk
+Project-URL: Repository, https://github.com/Olaverse-Labs/olaverse-foundry
+Project-URL: Issues, https://github.com/Olaverse-Labs/olaverse-foundry/issues
+Keywords: llm,distillation,model-merging,lora,skill-packs,african-nlp,olaverse,foundry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: torch
+Requires-Dist: torch>=2.0.0; extra == "torch"
+Requires-Dist: transformers>=4.40.0; extra == "torch"
+Requires-Dist: huggingface_hub>=0.20.0; extra == "torch"
+Requires-Dist: safetensors>=0.4.0; extra == "torch"
+Requires-Dist: accelerate>=0.27.0; extra == "torch"
+Provides-Extra: lego
+Requires-Dist: peft>=0.10.0; extra == "lego"
+Provides-Extra: merge
+Requires-Dist: mergekit; extra == "merge"
+Provides-Extra: data
+Requires-Dist: datasets>=2.18.0; extra == "data"
+Provides-Extra: align
+Requires-Dist: rapidfuzz>=3.0.0; extra == "align"
+Provides-Extra: logging
+Requires-Dist: wandb>=0.16.0; extra == "logging"
+Provides-Extra: all
+Requires-Dist: olaverse-foundry[align,data,lego,logging,merge,torch]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# olaverse-foundry
+
+**Build model families from a single pretrained seed.**
+
+`olaverse-foundry` is the training and model-factory layer of the Olaverse ecosystem. Where `olaverse` gives you ready-to-use NLP models, `foundry` lets you build new ones — distilling, growing, fusing, and adapting them for production.
+
+```
+seed → grow → distil / fuse → freeze → skill packs
+```
+
+---
+
+## Install
+
+```bash
+# Core (schema validation, growth planning — no GPU required)
+pip install olaverse-foundry
+
+# GPU training
+pip install olaverse-foundry[torch]
+
+# LoRA skill packs
+pip install olaverse-foundry[torch,lego]
+
+# Everything
+pip install olaverse-foundry[all]
+```
+
+---
+
+## Quick start — embedding distillation (200M student)
+
+```python
+from foundry import DataPipeline, EmbeddingDistillTrainer, EmbeddingDistillConfig
+from transformers import AutoModel, AutoTokenizer
+
+# Load student and teacher
+student = AutoModel.from_pretrained("microsoft/deberta-v3-base")
+teacher = AutoModel.from_pretrained("BAAI/bge-large-en-v1.5")
+tok     = AutoTokenizer.from_pretrained("microsoft/deberta-v3-base")
+
+# Stream data
+pipe = DataPipeline(
+    source       = my_hf_dataset,
+    tokenizer    = tok,
+    batch_size   = 32,
+    max_length   = 128,
+    mode         = "embed",
+    shuffle_buffer = 10_000,
+)
+
+# Train
+trainer = EmbeddingDistillTrainer(
+    student = student,
+    teacher = teacher,
+    config  = EmbeddingDistillConfig(
+        loss         = "cosine",
+        pool         = "mean",
+        epochs       = 3,
+        lr_scheduler = "cosine",
+        warmup_steps = 200,
+        torch_dtype  = "bfloat16",
+        save_every   = 1000,
+        save_dir     = "/checkpoints/embed-200m",
+        log_backend  = "wandb",
+    ),
+)
+
+result = trainer.train(pipe, eval_dataset=eval_pipe)
+print(result["eval_losses"])
+```
+
+---
+
+## Quick start — causal LM distillation with multiple teachers
+
+```python
+from foundry import (
+    DataPipeline, TorchDistillTrainer, TorchTrainConfig,
+    TeacherRegistry, FoundryRecipe,
+)
+
+# Build a registry of teachers
+teachers = TeacherRegistry.from_names(
+    ["meta-llama/Llama-3.1-70B", "Qwen/Qwen2-72B-Instruct"],
+    weights=[1.0, 0.8],
+)
+teachers.load_all()
+
+# Stream training data
+pipe = DataPipeline(
+    source     = my_dataset,
+    tokenizer  = tok,
+    batch_size = 8,
+    max_length = 2048,
+    mode       = "lm",
+)
+
+trainer = TorchDistillTrainer(
+    student  = my_3b_model,
+    teachers = teachers,
+    config   = TorchTrainConfig(
+        epochs                = 1,
+        lr_scheduler          = "cosine",
+        warmup_steps          = 500,
+        torch_dtype           = "bfloat16",
+        grad_accumulation_steps = 8,
+        save_every            = 500,
+        save_dir              = "/checkpoints/run1",
+        eval_every            = 100,
+        log_backend           = "wandb",
+    ),
+)
+
+result = trainer.train(pipe, eval_dataset=eval_pipe)
+```
+
+---
+
+## Key components
+
+| Module | What it does |
+|---|---|
+| `DataPipeline` | Converts HF datasets, string lists, or numpy arrays into trainer-ready batches. Supports streaming and reservoir shuffle. |
+| `TorchDistillTrainer` | Single-GPU distillation: CE + KL loss against one or more teachers. |
+| `CachedDistillTrainer` | Like `TorchDistillTrainer` but caches teacher logits on disk after the first pass. Subsequent epochs are free. Supports `accelerate` for multi-GPU. |
+| `EmbeddingDistillTrainer` | MSE / cosine loss on pooled sentence vectors. Use for bi-encoder / reranker distillation. |
+| `TeacherRegistry` | Pool of HF teacher models with relative weights. Handles `AutoModelForCausalLM` and `AutoModel` (encoders). |
+| `LogitCache` | In-memory + on-disk cache for top-k teacher logit distributions. |
+| `GrowthPlan` / `plan_growth` | Depth up-scaling via SOLAR-style layer duplication. Generates mergekit-compatible YAML. |
+| `SkillPack` / `SkillRegistry` | Detachable LoRA adapters bound to a specific base model hash. |
+| `save_as_peft` / `load_from_peft` | PEFT-format adapter round-trip (no peft library required). |
+| `MinEDAlignment` | Cross-tokenizer vocabulary alignment via edit distance. |
+| `DataPipeline` | Unified dataset adapter — HF datasets, streaming, raw text, numpy. |
+| `FoundryRecipe` / `EmbedRecipe` | Pydantic-validated YAML recipes — fail fast before GPU spend. |
+
+---
+
+## Training features
+
+All trainers share the same production-ready feature set:
+
+- **Mixed precision** — `torch_dtype="bfloat16"` or `"float16"`
+- **Gradient accumulation** — `grad_accumulation_steps=N`
+- **LR scheduler** — `"cosine"` / `"linear"` / `"constant"` with linear warmup
+- **Reproducibility** — `seed=42` sets torch + numpy + random before training
+- **Checkpointing** — `save_checkpoint(path)` / `resume_from_checkpoint(path)`
+- **Auto-checkpoint** — `save_every=N, save_dir="/path"` saves every N steps
+- **Eval loop** — `eval_every=N` evaluates on a held-out set every N steps
+- **W&B / TensorBoard** — `log_backend="wandb"` or `"tensorboard"`
+- **OOM handling** — CUDA OOM raises with actionable suggestions
+- **Streaming datasets** — `DataPipeline` wraps any HF `IterableDataset`
+- **Dataset shuffling** — `shuffle=True` or `shuffle_buffer=N` for streaming
+
+---
+
+## CLI
+
+```bash
+# Check your environment
+foundry doctor
+
+# Preview a recipe plan (no GPU spend)
+foundry plan recipe.yaml
+
+# Run a recipe
+foundry run recipe.yaml
+
+# Run an embedding distillation recipe
+foundry embed recipe.yaml
+
+# List fusion strategies
+foundry strategies
+```
+
+---
+
+## Recipe YAML
+
+```yaml
+# recipe.yaml — full causal-LM factory
+seed:
+  model: meta-llama/Llama-3.1-8B
+  init: pretrained
+
+grow:
+  method: depth_upscale
+  to_params: 15B
+
+teachers:
+  - role: reasoning
+    model: meta-llama/Llama-3.1-70B
+    weight: 1.0
+
+fusion:
+  strategy: min_ce
+  align: min_ed
+  cache: topk_64
+
+heal:
+  tokens: 100B
+  alpha: 0.3
+
+output:
+  freeze_base: true
+  skillpacks: [ola_math, ola_code]
+```
+
+---
+
+## Optional extras
+
+| Extra | Installs | When to use |
+|---|---|---|
+| `[torch]` | torch, transformers, safetensors, accelerate | Real training |
+| `[lego]` | peft | LoRA skill packs |
+| `[merge]` | mergekit | SOLAR depth up-scaling |
+| `[data]` | datasets | HuggingFace dataset streaming |
+| `[align]` | rapidfuzz | Fast cross-tokenizer alignment (100× speedup) |
+| `[logging]` | wandb | Experiment tracking |
+| `[all]` | everything | Full setup |
+
+---
+
+## Links
+
+- **Main SDK** — [olaverse](https://pypi.org/project/olaverse/) — ready-to-use African NLP models
+- **Homepage** — [olaverse.co.uk](https://olaverse.co.uk)
+- **GitHub** — [Olaverse-Labs/olaverse-foundry](https://github.com/Olaverse-Labs/olaverse-foundry)
+- **Issues** — [GitHub Issues](https://github.com/Olaverse-Labs/olaverse-foundry/issues)
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

olaverse_foundry-0.1.0/README.md

@@ -0,0 +1,236 @@
+# olaverse-foundry
+
+**Build model families from a single pretrained seed.**
+
+`olaverse-foundry` is the training and model-factory layer of the Olaverse ecosystem. Where `olaverse` gives you ready-to-use NLP models, `foundry` lets you build new ones — distilling, growing, fusing, and adapting them for production.
+
+```
+seed → grow → distil / fuse → freeze → skill packs
+```
+
+---
+
+## Install
+
+```bash
+# Core (schema validation, growth planning — no GPU required)
+pip install olaverse-foundry
+
+# GPU training
+pip install olaverse-foundry[torch]
+
+# LoRA skill packs
+pip install olaverse-foundry[torch,lego]
+
+# Everything
+pip install olaverse-foundry[all]
+```
+
+---
+
+## Quick start — embedding distillation (200M student)
+
+```python
+from foundry import DataPipeline, EmbeddingDistillTrainer, EmbeddingDistillConfig
+from transformers import AutoModel, AutoTokenizer
+
+# Load student and teacher
+student = AutoModel.from_pretrained("microsoft/deberta-v3-base")
+teacher = AutoModel.from_pretrained("BAAI/bge-large-en-v1.5")
+tok     = AutoTokenizer.from_pretrained("microsoft/deberta-v3-base")
+
+# Stream data
+pipe = DataPipeline(
+    source       = my_hf_dataset,
+    tokenizer    = tok,
+    batch_size   = 32,
+    max_length   = 128,
+    mode         = "embed",
+    shuffle_buffer = 10_000,
+)
+
+# Train
+trainer = EmbeddingDistillTrainer(
+    student = student,
+    teacher = teacher,
+    config  = EmbeddingDistillConfig(
+        loss         = "cosine",
+        pool         = "mean",
+        epochs       = 3,
+        lr_scheduler = "cosine",
+        warmup_steps = 200,
+        torch_dtype  = "bfloat16",
+        save_every   = 1000,
+        save_dir     = "/checkpoints/embed-200m",
+        log_backend  = "wandb",
+    ),
+)
+
+result = trainer.train(pipe, eval_dataset=eval_pipe)
+print(result["eval_losses"])
+```
+
+---
+
+## Quick start — causal LM distillation with multiple teachers
+
+```python
+from foundry import (
+    DataPipeline, TorchDistillTrainer, TorchTrainConfig,
+    TeacherRegistry, FoundryRecipe,
+)
+
+# Build a registry of teachers
+teachers = TeacherRegistry.from_names(
+    ["meta-llama/Llama-3.1-70B", "Qwen/Qwen2-72B-Instruct"],
+    weights=[1.0, 0.8],
+)
+teachers.load_all()
+
+# Stream training data
+pipe = DataPipeline(
+    source     = my_dataset,
+    tokenizer  = tok,
+    batch_size = 8,
+    max_length = 2048,
+    mode       = "lm",
+)
+
+trainer = TorchDistillTrainer(
+    student  = my_3b_model,
+    teachers = teachers,
+    config   = TorchTrainConfig(
+        epochs                = 1,
+        lr_scheduler          = "cosine",
+        warmup_steps          = 500,
+        torch_dtype           = "bfloat16",
+        grad_accumulation_steps = 8,
+        save_every            = 500,
+        save_dir              = "/checkpoints/run1",
+        eval_every            = 100,
+        log_backend           = "wandb",
+    ),
+)
+
+result = trainer.train(pipe, eval_dataset=eval_pipe)
+```
+
+---
+
+## Key components
+
+| Module | What it does |
+|---|---|
+| `DataPipeline` | Converts HF datasets, string lists, or numpy arrays into trainer-ready batches. Supports streaming and reservoir shuffle. |
+| `TorchDistillTrainer` | Single-GPU distillation: CE + KL loss against one or more teachers. |
+| `CachedDistillTrainer` | Like `TorchDistillTrainer` but caches teacher logits on disk after the first pass. Subsequent epochs are free. Supports `accelerate` for multi-GPU. |
+| `EmbeddingDistillTrainer` | MSE / cosine loss on pooled sentence vectors. Use for bi-encoder / reranker distillation. |
+| `TeacherRegistry` | Pool of HF teacher models with relative weights. Handles `AutoModelForCausalLM` and `AutoModel` (encoders). |
+| `LogitCache` | In-memory + on-disk cache for top-k teacher logit distributions. |
+| `GrowthPlan` / `plan_growth` | Depth up-scaling via SOLAR-style layer duplication. Generates mergekit-compatible YAML. |
+| `SkillPack` / `SkillRegistry` | Detachable LoRA adapters bound to a specific base model hash. |
+| `save_as_peft` / `load_from_peft` | PEFT-format adapter round-trip (no peft library required). |
+| `MinEDAlignment` | Cross-tokenizer vocabulary alignment via edit distance. |
+| `DataPipeline` | Unified dataset adapter — HF datasets, streaming, raw text, numpy. |
+| `FoundryRecipe` / `EmbedRecipe` | Pydantic-validated YAML recipes — fail fast before GPU spend. |
+
+---
+
+## Training features
+
+All trainers share the same production-ready feature set:
+
+- **Mixed precision** — `torch_dtype="bfloat16"` or `"float16"`
+- **Gradient accumulation** — `grad_accumulation_steps=N`
+- **LR scheduler** — `"cosine"` / `"linear"` / `"constant"` with linear warmup
+- **Reproducibility** — `seed=42` sets torch + numpy + random before training
+- **Checkpointing** — `save_checkpoint(path)` / `resume_from_checkpoint(path)`
+- **Auto-checkpoint** — `save_every=N, save_dir="/path"` saves every N steps
+- **Eval loop** — `eval_every=N` evaluates on a held-out set every N steps
+- **W&B / TensorBoard** — `log_backend="wandb"` or `"tensorboard"`
+- **OOM handling** — CUDA OOM raises with actionable suggestions
+- **Streaming datasets** — `DataPipeline` wraps any HF `IterableDataset`
+- **Dataset shuffling** — `shuffle=True` or `shuffle_buffer=N` for streaming
+
+---
+
+## CLI
+
+```bash
+# Check your environment
+foundry doctor
+
+# Preview a recipe plan (no GPU spend)
+foundry plan recipe.yaml
+
+# Run a recipe
+foundry run recipe.yaml
+
+# Run an embedding distillation recipe
+foundry embed recipe.yaml
+
+# List fusion strategies
+foundry strategies
+```
+
+---
+
+## Recipe YAML
+
+```yaml
+# recipe.yaml — full causal-LM factory
+seed:
+  model: meta-llama/Llama-3.1-8B
+  init: pretrained
+
+grow:
+  method: depth_upscale
+  to_params: 15B
+
+teachers:
+  - role: reasoning
+    model: meta-llama/Llama-3.1-70B
+    weight: 1.0
+
+fusion:
+  strategy: min_ce
+  align: min_ed
+  cache: topk_64
+
+heal:
+  tokens: 100B
+  alpha: 0.3
+
+output:
+  freeze_base: true
+  skillpacks: [ola_math, ola_code]
+```
+
+---
+
+## Optional extras
+
+| Extra | Installs | When to use |
+|---|---|---|
+| `[torch]` | torch, transformers, safetensors, accelerate | Real training |
+| `[lego]` | peft | LoRA skill packs |
+| `[merge]` | mergekit | SOLAR depth up-scaling |
+| `[data]` | datasets | HuggingFace dataset streaming |
+| `[align]` | rapidfuzz | Fast cross-tokenizer alignment (100× speedup) |
+| `[logging]` | wandb | Experiment tracking |
+| `[all]` | everything | Full setup |
+
+---
+
+## Links
+
+- **Main SDK** — [olaverse](https://pypi.org/project/olaverse/) — ready-to-use African NLP models
+- **Homepage** — [olaverse.co.uk](https://olaverse.co.uk)
+- **GitHub** — [Olaverse-Labs/olaverse-foundry](https://github.com/Olaverse-Labs/olaverse-foundry)
+- **Issues** — [GitHub Issues](https://github.com/Olaverse-Labs/olaverse-foundry/issues)
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

olaverse_foundry-0.1.0/foundry/__init__.py

@@ -0,0 +1,70 @@
+"""
+olaverse-foundry — a toolkit for building model families.
+
+One expensive ancestor, many cheap descendants.
+
+    seed → grow → fuse/heal → freeze → skill packs
+
+Quick start::
+
+    from foundry import Recipe
+
+    recipe = Recipe.load("my_recipe.yaml")
+    for line in recipe.plan():
+        print(line)
+
+    base = recipe.run()
+"""
+from foundry.contracts import ArchConfig, Student, Teacher, TokenizerAlignment
+from foundry.fusion import FusionKernel, IdentityAlignment, EMAlignment, MinEDAlignment
+from foundry.fusion import STRATEGY_REGISTRY, min_ce, mean_ce
+from foundry.growth import (
+    GrowthPlan, upscale_layer_map, layers_for_param_target, plan_growth,
+    growth_plan_to_mergekit_yaml, save_mergekit_config, run_merge,
+)
+from foundry.skillpacks import (
+    SkillPack, SkillRegistry,
+    save_as_peft, load_from_peft, peft_config_dict,
+)
+from foundry.teachers import TeacherRegistry, ToyTeacher, HFTeacher, LogitCache
+from foundry.training import (
+    DistillTrainer, TrainConfig,
+    TorchDistillTrainer, TorchTrainConfig,
+    CachedDistillTrainer, CachedDistillConfig,
+    EmbeddingDistillTrainer, EmbeddingDistillConfig, ToyEmbeddingTeacher,
+)
+from foundry.io import SeedResult, load_seed
+from foundry.recipes import Recipe, FoundryRecipe, EmbedRecipe, EmbedFusionConfig
+from foundry.backends import detect_backend
+from foundry.data import DataPipeline
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Contracts
+    "ArchConfig", "Student", "Teacher", "TokenizerAlignment",
+    # Fusion
+    "FusionKernel", "IdentityAlignment", "EMAlignment", "MinEDAlignment",
+    "STRATEGY_REGISTRY", "min_ce", "mean_ce",
+    # Growth
+    "GrowthPlan", "upscale_layer_map", "layers_for_param_target", "plan_growth",
+    "growth_plan_to_mergekit_yaml", "save_mergekit_config", "run_merge",
+    # Skill packs
+    "SkillPack", "SkillRegistry",
+    "save_as_peft", "load_from_peft", "peft_config_dict",
+    # Teachers
+    "TeacherRegistry", "ToyTeacher", "HFTeacher", "LogitCache",
+    # Training
+    "DistillTrainer", "TrainConfig",
+    "TorchDistillTrainer", "TorchTrainConfig",
+    "CachedDistillTrainer", "CachedDistillConfig",
+    "EmbeddingDistillTrainer", "EmbeddingDistillConfig", "ToyEmbeddingTeacher",
+    # IO / Seed
+    "SeedResult", "load_seed",
+    # Recipes
+    "Recipe", "FoundryRecipe", "EmbedRecipe", "EmbedFusionConfig",
+    # Backends
+    "detect_backend",
+    # Data
+    "DataPipeline",
+]

olaverse_foundry-0.1.0/foundry/backends.py

@@ -0,0 +1,100 @@
+"""
+Backend capability detection — what's available on this machine?
+"""
+from __future__ import annotations
+
+import sys
+
+
+def detect_backend() -> dict:
+    """
+    Check which optional backends are installed and available.
+
+    Returns:
+        dict with keys: torch, cuda, mps, peft, accelerate, mergekit,
+        safetensors, rapidfuzz, python_version, cuda_version,
+        gpu_count, gpu_vram_gb, summary.
+    """
+    result: dict = {
+        "torch":          False,
+        "cuda":           False,
+        "mps":            False,
+        "peft":           False,
+        "accelerate":     False,
+        "mergekit":       False,
+        "safetensors":    False,
+        "rapidfuzz":      False,
+        "wandb":          False,
+        "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+        "torch_version":  None,
+        "cuda_version":   None,
+        "gpu_count":      0,
+        "gpu_vram_gb":    [],   # list of VRAM per device in GB
+    }
+
+    try:
+        import torch
+        result["torch"]         = True
+        result["torch_version"] = torch.__version__
+        result["cuda"]          = torch.cuda.is_available()
+        result["mps"]           = (
+            hasattr(torch.backends, "mps") and torch.backends.mps.is_available()
+        )
+        if result["cuda"]:
+            result["cuda_version"] = torch.version.cuda
+            n = torch.cuda.device_count()
+            result["gpu_count"]  = n
+            result["gpu_vram_gb"] = [
+                round(torch.cuda.get_device_properties(i).total_memory / 1e9, 1)
+                for i in range(n)
+            ]
+    except ImportError:
+        pass
+
+    for pkg, key in [
+        ("peft",        "peft"),
+        ("accelerate",  "accelerate"),
+        ("mergekit",    "mergekit"),
+        ("safetensors", "safetensors"),
+        ("rapidfuzz",   "rapidfuzz"),
+        ("wandb",       "wandb"),
+    ]:
+        try:
+            __import__(pkg)
+            result[key] = True
+        except (ImportError, TypeError):
+            pass
+
+    # Build summary string
+    parts = []
+    if result["torch"]:
+        if result["cuda"]:
+            vram = result["gpu_vram_gb"]
+            vram_str = "+".join(f"{v}GB" for v in vram) if vram else "?"
+            parts.append(
+                f"torch {result['torch_version']} "
+                f"(CUDA {result['cuda_version']}, {result['gpu_count']}× GPU, {vram_str} VRAM)"
+            )
+        elif result["mps"]:
+            parts.append(f"torch {result['torch_version']} (MPS/Apple Silicon)")
+        else:
+            parts.append(f"torch {result['torch_version']} (CPU only)")
+    else:
+        parts.append("no torch — toy/numpy backend only")
+
+    for key in ("peft", "accelerate", "mergekit", "safetensors", "rapidfuzz", "wandb"):
+        if result[key]:
+            parts.append(key)
+
+    result["summary"] = "  ".join(parts)
+    return result
+
+
+def require_torch(feature: str = "this feature") -> None:
+    """Raise a helpful ImportError if torch is not installed."""
+    info = detect_backend()
+    if not info["torch"]:
+        raise ImportError(
+            f"{feature} requires torch. "
+            "Install with: pip install olaverse-foundry[torch]"
+        )