Metadata-Version: 2.5
Name: pin-derive
Version: 0.4.1
Summary: Python bindings for the pin-derive bidirectional constraint engine
Project-URL: Repository, https://github.com/nightwork-dev/pin-derive
Project-URL: Issues, https://github.com/nightwork-dev/pin-derive/issues
Project-URL: Documentation, https://nightwork-dev.github.io/pin-derive/
Author: Nightwork
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: constraints,procedural-generation,solver,wasm,wasmtime
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: wasmtime>=27
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

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

```bash
pip install pin-derive
```

For development from this repository:

```bash
cd rust/python
pip install -e .
```

## Usage

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

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

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