Serialization / Deserialization#

This page presents all APIs and classes related to serialization and deserialization in PyAgentSpec.

Serialization#

class pyagentspec.serialization.serializer.AgentSpecSerializer(plugins=None)#

Bases: object

Provides methods to serialize Agent Spec Components.

Parameters:: plugins (List[ComponentSerializationPlugin] | None) –

to_dict(component: Component) → Dict[str, Any]#

to_dict(component: Component, agentspec_version: AgentSpecVersionEnum | None) → Dict[str, Any]

to_dict(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None) → Dict[str, Any]

to_dict(component: Component, *, export_disaggregated_components: Literal[False]) → Dict[str, Any]

to_dict(component: Component, *, export_disaggregated_components: bool) → Dict[str, Any]

to_dict(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: Literal[False]) → Dict[str, Any]

to_dict(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]], export_disaggregated_components: Literal[True]) → Tuple[Dict[str, Any], Dict[str, Any]]

to_dict(component: Component, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: bool) → Dict[str, Any] | Tuple[Dict[str, Any], Dict[str, Any]]

Serialize a component and its sub-components to a dictionary.

Parameters:

component – The component to serialize.
agentspec_version – The Agent Spec version of the component.
disaggregated_components –
Configuration specifying the components/fields to disaggregate upon serialization. Each item can be:
- A Component: to disaggregate the component using its id
- A tuple (Component, str): to disaggregate the component using a custom id.
Note

Components in disaggregated_components are disaggregated even if export_disaggregated_components is False.
export_disaggregated_components – Whether to export the disaggregated components or not. Defaults to False.

Returns:

If export_disaggregated_components is True
ComponentAsDictT – A dictionary containing the serialization of the root component.
DisaggregatedComponentsAsDictT – A dictionary containing the serialization of the disaggregated components.
If export_disaggregated_components is False
ComponentAsDictT – A dictionary containing the serialization of the root component.

Examples

Basic serialization is done as follows.

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import VllmConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> llm = VllmConfig(
...     name="vllm",
...     model_id="model1",
...     url="http://dev.llm.url"
... )
>>> agent = Agent(
...     name="Simple Agent",
...     llm_config=llm,
...     system_prompt="Be helpful"
... )
>>> agent_config = AgentSpecSerializer().to_dict(agent)

To use component disaggregation, specify the component(s) to disaggregate in the disaggregated_components parameter, and ensure that export_disaggregated_components is set to True.

>>> llm = VllmConfig(
...     id="llm_id",
...     name="vllm",
...     model_id="model1",
...     url="http://dev.llm.url"
... )
>>> agent = Agent(name="Simple Agent", llm_config=llm, system_prompt="Be helpful")
>>> agent_config, disag_config = AgentSpecSerializer().to_dict(
...     component=agent,
...     disaggregated_components=[llm],
...     export_disaggregated_components=True,
... )
>>> list(disag_config["$referenced_components"].keys())
['llm_id']

Finally, you can specify custom ids for the disaggregated components.

>>> agent_config, disag_config = AgentSpecSerializer().to_dict(
...     component=agent,
...     disaggregated_components=[(llm, "custom_llm_id")],
...     export_disaggregated_components=True,
... )
>>> list(disag_config["$referenced_components"].keys())
['custom_llm_id']

to_json(component: Component) → str#

to_json(component: Component, agentspec_version: AgentSpecVersionEnum | None) → str

to_json(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None) → str

to_json(component: Component, *, export_disaggregated_components: Literal[False]) → str

to_json(component: Component, *, export_disaggregated_components: bool) → str | Tuple[str, str]

to_json(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: Literal[False]) → str

Serialize a component and its sub-components to JSON.

Parameters:

component – The component to serialize.
agentspec_version – The Agent Spec version of the component.
disaggregated_components –
Configuration specifying the components/fields to disaggregate upon serialization. Each item can be:
- A Component: to disaggregate the component using its id
- A tuple (Component, str): to disaggregate the component using a custom id.
Note

Components in disaggregated_components are disaggregated even if export_disaggregated_components is False.
export_disaggregated_components – Whether to export the disaggregated components or not. Defaults to False.
indent – The number of spaces to use for the JSON indentation.

Returns:

If export_disaggregated_components is True
str – The JSON serialization of the root component.
str – The JSON serialization of the disaggregated components.
If export_disaggregated_components is False
str – The JSON serialization of the root component.

Examples

See examples in the .to_dict method docstring.

to_yaml(component: Component) → str#

to_yaml(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None) → str

to_yaml(component: Component, *, export_disaggregated_components: Literal[False]) → str

to_yaml(component: Component, *, export_disaggregated_components: bool) → str | Tuple[str, str]

to_yaml(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: Literal[False]) → str

to_yaml(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]], export_disaggregated_components: Literal[True]) → Tuple[str, str]

Serialize a component and its sub-components to YAML.

Parameters:

component – The component to serialize.
agentspec_version – The Agent Spec version of the component
disaggregated_components –
Configuration specifying the components/fields to disaggregate upon serialization. Each item can be:
- A Component: to disaggregate the component using its id
- A tuple (Component, str): to disaggregate the component using a custom id.
Note

Components in disaggregated_components are disaggregated even if export_disaggregated_components is False.
export_disaggregated_components – Whether to export the disaggregated components or not. Defaults to False.

Returns:

If export_disaggregated_components is True
str – The YAML serialization of the root component.
str – The YAML serialization of the disaggregated components.
If export_disaggregated_components is False
str – The YAML serialization of the root component.

Examples

See examples in the .to_dict method docstring.

Deserialization#

class pyagentspec.serialization.deserializer.AgentSpecDeserializer(plugins=None)#

Bases: object

Provides methods to deserialize Agent Spec Components.

Parameters:: plugins (List[ComponentDeserializationPlugin] | None) –

from_dict(dict_content: Dict[str, Any]) → Component#

from_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Tuple[Component, str]] | None) → Component

from_dict(dict_content: Dict[str, Any], *, import_only_referenced_components: Literal[False]) → Component

from_dict(dict_content: Dict[str, Any], *, import_only_referenced_components: Literal[True]) → Dict[str, Component]

from_dict(dict_content: Dict[str, Any], *, import_only_referenced_components: bool) → Component | Dict[str, Component]

from_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Tuple[Component, str]] | None, import_only_referenced_components: Literal[False]) → Component

from_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Tuple[Component, str]] | None, import_only_referenced_components: Literal[True]) → Dict[str, Component]

from_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Tuple[Component, str]] | None, import_only_referenced_components: bool) → Component | Dict[str, Component]

Load a component and its sub-components from dictionary.

Parameters:

dict_content – The loaded serialized component representation as a dictionary.
components_registry – A dictionary of loaded components to use when deserializing the main component.
import_only_referenced_components – When True, loads the referenced/disaggregated components into a dictionary to be used as the components_registry when deserializing the main component. Otherwise, loads the main component. Defaults to False

Returns:

If import_only_referenced_components is False
Component – The deserialized component.
If import_only_referenced_components is False
Dict[str, Component] – A dictionary containing the loaded referenced components.

Examples

Basic deserialization is done as follows. First, serialize a component (here an Agent).

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import VllmConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> llm = VllmConfig(
...     name="vllm",
...     model_id="model1",
...     url="http://dev.llm.url"
... )
>>> agent = Agent(
...     name="Simple Agent",
...     llm_config=llm,
...     system_prompt="Be helpful"
... )
>>> agent_config = AgentSpecSerializer().to_dict(agent)

Then deserialize using the AgentSpecDeserializer.

>>> from pyagentspec.serialization import AgentSpecDeserializer
>>> deser_agent = AgentSpecDeserializer().from_dict(agent_config)

When using disaggregated components, the deserialization must be done in several phases, as follows.

>>> agent_config, disag_config = AgentSpecSerializer().to_dict(
...     component=agent,
...     disaggregated_components=[(llm, "custom_llm_id")],
...     export_disaggregated_components=True,
... )
>>> disag_components = AgentSpecDeserializer().from_dict(
...     disag_config,
...     import_only_referenced_components=True
... )
>>> deser_agent = AgentSpecDeserializer().from_dict(
...     agent_config,
...     components_registry=disag_components
... )

from_json(json_content: str) → Component#

from_json(json_content: str, components_registry: Mapping[str, Component | Tuple[Component, str]] | None) → Component

from_json(json_content: str, *, import_only_referenced_components: Literal[False]) → Component

from_json(json_content: str, *, import_only_referenced_components: Literal[True]) → Dict[str, Component]

from_json(json_content: str, *, import_only_referenced_components: bool) → Component | Dict[str, Component]

from_json(json_content: str, components_registry: Mapping[str, Component | Tuple[Component, str]] | None, import_only_referenced_components: Literal[False]) → Component

from_json(json_content: str, components_registry: Mapping[str, Component | Tuple[Component, str]] | None, import_only_referenced_components: Literal[True]) → Dict[str, Component]

from_json(json_content: str, components_registry: Mapping[str, Component | Tuple[Component, str]] | None, import_only_referenced_components: bool) → Component | Dict[str, Component]

Load a component and its sub-components from JSON.

Parameters:

json_content – The JSON content to use to deserialize the component.
components_registry – A dictionary of loaded components to use when deserializing the main component.
import_only_referenced_components – When True, loads the referenced/disaggregated components into a dictionary to be used as the components_registry when deserializing the main component. Otherwise, loads the main component. Defaults to False

Returns:

If import_only_referenced_components is False
Component – The deserialized component.
If import_only_referenced_components is False
Dict[str, Component] – A dictionary containing the loaded referenced components.

Examples

See examples in the .from_dict method docstring.

from_yaml(yaml_content: str) → Component#

from_yaml(yaml_content: str, components_registry: Mapping[str, Component | Tuple[Component, str]] | None) → Component

from_yaml(yaml_content: str, *, import_only_referenced_components: Literal[False]) → Component

