Planet Bridging

Universal bridging between AI engines through Loom.

Planet Bridging is the project that maps how models move between AI runtimes (“planets”) and Loom’s volumetric runtime. Each major framework — PyTorch, TensorFlow, JAX, ONNX Runtime, llama.cpp, CoreML, and others — speaks its own formats, operator dialects, and execution models. Models do not travel freely; they get converted, lose fidelity, or stay locked to one stack.

Planet Bridging exists so weights and topology can flow into Loom today (live stream → .entity → Loom infer), and out of Loom tomorrow (export to hub formats → any inference engine).

Implementation lives in the sibling repo planetbridging/. The PyPI package (planetbridging, currently v0.7.3) is the end-user lane: pip install + bundled loom-stream — no git clone, no go build, no compare-host HTTP.

Related Loom docs: entity.md (what .entity is), serialization.md (JSON + ENTITY persistence), bedrock_validation.md (Lucy seven-layer CPU gate inside Loom), layers.md (volumetric layer types).

What it means

Planets and the hub

Think of the AI ecosystem as a solar system:

Planet Bridging is not “reimplement every engine.” It is layer-aware translation: map foreign ops to Loom’s VolumetricLayer types (Dense, CNN1/2/3, MHA, LSTM, …), stream weights in a canonical JSON contract, and build a Loom network that forward-matches the native planet on shared fixtures.

Two halves of the bridge

Versioning intuition: 0.5 + 0.5 ≈ 1.0 — first half is into Loom; second half is out of Loom.

How it works (planets → Loom)

This is live weight streaming, not a classic ONNX → Safetensors → Loom file pipeline.

┌─────────────────┐     JSON layer stream      ┌──────────────┐     ┌─────────────┐
│  AI planet      │  ───────────────────────►  │ loom-stream  │ ──► │  .entity    │
│  PyTorch / TF   │   (weights + topology)     │  (Go CLI)    │     │  checkpoint │
│  JAX / sklearn  │                            └──────┬───────┘     └──────┬──────┘
└─────────────────┘                                   │                    │
       │                                              │                    ▼
       │ native forward on fixtures                   │              Loom infer
       └──────────────── compare ─────────────────────┴──────── PASS / EXACT / DIFF

1. Bedrock — a POC harness per Loom layer family (python/dense/, python/mha/, …). Each bedrock defines manifest models, fixtures, and per-planet engine handlers.
2. Planet handler — Python reads live in-memory weights from the framework, builds the stream payload, and calls loom-stream (HTTP in the compare host; patched to CLI in the PyPI package).
3. loom-stream — Go binary (planetbridging/cmd/loom-stream/) calls bridge.BuildNetworkFrom*Stream and writes a .entity file.
4. Compare — native planet forward vs Loom forward on the same x_test samples. Labels: EXACT, PASS (within fp32 tolerance), DIFF.

flowchart LR
  subgraph NOW["Today — INTO Loom"]
    P["Planets<br/>PyTorch · TF · JAX · sklearn"]
    B["13 bedrocks<br/>Dense · CNN · MHA · norms · …"]
    S["loom-stream"]
    E[".entity"]
    L["Loom infer"]
    C["Compare PASS"]
    P --> B --> S --> E --> L --> C
  end

  subgraph LATER["v1.0 — OUT of Loom"]
    L2["Loom hub"]
    H["ONNX · Safetensors · GGUF"]
    X["Any inference engine"]
    L2 -.-> H -.-> X
  end

  L --> L2

The 13 bedrock layer types

Each row is a Loom volumetric layer family with a planetbridging bedrock. All support PyTorch, TensorFlow, and JAX live streaming unless noted.

Bedrock here means: shared fixtures, manifest models, native forward reference, and stream builders — the “proof layer” that a planet’s weights map correctly into Loom. Lucy’s seven-layer CPU suite validates Loom internals; planetbridging bedrocks validate cross-planet parity.

PyPI package (v0.7.3) — pip-only workflow

Install

pip install 'planetbridging[pytorch,welvet]==0.7.3'
# optional cross-engine:
pip install 'planetbridging[tensorflow,jax]'

Python ≥ 3.10. The wheel ships:

Fixture .npz files are not in the wheel (PyPI 100 MB limit). They generate once on first use into ~/.planetbridging/fixtures/ (~86 MB total). Override with PLANETBRIDGING_FIXTURES_CACHE.

Minimal example

from planetbridging import engines

