From bad2704049a4bd8681590f83d0ea34a89b3b6bbf Mon Sep 17 00:00:00 2001 From: Andrew Tait Gehrhardt Date: Thu, 1 Aug 2024 21:28:51 -0600 Subject: [PATCH] Completed Functions docs and added some shared components to Tools docs. --- docs/tutorial/functions.md | 96 ++++++++++++++++++++++++- docs/tutorial/tools.md | 142 ++++++++++++++++++++++++++++++++++++- 2 files changed, 235 insertions(+), 3 deletions(-) diff --git a/docs/tutorial/functions.md b/docs/tutorial/functions.md index 4ea8e42..fd4ae35 100644 --- a/docs/tutorial/functions.md +++ b/docs/tutorial/functions.md @@ -257,15 +257,107 @@ Valves are configurable by admins alone and UserValves are configurable by any u ### Event Emitters +Event Emitters are used to add additional information to the chat interface. Similarly to Filter Outlets, Event Emitters are capable of appending content to the chat. Unlike Filter Outlets, they are not capable of stripping information. Additionally, emitters can be activated at any stage during the function. + +There are two different types of Event Emitters: + +#### Status +This is used to add statuses to a message while it is performing steps. These can be done at any stage during the Function. These statuses appear right above the message content. These are very useful for Functions that delay the LLM response or process large amounts of information. This allows you to inform users what is being processed in real-time. + +``` +await __event_emitter__( + { + "type": "status", # We set the type here + "data": {"description": "Message that shows up in the chat", "done": False}, + # Note done is False here indicating we are still emitting statuses + } + ) +```
Example ``` +async def test_function( + self, prompt: str, __user__: dict, __event_emitter__=None + ) -> str: + """ + This is a demo + :param test: this is a test parameter + """ + + await __event_emitter__( + { + "type": "status", # We set the type here + "data": {"description": "Message that shows up in the chat", "done": False}, + # Note done is False here indicating we are still emitting statuses + } + ) + + # Do some other logic here + await __event_emitter__( + { + "type": "status", + "data": {"description": "Completed a task message", "done": True}, + # Note done is True here indicating we are done emitting statuses + } + ) + + except Exception as e: + await __event_emitter__( + { + "type": "status", + "data": {"description": f"An error occured: {e}", "done": True}, + } + ) + + return f"Tell the user: {e}" ```
-### Event Emitters +#### Message +This type is used to append a message to the LLM at any stage in the Function. This means that you can append messages, embed images, and even render web pages before, or after, or during the LLM response. -## What sorts of things can Functions do? \ No newline at end of file +``` +await __event_emitter__( + { + "type": "message", # We set the type here + "data": {"content": "This message will be appended to the chat."}, + # Note that with message types we do NOT have to set a done condition + } + ) +``` + +
+Example + +``` +async def test_function( + self, prompt: str, __user__: dict, __event_emitter__=None + ) -> str: + """ + This is a demo + + :param test: this is a test parameter + """ + + await __event_emitter__( + { + "type": "message", # We set the type here + "data": {"content": "This message will be appended to the chat."}, + # Note that with message types we do NOT have to set a done condition + } + ) + + except Exception as e: + await __event_emitter__( + { + "type": "status", + "data": {"description": f"An error occured: {e}", "done": True}, + } + ) + + return f"Tell the user: {e}" +``` +
\ No newline at end of file diff --git a/docs/tutorial/tools.md b/docs/tutorial/tools.md index 72f02c2..429e6ef 100644 --- a/docs/tutorial/tools.md +++ b/docs/tutorial/tools.md @@ -40,4 +40,144 @@ Tools enable diverse use cases for interactive conversations by providing a wide - [**Web Search**](https://openwebui.com/t/constliakos/web_search/): Perform live web searches to fetch real-time information. - [**Image Generation**](https://openwebui.com/t/justinrahb/image_gen/): Generate images based on the user prompt -- [**External Voice Synthesis**](https://openwebui.com/t/justinrahb/elevenlabs_tts/): Make API requests within the chat to integrate external voice synthesis service ElevenLabs and generate audio based on the LLM output. \ No newline at end of file +- [**External Voice Synthesis**](https://openwebui.com/t/justinrahb/elevenlabs_tts/): Make API requests within the chat to integrate external voice synthesis service ElevenLabs and generate audio based on the LLM output. + +## Important Tools Components +### Valves and UserValves - (optional, but HIGHLY encouraged) + +Valves and UserValves are used to allow users to provide dyanmic details such as an API key or a configuration option. These will create a fillable field or a bool switch in the GUI menu for the given Tool. + +Valves are configurable by admins alone and UserValves are configurable by any users. + +
+Example + +``` +# Define and Valves + class Valves(BaseModel): + priority: int = Field( + default=0, description="Priority level for the filter operations." + ) + test_valve: int = Field( + default=4, description="A valve controlling a numberical value" + ) + pass + + # Define any UserValves + class UserValves(BaseModel): + test_user_valve: bool = Field( + default=False, description="A user valve controlling a True/False (on/off) switch" + ) + pass + + def __init__(self): + self.valves = self.Valves() + pass +``` +
+ +### Event Emitters +Event Emitters are used to add additional information to the chat interface. Similarly to Filter Outlets, Event Emitters are capable of appending content to the chat. Unlike Filter Outlets, they are not capable of stripping information. Additionally, emitters can be activated at any stage during the Tool. + +There are two different types of Event Emitters: + +#### Status +This is used to add statuses to a message while it is performing steps. These can be done at any stage during the Tool. These statuses appear right above the message content. These are very useful for Tools that delay the LLM response or process large amounts of information. This allows you to inform users what is being processed in real-time. + +``` +await __event_emitter__( + { + "type": "status", # We set the type here + "data": {"description": "Message that shows up in the chat", "done": False}, + # Note done is False here indicating we are still emitting statuses + } + ) +``` + +
+Example + +``` +async def test_function( + self, prompt: str, __user__: dict, __event_emitter__=None + ) -> str: + """ + This is a demo + + :param test: this is a test parameter + """ + + await __event_emitter__( + { + "type": "status", # We set the type here + "data": {"description": "Message that shows up in the chat", "done": False}, + # Note done is False here indicating we are still emitting statuses + } + ) + + # Do some other logic here + await __event_emitter__( + { + "type": "status", + "data": {"description": "Completed a task message", "done": True}, + # Note done is True here indicating we are done emitting statuses + } + ) + + except Exception as e: + await __event_emitter__( + { + "type": "status", + "data": {"description": f"An error occured: {e}", "done": True}, + } + ) + + return f"Tell the user: {e}" +``` +
+ +#### Message +This type is used to append a message to the LLM at any stage in the Tool. This means that you can append messages, embed images, and even render web pages before, or after, or during the LLM response. + +``` +await __event_emitter__( + { + "type": "message", # We set the type here + "data": {"content": "This message will be appended to the chat."}, + # Note that with message types we do NOT have to set a done condition + } + ) +``` + +
+Example + +``` +async def test_function( + self, prompt: str, __user__: dict, __event_emitter__=None + ) -> str: + """ + This is a demo + + :param test: this is a test parameter + """ + + await __event_emitter__( + { + "type": "message", # We set the type here + "data": {"content": "This message will be appended to the chat."}, + # Note that with message types we do NOT have to set a done condition + } + ) + + except Exception as e: + await __event_emitter__( + { + "type": "status", + "data": {"description": f"An error occured: {e}", "done": True}, + } + ) + + return f"Tell the user: {e}" +``` +
\ No newline at end of file