pin-derive for Python

Python bindings for pin-derive, a small bidirectional constraint engine: declare cells and multidirectional relations, pin any subset, and the rest derive from the same network.

The TypeScript engine in the repository root is the reference implementation. This package runs the Rust/wasm core through the wasmtime Python runtime and is held to the same conformance fixtures.

Install

Once published:

pip install pin-derive

For development from this repository:

cd rust/python
pip install -e .

Usage

from pin_derive import PinDerive

engine = PinDerive()  # loads the bundled wasm binary
snapshot = engine.solve({
    "cells": [
        {"id": "profit", "init": {"lo": 0, "hi": None}},
        {"id": "price", "init": {"lo": 0, "hi": None}},
        {"id": "margin", "init": {"lo": 0, "hi": None}},
    ],
    "relations": [
        {"type": "product", "z": "profit", "x": "price", "y": "margin"},
    ],
    "pins": [
        {"cell": "price", "value": {"lo": 50, "hi": 50}},
        {"cell": "margin", "value": {"lo": 0.2, "hi": 0.2}},
    ],
})

print(snapshot["cells"])
# profit is derived as 10; price and margin are pinned.

Pass an explicit wasm path only when testing a freshly built development artifact:

engine = PinDerive("../target/wasm32-unknown-unknown/release/pin_derive_wasm.wasm")

Bundled wasm

The wheel includes pin_derive/_pin_derive_wasm.wasm as package data. The wasm is platform-independent, so one pure-Python wheel can work across platforms while wasmtime supplies the runtime. The binary is committed into the package source and rebuilt/copied by release CI before building the wheel; this keeps pip install pin-derive from requiring a Rust toolchain.

To refresh it locally:

cd ../
cargo build --target wasm32-unknown-unknown --release
cp target/wasm32-unknown-unknown/release/pin_derive_wasm.wasm \
  python/src/pin_derive/_pin_derive_wasm.wasm

Full project

See the main repository README for the engine model, TypeScript API, Rust port, and interactive docs site: https://github.com/nightwork-dev/pin-derive.