Merge pull request #398 from taylorwilsdon/add_citation_tool_docs

Add citation tool docs

docs/features/plugin/tools/index.mdx

@@ -241,3 +241,72 @@ async def test_function(
             return f"Tell the user: {e}"
 ```
 </details>
+
+#### 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
+```
+
+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.
+
+<details>
+<summary>Example</summary>
+
+```
+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"},
+                },
+            }
+        )
+```
+</details>