From 3ce212327c6acdd050808ab74d2152c359197b39 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Tue, 2 Apr 2024 12:52:48 -0400 Subject: [PATCH] Add converation entity docs (#2132) * Add converation entity docs * Fix links --- blog/2023-01-24-conversation-updates.md | 2 +- docs/core/conversation/custom_agent.md | 49 -------------------- docs/core/entity/conversation.md | 59 +++++++++++++++++++++++++ docs/voice/overview.md | 6 +-- sidebars.js | 2 +- static/_redirects | 2 +- 6 files changed, 65 insertions(+), 55 deletions(-) delete mode 100644 docs/core/conversation/custom_agent.md create mode 100644 docs/core/entity/conversation.md diff --git a/blog/2023-01-24-conversation-updates.md b/blog/2023-01-24-conversation-updates.md index 97b1ecb5..e35fe8f4 100644 --- a/blog/2023-01-24-conversation-updates.md +++ b/blog/2023-01-24-conversation-updates.md @@ -5,7 +5,7 @@ authorImageURL: /img/profile/paulus.jpg title: "Future proofing the Conversation integration" --- -The Home Assistant 2023.2 release contains [PR 86592](https://github.com/home-assistant/core/pull/86592) and [PR 86484](https://github.com/home-assistant/core/pull/86484) which include breaking changes to [the conversation agent](/docs/core/conversation/custom_agent) API to future proof it. +The Home Assistant 2023.2 release contains [PR 86592](https://github.com/home-assistant/core/pull/86592) and [PR 86484](https://github.com/home-assistant/core/pull/86484) which include breaking changes to [the conversation agent](/docs/core/entity/conversation) API to future proof it. - Setting an agent now requires a config entry: `conversation.async_set_agent(hass, config_entry, agent). - Unsetting an agent now goes via a new endpoint: `conversation.async_unset_agent(hass, config_entry) diff --git a/docs/core/conversation/custom_agent.md b/docs/core/conversation/custom_agent.md deleted file mode 100644 index 1d5de73b..00000000 --- a/docs/core/conversation/custom_agent.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Conversation Agent ---- - -The conversation integration offers a standardized API for users to use human speech to interact with Home Assistant. The actual processing of human speech is handled by a conversation agent. - -The integration provides a default conversation agent that uses our own [intent recognizer](../../voice/intent-recognition) and [intent handlers](../../intent_index). - -## Creating a custom conversation agent - -It is possible for integrations to provide a custom conversation agent. The `async_process` method takes a `ConversationInput` object that contains the following data: - -| Name | Type | Description -| ---- | ---- | ----------- -| `text` | `str` | User input -| `context` | `Context` | HA context to attach to actions in HA -| `conversation_id` | `Optional[str]` | Can be used to track a multi-turn conversation. Return None if not supported -| `language` | `str` | Language of the text. If user did not provide one, it's set to the HA configured language. - -```python -from homeassistant.helpers import intent -from homeassistant.components.conversation import agent - - -async def async_setup(hass, config): - """Initialize your integration.""" - conversation.async_set_agent(hass, MyConversationAgent()) - - -class MyConversationAgent(agent.AbstractConversationAgent): - - @property - def attribution(self) -> agent.Attribution: - """Return the attribution.""" - return { - "name": "My Conversation Agent", - "url": "https://example.com", - } - - @abstractmethod - async def async_process(self, user_input: agent.ConversationInput) -> agent.ConversationResult: - """Process a sentence.""" - response = intent.IntentResponse(language=user_input.language) - response.async_set_speech("Test response") - return agent.ConversationResult( - conversation_id=None, - response=response - ) -``` diff --git a/docs/core/entity/conversation.md b/docs/core/entity/conversation.md new file mode 100644 index 00000000..42d34bdd --- /dev/null +++ b/docs/core/entity/conversation.md @@ -0,0 +1,59 @@ +--- +title: Conversation Entity +sidebar_label: Conversation +--- + +A conversation entity allows users to converse with Home Assistant. + +A conversation entity is derived from the [`homeassistant.components.conversation.ConversationEntity`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/conversation/entity.py). + +## Properties + +:::tip +Properties should always only return information from memory and not do I/O (like network requests). +::: + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| supported_languages | `list[str]` \| `Literal["*"]` | **Required** | The supported languages of the service. Return `"*"` if you support all. + +## Methods + +### Process + +This method is used to process an incoming chat message. + +```python +class MyConversationEntity(ConversationEntity): + """Represent a conversation entity.""" + + async def async_process(self, user_input: ConversationInput) -> ConversationResult: + """Process a sentence.""" + response = intent.IntentResponse(language=user_input.language) + response.async_set_speech("Test response") + return agent.ConversationResult( + conversation_id=None, + response=response + ) +``` + +A `ConversationInput` object contains the following data: + +| Name | Type | Description +| ---- | ---- | ----------- +| `text` | `str` | User input +| `context` | `Context` | HA context to attach to actions in HA +| `conversation_id` | `Optional[str]` | Can be used to track a multi-turn conversation. Return None if not supported +| `language` | `str` | Language of the text. If user did not provide one, it's set to the HA configured language. + +### Prepare + +As soon as Home Assistant knows a request is coming in, we will let the conversation entity prepare for it. This can be used to load a language model or other resources. This function is optional to implement. + +```python +class MyConversationEntity(ConversationEntity): + """Represent a conversation entity.""" + + async def async_prepare(self, language: str | None = None) -> None: + """Prepare a language for processing.""" +``` diff --git a/docs/voice/overview.md b/docs/voice/overview.md index 89a8e8f5..fa36b03e 100644 --- a/docs/voice/overview.md +++ b/docs/voice/overview.md @@ -27,10 +27,10 @@ graph TD; ``` - The **Assist Pipeline** integration is responsible for turning the user's speech into text, get it processed, and turn the response into speech. - - The **Conversation** integration is responsible for processing user's text. The built-in conversation agent does this by matching it to an intent. Integrations can provide [custom conversation agents](../core/conversation/custom_agent). + - The **Conversation** integration is responsible for processing user's text. The built-in conversation agent does this by matching it to an intent. Integrations can provide [custom conversation agents](../core/entity/conversation). - The **Intent** integration is responsible for executing the intent and returning a response. -- The **Text-to-Speech** integration is responsible for turning text into speech. -- The **Speech-to-Text** integration is responsible for turning speech into text. +- The **Text-to-Speech** integration is responsible for turning text into speech. Integrations can provide [custom text-to-speech agents](../core/entity/tts). +- The **Speech-to-Text** integration is responsible for turning speech into text. Integrations can provide [custom speech-to-text agents](../core/entity/stt). ## Capturing the user's speech diff --git a/sidebars.js b/sidebars.js index b55c47ba..2327128f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -203,7 +203,7 @@ module.exports = { { type: "category", label: "Conversation", - items: ["intent_conversation_api", "core/conversation/custom_agent"], + items: ["intent_conversation_api"], }, { type: "category", diff --git a/static/_redirects b/static/_redirects index a56129b0..fc90e37b 100644 --- a/static/_redirects +++ b/static/_redirects @@ -65,7 +65,7 @@ /docs/reproduce_state_index /docs/core/platform/reproduce_state /docs/significant_change_index /docs/core/platform/significant_change /docs/supervisor/developing /docs/supervisor/development - +/docs/core/conversation/custom_agent /docs/core/entity/conversation # Tidying moved pages /docs/creating_platform_example_sensor https://github.com/home-assistant/example-custom-config/tree/master/custom_components/example_sensor