model-osmosis 0.8.0

Universal Model Knowledge Transfer Framework — absorb, merge, stack, and bridge any ML model into another with zero training cost.

ModelOsmosis

ModelOsmosis is a Python framework for:

• operating models through a unified 4-command UX (make, protect, check, launch)
• transferring knowledge between models (absorb)
• merging model weights (merge, including modern merge strategies)
• pure deterministic weight merging (pipeline --mode weight-merge)
• stacking experts into Mixture-of-Experts style models (stack)
• converting models into a shared interchange format (.osmo)
• packaging runnable model images (.osmoimg) with compression + obfuscation
• running and serving those images from a CLI
• issuing signed invite codes with local activation ledger (invite)

This README is written from the current v0.8.0 codebase.

Status

• Version: 0.8.0
• Maturity: pre-1.0 (alpha in package metadata)
• Python: >=3.9
• License: MIT

Install

pip install model-osmosis

Optional extras:

• huggingface - transformers + hub integration
• vision - timm/torchvision helpers
• audio - audio model helpers
• diffusion - diffusers support
• multimodal - multimodal helpers
• lora - PEFT/LoRA support
• onnx - ONNX runtime support
• mlx - Apple MLX support
• tensorflow - TensorFlow/Keras support
• jax - JAX/Flax support
• demo - Gradio demo app
• all - most optional integrations

Examples:

pip install "model-osmosis[huggingface]"
pip install "model-osmosis[all]"

Run This One Command First

First-time quick demo (non-interactive, one command):

osmosis demo

What this guarantees:

• builds and saves a runnable .osmoimg
• validates metadata via inspect
• runs a smoke generation prompt
• prints a PASS/FAIL summary with output path, RAM estimate, codec/profile, and elapsed time

Defaults used by osmosis demo:

• model: HuggingFaceTB/SmolLM2-135M-Instruct
• output: models/quick_demo_smollm2_135m_instruct.osmoimg
• compression profile: lossless-max
• timeout gate: 30 minutes

Expected first-run time on a clean machine: about 10-30 minutes (mostly model download).

Quick Start (Python API)

1) Absorb knowledge from one model into another

import numpy as np
import torch.nn as nn
from model_osmosis import OsmosisPipeline, OsmosisConfig

source = nn.Sequential(nn.Linear(8, 64), nn.ReLU(), nn.Linear(64, 4))
target = nn.Sequential(nn.Linear(8, 16), nn.ReLU(), nn.Linear(16, 4))
sample = np.random.rand(200, 8).astype("float32")

pipeline = OsmosisPipeline(OsmosisConfig(verbose=False))
result = pipeline.absorb(source=source, target=target, sample_data=sample, auto_grow=True)

2) Merge multiple models

from model_osmosis import OsmosisPipeline

pipeline = OsmosisPipeline()
merged = pipeline.merge([model_a, model_b], strategy="slerp")

3) Stack models as experts

stacked = pipeline.stack([expert_a, expert_b, expert_c], train_gate=True)

4) Compare and benchmark

metrics = pipeline.compare(model_a, model_b, sample_data)
ranked = pipeline.benchmark([model_a, model_b, model_c], eval_data=sample_data)

.osmo Universal Format

.osmo is the internal interchange format used for conversion, merge, and composition across frameworks.

from model_osmosis import to_osmo, from_osmo, merge_osmo, save_osmo, load_osmo

osmo_a = to_osmo(model_a)
osmo_b = to_osmo(model_b)

merged = merge_osmo([osmo_a, osmo_b], strategy="weighted_average")
save_osmo(merged, "merged.osmo")

loaded = load_osmo("merged.osmo")
pytorch_state = from_osmo(loaded, target_framework="pytorch")

.osmoimg Portable Runtime Image

.osmoimg is a runnable image format with:

• compressed payload (zip container)
• obfuscation/encryption path during build
• runtime metadata (RAM estimate, framework, model type, etc.)
• offline trust signature support (Ed25519)
• inspectable trust/provenance/repro metadata
• immutable artifact identity metadata (artifact_id, manifest_sha256, tensor_index_sha256)
• embedded tokenizer bundle metadata in every image (real tokenizer assets required for text models)
• pluggable signer backends (local-keyring, aws-kms)
• optional non-blocking transparency logging hook
• CLI support for inspect/run/export/serve

