kinogaki 0.2.0

Python bindings for Prism — a structured file format your tools and agents can edit.

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.

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:

pip install kinogaki

Building from source

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

./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. "Kinogaki" is a trademark of Kinogaki LLC; see TRADEMARKS.md. Contributions are accepted under the Developer Certificate of Origin; see CONTRIBUTING.md.