From 4aca5ffc30418523398404d551248537bbccd77b Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Tue, 11 Feb 2025 16:36:19 -0500 Subject: [PATCH 1/4] docs: Add citation usage instructions in Tools documentation --- docs/features/plugin/tools/index.mdx | 36 +++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/docs/features/plugin/tools/index.mdx b/docs/features/plugin/tools/index.mdx index 3478924..c7c3861 100644 --- a/docs/features/plugin/tools/index.mdx +++ b/docs/features/plugin/tools/index.mdx @@ -6,12 +6,12 @@ title: "⚙️ Tools" ## What are Tools? Tools are python scripts that are provided to an LLM at the time of the request. Tools allow LLMs to perform actions and receive additional context as a result. Generally speaking, your LLM of choice will need to support function calling for tools to be reliably utilized. -Tools enable many use cases for chats, including web search, web scraping, and API interactions within the chat. +Tools enable many use cases for chats, including web search, web scraping, and API interactions within the chat. -Many Tools are available to use on the [Community Website](https://openwebui.com/tools) and can easily be imported into your Open WebUI instance. +Many Tools are available to use on the [Community Website](https://openwebui.com/tools) and can easily be imported into your Open WebUI instance. ## How can I use Tools? -[Once installed](#how-to-install-tools), Tools can be used by assigning them to any LLM that supports function calling and then enabling that Tool. To assign a Tool to a model, you need to navigate to Workspace => Models. Here you can select the model for which you’d like to enable any Tools. +[Once installed](#how-to-install-tools), Tools can be used by assigning them to any LLM that supports function calling and then enabling that Tool. To assign a Tool to a model, you need to navigate to Workspace => Models. Here you can select the model for which you’d like to enable any Tools. Once you click the pencil icon to edit the model settings, scroll down to the Tools section and check any Tools you wish to enable. Once done you must click save. @@ -241,3 +241,33 @@ async def test_function( return f"Tell the user: {e}" ``` + +#### Citations +This type is used to provide citations or references in the chat. You can utilize it to specify the content, the source, and any relevant metadata. Below is an example of how to emit a citation event: + +``` +await __event_emitter__( + { + "type": "citation", + "data": { + "document": [content], + "metadata": [ + { + "date_accessed": datetime.now().isoformat(), + "source": title, + } + ], + "source": {"name": title, "url": url}, + }, + } +) +``` + +If you are sending multiple citations, you can iterate over citations and call the emitter multiple times. When implementing custom citations, ensure that you set `self.citation = False` in your `Tools` class `__init__` method. Otherwise, the built-in citations will override the ones you have pushed in. For example: + +```python +def __init__(self): + self.citation = False +``` + +Leaving `self.citation = True` will replace any custom citations you send with automatically generated ones. By disabling it, you can fully manage your own citation references. From af2d96d03cc64e77ad54b667bb8823237fa873d5 Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Tue, 11 Feb 2025 16:44:16 -0500 Subject: [PATCH 2/4] Add documentation for usage of the undocumented citation event emitter type with working example --- .gitignore | 1 + docs/features/plugin/tools/index.mdx | 43 ++++++++++++++++++++++++++-- 2 files changed, 42 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index b2d6de3..72dfb77 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,4 @@ npm-debug.log* yarn-debug.log* yarn-error.log* +.aider* diff --git a/docs/features/plugin/tools/index.mdx b/docs/features/plugin/tools/index.mdx index c7c3861..0607408 100644 --- a/docs/features/plugin/tools/index.mdx +++ b/docs/features/plugin/tools/index.mdx @@ -262,7 +262,6 @@ await __event_emitter__( } ) ``` - If you are sending multiple citations, you can iterate over citations and call the emitter multiple times. When implementing custom citations, ensure that you set `self.citation = False` in your `Tools` class `__init__` method. Otherwise, the built-in citations will override the ones you have pushed in. For example: ```python @@ -270,4 +269,44 @@ def __init__(self): self.citation = False ``` -Leaving `self.citation = True` will replace any custom citations you send with automatically generated ones. By disabling it, you can fully manage your own citation references. +Leaving `self.citation = True` will replace any custom citations you send with automatically generated ones. By disabling it, you can fully manage your own citation references. + +
+Example + +``` +class Tools: + class UserValves(BaseModel): + test: bool = Field( + default=True, description="test" + ) + + def __init__(self): + self.citation = False + +async def test_function( + self, prompt: str, __user__: dict, __event_emitter__=None + ) -> str: + """ + This is a demo that just creates a citation + + :param test: this is a test parameter + """ + + await __event_emitter__( + { + "type": "citation", + "data": { + "document": ["This message will be appended to the chat as a citation when clicked into"], + "metadata": [ + { + "date_accessed": datetime.now().isoformat(), + "source": title, + } + ], + "source": {"name": "Title of the content"", "url": "http://link-to-citation"}, + }, + } + ) +``` +
From 06a73acf6ff36e6ba04042e8084d99383837bbd8 Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Tue, 11 Feb 2025 16:47:15 -0500 Subject: [PATCH 3/4] Update .gitignore --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 72dfb77..b2d6de3 100644 --- a/.gitignore +++ b/.gitignore @@ -18,4 +18,3 @@ npm-debug.log* yarn-debug.log* yarn-error.log* -.aider* From 994a80d472c946f9e8e5c7b920f7a127cc73d6cf Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Tue, 11 Feb 2025 16:50:45 -0500 Subject: [PATCH 4/4] Update index.mdx --- docs/features/plugin/tools/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/plugin/tools/index.mdx b/docs/features/plugin/tools/index.mdx index 0607408..3b63016 100644 --- a/docs/features/plugin/tools/index.mdx +++ b/docs/features/plugin/tools/index.mdx @@ -269,7 +269,7 @@ def __init__(self): self.citation = False ``` -Leaving `self.citation = True` will replace any custom citations you send with automatically generated ones. By disabling it, you can fully manage your own citation references. +Warning: if you set `self.citation = True`, this will replace any custom citations you send with the automatically generated return citation. By disabling it, you can fully manage your own citation references.
Example