Value capture¶

The engine exposes value capture through kyvvu_engine.__all__. Import from kyvvu_engine, not an engine submodule:

from datetime import date

from kyvvu_engine import capture_dict, capture_step_name, compliant_task_id, to_ijson_capture

input_data = capture_dict({"when": date(2026, 1, 2)})  # {"when": "2026-01-02"}
short = to_ijson_capture("abcdef", truncate=True, max_string_length=3)  # "abc…"
name = capture_step_name("model\n")                 # "model�"
task_id = compliant_task_id("thread/42")           # stable, valid task ID

to_ijson_capture(value) converts framework-captured values into I-JSON for Behavior fields. Tuples, sets and frozensets become lists; non-string mapping keys become strings; dates, times, decimals and UUIDs become strings; non-finite floats and integers outside the I-JSON range become strings; bytes become length markers; enum values, NumPy scalars and Pydantic models are converted recursively. Forbidden Unicode code points become U+FFFD, and other objects use a truncated repr(). capture_dict(value) applies the same conversion to an input or output dictionary and preserves None.

Capture is untruncated by default, apart from fallback representations (500 characters) and a 64-level cycle guard. Pass truncate=True for decorator capture. These keyword arguments control its limits; the exported constants show the defaults:

capture_step_name(value, fallback="unnamed") repairs a framework name. compliant_task_id(raw) and compliant_action_id(raw) keep valid IDs and map invalid IDs deterministically to an x- prefix and a SHA-256 digest. The public check_task_id, check_action_id and check_step_name functions validate caller-supplied identifiers and raise ValueError on invalid values.

Capture only values obtained from a framework or decorated function. Validate caller-supplied properties and meta as I-JSON instead of coercing them: policies read those fields, so conversion could change a decision.