haive.core.schema.field_definition¶

FieldDefinition for the Haive Schema System.

This module provides the FieldDefinition class, which represents a complete field definition including type, default value, metadata, and additional properties required for the Haive Schema System. FieldDefinition serves as the fundamental building block for dynamic schema composition and manipulation.

A FieldDefinition encapsulates all information needed to create a field in a Pydantic model, with additional Haive-specific metadata such as: - Whether the field is shared between parent and child graphs - Reducer functions for combining field values during state updates - Input/output relationships with specific engines - Association with structured output models - Source component identification

FieldDefinition objects are used extensively by SchemaComposer and StateSchemaManager when building dynamic schemas at runtime, providing a complete representation of each field’s characteristics and relationships.

Examples

from haive.core.schema import FieldDefinition from typing import List import operator

# Create a field definition for a context field field_def = FieldDefinition(

name=”context”, field_type=List[str], default_factory=list, description=”Retrieved document contexts”, shared=True, reducer=operator.add, # Concatenate lists when combining values input_for=[“llm_engine”], # This field is input for the LLM engine output_from=[“retriever_engine”] # This field is output from the retriever

)

# Get field info for model creation field_type, field_info = field_def.to_field_info()

# Get annotated field with embedded metadata field_type, field_info = field_def.to_annotated_field()

Classes¶

FieldDefinition

Complete field definition with metadata for the Haive Schema System.

Module Contents¶

class haive.core.schema.field_definition.FieldDefinition(name, field_type=None, *, type_hint=None, field_info=None, default=None, default_factory=None, description=None, shared=False, reducer=None, source=None, input_for=None, output_from=None, structured_model=None, **kwargs)[source]¶

Complete field definition with metadata for the Haive Schema System.

The FieldDefinition class encapsulates all information about a field, including its type, default value, description, and relationships to engines, making it the core building block for dynamic schema composition and manipulation.

This class provides methods to convert between different field representations (standard fields, annotated fields, dictionaries) and helps manage field metadata that extends beyond what Pydantic directly supports.

Parameters:
name¶

Field name used in the schema

Type:

str

field_type¶

Python type annotation for the field

Type:

Type[Any]

field_info¶

Optional existing Pydantic FieldInfo object

Type:

Any

default¶

Default value for the field

Type:

Any

default_factory¶

Factory function for default value

Type:

Optional[Callable[[], Any]]

description¶

Human-readable description of the field

Type:

Optional[str]

shared¶

Whether this field is shared with parent graphs

Type:

bool

reducer¶

Function to combine values during state updates

Type:

Optional[Callable]

source¶

Component that provided this field

Type:

Optional[str]

input_for¶

Engines that use this field as input

Type:

List[str]

output_from¶

Engines that produce this field as output

Type:

List[str]

structured_model¶

Name of structured model this field belongs to

Type:

Optional[str]

metadata¶

Additional metadata properties

Type:

Dict[str, Any]

Field metadata plays a crucial role in the Haive Schema System, enabling features like: - Field sharing for parent-child graph communication - Automatic state updates using reducer functions - Input/output tracking for engine integration - Structured output model association

Initialize a field definition with comprehensive metadata.

Accepts either field_type (preferred) or the legacy keyword type_hint used by some parts of the code-base. If field_type is omitted but type_hint is provided we use that value to maintain backwards compatibility.

classmethod extract_from_model_field(name, field_type, field_info, include_annotations=True)[source]¶

Extract a FieldDefinition from an existing Pydantic model field.

This class method creates a FieldDefinition by extracting information from an existing Pydantic model field. It preserves all field properties including default values, default factories, and descriptions. If include_annotations is True, it also extracts metadata from type annotations.

Parameters:

  • name (str) – Field name to use in the new FieldDefinition

  • field_type (Type[Any]) – Type annotation from the model field

  • field_info (Any) – Pydantic FieldInfo object containing field metadata

  • include_annotations (bool, optional) – Whether to extract metadata from Annotated types. When True, metadata from Annotated[Type, …] will be included in the field definition. Defaults to True.

Returns:

