# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. from __future__ import annotations from typing import Union, Optional from datetime import datetime from typing_extensions import Literal import httpx from ...types import ( conversation_fork_params, conversation_list_params, conversation_cancel_params, conversation_create_params, conversation_update_params, conversation_recompile_params, ) from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given from ..._utils import path_template, maybe_transform, async_maybe_transform from .messages import ( MessagesResource, AsyncMessagesResource, MessagesResourceWithRawResponse, AsyncMessagesResourceWithRawResponse, MessagesResourceWithStreamingResponse, AsyncMessagesResourceWithStreamingResponse, ) from ..._compat import cached_property from ..._resource import SyncAPIResource, AsyncAPIResource from ..._response import ( to_raw_response_wrapper, to_streamed_response_wrapper, async_to_raw_response_wrapper, async_to_streamed_response_wrapper, ) from ..._base_client import make_request_options from ...types.conversation import Conversation from ...types.conversation_list_response import ConversationListResponse from ...types.conversation_cancel_response import ConversationCancelResponse __all__ = ["ConversationsResource", "AsyncConversationsResource"] class ConversationsResource(SyncAPIResource): @cached_property def messages(self) -> MessagesResource: return MessagesResource(self._client) @cached_property def with_raw_response(self) -> ConversationsResourceWithRawResponse: """ This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content. For more information, see https://www.github.com/letta-ai/letta-python#accessing-raw-response-data-eg-headers """ return ConversationsResourceWithRawResponse(self) @cached_property def with_streaming_response(self) -> ConversationsResourceWithStreamingResponse: """ An alternative to `.with_raw_response` that doesn't eagerly read the response body. For more information, see https://www.github.com/letta-ai/letta-python#with_streaming_response """ return ConversationsResourceWithStreamingResponse(self) def create( self, *, agent_id: str, context_window_limit: Optional[int] | Omit = omit, description: Optional[str] | Omit = omit, hidden: bool | Omit = omit, model: Optional[str] | Omit = omit, model_settings: Optional[conversation_create_params.ModelSettings] | Omit = omit, summary: Optional[str] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> Conversation: """ Create a new conversation for an agent. Args: agent_id: The agent ID to create a conversation for context_window_limit: The context window limit for this conversation (overrides agent's context window). description: A generated description of the conversation used for search and bootstrap context. hidden: Whether the new conversation should be hidden from listings. model: The model handle for this conversation (overrides agent's model). Format: provider/model-name. model_settings: The model settings for this conversation (overrides agent's model settings). summary: A summary of the conversation. extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ return self._post( "/v1/conversations/", body=maybe_transform( { "context_window_limit": context_window_limit, "description": description, "hidden": hidden, "model": model, "model_settings": model_settings, "summary": summary, }, conversation_create_params.ConversationCreateParams, ), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=maybe_transform({"agent_id": agent_id}, conversation_create_params.ConversationCreateParams), ), cast_to=Conversation, ) def retrieve( self, conversation_id: str, *, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> Conversation: """ Retrieve a specific conversation. Args: conversation_id: The ID of the conv in the format 'conv-' extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return self._get( path_template("/v1/conversations/{conversation_id}", conversation_id=conversation_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=Conversation, ) def update( self, conversation_id: str, *, archived: Optional[bool] | Omit = omit, context_window_limit: Optional[int] | Omit = omit, description: Optional[str] | Omit = omit, last_message_at: Union[str, datetime, None] | Omit = omit, model: Optional[str] | Omit = omit, model_settings: Optional[conversation_update_params.ModelSettings] | Omit = omit, summary: Optional[str] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> Conversation: """ Update a conversation. Args: conversation_id: The ID of the conv in the format 'conv-' archived: Whether the conversation is archived. context_window_limit: The context window limit for this conversation (overrides agent's context window). description: A generated description of the conversation used for search and bootstrap context. last_message_at: Timestamp of the most recent message request sent to this conversation. model: The model handle for this conversation (overrides agent's model). Format: provider/model-name. model_settings: The model settings for this conversation (overrides agent's model settings). summary: A summary of the conversation. extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return self._patch( path_template("/v1/conversations/{conversation_id}", conversation_id=conversation_id), body=maybe_transform( { "archived": archived, "context_window_limit": context_window_limit, "description": description, "last_message_at": last_message_at, "model": model, "model_settings": model_settings, "summary": summary, }, conversation_update_params.ConversationUpdateParams, ), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=Conversation, ) def list( self, *, after: Optional[str] | Omit = omit, agent_id: Optional[str] | Omit = omit, archive_status: Literal["unarchived", "archived", "all"] | Omit = omit, limit: int | Omit = omit, order: Literal["asc", "desc"] | Omit = omit, order_by: Literal["created_at", "last_run_completion", "last_message_at"] | Omit = omit, summary_search: Optional[str] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> ConversationListResponse: """ List all conversations for an agent (or all conversations if agent_id not provided). Args: after: Cursor for pagination (conv ID). Returns results relative to this ID in the specified sort order. Expected format: 'conv-' agent_id: The agent ID to list conversations for (optional - returns all conversations if not provided) archive_status: Whether to return unarchived conversations only, archived conversations only, or all conversations limit: Maximum number of conversations to return order: Sort order for conversations. 'asc' for oldest first, 'desc' for newest first order_by: Field to sort by summary_search: Search for text within conversation summaries extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ return self._get( "/v1/conversations/", options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=maybe_transform( { "after": after, "agent_id": agent_id, "archive_status": archive_status, "limit": limit, "order": order, "order_by": order_by, "summary_search": summary_search, }, conversation_list_params.ConversationListParams, ), ), cast_to=ConversationListResponse, ) def delete( self, conversation_id: str, *, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> object: """ Delete a conversation. The conversation will no longer appear in list operations. Args: conversation_id: The ID of the conv in the format 'conv-' extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return self._delete( path_template("/v1/conversations/{conversation_id}", conversation_id=conversation_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=object, ) def cancel( self, conversation_id: str, *, agent_id: Optional[str] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> ConversationCancelResponse: """ Cancel runs associated with a conversation. Note: To cancel active runs, Redis is required. **Agent-direct mode**: Pass conversation_id="default" with agent_id query parameter to cancel runs for the agent's default conversation. **Deprecated**: Passing an agent ID as conversation_id still works but will be removed. Args: conversation_id: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). agent_id: Agent ID for agent-direct mode with 'default' conversation extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return self._post( path_template("/v1/conversations/{conversation_id}/cancel", conversation_id=conversation_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=maybe_transform({"agent_id": agent_id}, conversation_cancel_params.ConversationCancelParams), ), cast_to=ConversationCancelResponse, ) def fork( self, conversation_id: str, *, agent_id: Optional[str] | Omit = omit, hidden: bool | Omit = omit, message_id: Optional[str] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> Conversation: """ Fork an existing conversation. Creates a new conversation that shares the same in-context messages as the source conversation, but with a newly compiled system message reflecting the latest memory block values. The forked conversation belongs to the same agent as the source. If message_id is provided, only source in-context messages up to and including that message are included in the fork. **Agent-direct mode**: Pass conversation_id="default" with agent_id query parameter to fork the agent's default (agent-direct) message history into a new conversation. **Deprecated**: Passing an agent ID as conversation_id still works but will be removed. Args: conversation_id: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). agent_id: Agent ID for agent-direct mode with 'default' conversation hidden: Whether the forked conversation should be hidden from listings message_id: The ID of the message in the format 'message-' extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return self._post( path_template("/v1/conversations/{conversation_id}/fork", conversation_id=conversation_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=maybe_transform( { "agent_id": agent_id, "hidden": hidden, "message_id": message_id, }, conversation_fork_params.ConversationForkParams, ), ), cast_to=Conversation, ) def recompile( self, conversation_id: str, *, dry_run: bool | Omit = omit, agent_id: Optional[str] | Omit = omit, compaction_settings: Optional[conversation_recompile_params.CompactionSettings] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> str: """ Manually trigger system prompt recompilation for a conversation. Args: conversation_id: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). dry_run: If True, do not persist changes; still returns the compiled system prompt. agent_id: Agent ID for agent-direct mode with 'default' conversation. Use with conversation_id='default' in the URL path. compaction_settings: Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return self._post( path_template("/v1/conversations/{conversation_id}/recompile", conversation_id=conversation_id), body=maybe_transform( { "agent_id": agent_id, "compaction_settings": compaction_settings, }, conversation_recompile_params.ConversationRecompileParams, ), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=maybe_transform({"dry_run": dry_run}, conversation_recompile_params.ConversationRecompileParams), ), cast_to=str, ) class AsyncConversationsResource(AsyncAPIResource): @cached_property def messages(self) -> AsyncMessagesResource: return AsyncMessagesResource(self._client) @cached_property def with_raw_response(self) -> AsyncConversationsResourceWithRawResponse: """ This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content. For more information, see https://www.github.com/letta-ai/letta-python#accessing-raw-response-data-eg-headers """ return AsyncConversationsResourceWithRawResponse(self) @cached_property def with_streaming_response(self) -> AsyncConversationsResourceWithStreamingResponse: """ An alternative to `.with_raw_response` that doesn't eagerly read the response body. For more information, see https://www.github.com/letta-ai/letta-python#with_streaming_response """ return AsyncConversationsResourceWithStreamingResponse(self) async def create( self, *, agent_id: str, context_window_limit: Optional[int] | Omit = omit, description: Optional[str] | Omit = omit, hidden: bool | Omit = omit, model: Optional[str] | Omit = omit, model_settings: Optional[conversation_create_params.ModelSettings] | Omit = omit, summary: Optional[str] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> Conversation: """ Create a new conversation for an agent. Args: agent_id: The agent ID to create a conversation for context_window_limit: The context window limit for this conversation (overrides agent's context window). description: A generated description of the conversation used for search and bootstrap context. hidden: Whether the new conversation should be hidden from listings. model: The model handle for this conversation (overrides agent's model). Format: provider/model-name. model_settings: The model settings for this conversation (overrides agent's model settings). summary: A summary of the conversation. extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ return await self._post( "/v1/conversations/", body=await async_maybe_transform( { "context_window_limit": context_window_limit, "description": description, "hidden": hidden, "model": model, "model_settings": model_settings, "summary": summary, }, conversation_create_params.ConversationCreateParams, ), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=await async_maybe_transform( {"agent_id": agent_id}, conversation_create_params.ConversationCreateParams ), ), cast_to=Conversation, ) async def retrieve( self, conversation_id: str, *, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> Conversation: """ Retrieve a specific conversation. Args: conversation_id: The ID of the conv in the format 'conv-' extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return await self._get( path_template("/v1/conversations/{conversation_id}", conversation_id=conversation_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=Conversation, ) async def update( self, conversation_id: str, *, archived: Optional[bool] | Omit = omit, context_window_limit: Optional[int] | Omit = omit, description: Optional[str] | Omit = omit, last_message_at: Union[str, datetime, None] | Omit = omit, model: Optional[str] | Omit = omit, model_settings: Optional[conversation_update_params.ModelSettings] | Omit = omit, summary: Optional[str] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> Conversation: """ Update a conversation. Args: conversation_id: The ID of the conv in the format 'conv-' archived: Whether the conversation is archived. context_window_limit: The context window limit for this conversation (overrides agent's context window). description: A generated description of the conversation used for search and bootstrap context. last_message_at: Timestamp of the most recent message request sent to this conversation. model: The model handle for this conversation (overrides agent's model). Format: provider/model-name. model_settings: The model settings for this conversation (overrides agent's model settings). summary: A summary of the conversation. extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return await self._patch( path_template("/v1/conversations/{conversation_id}", conversation_id=conversation_id), body=await async_maybe_transform( { "archived": archived, "context_window_limit": context_window_limit, "description": description, "last_message_at": last_message_at, "model": model, "model_settings": model_settings, "summary": summary, }, conversation_update_params.ConversationUpdateParams, ), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=Conversation, ) async def list( self, *, after: Optional[str] | Omit = omit, agent_id: Optional[str] | Omit = omit, archive_status: Literal["unarchived", "archived", "all"] | Omit = omit, limit: int | Omit = omit, order: Literal["asc", "desc"] | Omit = omit, order_by: Literal["created_at", "last_run_completion", "last_message_at"] | Omit = omit, summary_search: Optional[str] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> ConversationListResponse: """ List all conversations for an agent (or all conversations if agent_id not provided). Args: after: Cursor for pagination (conv ID). Returns results relative to this ID in the specified sort order. Expected format: 'conv-' agent_id: The agent ID to list conversations for (optional - returns all conversations if not provided) archive_status: Whether to return unarchived conversations only, archived conversations only, or all conversations limit: Maximum number of conversations to return order: Sort order for conversations. 'asc' for oldest first, 'desc' for newest first order_by: Field to sort by summary_search: Search for text within conversation summaries extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ return await self._get( "/v1/conversations/", options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=await async_maybe_transform( { "after": after, "agent_id": agent_id, "archive_status": archive_status, "limit": limit, "order": order, "order_by": order_by, "summary_search": summary_search, }, conversation_list_params.ConversationListParams, ), ), cast_to=ConversationListResponse, ) async def delete( self, conversation_id: str, *, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> object: """ Delete a conversation. The conversation will no longer appear in list operations. Args: conversation_id: The ID of the conv in the format 'conv-' extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return await self._delete( path_template("/v1/conversations/{conversation_id}", conversation_id=conversation_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=object, ) async def cancel( self, conversation_id: str, *, agent_id: Optional[str] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> ConversationCancelResponse: """ Cancel runs associated with a conversation. Note: To cancel active runs, Redis is required. **Agent-direct mode**: Pass conversation_id="default" with agent_id query parameter to cancel runs for the agent's default conversation. **Deprecated**: Passing an agent ID as conversation_id still works but will be removed. Args: conversation_id: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). agent_id: Agent ID for agent-direct mode with 'default' conversation extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return await self._post( path_template("/v1/conversations/{conversation_id}/cancel", conversation_id=conversation_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=await async_maybe_transform( {"agent_id": agent_id}, conversation_cancel_params.ConversationCancelParams ), ), cast_to=ConversationCancelResponse, ) async def fork( self, conversation_id: str, *, agent_id: Optional[str] | Omit = omit, hidden: bool | Omit = omit, message_id: Optional[str] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> Conversation: """ Fork an existing conversation. Creates a new conversation that shares the same in-context messages as the source conversation, but with a newly compiled system message reflecting the latest memory block values. The forked conversation belongs to the same agent as the source. If message_id is provided, only source in-context messages up to and including that message are included in the fork. **Agent-direct mode**: Pass conversation_id="default" with agent_id query parameter to fork the agent's default (agent-direct) message history into a new conversation. **Deprecated**: Passing an agent ID as conversation_id still works but will be removed. Args: conversation_id: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). agent_id: Agent ID for agent-direct mode with 'default' conversation hidden: Whether the forked conversation should be hidden from listings message_id: The ID of the message in the format 'message-' extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return await self._post( path_template("/v1/conversations/{conversation_id}/fork", conversation_id=conversation_id), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=await async_maybe_transform( { "agent_id": agent_id, "hidden": hidden, "message_id": message_id, }, conversation_fork_params.ConversationForkParams, ), ), cast_to=Conversation, ) async def recompile( self, conversation_id: str, *, dry_run: bool | Omit = omit, agent_id: Optional[str] | Omit = omit, compaction_settings: Optional[conversation_recompile_params.CompactionSettings] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, extra_query: Query | None = None, extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> str: """ Manually trigger system prompt recompilation for a conversation. Args: conversation_id: The conversation identifier. Can be a conversation ID ('conv-'), 'default' for agent-direct mode (with agent_id parameter), or an agent ID ('agent-') for backwards compatibility (deprecated). dry_run: If True, do not persist changes; still returns the compiled system prompt. agent_id: Agent ID for agent-direct mode with 'default' conversation. Use with conversation_id='default' in the URL path. compaction_settings: Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. extra_headers: Send extra headers extra_query: Add additional query parameters to the request extra_body: Add additional JSON properties to the request timeout: Override the client-level default timeout for this request, in seconds """ if not conversation_id: raise ValueError(f"Expected a non-empty value for `conversation_id` but received {conversation_id!r}") return await self._post( path_template("/v1/conversations/{conversation_id}/recompile", conversation_id=conversation_id), body=await async_maybe_transform( { "agent_id": agent_id, "compaction_settings": compaction_settings, }, conversation_recompile_params.ConversationRecompileParams, ), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout, query=await async_maybe_transform( {"dry_run": dry_run}, conversation_recompile_params.ConversationRecompileParams ), ), cast_to=str, ) class ConversationsResourceWithRawResponse: def __init__(self, conversations: ConversationsResource) -> None: self._conversations = conversations self.create = to_raw_response_wrapper( conversations.create, ) self.retrieve = to_raw_response_wrapper( conversations.retrieve, ) self.update = to_raw_response_wrapper( conversations.update, ) self.list = to_raw_response_wrapper( conversations.list, ) self.delete = to_raw_response_wrapper( conversations.delete, ) self.cancel = to_raw_response_wrapper( conversations.cancel, ) self.fork = to_raw_response_wrapper( conversations.fork, ) self.recompile = to_raw_response_wrapper( conversations.recompile, ) @cached_property def messages(self) -> MessagesResourceWithRawResponse: return MessagesResourceWithRawResponse(self._conversations.messages) class AsyncConversationsResourceWithRawResponse: def __init__(self, conversations: AsyncConversationsResource) -> None: self._conversations = conversations self.create = async_to_raw_response_wrapper( conversations.create, ) self.retrieve = async_to_raw_response_wrapper( conversations.retrieve, ) self.update = async_to_raw_response_wrapper( conversations.update, ) self.list = async_to_raw_response_wrapper( conversations.list, ) self.delete = async_to_raw_response_wrapper( conversations.delete, ) self.cancel = async_to_raw_response_wrapper( conversations.cancel, ) self.fork = async_to_raw_response_wrapper( conversations.fork, ) self.recompile = async_to_raw_response_wrapper( conversations.recompile, ) @cached_property def messages(self) -> AsyncMessagesResourceWithRawResponse: return AsyncMessagesResourceWithRawResponse(self._conversations.messages) class ConversationsResourceWithStreamingResponse: def __init__(self, conversations: ConversationsResource) -> None: self._conversations = conversations self.create = to_streamed_response_wrapper( conversations.create, ) self.retrieve = to_streamed_response_wrapper( conversations.retrieve, ) self.update = to_streamed_response_wrapper( conversations.update, ) self.list = to_streamed_response_wrapper( conversations.list, ) self.delete = to_streamed_response_wrapper( conversations.delete, ) self.cancel = to_streamed_response_wrapper( conversations.cancel, ) self.fork = to_streamed_response_wrapper( conversations.fork, ) self.recompile = to_streamed_response_wrapper( conversations.recompile, ) @cached_property def messages(self) -> MessagesResourceWithStreamingResponse: return MessagesResourceWithStreamingResponse(self._conversations.messages) class AsyncConversationsResourceWithStreamingResponse: def __init__(self, conversations: AsyncConversationsResource) -> None: self._conversations = conversations self.create = async_to_streamed_response_wrapper( conversations.create, ) self.retrieve = async_to_streamed_response_wrapper( conversations.retrieve, ) self.update = async_to_streamed_response_wrapper( conversations.update, ) self.list = async_to_streamed_response_wrapper( conversations.list, ) self.delete = async_to_streamed_response_wrapper( conversations.delete, ) self.cancel = async_to_streamed_response_wrapper( conversations.cancel, ) self.fork = async_to_streamed_response_wrapper( conversations.fork, ) self.recompile = async_to_streamed_response_wrapper( conversations.recompile, ) @cached_property def messages(self) -> AsyncMessagesResourceWithStreamingResponse: return AsyncMessagesResourceWithStreamingResponse(self._conversations.messages)