# UAgents AI-Engine Integration
## 📌 Overview
This package provides the necessary types for integrating AI-Engine with UAgents, enabling structured responses and request handling within the UAgents framework. It includes models for handling various response types, key-value pairs, and booking requests.
## Installation
To install the package, use the following command:
```bash
pip install uagents-ai-engine
```
## Usage
### Importing the Package
To use the models provided by this package, import them as follows:
```python
from ai_engine.chitchat import ChitChatDialogue
from ai_engine.messages import DialogueMessage
from ai_engine.dialogue import EdgeMetadata, EdgeDescription
```
The `chitchat`, `messages`, and `dialogue` modules provide essential classes, types, and functions to facilitate structured and dynamic interactions with the agent. These modules support an open-ended communication model, allowing users to engage in an ongoing dialogue with the agent. After each user message, the agent responds, enabling a continuous and interactive conversation that can proceed as long as needed.
```python
from ai_engine.types import UAgentResponseType, KeyValue, UAgentResponse, BookingRequest
```
The `types` module offers a comprehensive set of models for handling responses, key-value pairs, and booking requests. This module is designed for scenarios where a single exchange is sufficient. The user sends a message, receives a well-structured response from the agent, and the interaction concludes efficiently. This approach is ideal for straightforward queries and tasks.
### 📦 Components
### 1. Response Models
The following classes are used for non-dialogue agent communication.
#### UAgentResponseType
An enumeration defining the types of responses that an agent can provide:
```python
class UAgentResponseType(Enum):
FINAL = "final"
ERROR = "error"
VALIDATION_ERROR = "validation_error"
SELECT_FROM_OPTIONS = "select_from_options"
FINAL_OPTIONS = "final_options"
```
#### KeyValue
A model representing a key-value pair. It is usually used by the AI-Engine as a way to provide multiple choice options to the user:
```python
class KeyValue(Model):
key: str
value: str
```
#### UAgentResponse
A model for structuring the response from an agent:
```python
class UAgentResponse(Model):
version: Literal["v1"] = "v1"
type: UAgentResponseType
request_id: Optional[str]
agent_address: Optional[str]
message: Optional[str]
options: Optional[List[KeyValue]]
verbose_message: Optional[str]
verbose_options: Optional[List[KeyValue]]
```
**Attributes:**
- `version`: The version of the response model (default is "v1").
- `type`: The type of the response, based on `UAgentResponseType`.
- `request_id`: An optional identifier for the request.
- `agent_address`: An optional address of the agent.
- `message`: An optional message from the agent.
- `options`: An optional list of key-value options.
- `verbose_message`: An optional verbose message from the agent.
- `verbose_options`: An optional list of verbose key-value options.
#### BookingRequest
A model for handling booking requests:
```python
class BookingRequest(Model):
request_id: str
user_response: str
user_email: str
user_full_name: str
```
**Attributes:**
- `request_id`: The unique identifier for the booking request.
- `user_response`: The response from the user.
- `user_email`: The email address of the user.
- `user_full_name`: The full name of the user.
### 2. Dialogue Management
#### ChitChatDialogue
A specific dialogue class for AI-Engine enabled chit-chat:
```python
class ChitChatDialogue(Dialogue):
def on_initiate_session(self, model: Type[Model]):
# ... (session initiation logic)
def on_reject_session(self, model: Type[Model]):
# ... (session rejection logic)
def on_start_dialogue(self, model: Type[Model]):
# ... (dialogue start logic)
def on_continue_dialogue(self, model: Type[Model]):
# ... (dialogue continuation logic)
def on_end_session(self, model: Type[Model]):
# ... (session end logic)
```
How to initialize a `ChitChatDialogue` instance:
```python
agent = Agent()
# instantiate the dialogues
chitchat_dialogue = ChitChatDialogue(
version="0.1",
storage=agent.storage,
)
```
For a more in depth example, see the [ChitChatDialogue](https://github.com/fetchai/uAgents/blob/main/integrations/fetch-ai-engine/examples/simple_agent.py) example.
### 3. Extending Dialogue with Metadata
#### EdgeMetadata
Metadata for the edges to specify targets and observability:
- `system` implies AI Engine processing
- `user` is direct message to the user
- `ai` is a message to the AI Engine
- `agent` is a message to the agent.
```python
class EdgeMetadata(BaseModel):
target: Literal["user", "ai", "system", "agent"]
observable: bool
```
#### EdgeDescription
A structured description for the edge:
```python
class EdgeDescription(BaseModel):
description: str
metadata: EdgeMetadata
```
### Create Edge Function
Function to create an edge with metadata:
```python
init_session = create_edge(
name="Initiate session",
description="Every dialogue starts with this transition.",
target="user",
observable=True,
parent=default_state,
child=init_state,
)
```
### 3. Message Types
The following classes are used for dialogue agent communication.
#### BaseMessage
A base model for all messages:
```python
class BaseMessage(Model):
message_id: UUID
timestamp: datetime
```
#### DialogueMessage
A model for generic dialogue messages:
```python
class DialogueMessage(BaseMessage):
type: Literal["agent_message", "agent_json", "user_message"]
agent_message: Optional[str]
agent_json: Optional[AgentJSON]
user_message: Optional[str]
```
Can be initialized as follows, we'll call this class `ChitChatDialogueMessage`:
```python
class ChitChatDialogueMessage(DialogueMessage):
"""ChitChat dialogue message"""
pass
```
And then use it as follows:
```python
@chitchat_dialogue.on_continue_dialogue(ChitChatDialogueMessage)
```
Where `chitchat_dialogue` is defined above in the `ChitChatDialogue` section and `on_continue_dialogue` is a method of the `ChitChatDialogue` class that can be extended.
## AI-Engine Integration
This integration adds the required types for AI-Engine to interact with UAgents effectively. The `UAgentResponse` model serves as the primary structure for agent responses, while `BookingRequest` handles user booking requests.
### Digest
`UAgentResponse` digest:
```
model:cf0d1367c5f9ed8a269de559b2fbca4b653693bb8315d47eda146946a168200e
```
Raw data
{
"_id": null,
"home_page": null,
"name": "uagents-ai-engine",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "uagents, agents, ai, ai-engine, fetch.ai",
"author": "Fetch.AI Limited",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c8/18/c48bb8ae6a6be61ceb3bdf056c3dc3fba7409ab8370046e1aab8193c9ad1/uagents_ai_engine-0.6.0.tar.gz",
"platform": null,
"description": "# UAgents AI-Engine Integration\n\n## \ud83d\udccc Overview\n\nThis package provides the necessary types for integrating AI-Engine with UAgents, enabling structured responses and request handling within the UAgents framework. It includes models for handling various response types, key-value pairs, and booking requests.\n\n## Installation\n\nTo install the package, use the following command:\n\n```bash\npip install uagents-ai-engine\n```\n\n## Usage\n\n### Importing the Package\n\nTo use the models provided by this package, import them as follows:\n\n```python\nfrom ai_engine.chitchat import ChitChatDialogue\nfrom ai_engine.messages import DialogueMessage\nfrom ai_engine.dialogue import EdgeMetadata, EdgeDescription\n```\n\nThe `chitchat`, `messages`, and `dialogue` modules provide essential classes, types, and functions to facilitate structured and dynamic interactions with the agent. These modules support an open-ended communication model, allowing users to engage in an ongoing dialogue with the agent. After each user message, the agent responds, enabling a continuous and interactive conversation that can proceed as long as needed.\n\n```python\nfrom ai_engine.types import UAgentResponseType, KeyValue, UAgentResponse, BookingRequest\n```\n\nThe `types` module offers a comprehensive set of models for handling responses, key-value pairs, and booking requests. This module is designed for scenarios where a single exchange is sufficient. The user sends a message, receives a well-structured response from the agent, and the interaction concludes efficiently. This approach is ideal for straightforward queries and tasks.\n\n### \ud83d\udce6 Components\n\n### 1. Response Models\n\nThe following classes are used for non-dialogue agent communication.\n\n#### UAgentResponseType\n\nAn enumeration defining the types of responses that an agent can provide:\n\n```python\nclass UAgentResponseType(Enum):\n FINAL = \"final\"\n ERROR = \"error\"\n VALIDATION_ERROR = \"validation_error\"\n SELECT_FROM_OPTIONS = \"select_from_options\"\n FINAL_OPTIONS = \"final_options\"\n```\n\n#### KeyValue\n\nA model representing a key-value pair. It is usually used by the AI-Engine as a way to provide multiple choice options to the user:\n\n```python\nclass KeyValue(Model):\n key: str\n value: str\n```\n\n#### UAgentResponse\n\nA model for structuring the response from an agent:\n\n```python\nclass UAgentResponse(Model):\n version: Literal[\"v1\"] = \"v1\"\n type: UAgentResponseType\n request_id: Optional[str]\n agent_address: Optional[str]\n message: Optional[str]\n options: Optional[List[KeyValue]]\n verbose_message: Optional[str]\n verbose_options: Optional[List[KeyValue]]\n```\n\n**Attributes:**\n\n- `version`: The version of the response model (default is \"v1\").\n- `type`: The type of the response, based on `UAgentResponseType`.\n- `request_id`: An optional identifier for the request.\n- `agent_address`: An optional address of the agent.\n- `message`: An optional message from the agent.\n- `options`: An optional list of key-value options.\n- `verbose_message`: An optional verbose message from the agent.\n- `verbose_options`: An optional list of verbose key-value options.\n\n#### BookingRequest\n\nA model for handling booking requests:\n\n```python\nclass BookingRequest(Model):\n request_id: str\n user_response: str\n user_email: str\n user_full_name: str\n```\n\n**Attributes:**\n\n- `request_id`: The unique identifier for the booking request.\n- `user_response`: The response from the user.\n- `user_email`: The email address of the user.\n- `user_full_name`: The full name of the user.\n\n### 2. Dialogue Management\n\n#### ChitChatDialogue\n\nA specific dialogue class for AI-Engine enabled chit-chat:\n\n```python\nclass ChitChatDialogue(Dialogue):\n def on_initiate_session(self, model: Type[Model]):\n # ... (session initiation logic)\n\n def on_reject_session(self, model: Type[Model]):\n # ... (session rejection logic)\n\n def on_start_dialogue(self, model: Type[Model]):\n # ... (dialogue start logic)\n\n def on_continue_dialogue(self, model: Type[Model]):\n # ... (dialogue continuation logic)\n\n def on_end_session(self, model: Type[Model]):\n # ... (session end logic)\n```\n\nHow to initialize a `ChitChatDialogue` instance:\n\n```python\n\nagent = Agent()\n\n# instantiate the dialogues\nchitchat_dialogue = ChitChatDialogue(\n version=\"0.1\",\n storage=agent.storage,\n)\n```\n\nFor a more in depth example, see the [ChitChatDialogue](https://github.com/fetchai/uAgents/blob/main/integrations/fetch-ai-engine/examples/simple_agent.py) example.\n\n### 3. Extending Dialogue with Metadata\n\n#### EdgeMetadata\n\nMetadata for the edges to specify targets and observability:\n\n- `system` implies AI Engine processing\n- `user` is direct message to the user\n- `ai` is a message to the AI Engine\n- `agent` is a message to the agent.\n\n```python\nclass EdgeMetadata(BaseModel):\n target: Literal[\"user\", \"ai\", \"system\", \"agent\"]\n observable: bool\n```\n\n#### EdgeDescription\n\nA structured description for the edge:\n\n```python\nclass EdgeDescription(BaseModel):\n description: str\n metadata: EdgeMetadata\n```\n\n### Create Edge Function\n\nFunction to create an edge with metadata:\n\n```python\ninit_session = create_edge(\n name=\"Initiate session\",\n description=\"Every dialogue starts with this transition.\",\n target=\"user\",\n observable=True,\n parent=default_state,\n child=init_state,\n)\n```\n\n### 3. Message Types\n\nThe following classes are used for dialogue agent communication.\n\n#### BaseMessage\n\nA base model for all messages:\n\n```python\nclass BaseMessage(Model):\n message_id: UUID\n timestamp: datetime\n```\n\n#### DialogueMessage\n\nA model for generic dialogue messages:\n\n```python\nclass DialogueMessage(BaseMessage):\n type: Literal[\"agent_message\", \"agent_json\", \"user_message\"]\n agent_message: Optional[str]\n agent_json: Optional[AgentJSON]\n user_message: Optional[str]\n```\n\nCan be initialized as follows, we'll call this class `ChitChatDialogueMessage`:\n\n```python\nclass ChitChatDialogueMessage(DialogueMessage):\n \"\"\"ChitChat dialogue message\"\"\"\n\n pass\n```\n\nAnd then use it as follows:\n\n```python\n@chitchat_dialogue.on_continue_dialogue(ChitChatDialogueMessage)\n```\n\nWhere `chitchat_dialogue` is defined above in the `ChitChatDialogue` section and `on_continue_dialogue` is a method of the `ChitChatDialogue` class that can be extended.\n\n## AI-Engine Integration\n\nThis integration adds the required types for AI-Engine to interact with UAgents effectively. The `UAgentResponse` model serves as the primary structure for agent responses, while `BookingRequest` handles user booking requests.\n\n### Digest\n\n`UAgentResponse` digest:\n\n```\nmodel:cf0d1367c5f9ed8a269de559b2fbca4b653693bb8315d47eda146946a168200e\n```\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Integrating AI-Engine with UAgents",
"version": "0.6.0",
"project_urls": null,
"split_keywords": [
"uagents",
" agents",
" ai",
" ai-engine",
" fetch.ai"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c0ec88def2f31afc16c1a53aa1e65eb5f4114880123ebde33f30d913f70c73b3",
"md5": "2d35fe0fe4b3a4ca04fdf74459948fd1",
"sha256": "6162209f5c83cc7b56f1eff323956f3ed1274a393170e4bcc657ba04cfd7b8b2"
},
"downloads": -1,
"filename": "uagents_ai_engine-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d35fe0fe4b3a4ca04fdf74459948fd1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 7554,
"upload_time": "2024-10-22T16:30:21",
"upload_time_iso_8601": "2024-10-22T16:30:21.578841Z",
"url": "https://files.pythonhosted.org/packages/c0/ec/88def2f31afc16c1a53aa1e65eb5f4114880123ebde33f30d913f70c73b3/uagents_ai_engine-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c818c48bb8ae6a6be61ceb3bdf056c3dc3fba7409ab8370046e1aab8193c9ad1",
"md5": "b8ed18201e234ad8a228855145c68e8b",
"sha256": "fb9e85c2db9652b43797ae35e864eeee1502604ad1efd055fe5de4526e2350ed"
},
"downloads": -1,
"filename": "uagents_ai_engine-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "b8ed18201e234ad8a228855145c68e8b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 5837,
"upload_time": "2024-10-22T16:30:23",
"upload_time_iso_8601": "2024-10-22T16:30:23.093930Z",
"url": "https://files.pythonhosted.org/packages/c8/18/c48bb8ae6a6be61ceb3bdf056c3dc3fba7409ab8370046e1aab8193c9ad1/uagents_ai_engine-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 16:30:23",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "uagents-ai-engine"
}
JSON