Metadata-Version: 2.4
Name: kinogaki
Version: 0.2.0
Summary: Python bindings for Prism — a structured file format your tools and agents can edit.
Author-email: Dy Mokomi <dy@dymokomi.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://core.kinogaki.com
Project-URL: Documentation, https://core.kinogaki.com
Keywords: prism,kinogaki,file-format,scene,document
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# kinogaki — Python bindings for Prism

`kinogaki` is the Python binding for **Prism**, a structured file format your tools and agents can
edit. It is a thin, native layer over KinogakiCore (the C++ library) through its C ABI — the model
mirrors the C++ API one-to-one.

```python
import kinogaki as kg

doc = kg.Document()
doc.append("/world", "group")
doc.append("/world/red", "material").set("out", (0.9, 0.15, 0.15))
doc.append("/world/ball", "object") \
   .set("radius", 1.5) \
   .set("albedo", (1, 1, 1))
doc.connect("/world/red.out", "/world/ball.albedo")   # source output drives target input

text = kg.serialize(doc)                 # the .prisma (ASCII) bytes
again = kg.deserialize(text)             # parse text or binary back
print(kg.evaluate(again, "/world/ball.albedo"))   # (0.9, 0.15, 0.15) — through the connection
```

## The API at a glance

- **`kg.Document()`** — an ordered tree of typed prims plus the connections between their slots.
- **`doc.append(path, type) -> Handle`** — add a prim (its parent must exist); returns a chainable cursor.
- **`Handle.set(key, value)`** — author a typed property. The Prism type is inferred from the native
  value: `bool`/`int`/`float`/`str`, or a 2/3/6/32-length number sequence → float2/float3/matrix/spectrum.
- **`Handle.set_meta(key, value)`** — string metadata (non-animatable, separate from properties).
- **`doc.edit(path) -> Handle`** — a cursor for reading: `get_float`, `get_int`, `get_bool`,
  `get_float2/3`, `get_str`, `get_meta` (permissive, with defaults) and `require_float`,
  `require_float3`, `require_str` (strict — raise `PrismError`).
- **`doc.connect(source, target)`** — wire an output slot to an input slot (one source per target).
- **`doc.remove(path)` · `doc.rename(from, to)` · `doc.has(path)` · `doc.prim(path)` · `doc.prims()`**.
- **`kg.serialize(doc, binary=False)` · `kg.deserialize(data)` · `kg.evaluate(doc, slot, time=0)`**.

Values are native both ways — no wrapper objects.

## Installing

The package ships a universal (`arm64` + `x86_64`) native library, so there is nothing to compile:

```sh
pip install kinogaki
```

## Building from source

Clone `kinogaki/kinogaki-core` as a sibling of this repo, then:

```sh
./build.sh                 # compiles KinogakiCore → kinogaki/_native/libkinogaki_core.dylib
python -m pip install -e . # editable install
python tests/test_kinogaki.py
```

`KINOGAKI_CORE_LIB` overrides which native library is loaded, if you keep it elsewhere.

## License

The Prism file format is open and free to implement. The code in this repository
is licensed under the Apache License 2.0; see [LICENSE](LICENSE). "Kinogaki" is a
trademark of Kinogaki LLC; see [TRADEMARKS.md](TRADEMARKS.md). Contributions are
accepted under the Developer Certificate of Origin; see
[CONTRIBUTING.md](CONTRIBUTING.md).
