haive.core.engine.base.reference¶

Component reference implementation for the Haive engine system.

This module provides a reference mechanism that allows components to be referenced by their ID, name, or type, and resolved at runtime. This enables lazy loading, serialization of references, and dynamic resolution of components.

Classes¶

ComponentRef

Reference to a component that can be resolved at runtime.

Module Contents¶

class haive.core.engine.base.reference.ComponentRef(/, **data)[source]¶

Bases: pydantic.BaseModel, Generic[T]

Reference to a component that can be resolved at runtime.

This class provides a way to reference components (engines, tools, etc.) without directly holding the instance. References can be resolved to the actual component when needed, enabling serialization, lazy loading, and runtime configuration.

Parameters:: data (Any)

id¶

Unique identifier of the referenced component.

Type:: Optional[str]

name¶

Name of the referenced component.

Type:: Optional[str]

type¶

Type of the referenced component.

Type:: Optional[Union[str, EngineType]]

config_overrides¶

Configuration overrides to apply when resolving.

Type:: Dict[str, Any]

extensions¶

Extensions to apply to the component.

Type:: List[Dict[str, Any]]

_resolved¶

Private cache for the resolved component instance.

Type:: Optional[T]

Type Parameters:: T: The type of the component that will be resolved.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod from_engine(engine)[source]¶

Create a reference from an engine instance.

Factory method to create a component reference that points to the given engine.
Args:
engine: The engine to reference.

Returns:
ComponentRef: A new component reference pointing to the engine.

Examples:
>>> from haive.core.engine.base import Engine

from haive.core.engine.base.types import EngineType

>>> engine = Engine(name="my_engine", engine_type=EngineType.LLM)
>>> ref = ComponentRef.from_engine(engine)
>>> ref.name
'my_engine'
>>> ref.type
<EngineType.LLM: 'llm'>

Parameters:: engine (Any)
Return type:: ComponentRef

invalidate_cache()[source]¶

Clear the cached resolved component.

Forces the next call to resolve() to fetch the component fresh rather than using the cached instance.

Examples

>>> ref = ComponentRef(name="gpt-4", type=EngineType.LLM)
>>> engine1 = ref.resolve()  # Resolves and caches
>>> ref.invalidate_cache()
>>> engine2 = ref.resolve()  # Re-resolves fresh

Return type:: None

resolve()[source]¶

Resolve this reference to the actual component.

Attempts to find and return the referenced component. If the component has been previously resolved and cached, returns the cached instance.

Returns:: The resolved component instance, or None if not found.
Return type:: Optional[T]

Examples

>>> # Create a reference to an LLM engine
>>> ref = ComponentRef(name="gpt-4", type=EngineType.LLM)
>>> # Resolve the reference to get the actual engine
>>> llm_engine = ref.resolve()
>>> if llm_engine:
...     response = llm_engine.generate("Hello, world!")

model_config¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].