from_yaml(yaml_content: str, *, import_only_referenced_components: Literal[True]) → Dict[str, Component]

from_yaml(yaml_content: str, *, import_only_referenced_components: bool) → Component | Dict[str, Component]

from_yaml(yaml_content: str, components_registry: Mapping[str, Component | Tuple[Component, str]] | None, import_only_referenced_components: Literal[False]) → Component

from_yaml(yaml_content: str, components_registry: Mapping[str, Component | Tuple[Component, str]] | None, import_only_referenced_components: Literal[True]) → Dict[str, Component]

from_yaml(yaml_content: str, components_registry: Mapping[str, Component | Tuple[Component, str]] | None, import_only_referenced_components: bool) → Component | Dict[str, Component]

Load a component and its sub-components from YAML.

Parameters:

yaml_content – The YAML content to use to deserialize the component.
components_registry – A dictionary of loaded components to use when deserializing the main component.
import_only_referenced_components – When True, loads the referenced/disaggregated components into a dictionary to be used as the components_registry when deserializing the main component. Otherwise, loads the main component. Defaults to False

Returns:

If import_only_referenced_components is False
Component – The deserialized component.
If import_only_referenced_components is False
Dict[str, Component] – A dictionary containing the loaded referenced components.

Examples

See examples in the .from_dict method docstring.

Serialization plugins#

class pyagentspec.serialization.serializationcontext.SerializationContext#

Bases: object

Interface for the serialization of Components.

abstract dump_field(value: bool, info: FieldInfoTypeT | None) → bool#
abstract dump_field(value: int, info: FieldInfoTypeT | None) → int
abstract dump_field(value: float, info: FieldInfoTypeT | None) → float
abstract dump_field(value: str, info: FieldInfoTypeT | None) → str
abstract dump_field(value: List[T], info: FieldInfoTypeT | None) → List[Any]
abstract dump_field(value: Dict[str, T], info: FieldInfoTypeT | None) → Dict[str, Any]
abstract dump_field(value: BaseModel, info: FieldInfoTypeT | None) → Dict[str, Any]: Dump a component field based on its value and optional info.

class pyagentspec.serialization.serializationplugin.ComponentSerializationPlugin#

Bases: ABC

Base class for Component serialization plugins.

abstract property plugin_name: str#: Return the plugin name.

abstract property plugin_version: str#: Return the plugin version.

abstract serialize(component, serialization_context)#

Serialize a component that the plugin should support.

Parameters:

component (Component) –
serialization_context (SerializationContext) –

Return type:

Dict[str, Any]

abstract supported_component_types()#

Indicate what component types the plugin supports.

Return type:: List[str]

class pyagentspec.serialization.pydanticserializationplugin.PydanticComponentSerializationPlugin(component_types_and_models)#

Bases: ComponentSerializationPlugin

Serialization plugin for Pydantic Components.

Parameters:: component_types_and_models (Mapping[str, Type[BaseModel]]) –

property plugin_name: str#: Return the plugin name.

property plugin_version: str#: Return the plugin version.

serialize(component, serialization_context)#

Serialize a Pydantic component.

Parameters:

component (Component) –
serialization_context (SerializationContext) –

Return type:

Dict[str, Any]

supported_component_types()#

Indicate what component types the plugin supports.

Return type:: List[str]

Deserialization plugins#

class pyagentspec.serialization.deserializationcontext.DeserializationContext#

Bases: ABC

Interface for the deserialization of Components.

abstract get_component_type(content)#

Get the type of a component from the dedicated special field.

Parameters:: content (Dict[str, Any]) –
Return type:: str

abstract load_field(content, annotation)#

Load a field based on its serialized field content and annotated type.

Parameters:

content (Dict[str, Any]) –
annotation (type | None) –

Return type:

Any

class pyagentspec.serialization.deserializationplugin.ComponentDeserializationPlugin#

Bases: ABC

Base class for Component deserialization plugins.

abstract deserialize(serialized_component, deserialization_context)#

Deserialize a serialized component that the plugin should support.

Parameters:

serialized_component (Dict[str, Any]) –
deserialization_context (DeserializationContext) –

Return type:

Component

abstract property plugin_name: str#: Return the plugin name.

abstract property plugin_version: str#: Return the plugin version.

abstract supported_component_types()#

Indicate what component types the plugin supports.

Return type:: List[str]

class pyagentspec.serialization.pydanticdeserializationplugin.PydanticComponentDeserializationPlugin(component_types_and_models)#

Bases: ComponentDeserializationPlugin

Deserialization plugin for Pydantic Components.

Parameters:: component_types_and_models (Mapping[str, Type[BaseModel]]) –

deserialize(serialized_component, deserialization_context)#

Deserialize a serialized Pydantic model.

Parameters:

serialized_component (Dict[str, Any]) –
deserialization_context (DeserializationContext) –

Return type:

Component

property plugin_name: str#: Return the plugin name.

property plugin_version: str#: Return the plugin version.

supported_component_types()#

Indicate what component types the plugin supports.

Return type:: List[str]