A new FieldDefinition instance containing all the

extracted information from the model field.

Return type:

FieldDefinition

Examples

# Extract field from an existing model from pydantic import BaseModel, Field

class MyModel(BaseModel):
items: List[str] = Field(

default_factory=list, description=”List of items”

)

# Get model field info field_name = “items” field_type = MyModel.model_fields[field_name].annotation field_info = MyModel.model_fields[field_name]

# Extract field definition field_def = FieldDefinition.extract_from_model_field(

field_name, field_type, field_info

)

get_reducer_name()[source]¶

Get the reducer function name for serialization purposes.

This method attempts to extract a meaningful, serializable string representation of the field’s reducer function. It tries several approaches, in order: 1. Use the function’s __name__ attribute 2. Use the function’s __qualname__ attribute (includes class name for methods) 3. Fall back to string representation

For functions with a __module__ attribute, the module path is included to enable proper importing and resolution during deserialization.

Returns:

String representation of the reducer function that can

be used for serialization, or None if no reducer is defined.

Return type:

Optional[str]

Examples

import operator

field_def = FieldDefinition(

name=”count”, field_type=int, default=0, reducer=operator.add

)

reducer_name = field_def.get_reducer_name() # Returns: “operator.add”

to_annotated_field()[source]¶

Convert to an annotated field type and info pair for model creation.

This method generates a field type and info pair using Python’s Annotated type, which embeds metadata directly in the type annotation. This approach allows the field to carry additional Haive-specific metadata like shared status, reducer functions, and engine I/O relationships.

Annotated fields preserve their metadata when schemas are composed or manipulated, making them ideal for complex schema operations.

Returns:

A tuple containing:

  • annotated_field_type: Python type wrapped in Annotated with metadata

  • field_info: Pydantic FieldInfo object with standard field properties

Return type:

Tuple[Type[Any], Any]

Examples

from pydantic import create_model

# Create a field definition with reducer field_def = FieldDefinition(

name=”items”, field_type=List[str], default_factory=list, description=”Collection of items”, reducer=operator.add # Will be embedded in the annotation

)

# Get annotated field field_type, field_info = field_def.to_annotated_field()

# Use in model creation - metadata persists in the type annotation MyModel = create_model(

“MyModel”, items=(field_type, field_info), __module__=__name__

)

to_dict()[source]¶

Convert the field definition to a serializable dictionary.

This method creates a complete dictionary representation of the field definition, suitable for serialization or debugging. The dictionary includes all field properties including type, default values, description, and all metadata.

Special handling is applied to: - The field_type, which is converted to a string representation - The default_factory, which is converted to a string if present - The reducer function, which is converted to a string name via get_reducer_name()

Returns:

Dictionary representation of the field definition with

all properties and metadata.

Return type:

Dict[str, Any]

Examples

field_def = FieldDefinition(

name=”items”, field_type=List[str], default_factory=list, description=”Collection of items”, shared=True, reducer=operator.add

)

data = field_def.to_dict() # Returns a dictionary with all field properties # { # “name”: “items”, # “field_type”: “typing.List[str]”, # “default”: None, # “default_factory”: “<built-in function list>”, # “description”: “Collection of items”, # “shared”: True, # “reducer”: “operator.add”, # “source”: None, # “input_for”: [], # “output_from”: [], # “structured_model”: None # }

to_field_info()[source]¶

Convert to a field type and info pair for standard model creation.

This method generates the necessary type and field_info objects needed to create a field in a Pydantic model. It produces a standard field (not using Python’s Annotated type) that can be used in model creation.

Returns:

A tuple containing:

  • field_type: The Python type annotation for the field

  • field_info: The Pydantic FieldInfo object with field metadata

Return type:

Tuple[Type[Any], Any]

Examples

from pydantic import create_model

# Create a field definition field_def = FieldDefinition(

name=”count”, field_type=int, default=0, description=”Counter value”

)

# Get field info for model creation field_type, field_info = field_def.to_field_info()

# Use in model creation MyModel = create_model(

“MyModel”, count=(field_type, field_info), __module__=__name__

)