Python example:

from model_osmosis.format.image import OsmoImage

image = OsmoImage.build(
    "HuggingFaceTB/SmolLM2-135M-Instruct",
    name="quick-demo",
    compression_profile="lossless-max",
    trust_sign=True,
    signer_backend="local-keyring",  # or "aws-kms"
    provenance_mode="private",
    repro_mode="strict",
)
image.save(
    "quick-demo.osmoimg",
    compression_profile="lossless-max",
    trust_sign=True,
    signer_backend="local-keyring",
    provenance_mode="private",
    repro_mode="strict",
)

info = OsmoImage.inspect("quick-demo.osmoimg")
print(info["runtime"]["min_ram_gb"])
print(info["runtime"]["trust_status"])

Phase 2 trust env knobs (optional):

# signer backend selection
set OSMOSIS_SIGNER_BACKEND=aws-kms
set OSMOSIS_KMS_PROVIDER=azure-kv
set OSMOSIS_KMS_KEY_REF=kv://prod/model-osmosis/signing-key

# transparency hook (non-blocking if endpoint fails/unavailable)
set OSMOSIS_TRANSPARENCY_URL=https://transparency.example.com/events

CLI Overview (osmosis)

Entry point:

osmosis --help

The current CLI provides 36 commands:

Recommended 4-command workflow

• make - model operation side (merge, weight-merge, absorb, stack, cross-merge)
• protect - package model into trusted .osmoimg (compression/signing/provenance/repro)
• check - inspect + verify + self-check (optional benchmark/release checks)
• launch - runtime side (run, serve, export)

Example:

# 1) Build/optimize model side
osmosis make --mode weight-merge --models pt:./a.pt pt:./b.pt --output-type osmo -o models/merged.osmo

# 2) Package as trusted osmoimg
osmosis protect models/merged.osmo -o models/merged.osmoimg --compression-profile lossless-max

# 3) Validate artifact
osmosis check models/merged.osmoimg --self-check-level smoke

# 4) Launch runtime
osmosis launch models/merged.osmoimg --action run --prompt "Hello"

Image and runtime commands

• protect - package model into trusted .osmoimg with compression/signing/provenance controls
• check - unified validation gate for .osmoimg (inspect + trust verify + self-check)
• launch - unified runtime entrypoint for run|serve|export
• artifact - git-integrated .osmoimg tracking, verification, and hook install
• demo - one-command first-time build+validate+smoke-run path
• doctor - preflight diagnostics (deps/network/disk/RAM) with one-line fixes
• build - build .osmoimg from model path or HF model id
• run - run inference from .osmoimg (returns generated text only by default)
• inspect - inspect metadata without full load
• export - export .osmoimg back to framework format
• register - register/unregister .osmoimg with OS
• images - list .osmoimg files in a directory
• pull - pull HF model and save as .osmoimg
• transcode - rewrite image with selected compression profile
• push - push .osmoimg to HuggingFace Hub
• diff - compare metadata of two images
• validate - validate file integrity and loadability
• verify - verify trust signature status, signer trust, and optional --repro-check
• quantize - quantize image weights (CLI helper)
• serve - start HTTP server for inference
• history - show build/export metadata history
• benchmark-runtime - run runtime KPI benchmark against repo baseline thresholds
• trust - manage local signing keys and trusted signers
• invite - signed invite-code generation, verification, activation, and status

Invite Licensing (osmosis invite)

Issue signed invite codes and activate installations with a local append-only hash-chain ledger.

# issuer side only (requires issuer mode): create one invite code
set OSMOSIS_INVITE_ISSUER=1
osmosis invite create --name "partner-a" --max-activations 1

# recipient side: verify then activate by pasted code text
osmosis invite verify --code "<paste-code>"
osmosis invite activate --code "<paste-code>"
osmosis invite status --show-ledger

Invite enforcement is enabled by default (all non-invite commands require activation first).

Optional override for local development only:

set OSMOSIS_REQUIRE_INVITE=0

Git Artifact Tracking (osmosis artifact)

Track trusted .osmoimg artifacts in git workflows so unexpected file changes are caught before shipping.

# track one or more artifacts into deterministic lock file
osmosis artifact track models/prod.osmoimg
osmosis artifact track models/prod_a.osmoimg models/prod_b.osmoimg

