References

Typed memory pointer declarations. Customer code may supply a glimpse callback that produces a small JSON summary stored alongside the reference.

define_reference

define_reference(name: 'str', schema: 'Any', ttl_ms: 'int | None' = None, glimpse: 'Callable[[Any], Any] | None' = None) -> 'ReferenceSpec'

Parameter	Type	Default
name	str	required
schema	Any	required
ttl_ms	int | None	None
glimpse	Callable[[Any], Any] | None	None

Returns: ReferenceSpec

Create a validated Flow AI reference spec with optional customer glimpse code.

Args: name: Reference kind name used when creating and resolving references. schema: Schema of the referenced value: a JSON Schema mapping, a Pydantic model class, a simple type map, or any type hint Pydantic can export. ttl_ms: Optional time-to-live in milliseconds for stored values; must be non-negative when set. glimpse: Optional Python callback that derives the stored glimpse from the full value. It runs once before storing and is excluded from the Rust wire spec.

Returns: A frozen, validated ReferenceSpec.

Raises: TypeError: If the schema input cannot be normalized to JSON Schema. pydantic.ValidationError: If ttl_ms is negative.

ReferenceSpec

ReferenceSpec(*, name: str, schema: dict[str, typing.Any], ttlMs: Annotated[int | None, Ge(ge=0)] = None, glimpse: collections.abc.Callable[[typing.Any], typing.Any] | None = None) -> None

Parameter	Type	Default
name	str	required
schema	dict	required
ttlMs	typing.Annotated	None
glimpse	collections.abc.Callable[[Any], Any] | None	None

Returns: None

Named typed memory pointer declaration.

glimpse is a Python-only customer callback. It is excluded from the Rust wire spec; hosts call it before storing a reference and pass the resulting JSON glimpse to the runtime.