Transforms#

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

Transform base classes#

MessageTransform#

class pyagentspec.transforms.MessageTransform(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v26_2_0, max_agentspec_version=AgentSpecVersionEnum.v26_2_0)#

Bases: Component

Base class for message transformation components.

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

Summarization transforms#

MessageSummarizationTransform#

class pyagentspec.transforms.MessageSummarizationTransform(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v26_2_0, max_agentspec_version=AgentSpecVersionEnum.v26_2_0, llm, max_message_size=20000, summarization_instructions='Please make a summary of this message. Include relevant information and keep it short. Your response will replace the message, so just output the summary directly, no introduction needed.', summarized_message_template='Summarized message: {{summary}}', max_cache_size=10000, max_cache_lifetime=14400, cache_collection_name='summarized_messages_cache', datastore=<factory>)#

Bases: MessageTransform

Summarizes oversized messages using an LLM and optionally caches summaries.

This is useful for long conversations where the context can become too large for the LLM to handle.

Examples

>>> from pyagentspec.transforms import MessageSummarizationTransform
>>> summarization_transform = MessageSummarizationTransform(
...     name="message-summarizer",
...     llm=llm_config,
...     max_message_size=30_000
... )
Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of the collection in the datastore for caching summarized messages.

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • llm (LlmConfig) – LLM configuration for summarization.

  • max_message_size (int) – Maximum message size in characters before triggering summarization.

  • summarization_instructions (str) –

  • summarized_message_template (str) – Template for formatting the summarized message output.

  • max_cache_size (int | None) – Maximum number of cache entries to keep.

  • max_cache_lifetime (int | None) – Maximum lifetime of cache entries in seconds.

  • cache_collection_name (str) – Name of the collection in the datastore for caching summarized messages.

  • datastore (InMemoryCollectionDatastore | OracleDatabaseDatastore | PostgresDatabaseDatastore | None) –

DEFAULT_COLLECTION_NAME: ClassVar[str] = 'summarized_messages_cache'#
cache_collection_name: str#

Name of the collection in the datastore for caching summarized messages.

datastore: InMemoryCollectionDatastore | OracleDatabaseDatastore | PostgresDatabaseDatastore | None#

Datastore on which to store the cache. By default, an in-memory datastore is created. If None, no caching will happen.

static get_entity_definition()#
Return type:

Property

llm: LlmConfig#

LLM configuration for summarization.

max_cache_lifetime: int | None#

Maximum lifetime of cache entries in seconds.

max_cache_size: int | None#

Maximum number of cache entries to keep.

max_message_size: int#

Maximum message size in characters before triggering summarization.

summarization_instructions: str#

Instructions for the LLM on how to summarize messages.

summarized_message_template: str#

Template for formatting the summarized message output.

ConversationSummarizationTransform#

class pyagentspec.transforms.ConversationSummarizationTransform(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v26_2_0, max_agentspec_version=AgentSpecVersionEnum.v26_2_0, llm, max_num_messages=50, min_num_messages=10, summarization_instructions='Please make a summary of this conversation. Include relevant information and keep it short. Your response will replace the messages, so just output the summary directly, no introduction needed.', summarized_conversation_template='Summarized conversation: {{summary}}', max_cache_size=10000, max_cache_lifetime=14400, cache_collection_name='summarized_conversations_cache', datastore=<factory>)#

Bases: MessageTransform

Summarizes conversations exceeding a given number of messages using an LLM and caches conversation summaries in a Datastore.

This is useful to reduce long conversation history into a concise context for downstream LLM calls.

Examples

>>> from pyagentspec.transforms import ConversationSummarizationTransform
>>> summarization_transform = ConversationSummarizationTransform(
...     name="conversation-summarizer",
...     llm=llm_config,
...     max_num_messages=30,
...     min_num_messages=10
... )
Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of the collection in the datastore for caching summarized conversations.

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • llm (LlmConfig) – LLM configuration for conversation summarization.

  • max_num_messages (int) – Maximum number of messages before triggering summarization. When the conversation exceeds this number of messages, the older messages will be summarized, except the most recent min_num_messages ones who are kept unsummarized.

  • min_num_messages (int) – Minimum number of recent messages to keep unsummarized. For example, if min_num_messages is 10 and max_num_messages is 50, then with a conversation of 20 messages, the conversation will not be summarized, but if the conversation has 51 messages, the last 10 won’t be summarized, the 41 others will (in one or more summarization messages).

  • summarization_instructions (str) –

  • summarized_conversation_template (str) – Template for formatting the summarized conversation output.

  • max_cache_size (int | None) – Maximum number of cache entries to keep.

  • max_cache_lifetime (int | None) – Maximum lifetime of cache entries in seconds.

  • cache_collection_name (str) – Name of the collection in the datastore for caching summarized conversations.

  • datastore (InMemoryCollectionDatastore | OracleDatabaseDatastore | PostgresDatabaseDatastore | None) –

DEFAULT_COLLECTION_NAME: ClassVar[str] = 'summarized_conversations_cache'#
cache_collection_name: str#

Name of the collection in the datastore for caching summarized conversations.

datastore: InMemoryCollectionDatastore | OracleDatabaseDatastore | PostgresDatabaseDatastore | None#

Datastore on which to store the cache. By default, an in-memory datastore is created. If None, no caching will happen.

static get_entity_definition()#
Return type:

Property

llm: LlmConfig#

LLM configuration for conversation summarization.

max_cache_lifetime: int | None#

Maximum lifetime of cache entries in seconds.

max_cache_size: int | None#

Maximum number of cache entries to keep.

max_num_messages: int#

Maximum number of messages before triggering summarization.

When the conversation exceeds this number of messages, the older messages will be summarized, except the most recent min_num_messages ones who are kept unsummarized.

min_num_messages: int#

Minimum number of recent messages to keep unsummarized.

For example, if min_num_messages is 10 and max_num_messages is 50, then with a conversation of 20 messages, the conversation will not be summarized, but if the conversation has 51 messages, the last 10 won’t be summarized, the 41 others will (in one or more summarization messages).

summarization_instructions: str#

Instructions for the LLM on how to summarize conversations.

summarized_conversation_template: str#

Template for formatting the summarized conversation output.