# verify tracked artifacts (single or all)
osmosis artifact verify models/prod.osmoimg
osmosis artifact verify --all

# install pre-commit + pre-push hooks to enforce verification
osmosis artifact hook install

Default lock file:

• .model_osmosis/artifacts.lock.json

What is tracked per artifact:

• path
• payload hash and artifact identity fields
• signer/key/signature metadata
• codec/profile/header metadata

Typical team flow:

1. Track approved artifact versions with artifact track.
2. Commit artifacts.lock.json to git.
3. Enforce artifact verify --all in hooks/CI.
4. If artifact is intentionally updated, re-run artifact track and commit the lock update.

Model workflow commands

• make - unified model operation command for merge|weight-merge|absorb|stack|cross-merge
• pipeline - unified merge/weight-merge/absorb/stack flow with multi-format output
• merge - merge multiple models (including cross merge options)
• obfuscate - obfuscate model weights
• compare - compare two models on sample data
• benchmark - benchmark merge strategies
• info - inspect model-level info
• convert - convert model between formats/frameworks
• version - print package version

Unified Pipeline (osmosis pipeline)

Use one command to run merge/weight-merge/absorb/stack and export outputs:

# merge -> protected osmoimg (compression + obfuscation)
osmosis pipeline --mode merge --output-type osmoimg \
  --models hf:HuggingFaceTB/SmolLM2-135M-Instruct pt:./models/model_b.pt \
  --compression-profile lossless-max \
  --trust-sign --provenance private --repro-mode strict \
  -o models/unified_merge.osmoimg

# absorb -> protected pytorch output (obfuscation-only)
osmosis pipeline --mode absorb --output-type pytorch \
  --source pt:./models/source.pt --target pt:./models/target.pt \
  -o models/absorbed.pt

# stack -> ONNX (requires shape)
osmosis pipeline --mode stack --output-type onnx \
  --models pt:./models/expert_a.pt pt:./models/expert_b.pt \
  --onnx-input-shape 1,128 -o models/stacked.onnx

# weight-merge -> pure weights with coverage gate (raw output unprotected by default)
osmosis pipeline --mode weight-merge --output-type pytorch \
  --models pt:./models/a.pt pt:./models/b.pt \
  --merge-strategy weighted_average --coverage-floor 0.70 \
  -o models/weight_merged.pt

Supported --output-type values (11):

• osmoimg
• osmo
• pytorch
• hf
• onnx
• tensorflow
• keras
• jax
• flax
• safetensors
• torchscript

Model reference syntax supported by unified pipeline:

• hf:repo/id
• pt:path/to/model.pt
• onnx:path/to/model.onnx
• tf:path/to/saved_model_or_h5
• jax:path/to/params.npz
• plain paths are auto-detected

Reliability flags for unified pipeline:

• --dry-run runs preflight + route resolution only (no writes)
• --report-file PATH saves deterministic operation report JSON
• --self-check / --no-self-check controls post-write artifact validation (default: on)
• --coverage-floor applies to --mode weight-merge (minimum per-model merged byte coverage, default 0.70)
• --strategy-engine {auto,off} controls smart recipe selection for merge/weight-merge (default: auto)

Protection behavior:

• --output-type osmoimg: protected container path (compression + obfuscation + trust metadata)
• --mode weight-merge with raw outputs (pytorch/hf/onnx/...): unprotected by default (pure weight export)

Smart merge behavior:

• merge and pipeline --mode merge|weight-merge default to smart recipe selection when strategy is auto
• explicit strategy flags still win (--strategy, --merge-strategy)
• smart selection metadata is written to pipeline operation reports and merge provenance fields for .osmoimg

Troubleshooting Matrix

Symptom	Why it happens	Fix
absorb target unsupported	target absorber currently expects torch/sklearn-compatible targets	use pt:/HF-compatible target
stack expert unsupported	stack requires torch-compatible experts	use torch/HF/ONNX experts
ONNX export fails with missing shape	ONNX export needs static input shape	add --onnx-input-shape 1,128
TorchScript export fails on scripting	model cannot be scripted directly	add --trace-input-shape 1,128 for trace fallback
Raw outputs not compressed	compression container applies to .osmoimg only	use --output-type osmoimg for compression

End-to-End Quick Demo (CPU, first-time user)

Run:

osmosis demo

Example success output includes:

• Status: PASS
• output path under models/
• RAM estimate
• payload codec + compression profile
• elapsed time

After demo passes:

osmosis inspect models/quick_demo_smollm2_135m_instruct.osmoimg
osmosis check models/quick_demo_smollm2_135m_instruct.osmoimg --self-check-level smoke
osmosis run models/quick_demo_smollm2_135m_instruct.osmoimg --prompt "Hello"
osmosis launch models/quick_demo_smollm2_135m_instruct.osmoimg --action run --prompt "Hello"
osmosis serve models/quick_demo_smollm2_135m_instruct.osmoimg --port 8080

Run output behavior:

• default: returns newly generated tokens only (better chat UX)
• legacy compatibility: add --include-prompt to include the original prompt in output

# default (new tokens only)
osmosis run models/quick_demo_smollm2_135m_instruct.osmoimg --prompt "Hello"

# legacy behavior (prompt + completion)
osmosis run models/quick_demo_smollm2_135m_instruct.osmoimg --prompt "Hello" --include-prompt

Merge Strategies in v0.8.0

Implemented strategies include:

• weighted_average - weighted tensor average
• slerp - spherical interpolation
• ties - conflict-aware TIES merge
• dare
• breadcrumbs
• consensus
• auto (pipeline-level strategy selection path)

Obfuscation

Core obfuscation components are in model_osmosis/obfuscation/:

• graph-based transform grouping
• neuron permutation
• basis rotation
• weight scaling
• metadata randomization
• optional verification

Pipeline usage:

from model_osmosis import OsmosisPipeline
from model_osmosis.obfuscation import ObfuscationConfig

pipeline = OsmosisPipeline()
cfg = ObfuscationConfig(preserve_quality=True, seed=42)
protected = pipeline.obfuscate(model, obfuscation_config=cfg)

Adapters and Supported Domains

Core adapter:

• HuggingFace adapter (always available in package code)

Lazy optional adapters:

• vision
• audio
• diffusion
• multimodal
• LoRA/PEFT
• ONNX
• MLX
• TensorFlow
• JAX

Install the matching optional dependency group before using those adapters.

Repository Layout

model_osmosis/
  adapters/        # source-framework adapters
  absorbers/       # target injection logic
  core/            # config + exceptions
  extractors/      # source extraction logic
  format/          # .osmo + .osmoimg + converters
  growers/         # target capacity growth
  knowledge/       # universal knowledge representation
  merging/         # merge algorithms and cross-merge utilities
  obfuscation/     # obfuscation transforms + verification
  optimizer/       # local self-optimizer state + profile selection
  services/        # service-layer logic shared by CLI commands
  stacking/        # MoE-style stacking
  pipeline.py      # main orchestrator API
  cli.py           # command-line interface
examples/
tests/
demo/
benchmark.py

Tests

Run full test suite:

pytest tests -v

Selected suites:

• tests/test_e2e_pipeline.py
• tests/test_v060_features.py
• tests/test_osmo_image.py
• tests/test_cli_new_commands.py

Clean-Machine Validation Pass

Local reproducible validation:

python scripts/validate_clean_machine.py \
  --install-spec "model-osmosis[huggingface,compression]" \
  --timeout-minutes 30

For repository validation (install from local source instead of PyPI):

python scripts/validate_clean_machine.py \
  --install-spec ".[huggingface,compression]" \
  --timeout-minutes 30

The script creates a fresh virtual environment, installs dependencies, runs osmosis demo, runs inspect on the generated artifact, and writes logs + summary.json under clean_machine_validation_artifacts/.

CI release gate:

• .github/workflows/clean-machine-validation.yml
• runs on Windows + Linux + macOS
• uploads validation logs/artifacts for each OS

Benchmark Script

benchmark.py includes three demonstration benchmarks:

• absorb with growth (PyTorch -> PyTorch)
• cross-framework style transfer (scikit-learn tree -> PyTorch)
• merge benchmark using multiple weak experts

Run:

python benchmark.py

Known Notes and Limitations

• 0.8.0 is pre-1.0. APIs and internals may still evolve.
• Small general models (for example distilgpt2) are useful for runtime demos but are not instruction-tuned chat models.
• Some advanced adapter paths require optional packages and/or external model downloads.
• For Windows users, HuggingFace cache symlink warnings are common without Developer Mode; this impacts disk usage more than correctness.

License

MIT