result = engines.stream("mha", "pytorch")
print(result.native_vs_loom)   # PASS
print(result.entity_path)      # path to .entity

Three-way ladder (native → loom-stream → welvet)

Welvet is Loom’s Python binding (welvet on PyPI). After streaming, reload the same .entity and compare forwards:

from planetbridging import engines

result = engines.stream("cnn1", "pytorch", try_welvet=True)
# result.native, result.loom_stream, result.welvet — all compared

Welvet reload is solid on: cnn1–cnn3, mha, layernorm, embedding, rmsnorm, swiglu (and mostly dense). Still flaky: lstm, rnn, mixer, residual.

Python API surface

Primary: engines

from planetbridging import engines

engines.stream("layernorm", "tensorflow")           # one bedrock, one planet
engines.stream_all_planets("cnn2")                  # PyTorch + TF + JAX on same layer
engines.stream_all_bedrocks("pytorch")              # all 13 types
engines.ladder("mha", "numpy")                        # numpy ref → loom → welvet
engines.available_planets("dense")                    # ('pytorch', 'tensorflow', 'jax', 'sklearn')
engines.installed_planets("dense")                    # what's importable right now

Returns EngineStreamResult: entity_path, native, loom_stream, compare labels, optional welvet arrays.

Custom dense models: absorb

For your own sequential fully-connected stack (not manifest POC models):

import torch
from planetbridging import absorb

model = torch.nn.Sequential(
    torch.nn.Linear(32, 64),
    torch.nn.ReLU(),
    torch.nn.Linear(64, 8),
)

result = absorb.pytorch(model, input_dim=32, layer_units=[64, 8], output_path="my.entity")

Also: absorb.keras(), absorb.jax(), absorb.sklearn() — dense stacks only.

Low-level: stream

from planetbridging.stream import stream_bedrock, stream_dense, stream_mha

Direct JSON envelope → loom-stream → StreamResult. Used by smoke tests and advanced callers.

Smoke / ladder (numpy reference)

from planetbridging import run_bedrock_smoke, run_bedrock_ladder

run_bedrock_smoke("layernorm")          # numpy native → loom-stream, no live torch
run_bedrock_ladder("mha", try_welvet=True)

What you can do today

What “import into Loom” actually means

You are not dropping an arbitrary TensorFlow graph into a black box. You are:

1. Expressing weights in Loom’s volumetric layer vocabulary (one of the 13 bedrock types, or a dense stack via absorb).
2. Streaming those weights through loom-stream into a native .entity checkpoint.
3. Running Loom forward and proving it matches the source planet on shared test inputs.

That .entity is the same format Lucy [7] uses for save/reload — topology + native-packed weights in one binary file.

Compare host vs PyPI package

The compare host uses HTTP (POST /api/v1/loom/stream/*). The PyPI package patches those calls to invoke loom-stream as a subprocess — same JSON contract, no server required.

Environment variables

Examples (shipped in wheel)

EXAMPLES=$(python -c "import pathlib, planetbridging as pb; print(pathlib.Path(pb.__file__).parent / 'examples')")
python "$EXAMPLES/01_hello_stream.py"
python "$EXAMPLES/05_welvet_ladder.py" cnn1 mha

Outputs land in ./.planetbridging/examples/ under your current working directory.

Roadmap — what it could do

v1.0 — Loom → other engines

Export from Loom hub formats, then route to any inference planet:

Loom .entity  →  Safetensors / ONNX / GGUF  →  ORT · llama.cpp · CoreML · …

v1.x — file-based import

Pure-Go readers in the bridge (no live Python planet):

See planetbridging/python/dense/README.md for stdlib-only feasibility notes.

v1.x → 2.0 — completeness

• More layer types (ConvTranspose, Softmax, …)
• More planets (ONNX Runtime live, Paddle, …)
• Tighter deep-stack determinism (Mixer v2 from POC → PASS)
• Documented lossy conversion paths

Repo layout (planetbridging/)

How this fits Loom

One sentence: Planet Bridging lets you build or train on the planet you already use, stream weights into Loom’s native .entity format, and prove Loom runs the same math — with a pip-installable path that needs no Go toolchain on the user machine.

Related links

• planetbridging on PyPI
• planetbridging README — release matrix, compare host quick start
• entity.md — ENTITY format spec
• flutter.md — welvet on mobile
• v080_release.md — Loom v0.80 ENTITY + Planet Bridging POC milestone