Metadata-Version: 2.4
Name: mundus
Version: 0.1.0
Summary: A modular hub for generative world models and World Action Models
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: sana
Requires-Dist: torch; extra == "sana"
Requires-Dist: numpy; extra == "sana"
Requires-Dist: einops; extra == "sana"
Requires-Dist: timm; extra == "sana"
Requires-Dist: transformers; extra == "sana"
Requires-Dist: safetensors; extra == "sana"
Requires-Dist: termcolor; extra == "sana"
Requires-Dist: torchvision; extra == "sana"
Requires-Dist: huggingface-hub; extra == "sana"
Requires-Dist: imageio; extra == "sana"

# Mundus

Mundus is a self-contained, provider-based hub for video/image generators,
learned world models, representation models, and WAMs.  Its SANA integration
is bundled in `mundus.sana`; it does not import or require the sibling
`sana_sim` project at runtime. Providers have one common generation interface;
heavyweight models are loaded only when used.

The core has no runtime dependencies. For the bundled SANA provider, install
the optional runtime once with `pip install -e '.[sana]'`.

## Standalone SANA video generation

```python
from mundus import Mundus

world = Mundus.from_pretrained(
    "sana-video",
    model_path="checkpoints/SANA_Video_2B_480p.pth",
    vae_path="checkpoints/Wan2.1_VAE.pth",
)
result = world.generate("A robot carefully opens a drawer", num_frames=81, seed=42)
result.save("robot.mp4")
```

## SANA MoT WAM

`migma.models.wms.samot.SanaMoTWAM` keeps the loaded SANA denoiser as the
video branch and adds an action diffusion head.  The action head reads SANA's
per-layer normalized video tokens (world memory) and its own action tokens;
the video branch never reads action tokens.  This is the asymmetric
Mixture-of-Transformers contract and preserves the normal SANA video output.

```python
from migma.models.wms.samot import SanaMoTWAM

provider = world.model
wam = SanaMoTWAM(provider.backbone, action_dim=7, max_action_horizon=32).cuda()
text, mask = provider.encode_text("Robot reaches for the drawer handle")
video_noise, action_noise = wam(
    noisy_video, video_timestep, text, mask, noisy_actions,
)
```

Train the two outputs with the appropriate SANA video denoising loss and the
action flow/noise loss.  SANA can be frozen initially, then selectively
unfrozen for joint WAM finetuning.

## Extending the hub

Implement the `WorldModel` protocol (`model_id`, `capabilities`, and
`generate(request)`), then register a factory:

```python
from mundus import registry
registry.register("my-world-model", MyWorldModel)
```

No provider has to share model internals with another provider.  A provider
that exposes a backbone may additionally be used by a WAM adapter.
