> For the complete documentation index, see [llms.txt](/llms.txt). Every page on this site is also available as markdown at `<path>.md`.

# References

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

<span id="flowai_harness.references.define_reference"></span>

## `define_reference`

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

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>schema</code></td>
<td><code>Any</code></td>
<td>required</td>
</tr>
<tr>
<td><code>ttl_ms</code></td>
<td><code>int | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>glimpse</code></td>
<td><code>Callable[[Any], Any] | None</code></td>
<td><code>None</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>ReferenceSpec</code></p>

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.

<span id="flowai_harness.references.ReferenceSpec"></span>

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

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>schema</code></td>
<td><code>dict</code></td>
<td>required</td>
</tr>
<tr>
<td><code>ttlMs</code></td>
<td><code>typing.Annotated</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>glimpse</code></td>
<td><code>collections.abc.Callable[[Any], Any] | None</code></td>
<td><code>None</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>None</code></p>

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.