From 72d82052b9bb2b2178dc8f6a2b1d34f7145a08d4 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 40ad4913db5b9f3c113a9c80b8a2cf106bc5dbfb 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 89a171b8e81b0adcb66e331def20e754b888c2f4 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 253373888c49cd35b4cfc076c75a675fa39ae00d 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