# 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

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

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

## Run This One Command First

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

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

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

```python
from model_osmosis import OsmosisPipeline

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

### 3) Stack models as experts

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

### 4) Compare and benchmark

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

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

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

```bash
# 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:

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

```bash
# 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.

```bash
# 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:

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

```bash
# 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:

```bash
# 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:

```bash
osmosis demo
```

Example success output includes:

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

After demo passes:

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

```bash
# 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:

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

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

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

```bash
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):

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

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