Standardize conversation agents passing in ChatSession

[balloob]

Context

There is a new helper called ChatSession to handle ongoing conversations, and conversation provides ChatLog as a way to attach messages to a conversation. Instead of requiring all conversation agents to request it, we can standardize a new method, in a backwards compatible way to pass this in.

Old method to process an incoming chat from a user:

    async def async_process(
        self, user_input: conversation.ConversationInput
    ) -> conversation.ConversationResult:
        """Process a sentence."""

Proposal

The proposal is to change it to the following:

    async def async_process(
        self, user_input: conversation.ConversationInput
    ) -> conversation.ConversationResult:
        """Process a sentence."""
        with (
            chat_session.async_get_chat_session(
                self.hass, user_input.conversation_id
            ) as session,
            conversation.async_get_chat_log(self.hass, session, user_input) as chat_log,
        ):
            return await self._async_handle_message(user_input, chat_log)

    async def _async_handle_message(
        self,
        user_input: conversation.ConversationInput,
        chat_log: conversation.ChatLog,
    ) -> conversation.ConversationResult:
        """Call the API."""

Conversation agents that leverage ChatSession and ChatLog can migrate their code to use the new _async_handle_message method. Unmigrated conversation agents can continue to use the async_process method as before.

This approach is already being used by all conversation agents: OpenAI, Google, Anthropic and Ollama.

Alternatives

We can inspect the async_process method to see if it supports the ChatSession parameter. We can also add a variable to the class to indicate if it implements v1 or v2 of the process API.

[allenporter]

Generally: Looks good to me. This seems like a good simple step forward as we expand the capabilities of ChatSession.

Do we want ConversationInput as a parameter of ChatSession? There are cases where I think the ChatSession needs arguments such as agent_id Notably the conversation_id in the ConversationInput is stale since the ChatSession may make a new id.

[balloob]

The conversation ID in the ConversationInput is indeed not to be trusted. It is what the user remembered their conversation to be. If it is old, a new one was generated. session.conversation_id is always the right one.

I've updated the above API to reflect the split of ChatSession and ChatLog.

[abmantis]

This was discussed and approved in the architecture meeting ✅