diff --git a/README.md b/README.md index f614dd722..8995af368 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ There is a [dedicated channel for Docs on our official Discord](https://discord. ### 🪝 Hooks documentation -To help documenting the [hooks table](./mkdocs/technical/plugins/hooks.md#available-hooks), ensure these elements are not missing and please keep the order: +To help documenting the [hooks table](mkdocs/plugins/hooks.md#available-hooks), ensure these elements are not missing and please keep the order: 1. Annotation number with bold heading 2. *Input arguments* description with *code snippet* example diff --git a/mkdocs.yml b/mkdocs.yml index 941d77512..227a0d79f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,7 +20,7 @@ plugins: - mkdocstrings: handlers: python: - paths: [mkdocs/technical/API_Documentation] + paths: [mkdocs/API_Documentation] options: docstring_style: numpy @@ -36,77 +36,77 @@ nav: - Playing with the Cat: quickstart/play-with-the-cat.md # - Interacting using APIs: quickstart/interact-using-api.md - Uploading a Document: quickstart/upload-document.md - - Installing a Plugin: plugins-registry/installing-plugin.md + - Installing a Plugin: quickstart/installing-plugin.md - Creating a Plugin: quickstart/prepare-plugin.md - Writing the first Tool: quickstart/writing-tool.md - Writing the first Hook: quickstart/writing-hook.md - Stopping the Cat: quickstart/stopping-the-cat.md - Plugins: - - Plugin: technical/plugins/plugins.md - - Tools: technical/plugins/tools.md - - Hooks: technical/plugins/hooks.md - - Forms: technical/plugins/forms.md - - Logging: technical/plugins/logging.md - - Settings: technical/plugins/settings.md - - Dependencies: technical/plugins/dependencies.md - - Python Reference: technical/API_Documentation/ + - Plugin: plugins/plugins.md + - Tools: plugins/tools.md + - Hooks: plugins/hooks.md + - Forms: plugins/forms.md + - Logging: plugins/logging.md + - Settings: plugins/settings.md + - Dependencies: plugins/dependencies.md + - Python Reference: API_Documentation/ - Registry: - - Using the Plugin Template: plugins-registry/plugin-from-template.md - - Publishing a Plugin: plugins-registry/publishing-plugin.md + - Using the Plugin Template: plugins/plugins-registry/plugin-from-template.md + - Publishing a Plugin: plugins/plugins-registry/publishing-plugin.md - Debugging: - - Visual Studio Code: technical/debugging/vscode.md + - Visual Studio Code: plugins/debugging/vscode.md - Framework: - LLM Concepts: - - Language Models: llm-concepts/llm.md - - Retrieval Augmented Generation: llm-concepts/rag.md - - Prompt: llm-concepts/prompt.md - - Encoder: llm-concepts/embedder.md - - Vector Memory: llm-concepts/vector-memory.md + - Language Models: framework/llm-concepts/llm.md + - Retrieval Augmented Generation: framework/llm-concepts/rag.md + - Prompt: framework/llm-concepts/prompt.md + - Encoder: framework/llm-concepts/embedder.md + - Vector Memory: framework/llm-concepts/vector-memory.md - Cat Components: - - The Core: conceptual/cheshire_cat/core.md + - The Core: framework/cat-components/cheshire_cat/core.md - The Agent: - - Introduction: conceptual/cheshire_cat/agent.md - - Tool Chain: conceptual/cheshire_cat/tool_chain.md - - Memory Chain: conceptual/cheshire_cat/memory_chain.md + - Introduction: framework/cat-components/cheshire_cat/agent.md + - Tool Chain: framework/cat-components/cheshire_cat/tool_chain.md + - Memory Chain: framework/cat-components/cheshire_cat/memory_chain.md - The Prompts: - - Main Prompt: conceptual/prompts/main_prompt.md - - Instruction Prompt: conceptual/prompts/instructions.md + - Main Prompt: framework/cat-components/prompts/main_prompt.md + - Instruction Prompt: framework/cat-components/prompts/instructions.md - The Vector Memory: - - Vector Memory Collections: conceptual/memory/vector_memory.md + - Vector Memory Collections: framework/cat-components/memory/vector_memory.md - The Long Term Memory: - - Introduction: conceptual/memory/long_term_memory.md - - Episodic Memory: conceptual/memory/episodic_memory.md - - Declarative Memory: conceptual/memory/declarative_memory.md - - Procedural Memory: conceptual/memory/procedural_memory.md - - The Working Memory: conceptual/memory/working_memory.md - - The Rabbit Hole: conceptual/cheshire_cat/rabbit_hole.md - - The Mad Hatter: conceptual/cheshire_cat/mad_hatter.md + - Introduction: framework/cat-components/memory/long_term_memory.md + - Episodic Memory: framework/cat-components/memory/episodic_memory.md + - Declarative Memory: framework/cat-components/memory/declarative_memory.md + - Procedural Memory: framework/cat-components/memory/procedural_memory.md + - The Working Memory: framework/cat-components/memory/working_memory.md + - The Rabbit Hole: framework/cat-components/cheshire_cat/rabbit_hole.md + - The Mad Hatter: framework/cat-components/cheshire_cat/mad_hatter.md - Technical Diagrams: - - The Cat Bootstrap: technical/flows/cat-bootstrap.md - - Chatting with the Cat: technical/flows/chatting-with-the-cat.md - - Plugins Lifecycle: technical/flows/plugins-lifecycle.md + - The Cat Bootstrap: framework/flows/cat-bootstrap.md + - Chatting with the Cat: framework/flows/chatting-with-the-cat.md + - Plugins Lifecycle: framework/flows/plugins-lifecycle.md - Production: - Client Libraries: - - Python: technical/clientlib/clientlib-python.md - - TypeScript: technical/clientlib/clientlib-typescript.md - - PHP: technical/clientlib/clientlib-php.md - - Ruby: technical/clientlib/clientlib-ruby.md - - C#: technical/clientlib/clientlib-csharp.md + - Python: production/clientlib/clientlib-python.md + - TypeScript: production/clientlib/clientlib-typescript.md + - PHP: production/clientlib/clientlib-php.md + - Ruby: production/clientlib/clientlib-ruby.md + - C#: production/clientlib/clientlib-csharp.md - Administrations: - - Architecture: administrators/architecture.md - - Environment Variables: administrators/env-variables.md - - User Management: technical/advanced/user_system.md - - Automatic Tests: technical/advanced/tests.md + - Architecture: production/administrators/architecture.md + - Environment Variables: production/administrators/env-variables.md + - User Management: production/advanced/user_system.md + - Automatic Tests: production/advanced/tests.md - Use Cases: - - Cat as Main product: use-cases/main-product.md - - Cat as Sidecar of your product: use-cases/side-car.md - - Cat as Discord BOT: use-cases/discord-bot.md + - Cat as Main product: production/use-cases/main-product.md + - Cat as Sidecar of your product: production/use-cases/side-car.md + - Cat as Discord BOT: production/use-cases/discord-bot.md - Guides: # - How to update the Cat Core: guides/update-the-core.md - - How to backup the Long Term Memory: technical/advanced/memory_backup.md + - How to backup the Long Term Memory: production/advanced/memory_backup.md - FAQ: faq.md # - Altro: diff --git a/mkdocs/assets/diagrams/chatting-with-the-cat.drawio b/mkdocs/assets/diagrams/chatting-with-the-cat.drawio index 181e85cc7..5fecff027 100644 --- a/mkdocs/assets/diagrams/chatting-with-the-cat.drawio +++ b/mkdocs/assets/diagrams/chatting-with-the-cat.drawio @@ -697,7 +697,7 @@ - + @@ -900,7 +900,7 @@ - + @@ -917,7 +917,7 @@ - + @@ -928,7 +928,7 @@ - + @@ -960,17 +960,17 @@ - + - + - + @@ -1671,7 +1671,7 @@ - + @@ -1679,7 +1679,7 @@ - + @@ -1697,12 +1697,12 @@ - + - + @@ -1880,7 +1880,7 @@ - + diff --git a/mkdocs/conceptual/cheshire_cat/core.md b/mkdocs/conceptual/cheshire_cat/core.md deleted file mode 100644 index 29837fda8..000000000 --- a/mkdocs/conceptual/cheshire_cat/core.md +++ /dev/null @@ -1,3 +0,0 @@ -# The Core - -![Schema of the Cheshire Cat components](../../assets/img/diagrams/components.png){width=600px style="display: block; margin: 0 auto"} diff --git a/mkdocs/conceptual/cheshire_cat/rabbit_hole.md b/mkdocs/conceptual/cheshire_cat/rabbit_hole.md deleted file mode 100644 index 581c62694..000000000 --- a/mkdocs/conceptual/cheshire_cat/rabbit_hole.md +++ /dev/null @@ -1,8 +0,0 @@ -# Rabbit Hole - -The Rabbit Hole is the Cat's component that takes care of ingesting documents and storing them in the [declarative memory](../memory/long_term_memory.md). -You can interact with it either through its [endpoint](../../technical/basics/basics.md), the [GUI](../../technical/basics/admin/admin-interface.md) or a Python script. - -Currently supported file formats are: `.txt`, `.md`, `.pdf` or `.html` via web URL. - -![Schema of the Cheshire Cat components](../../assets/img/diagrams/rabbithole.jpg){width=400px style="display: block; margin: 0 auto"} \ No newline at end of file diff --git a/mkdocs/conceptual/cheshire_cat/agent.md b/mkdocs/framework/cat-components/cheshire_cat/agent.md similarity index 91% rename from mkdocs/conceptual/cheshire_cat/agent.md rename to mkdocs/framework/cat-components/cheshire_cat/agent.md index 29538b665..a4fcbdeb2 100644 --- a/mkdocs/conceptual/cheshire_cat/agent.md +++ b/mkdocs/framework/cat-components/cheshire_cat/agent.md @@ -13,7 +13,7 @@ When suitable tools for the task at hand are retrieved from the [procedural memo the Agent Manager calls the Tool Agent to execute the tool chain; otherwise the memory chain is executed to answer the user's question with the context retrieved from the episodic and declarative [memories](../memory/long_term_memory.md). -![Schema of the Cheshire Cat memories](../../assets/img/diagrams/agent-manager.jpg){width=400px style="display: block; margin: 0 auto"} +![Schema of the Cheshire Cat memories](../../../assets/img/diagrams/agent-manager.jpg){width=400px style="display: block; margin: 0 auto"} Specifically, the default execution pipeline is the following: diff --git a/mkdocs/framework/cat-components/cheshire_cat/core.md b/mkdocs/framework/cat-components/cheshire_cat/core.md new file mode 100644 index 000000000..0a68ee725 --- /dev/null +++ b/mkdocs/framework/cat-components/cheshire_cat/core.md @@ -0,0 +1,3 @@ +# The Core + +![Schema of the Cheshire Cat components](../../../assets/img/diagrams/components.png){width=600px style="display: block; margin: 0 auto"} diff --git a/mkdocs/conceptual/cheshire_cat/mad_hatter.md b/mkdocs/framework/cat-components/cheshire_cat/mad_hatter.md similarity index 61% rename from mkdocs/conceptual/cheshire_cat/mad_hatter.md rename to mkdocs/framework/cat-components/cheshire_cat/mad_hatter.md index d76951c74..59dbf4010 100644 --- a/mkdocs/conceptual/cheshire_cat/mad_hatter.md +++ b/mkdocs/framework/cat-components/cheshire_cat/mad_hatter.md @@ -1,4 +1,4 @@ -![Mad Hatter generated by Midjourney](../../assets/img/mad_hatter_10.png) +![Mad Hatter generated by Midjourney](../../../assets/img/mad_hatter_10.png) # Mad Hatter @@ -9,6 +9,6 @@ Specifically, the Mad Hatter lists all available plugins in proper folder and so When the Cat invokes them, it executes them following that order. !!! note "Developer documentation" - - [How to write a plugin](../../technical/plugins/plugins.md) - - [Hooks](../../technical/plugins/hooks.md) - - [Tools](../../technical/plugins/tools.md) + - [How to write a plugin](../../../plugins/plugins.md) + - [Hooks](../../../plugins/hooks.md) + - [Tools](../../../plugins/tools.md) diff --git a/mkdocs/conceptual/cheshire_cat/memory_chain.md b/mkdocs/framework/cat-components/cheshire_cat/memory_chain.md similarity index 68% rename from mkdocs/conceptual/cheshire_cat/memory_chain.md rename to mkdocs/framework/cat-components/cheshire_cat/memory_chain.md index 9ae137c66..fdfadecca 100644 --- a/mkdocs/conceptual/cheshire_cat/memory_chain.md +++ b/mkdocs/framework/cat-components/cheshire_cat/memory_chain.md @@ -4,4 +4,4 @@ The Memory Chain is a simple chain that takes the user's input and the context r [memories](../memory/long_term_memory.md) and formats them in the [main prompt](../prompts/main_prompt.md). Such prompt is submitted to the language model. -![Schema of the Cheshire Cat memories](../../assets/img/diagrams/memory-chain.jpg){width=650px style="display: block; margin: 0 auto"} +![Schema of the Cheshire Cat memories](../../../assets/img/diagrams/memory-chain.jpg){width=650px style="display: block; margin: 0 auto"} diff --git a/mkdocs/framework/cat-components/cheshire_cat/rabbit_hole.md b/mkdocs/framework/cat-components/cheshire_cat/rabbit_hole.md new file mode 100644 index 000000000..d49665606 --- /dev/null +++ b/mkdocs/framework/cat-components/cheshire_cat/rabbit_hole.md @@ -0,0 +1,8 @@ +# Rabbit Hole + +The Rabbit Hole is the Cat's component that takes care of ingesting documents and storing them in the [declarative memory](../memory/long_term_memory.md). +You can interact with it either through its [endpoint](../../../technical/basics/basics.md), the [GUI](../../../technical/basics/admin/admin-interface.md) or a Python script. + +Currently supported file formats are: `.txt`, `.md`, `.pdf` or `.html` via web URL. + +![Schema of the Cheshire Cat components](../../../assets/img/diagrams/rabbithole.jpg){width=400px style="display: block; margin: 0 auto"} \ No newline at end of file diff --git a/mkdocs/conceptual/cheshire_cat/tool_chain.md b/mkdocs/framework/cat-components/cheshire_cat/tool_chain.md similarity index 84% rename from mkdocs/conceptual/cheshire_cat/tool_chain.md rename to mkdocs/framework/cat-components/cheshire_cat/tool_chain.md index 6f258fe5a..2ef63dd87 100644 --- a/mkdocs/conceptual/cheshire_cat/tool_chain.md +++ b/mkdocs/framework/cat-components/cheshire_cat/tool_chain.md @@ -9,4 +9,4 @@ from the Cat's [procedural memory](../memory/long_term_memory.md). The tools selection and usage is planned according to a set of [instructions](../prompts/main_prompt.md#instructions). Finally, the Tool Agent parses the formatting of the tool output. -![Schema of the Cheshire Cat memories](../../assets/img/diagrams/tool-chain.jpg){width=650px style="display: block; margin: 0 auto"} +![Schema of the Cheshire Cat memories](../../../assets/img/diagrams/tool-chain.jpg){width=650px style="display: block; margin: 0 auto"} diff --git a/mkdocs/conceptual/llm.md b/mkdocs/framework/cat-components/llm.md similarity index 90% rename from mkdocs/conceptual/llm.md rename to mkdocs/framework/cat-components/llm.md index 06635d71e..3290069eb 100644 --- a/mkdocs/conceptual/llm.md +++ b/mkdocs/framework/cat-components/llm.md @@ -31,6 +31,6 @@ For instance, measuring the distance between two points can inform us about the ## Language Models flow :material-information-outline:{ title="click on the nodes with hooks to see their documentation" } !!! note "Developer documentation" - [Language Models hooks](../technical/API_Documentation/mad_hatter/core_plugin/hooks/models.md) + [Language Models hooks](../../API_Documentation/mad_hatter/core_plugin/hooks/models.md) -Nodes with the 🪝 point the execution places where there is an available [hook](../technical/plugins/plugins.md) to customize the execution pipeline. +Nodes with the 🪝 point the execution places where there is an available [hook](../../plugins/plugins.md) to customize the execution pipeline. diff --git a/mkdocs/conceptual/memory/declarative_memory.md b/mkdocs/framework/cat-components/memory/declarative_memory.md similarity index 66% rename from mkdocs/conceptual/memory/declarative_memory.md rename to mkdocs/framework/cat-components/memory/declarative_memory.md index 036c99389..2b9865d84 100644 --- a/mkdocs/conceptual/memory/declarative_memory.md +++ b/mkdocs/framework/cat-components/memory/declarative_memory.md @@ -4,4 +4,4 @@ The *Declarative Memory* contains uploaded documents' content. It is stored in a The `declarative memory` is a key component in the [memory chain](../cheshire_cat/memory_chain.md). -![Schema of the Cheshire Cat memories](../../assets/img/diagrams/declarative-memory.jpg){width=550px style="display: block; margin: 0 auto"} \ No newline at end of file +![Schema of the Cheshire Cat memories](../../../assets/img/diagrams/declarative-memory.jpg){width=550px style="display: block; margin: 0 auto"} \ No newline at end of file diff --git a/mkdocs/conceptual/memory/episodic_memory.md b/mkdocs/framework/cat-components/memory/episodic_memory.md similarity index 67% rename from mkdocs/conceptual/memory/episodic_memory.md rename to mkdocs/framework/cat-components/memory/episodic_memory.md index 0603a465a..b1049b385 100644 --- a/mkdocs/conceptual/memory/episodic_memory.md +++ b/mkdocs/framework/cat-components/memory/episodic_memory.md @@ -4,4 +4,4 @@ The *Episodic Memory* contains user and eventually cat utterances. It is stored The `episodic memory` is a key component in the [memory chain](../cheshire_cat/memory_chain.md). -![Schema of the Cheshire Cat memories](../../assets/img/diagrams/episodic-memory.jpg){width=550px style="display: block; margin: 0 auto"} \ No newline at end of file +![Schema of the Cheshire Cat memories](../../../assets/img/diagrams/episodic-memory.jpg){width=550px style="display: block; margin: 0 auto"} \ No newline at end of file diff --git a/mkdocs/conceptual/memory/long_term_memory.md b/mkdocs/framework/cat-components/memory/long_term_memory.md similarity index 69% rename from mkdocs/conceptual/memory/long_term_memory.md rename to mkdocs/framework/cat-components/memory/long_term_memory.md index a2a22ec1f..c43462e9d 100644 --- a/mkdocs/conceptual/memory/long_term_memory.md +++ b/mkdocs/framework/cat-components/memory/long_term_memory.md @@ -7,13 +7,13 @@ The name of this memory is `Long Term Memory` (LTM), it is made of three compone - [*Declarative Memory*](declarative_memory.md), contains an extract of documents uploaded to the Cat; - [*Procedural Memory*](procedural_memory.md), contains the set of Python functions that defines what the Cat is able to do. -![Schema of the Cheshire Cat memories](../../assets/img/diagrams/ltm.jpg){width=450px style="display: block; margin: 0 auto"} +![Schema of the Cheshire Cat memories](../../../assets/img/diagrams/ltm.jpg){width=450px style="display: block; margin: 0 auto"} -During conversation between the Cat and the user, the memories are accessed by the Cat to retrieve relevant context for passing to the LLM and are updated when the LLM responds (details of the read and write flow of the Long Term Memory can be found in this [diagram](../../../technical/flows/chatting-with-the-cat/)). +During conversation between the Cat and the user, the memories are accessed by the Cat to retrieve relevant context for passing to the LLM and are updated when the LLM responds (details of the read and write flow of the Long Term Memory can be found in this [diagram](../../flows/chatting-with-the-cat.md)). The retrieved relevant context is used to make up the [Main prompt](../prompts/main_prompt.md) and the Instruction prompt. -You can interact with the LTM using the [memory](../../technical/basics/admin/memory.md) page of the Admin Portal. +You can interact with the LTM using the [memory](../../../technical/basics/admin/memory.md) page of the Admin Portal. -Check about `long term memory` [backup](../../technical/advanced/memory_backup.md) to prevent loosing `cat` memories. \ No newline at end of file +Check about `long term memory` [backup](../../../technical/advanced/memory_backup.md) to prevent loosing `cat` memories. \ No newline at end of file diff --git a/mkdocs/conceptual/memory/procedural_memory.md b/mkdocs/framework/cat-components/memory/procedural_memory.md similarity index 56% rename from mkdocs/conceptual/memory/procedural_memory.md rename to mkdocs/framework/cat-components/memory/procedural_memory.md index de6e3d18c..dce32efa0 100644 --- a/mkdocs/conceptual/memory/procedural_memory.md +++ b/mkdocs/framework/cat-components/memory/procedural_memory.md @@ -2,6 +2,6 @@ The *Procedural Memory* contains tools and knowledge on how to do things. It is stored in a vector memory collection together with `declarative` and `episodic` memories. -To dive into `procedural memory` and `tool docstrings` reference the [tool basics](../../quickstart/writing-tool.md) page. +To dive into `procedural memory` and `tool docstrings` reference the [tool basics](../../../quickstart/writing-tool.md) page. -![Schema of the Cheshire Cat memories](../../assets/img/diagrams/procedural-memory.jpg){width=550px style="display: block; margin: 0 auto"} \ No newline at end of file +![Schema of the Cheshire Cat memories](../../../assets/img/diagrams/procedural-memory.jpg){width=550px style="display: block; margin: 0 auto"} \ No newline at end of file diff --git a/mkdocs/conceptual/memory/vector_memory.md b/mkdocs/framework/cat-components/memory/vector_memory.md similarity index 93% rename from mkdocs/conceptual/memory/vector_memory.md rename to mkdocs/framework/cat-components/memory/vector_memory.md index adbe60369..72f0d8ef1 100644 --- a/mkdocs/conceptual/memory/vector_memory.md +++ b/mkdocs/framework/cat-components/memory/vector_memory.md @@ -15,7 +15,7 @@ By default, Vector Memory Collections are created when the Cat is installed or a ## Vector Memory Collections flow :material-information-outline:{ title="click on the nodes with hooks to see their documentation" } !!! note "Developer documentation" - [Vector Memory Collections hooks](../../technical/API_Documentation/mad_hatter/core_plugin/hooks/memory.md) + [Vector Memory Collections hooks](../../API_Documentation/mad_hatter/core_plugin/hooks/memory.md) ```mermaid flowchart LR diff --git a/mkdocs/conceptual/memory/working_memory.md b/mkdocs/framework/cat-components/memory/working_memory.md similarity index 89% rename from mkdocs/conceptual/memory/working_memory.md rename to mkdocs/framework/cat-components/memory/working_memory.md index a1102178b..e8d375445 100644 --- a/mkdocs/conceptual/memory/working_memory.md +++ b/mkdocs/framework/cat-components/memory/working_memory.md @@ -10,7 +10,7 @@ Additionally, it collects relevant context from the *episodic*, *declarative* an The Working Memory can be used also to store custom data during a session. This capability is essential for creating a [state machine](#use-the-working-memory-as-a-state-machine) within your own plugin. -![Schema of the Cheshire Cat memories](../../assets/img/diagrams/working-memory.jpg){width=500px style="display: block; margin: 0 auto"} +![Schema of the Cheshire Cat memories](../../../assets/img/diagrams/working-memory.jpg){width=500px style="display: block; margin: 0 auto"} ## Interacting with the Working Memory @@ -55,13 +55,13 @@ One of the most powerful features of the Working Memory is its ability to functi Each time you send a message to the Cat, it stores useful data in the Working Memory, which can be retrieved to produce the output for the next message. This, along with the ability to store custom data throughout the session, is the key to implementing your specific agent in a more programmatic way. -An example of this usage in the Cheshire Cat is the [Conversational Form](../../technical/plugins/forms.md) which provides a well-crafted and comprehensive state machine to guide both the user and LLM during the conversation. +An example of this usage in the Cheshire Cat is the [Conversational Form](../../../plugins/forms.md) which provides a well-crafted and comprehensive state machine to guide both the user and LLM during the conversation. ### Example of the Working Memory as a State Machine Given that the Conversational Form state-machine implementation is quite advanced, let's create a simpler example: a technical support agent for the Cheshire Cat. -First of all, we need to create a new plugin. [Plugin? Is that some kind of exotic dish?](../../quickstart/prepare-plugin.md) +First of all, we need to create a new plugin. [Plugin? Is that some kind of exotic dish?](../../../quickstart/prepare-plugin.md) Once there, we need to define what are the states of our conversation. This can be done by creating a `SupportRequest` enum. Like so: @@ -74,7 +74,7 @@ class SupportRequest(Enum): ASK_HELP = 3 ``` -Now, we need to build a state machine to manage the conversation flow without blocking users who do not require support. To achieve this, we will use the [`agent_fast_reply`](../../technical/plugins/hooks.md#available-hooks) hook. This hook will check if a support request has already been initiated in the current session using the Working Memory. If no request exists, it will classify the user input as either support-related or not. If it is, the request state will begin to be tracked in the Working Memory. +Now, we need to build a state machine to manage the conversation flow without blocking users who do not require support. To achieve this, we will use the [`agent_fast_reply`](../../../plugins/hooks.md#available-hooks) hook. This hook will check if a support request has already been initiated in the current session using the Working Memory. If no request exists, it will classify the user input as either support-related or not. If it is, the request state will begin to be tracked in the Working Memory. ```python @@ -126,8 +126,8 @@ Now we can write some code to control the conversation flow in a more granular a ``` -As you've noticed, this state machine is quite basic and does not include comprehensive features such as handling conversation exits. Additionally, strict control flow chatbot like this belong to an older generation of chatbot design. +As you've noticed, this state machine is quite basic and does not include comprehensive features such as handling conversation exits. Additionally, strict control flow chatbot like this belong to an older generation of chatbot design. -For a more dynamic and stateful approach you can check the [Conversational Form](https://github.com/CheshireCatAI/conversational-forms). +For a more dynamic and stateful approach you can check the [Conversational Form](https://github.com/CheshireCatAI/conversational-forms). -Nevertheless, if you need complete control over your conversation flow, you can extend this example by incorporating more dynamic steps, interactions with LLMs, and other features. \ No newline at end of file +Nevertheless, if you need complete control over your conversation flow, you can extend this example by incorporating more dynamic steps, interactions with LLMs, and other features. diff --git a/mkdocs/conceptual/plugins.md b/mkdocs/framework/cat-components/plugins.md similarity index 87% rename from mkdocs/conceptual/plugins.md rename to mkdocs/framework/cat-components/plugins.md index 9dc0f65b8..e5e85c981 100644 --- a/mkdocs/conceptual/plugins.md +++ b/mkdocs/framework/cat-components/plugins.md @@ -15,10 +15,9 @@ Tools are custom Python functions that are called by the [Tool Agent](cheshire_c They come with a rich docstring upon with the [Tool Agent](cheshire_cat/agent.md) chooses *whether* and *which* tool is the most suitable to fulfill the user's request. The list of available tools ends up in the [Instruction Prompt](prompts/instructions.md), that instructs the [Tool Agent](cheshire_cat/agent.md) on how to structure its reasoning. - ![Schema of the Cheshire Cat components](../../assets/img/diagrams/plugin2.jpg){width=300px} !!! note "Developer documentation" - - [How to write a plugin](../technical/plugins/plugins.md) - - [Hooks](../technical/plugins/hooks.md) - - [Tools](../technical/plugins/tools.md) + - [How to write a plugin](../../plugins/plugins.md) + - [Hooks](../../plugins/hooks.md) + - [Tools](../../plugins/tools.md) diff --git a/mkdocs/conceptual/prompts/instructions.md b/mkdocs/framework/cat-components/prompts/instructions.md similarity index 96% rename from mkdocs/conceptual/prompts/instructions.md rename to mkdocs/framework/cat-components/prompts/instructions.md index 7b6ceefa0..7f07c9d09 100644 --- a/mkdocs/conceptual/prompts/instructions.md +++ b/mkdocs/framework/cat-components/prompts/instructions.md @@ -23,4 +23,4 @@ Thought: Do I need to use a tool? No AI: [your response here]""" ``` -where the placeholder `{tool_names}` is replaced with the list of Python [tools](../plugins.md) retrieved from the [procedural memory](../memory/long_term_memory.md). \ No newline at end of file +where the placeholder `{tool_names}` is replaced with the list of Python [tools](../plugins.md) retrieved from the [procedural memory](../memory/long_term_memory.md). diff --git a/mkdocs/conceptual/prompts/main_prompt.md b/mkdocs/framework/cat-components/prompts/main_prompt.md similarity index 94% rename from mkdocs/conceptual/prompts/main_prompt.md rename to mkdocs/framework/cat-components/prompts/main_prompt.md index 8746bc9f8..5c6b49a5f 100644 --- a/mkdocs/conceptual/prompts/main_prompt.md +++ b/mkdocs/framework/cat-components/prompts/main_prompt.md @@ -55,7 +55,7 @@ The purpose of this component is to gather few variables, that are: - chat_history: the recent conversation between the user and the Cat (i.e. the last three turns of conversation); - input: the user's message -![Schema of the Cheshire Cat prompt](../../assets/img/diagrams/prompt.jpg){width=400px style="display: block; margin: 0 auto"} +![Schema of the Cheshire Cat prompt](../../../assets/img/diagrams/prompt.jpg){width=400px style="display: block; margin: 0 auto"} ## References diff --git a/mkdocs/technical/flows/cat-bootstrap.md b/mkdocs/framework/flows/cat-bootstrap.md similarity index 100% rename from mkdocs/technical/flows/cat-bootstrap.md rename to mkdocs/framework/flows/cat-bootstrap.md diff --git a/mkdocs/technical/flows/chatting-with-the-cat.md b/mkdocs/framework/flows/chatting-with-the-cat.md similarity index 100% rename from mkdocs/technical/flows/chatting-with-the-cat.md rename to mkdocs/framework/flows/chatting-with-the-cat.md diff --git a/mkdocs/technical/flows/plugins-lifecycle.md b/mkdocs/framework/flows/plugins-lifecycle.md similarity index 100% rename from mkdocs/technical/flows/plugins-lifecycle.md rename to mkdocs/framework/flows/plugins-lifecycle.md diff --git a/mkdocs/llm-concepts/embedder.md b/mkdocs/framework/llm-concepts/embedder.md similarity index 100% rename from mkdocs/llm-concepts/embedder.md rename to mkdocs/framework/llm-concepts/embedder.md diff --git a/mkdocs/llm-concepts/llm.md b/mkdocs/framework/llm-concepts/llm.md similarity index 98% rename from mkdocs/llm-concepts/llm.md rename to mkdocs/framework/llm-concepts/llm.md index a1f99dd0f..657abb234 100644 --- a/mkdocs/llm-concepts/llm.md +++ b/mkdocs/framework/llm-concepts/llm.md @@ -16,4 +16,4 @@ A completion model takes a string as input and generates a plausible answer by c !!! warning A LLM answer should not be accepted as-is, since LLM are subjected to hallucinations. Namely, their main goal is to generate plausible answers from the syntactical point of view. - Thus, the provided answer could come from completely invented information. \ No newline at end of file + Thus, the provided answer could come from completely invented information. diff --git a/mkdocs/llm-concepts/prompt.md b/mkdocs/framework/llm-concepts/prompt.md similarity index 93% rename from mkdocs/llm-concepts/prompt.md rename to mkdocs/framework/llm-concepts/prompt.md index 8f6309e19..eb075d5da 100644 --- a/mkdocs/llm-concepts/prompt.md +++ b/mkdocs/framework/llm-concepts/prompt.md @@ -21,7 +21,7 @@ Examples of Prompts: *< child>: Teach me about patience.* - *< grandparent>: The river that carves the deepest* valley flows from a modest spring; the grandest symphony originates from a single note; the most intricate + *< grandparent>: The river that carves the deepest* valley flows from a modest spring; the grandest symphony originates from a single note; the most intricate tapestry begins with a solitary thread.* - - *< child>: Teach me about resilience."* \ No newline at end of file + + *< child>: Teach me about resilience."* diff --git a/mkdocs/llm-concepts/rag.md b/mkdocs/framework/llm-concepts/rag.md similarity index 77% rename from mkdocs/llm-concepts/rag.md rename to mkdocs/framework/llm-concepts/rag.md index db041b3cb..140ae372e 100644 --- a/mkdocs/llm-concepts/rag.md +++ b/mkdocs/framework/llm-concepts/rag.md @@ -2,13 +2,14 @@ **Retrieval Augmented Generation (RAG)** is an AI framework for improving the quality of responses generated by large language models (LLMs) by grounding the model on external sources of information. RAG uses semantic search to retrieve relevant and up-to-date information from a wide range of sources, including books, articles, websites, and databases. This information is then used to inform and improve the text generation of the LLM. -RAG has several advantages over traditional language models. -* First, it can provide more accurate and up-to-date responses, as it is able to access the latest information. -* Second, it can reduce the risk of generating erroneous or misleading content, as it is grounded on a verified knowledge base. +RAG has several advantages over traditional language models. + +* First, it can provide more accurate and up-to-date responses, as it is able to access the latest information. +* Second, it can reduce the risk of generating erroneous or misleading content, as it is grounded on a verified knowledge base. * Finally, RAG can be used to generate different creative text formats, such as poems, code, scripts, musical pieces, emails, and letters.
-![RAG](../assets/img/diagrams/rag.jpg) +![RAG](../../assets/img/diagrams/rag.jpg)
diff --git a/mkdocs/llm-concepts/vector-memory.md b/mkdocs/framework/llm-concepts/vector-memory.md similarity index 90% rename from mkdocs/llm-concepts/vector-memory.md rename to mkdocs/framework/llm-concepts/vector-memory.md index 0a82b36ca..feef8a195 100644 --- a/mkdocs/llm-concepts/vector-memory.md +++ b/mkdocs/framework/llm-concepts/vector-memory.md @@ -4,13 +4,13 @@ When we talk about Vector Memory we talk about Vector Database. A Vector Database is a particular kind of DB that stores information in form of high-dimensional vectors called embeddings. The embeddings are representations of text, image, sounds, ... -![word_embeddings](../assets/img/vector_memory/word_embeddings.png) +![word_embeddings](../../assets/img/vector_memory/word_embeddings.png) -As Vector Memory the Cheshire-Cat using [Qdrant](https://qdrant.tech/), the VectorDBs offer also optimized methods for information retrieval usually based on [Cosine similarity](https://en.wikipedia.org/wiki/Cosine_similarity). From wikipedia +As Vector Memory the Cheshire-Cat using [Qdrant](https://qdrant.tech/), the VectorDBs offer also optimized methods for information retrieval usually based on [Cosine similarity](https://en.wikipedia.org/wiki/Cosine_similarity). From wikipedia: > *"Cosine similarity is a measure of similarity between two non-zero vectors defined in an inner product space. Cosine similarity is the cosine of the angle between the vectors; that is, it is the dot product of the vectors divided by the product of their lengths. It follows that the cosine similarity does not depend on the magnitudes of the vectors, but only on their angle."* -![cosine similarity](../assets/img/vector_memory/cosine.png) +![cosine similarity](../../assets/img/vector_memory/cosine.png) ## Semantic Search diff --git a/mkdocs/index.md b/mkdocs/index.md index 689e41dbd..3fa4de3c2 100644 --- a/mkdocs/index.md +++ b/mkdocs/index.md @@ -1,4 +1,5 @@ -# 👋 Hello, dear! +# 👋 Hello, dear + ``` "Every adventure requires a first step". (Alice's Adventures in Wonderland - Lewis Carroll) @@ -8,7 +9,7 @@
-- 🏃 __Onboarding__ +- 🏃 __Onboarding__ --- @@ -22,17 +23,17 @@ Dive into advanced concepts to develop and publish your plugin! - [:octicons-arrow-right-24: Plugin documentation](technical/plugins/plugins.md) + [:octicons-arrow-right-24: Plugin documentation](plugins/plugins.md) -- 🪝 __Hooks__ +- 🪝 __Hooks__ --- Explore all the available hooks to customize the Cat! - [:octicons-arrow-right-24: Available Hooks](technical/plugins/hooks.md#available-hooks) + [:octicons-arrow-right-24: Available Hooks](plugins/hooks.md#available-hooks) -- 🚀 __Deploy__ +- 🚀 __Deploy__ --- @@ -42,23 +43,22 @@
- ## Cheshire Cat Features -The Cheshire Cat is an open-source, hackable and production-ready framework that allows developing intelligent personal -AI assistant agents on top of [Large Language Models](conceptual/llm.md) (LLM). +The Cheshire Cat is an open-source, hackable and production-ready framework that allows developing intelligent personal +AI assistant agents on top of [Large Language Models](framework/cat-components/llm.md) (LLM).
-- 🧰 __API first framework__ +- 🧰 __API first framework__ --- Chat with the Cat and interact with its endpoints! - [:octicons-arrow-right-24: Python API](technical/clientlib/clientlib-python.md) + [:octicons-arrow-right-24: Python API](production/clientlib/clientlib-python.md) -- 🚀 __Extendable via plugins in Python__ +- 🚀 __Extendable via plugins in Python__ --- @@ -66,32 +66,31 @@ AI assistant agents on top of [Large Language Models](conceptual/llm.md) (LLM). [:octicons-arrow-right-24: Write your first plugin](quickstart/prepare-plugin.md) -- 🌍 __Language model agnostic__ +- 🌍 __Language model agnostic__ --- Easily choose from a plenty of models to use! - :octicons-arrow-right-24: Tutorials coming soon... + [:octicons-arrow-right-24: compatible-models](production/administrators/architecture#compatible-models) - -- 📜 __Can ingest documents__ +- 📜 __Can ingest documents__ --- Ground the model based on your knowledge base! - [:octicons-arrow-right-24: Retrieval Augmented Generation](llm-concepts/rag.md) + [:octicons-arrow-right-24: Retrieval Augmented Generation](framework/llm-concepts/rag.md) -- 🐘 __Local Long term memory__ +- 🐘 __Local Long term memory__ --- Make use of a persistent memory across restarts! - [:octicons-arrow-right-24: Cat's Long Term Memory](conceptual/memory/long_term_memory.md) + [:octicons-arrow-right-24: Cat's Long Term Memory](framework/cat-components/memory/long_term_memory.md) -- 🐋 __100% dockerized__ +- 🐋 __100% dockerized__ --- @@ -101,7 +100,7 @@ AI assistant agents on top of [Large Language Models](conceptual/llm.md) (LLM).
-## Get in touch with us! +## Get in touch with us [:fontawesome-brands-discord: Discord](https://discord.gg/bHX5sNFCYU){ .md-button .md-button--primary } 👈 Join our Discord community where you can @@ -110,7 +109,6 @@ mentioning `@Cheshire Cat AI`. **Remember to give the project a star! ⭐ and thanks! 🙏** - ![Wikipedia picture of the Cheshire Cat](assets/img/cheshire-cat-tree-shade.jpg) "Would you tell me, please, which way I ought to go from here?" diff --git a/mkdocs/technical/debugging/vscode.md b/mkdocs/plugins/debugging/vscode.md similarity index 94% rename from mkdocs/technical/debugging/vscode.md rename to mkdocs/plugins/debugging/vscode.md index 4ec742f71..466aa6648 100644 --- a/mkdocs/technical/debugging/vscode.md +++ b/mkdocs/plugins/debugging/vscode.md @@ -1,6 +1,6 @@ # 🚀 Debug with Visual Studio Code -The `Debug Server for VSCode` plugin helps you to debug the Cat with Visual Studio Code, install it from the [public plugins registry](../../plugins-registry/installing-plugin.md) or [download the zip file](https://github.com/sambarza/cc-vscode-debugpy) (and follow the [Manual Instruction](../../plugins-registry/installing-plugin.md/#manual-installation)). +The `Debug Server for VSCode` plugin helps you to debug the Cat with Visual Studio Code, install it from the [public plugins registry](../../quickstart/installing-plugin.md#manual-installation#Through-the-Admin-Dashboard) or [download the zip file](https://github.com/sambarza/cc-vscode-debugpy) (and follow the [Manual Instruction](../../quickstart/installing-plugin.md#manual-installation)). ## Add a new port to the container diff --git a/mkdocs/technical/plugins/dependencies.md b/mkdocs/plugins/dependencies.md similarity index 100% rename from mkdocs/technical/plugins/dependencies.md rename to mkdocs/plugins/dependencies.md diff --git a/mkdocs/technical/plugins/forms.md b/mkdocs/plugins/forms.md similarity index 95% rename from mkdocs/technical/plugins/forms.md rename to mkdocs/plugins/forms.md index a3444f0f9..2c62e9e33 100644 --- a/mkdocs/technical/plugins/forms.md +++ b/mkdocs/plugins/forms.md @@ -2,7 +2,6 @@ Forms are Particular Tools useful for collecting user information during a conversation! - ## How the Forms work Imagine a scenario where you need to create an Order system for a pizzeria, using only the conversation with the user. The user must provide three pieces of information: @@ -67,7 +66,7 @@ class PizzaForm(CatForm): #(3) 1. Pydantic class representing the information you need to retrieve. 2. Every class decorated with `@forms` is a Form. 3. Every Form must inherit from `CatForm`. -4. Description of the Form. +4. Description of the Form. 5. Pydantic class name. 6. Each Form must include a list of *start examples* to guide the LLM in identifying and initiating the form. This is close to the tool's docstring principle. 7. Each Form must include a list of *stop examples* to help the LLM in determining when to stop the form during the conversation. @@ -130,9 +129,9 @@ The Validation Phase is when the Form attempts to construct the model, allowing The Visualization Phase is when the Form shows the model's status to the user by displaying a message. -By default the cat displays the forms like so ![display form](../../assets/img/technical/forms/how_is_display.png) +By default the cat displays the forms like so ![display form](../assets/img/technical/forms/how_is_display.png) -When there is invalid info retrieved from the conversation, the Cat specifies the issue ![display invalid info](../../assets/img/technical/forms/how_invalid_is_display.png) +When there is invalid info retrieved from the conversation, the Cat specifies the issue ![display invalid info](../assets/img/technical/forms/how_invalid_is_display.png) You can modify this phase by overriding the `def message(self)` method: diff --git a/mkdocs/technical/plugins/hooks.md b/mkdocs/plugins/hooks.md similarity index 90% rename from mkdocs/technical/plugins/hooks.md rename to mkdocs/plugins/hooks.md index de5510f65..7028f7973 100644 --- a/mkdocs/technical/plugins/hooks.md +++ b/mkdocs/plugins/hooks.md @@ -3,6 +3,7 @@ Hooks are Python functions that are called directly from the Cat at runtime, they allow you to change how the Cat internally works without directly modifying the Cat itself. ## How the Hooks work + To create a hook, you first need to create a [plugin](plugins.md) that contains it. Once the plugin is created, you can insert hooks inside the plugin, a single plugin can contain multiple hooks. A hook is simply a Python function that uses the `@hook` decorator, the function's name determines when it will be called. @@ -36,13 +37,15 @@ def before_cat_sends_message(final_output, cat): *Some hooks receive more than one argument, the value determined by the Cat is always the first argument, all the other parameters are solely context parameters, which hooks cannot modify, the last parameter is always the Cat instance.* ## Multiple Implementations -Several plugins can implement the same hook. The argument `priority` of the `@hook` decorator allows you to set the priority of the hook, the default value is 1. + +Several plugins can implement the same hook. The argument `priority` of the `@hook` decorator allows you to set the priority of the hook, the default value is 1. The Cat calls the implementations in order of priority. Hooks with a higher priority number will be called first. The following hooks will receive the value returned by the previous hook. In this way, hooks can be chained together to create complex behaviors. If two plugins have the same priority, the order in which they are called is not guaranteed. ## Available Hooks + You can view the list of available hooks by exploring the Cat source code under the folder `core/cat/mad_hatter/core_plugin/hooks`. All the hooks you find in there define default Cat's behavior and are ready to be overridden by your plugins. @@ -89,7 +92,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_bootstrap) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_bootstrap) - [Debugger plugin](https://github.com/sambarza/cc-vscode-debugpy) 2. **Input arguments** @@ -107,7 +110,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.after_cat_bootstrap) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.after_cat_bootstrap) 3. **Input arguments** `user_message_json`: a dictionary with the JSON message sent via WebSocket. E.g.: @@ -132,7 +135,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_reads_message) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_reads_message) 4. **Input arguments** `user_message`: a string with the user's message that will be used to query the vector memories. E.g.: @@ -157,7 +160,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resourcer" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.cat_recall_query) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.cat_recall_query) - [HyDE plugin](https://github.com/Furrmidable-Crew/ccat_hyde) 5. **Input arguments** @@ -175,7 +178,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_recalls_memories) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_recalls_memories) 6. **Input arguments** `episodic_recall_config`: dictionary with the recall configuration for the episodic memory. Default is: @@ -204,7 +207,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_recalls_episodic_memories) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_recalls_episodic_memories) - [C.A.T. plugin](https://github.com/Furrmidable-Crew/cat_advanced_tools) 7. **Input arguments** @@ -235,7 +238,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_recalls_declarative_memories) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_recalls_declarative_memories) - [RabbitHole segmentation plugin](https://github.com/team-sviluppo/cc_rabbithole_segmentation) - [C.A.T. plugin](https://github.com/Furrmidable-Crew/cat_advanced_tools) @@ -266,7 +269,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_recalls_procedural_memories) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_recalls_procedural_memories) - [C.A.T. plugin](https://github.com/Furrmidable-Crew/cat_advanced_tools) 9. **Input arguments** @@ -284,7 +287,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.after_cat_recalls_memories) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.after_cat_recalls_memories) 10. **Input arguments** `doc`: Langchain Document to be inserted in memory. E.g.: @@ -312,7 +315,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_stores_episodic_memory) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_stores_episodic_memory) 11. **Input arguments** `message`: the dictionary containing the Cat's answer that will be sent via WebSocket. E.g.: @@ -350,10 +353,10 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_sends_message) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/flow/#cat.mad_hatter.core_plugin.hooks.flow.before_cat_sends_message) === "🤖 Agent" - +
| Name | Description | @@ -395,7 +398,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/agent/#cat.mad_hatter.core_plugin.hooks.agent.before_agent_starts) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/agent/#cat.mad_hatter.core_plugin.hooks.agent.before_agent_starts) 2. **Input arguments** `fast_reply`: empty dictionary. @@ -424,7 +427,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/agent/#cat.mad_hatter.core_plugin.hooks.agent.agent_fast_reply) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/agent/#cat.mad_hatter.core_plugin.hooks.agent.agent_fast_reply) - [Stay on topic plugin](https://github.com/Furrmidable-Crew/stay_on_topic) 3. **Input arguments** @@ -453,7 +456,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/prompt/#cat.mad_hatter.core_plugin.hooks.prompt.agent_prompt_prefix) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/prompt/#cat.mad_hatter.core_plugin.hooks.prompt.agent_prompt_prefix) 4. **Input arguments** `prompt_suffix`: string with the ending part of the prompt containing the memories and the chat history. @@ -508,7 +511,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/prompt/#cat.mad_hatter.core_plugin.hooks.prompt.agent_prompt_suffix) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/prompt/#cat.mad_hatter.core_plugin.hooks.prompt.agent_prompt_suffix) - [C.A.T. plugin](https://github.com/Furrmidable-Crew/cat_advanced_tools) 5. **Input arguments** @@ -534,7 +537,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/agent/#cat.mad_hatter.core_plugin.hooks.agent.agent_allowed_tools) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/agent/#cat.mad_hatter.core_plugin.hooks.agent.agent_allowed_tools) 6. **Input arguments** `instructions`: string with the reasoning template. Default is: @@ -581,10 +584,10 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/prompt/#cat.mad_hatter.core_plugin.hooks.prompt.agent_prompt_instructions) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/prompt/#cat.mad_hatter.core_plugin.hooks.prompt.agent_prompt_instructions) === "🐰 Rabbit Hole" - +
| Name | Description | @@ -628,7 +631,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.rabbithole_instantiates_parsers) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.rabbithole_instantiates_parsers) - [IngestAnything plugin](https://github.com/Furrmidable-Crew/IngestAnything) 2. **Input arguments** @@ -657,7 +660,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.before_rabbithole_insert_memory) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.before_rabbithole_insert_memory) - [RabbitHole segmentation plugin](https://github.com/team-sviluppo/cc_rabbithole_segmentation) - [Summarization plugin](https://github.com/Furrmidable-Crew/ccat_summarization) @@ -682,7 +685,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.before_rabbithole_splits_text) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.before_rabbithole_splits_text) 4. **Input arguments** `chunks`: list of Langchain documents with text chunks. @@ -704,7 +707,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.after_rabbithole_splitted_text) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.after_rabbithole_splitted_text) 5. **Input arguments** `docs`: list of chunked Langchain documents before being inserted in memory. @@ -735,7 +738,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.before_rabbithole_stores_documents) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.before_rabbithole_stores_documents) - [Summarization plugin](https://github.com/Furrmidable-Crew/ccat_summarization) 6. **Input arguments** @@ -755,7 +758,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.after_rabbithole_stored_documents) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.after_rabbithole_stored_documents) 7. **Input arguments** @@ -782,7 +785,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.rabbithole_instantiates_parsers) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.rabbithole_instantiates_parsers) - [IngestAnything Plugin](https://github.com/Furrmidable-Crew/IngestAnything) 8. **Input arguments** @@ -803,10 +806,10 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.rabbithole_instantiates_splitter) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/hooks/rabbithole/#cat.mad_hatter.core_plugin.hooks.rabbithole.rabbithole_instantiates_splitter) === "🔌 Plugin" - +
| Name | Description | @@ -845,7 +848,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.activated) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.activated) - [Plugin object](https://github.com/cheshire-cat-ai/core/blob/main/core/cat/mad_hatter/plugin.py#L25) 2. **Input arguments** @@ -877,7 +880,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.deactivated) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.deactivated) - [Plugin object](https://github.com/cheshire-cat-ai/core/blob/main/core/cat/mad_hatter/plugin.py#L25) 3. **Input arguments** @@ -925,7 +928,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - [Example Plugin: C.A.T. Cat Advanced Tools](https://github.com/Furrmidable-Crew/cat_advanced_tools) - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.settings_schema) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.settings_schema) - [Plugin object](https://github.com/cheshire-cat-ai/core/blob/main/core/cat/mad_hatter/plugin.py#L25) 4. **Input arguments** @@ -975,7 +978,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.settings_model) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.settings_model) - [Plugin object](https://github.com/cheshire-cat-ai/core/blob/main/core/cat/mad_hatter/plugin.py#L25) 5. **Input arguments** @@ -1007,7 +1010,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.load_settings) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.load_settings) - [Plugin object](https://github.com/cheshire-cat-ai/core/blob/main/core/cat/mad_hatter/plugin.py#L25) 6. **Input arguments** @@ -1043,7 +1046,7 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d ??? note "Other resources" - - [Python reference](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.save_settings) + - [Python reference](https://cheshire-cat-ai.github.io/docs/API_Documentation/mad_hatter/core_plugin/settings/#cat.mad_hatter.core_plugin.settings.save_settings) - [Plugin object](https://github.com/cheshire-cat-ai/core/blob/main/core/cat/mad_hatter/plugin.py#L25) === "🏭 Factory" @@ -1136,5 +1139,4 @@ Not all the hooks have been documented yet. ( [help needed! 😸](https://d - [Python reference]() - [Plugin object](https://github.com/cheshire-cat-ai/core/blob/main/core/cat/mad_hatter/core_plugin/hooks/language.py#L23) - -> **_NOTE:_** Any function in a plugin decorated by `@plugin` and named properly (among the list of available overrides, **Plugin** tab in the table above) is used to override plugin behaviour. These are not hooks because they are not piped, they are *specific* for every plugin. +> ***NOTE:*** Any function in a plugin decorated by `@plugin` and named properly (among the list of available overrides, **Plugin** tab in the table above) is used to override plugin behaviour. These are not hooks because they are not piped, they are *specific* for every plugin. diff --git a/mkdocs/technical/plugins/logging.md b/mkdocs/plugins/logging.md similarity index 94% rename from mkdocs/technical/plugins/logging.md rename to mkdocs/plugins/logging.md index fddb5d4da..f4fee1d9e 100644 --- a/mkdocs/technical/plugins/logging.md +++ b/mkdocs/plugins/logging.md @@ -17,17 +17,22 @@ Note that the logger is created by default with level `WARNING` (`LOG_LEVEL=${LO Logging messages which are less severe than *level* will be ignored; logging messages which have severity *level* or higher will be emitted to the console. ## How to + The logging system can be imported like this + ``` from cat.log import log ``` + and then used as easy as: + ``` log.error("A simple text here") log.info(f"Value of user message is {user_message_json["text"]}") log.critical(variable_value) ``` -Take a look [here](https://cheshire-cat-ai.github.io/docs/technical/API_Documentation/log/) if you want to better understand how the log system is implemented. + +Take a look [here](https://cheshire-cat-ai.github.io/docs///API_Documentation/log/) if you want to better understand how the log system is implemented. ## Examples @@ -91,4 +96,4 @@ Follows an example of the console log for each log level. - what the console logs: - cheshire_cat_core | [2024-01-20 18:11:24.992] CRITICAL cat.plugins.cat-formatter.cat_formatter..before_cat_reads_message::26 => 'user message: The answer to all questions is 42.' \ No newline at end of file + cheshire_cat_core | [2024-01-20 18:11:24.992] CRITICAL cat.plugins.cat-formatter.cat_formatter..before_cat_reads_message::26 => 'user message: The answer to all questions is 42.' diff --git a/mkdocs/plugins-registry/plugin-from-template.md b/mkdocs/plugins/plugins-registry/plugin-from-template.md similarity index 88% rename from mkdocs/plugins-registry/plugin-from-template.md rename to mkdocs/plugins/plugins-registry/plugin-from-template.md index 1f08ffc12..60389bfc0 100644 --- a/mkdocs/plugins-registry/plugin-from-template.md +++ b/mkdocs/plugins/plugins-registry/plugin-from-template.md @@ -3,17 +3,19 @@ We have prepared a GitHub template for you to expedite the creation of a new plugin, ready for publication in the public Registry. The template includes a complete scaffolding for the plugin and the GitHub action configuration to release the plugin package. ## Creating the new plugin + In the example we will create a plugin for the Poetic Socks Seller (refer to the Quickstart section if you're not familiar with it). In the next steps, replace `poetic_sock_seller` with the name of you futuristic plugin! Navigate to the [plugin-template](https://github.com/cheshire-cat-ai/plugin-template){:target="_blank"} GitHub repository, click on `Use this template` and, then, `Create a new repository`: -![Alt text](../assets/img/quickstart/prepare-plugin/create-from-template.png) +![Alt text](../../assets/img/quickstart/prepare-plugin/create-from-template.png) as repository name and then click on `Create repository`: -![Alt text](../assets/img/quickstart/prepare-plugin/repo-name.png) +![Alt text](../../assets/img/quickstart/prepare-plugin/repo-name.png) ## Cloning the Plugin + Now that you set up the remote repository on GitHub, you need to set up the code locally. Hence, clone the repository directly in the Cat’s plugins folder on your machine: @@ -23,7 +25,9 @@ git clone https://github.com/[your_account_name]/poetic_sock_seller.git ``` ## Customizing the Plugin + Finally, run the setup.py script to customize the repository: + ``` shell cd poetic_sock_seller python setup.py @@ -31,11 +35,12 @@ python setup.py The script will prompt you to write the name of your plugin, `Poetic Sock Seller`. The output in the terminal should look like: ->![Alt text](../assets/img/quickstart/prepare-plugin/shell-setup.png) +>![Alt text](../../assets/img/quickstart/prepare-plugin/shell-setup.png) The template contains a source code example, look at it in the `poetic_sock_seller.py` file. ### 📦 Release Creation + A repository created with our template automatically includes the creation of a release on GitHub through a GitHub action. This automation happens whenever you push changes to the `main` branch and the `version` number in the `plugin.json` file changes. The release is automatically tagged with the version number and released in all the formats supported by GitHub. -For details about the GitHub action, refer to the file `.github/workflows/main.yml`. \ No newline at end of file +For details about the GitHub action, refer to the file `.github/workflows/main.yml`. diff --git a/mkdocs/plugins-registry/publishing-plugin.md b/mkdocs/plugins/plugins-registry/publishing-plugin.md similarity index 97% rename from mkdocs/plugins-registry/publishing-plugin.md rename to mkdocs/plugins/plugins-registry/publishing-plugin.md index 3a0f6c78c..a6eb5d51e 100644 --- a/mkdocs/plugins-registry/publishing-plugin.md +++ b/mkdocs/plugins/plugins-registry/publishing-plugin.md @@ -13,7 +13,7 @@ You can find the repository at this address: [https://github.com/cheshire-cat-ai Click on the colorful "Use this template" button at the top and choose to create a new repository. Once you've chosen the name for your repository and cloned the code to your machine, you can run the setup script to clean up the files and rename everything as needed. ```bash -$ python setup.py +python setup.py ``` To learn more about how to work with the plugin template, read [this dedicated page](plugin-from-template.md). @@ -27,7 +27,7 @@ A repository created with our template automatically includes the creation of a Here's the documentation related to managing releases on GitHub: [https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) !!! info - Remember to change the `version` number in `plugin.json` only when you actually want to create a new version of your plugin. While you're in development, you can either open a develop branch (the automation only runs on the main branch) or continue to push to the main branch without changing the version number. + Remember to change the `version` number in `plugin.json` only when you actually want to create a new version of your plugin. While you're in development, you can either open a develop branch (the automation only runs on the main branch) or continue to push to the main branch without changing the version number. ## 📜 Take Care of the `plugin.json` @@ -40,7 +40,7 @@ In reality, there are only 3 mandatory fields for publishing in the registry: `n Below is a list of the fields with a brief explanation. !!! warning - Fields marked with the asterisk (*) are mandatory. + Fields marked with the asterisk (*) are mandatory. - `name`**\***: The name of your plugin. - `version`**\***: The last stable version number. @@ -75,7 +75,6 @@ If, after patiently waiting within this 24-hour window, your plugin doesn't show Remember, our goal is to make your plugin available to our community seamlessly. Your cooperation and patience in allowing for the cache expiry are appreciated as we work to ensure a smooth plugin publishing process. - ## 🔔 Stay Updated The final step is to stay informed about what's happening in the magical world of Cheshire Cat so that you can keep your plugin up to date with the latest developments. To facilitate this, we've created a dedicated channel for plugin developers on our [official Discord server](https://discord.com/invite/bHX5sNFCYU). @@ -84,4 +83,4 @@ We invite you to become a part of our community and let a moderator know that yo If you don't use Discord or prefer not to login on our server, we still encourage you to try to keep up with Cheshire Cat AI's updates. We'll conduct periodic review cycles, and if your plugin becomes too outdated or non-functional after some time, we may have to remove it from the registry. -*Looking forward to seeing you among our amazing plugin developers!* \ No newline at end of file +*Looking forward to seeing you among our amazing plugin developers!* diff --git a/mkdocs/technical/plugins/plugins.md b/mkdocs/plugins/plugins.md similarity index 100% rename from mkdocs/technical/plugins/plugins.md rename to mkdocs/plugins/plugins.md diff --git a/mkdocs/technical/plugins/settings.md b/mkdocs/plugins/settings.md similarity index 92% rename from mkdocs/technical/plugins/settings.md rename to mkdocs/plugins/settings.md index 5ddd3edc2..329dee5a4 100644 --- a/mkdocs/technical/plugins/settings.md +++ b/mkdocs/plugins/settings.md @@ -72,16 +72,16 @@ def settings_model(): Now go to the admin in `Plugins` page and click the cog near the activation toggle: -![Open settings](../../assets/img/admin_screenshots/plugin_settings/settings.png) +![Open settings](../assets/img/admin_screenshots/plugin_settings/settings.png) A side panel will open, where you and your plugin's users can choose settings in a comfy way.
- ![Form part 1](../../assets/img/admin_screenshots/plugin_settings/form1.png){ width="500" } + ![Form part 1](../assets/img/admin_screenshots/plugin_settings/form1.png){ width="500" }
- ![Form part 2](../../assets/img/admin_screenshots/plugin_settings/form2.png){ width="500" } + ![Form part 2](../assets/img/admin_screenshots/plugin_settings/form2.png){ width="500" }
## Access settings from within your plugin diff --git a/mkdocs/technical/plugins/tools.md b/mkdocs/plugins/tools.md similarity index 96% rename from mkdocs/technical/plugins/tools.md rename to mkdocs/plugins/tools.md index e9e888101..180d195f4 100644 --- a/mkdocs/technical/plugins/tools.md +++ b/mkdocs/plugins/tools.md @@ -130,14 +130,14 @@ def convert_currency(tool_input, cat): # (1) **Cat's reasoning** (you can see this in the terminal logs): > **Thought**: Do I need to use a tool? Yes -> **Action**: convert_currency +> **Action**: convert_currency > **Action Input**: 10.5 > **Observation**: 11.235000000000001 **Cat's answer**: > 10.5 euros is equivalent to 11.235000000000001 dollars. -Writing as tool is as simple as this. The core aspect to remember are: +Writing as tool is as simple as this. The core aspect to remember are: 1. the docstring from where the LLM understand how to use the tool and how the input should look like. 2. the two input arguments, i.e. the first is the string the LLM take from the chat and the Cat instance; @@ -187,7 +187,7 @@ def convert_currency(tool_input, cat): > Can you convert 10.5 euro to dollars? **Cat's reasoning** (from the terminal logs): -> the reasoning is not displayed as the goal of the `return_direct=True` parameter is to skip those steps and return the output directly. +> the reasoning is not displayed as the goal of the `return_direct=True` parameter is to skip those steps and return the output directly. **Cat's answer**: > Result of the conversion: 10.50 EUR -> 11.24 USD @@ -246,7 +246,7 @@ def convert_currency(tool_input, cat): # (1) **Cat's answer**: > 7.5 euros is equal to 6.45 British Pounds. -As you may see, the [Agent](../../conceptual/cheshire_cat/agent.md) correctly understands the desired output from the message +As you may see, the [Agent](../framework/cat-components/cheshire_cat/agent.md) correctly understands the desired output from the message and passes it to the tool function as explained in the docstring. Then, it is up to us parse the two inputs correctly for our tool. ### External library & the cat parameter @@ -315,18 +315,17 @@ the quality of our tool code. > **Action Input**: 67-JPY > **Observation**: 67€ = 9846.99¥; - TODO: - a better example? - show how tools are displayed in the prompt and how the LLM selects them - more examples with little variations - - the tool calls an external service - - the tool reads/writes a file - - the input string contains a dictionary (to be parsed with `json.loads`) - - the tool manages a conversational form - - show how you can access cat's functionality (memory, llm, embedder, rabbit_hole) from inside a tool - - what else? dunno + - the tool calls an external service + - the tool reads/writes a file + - the input string contains a dictionary (to be parsed with `json.loads`) + - the tool manages a conversational form + - show how you can access cat's functionality (memory, llm, embedder, rabbit_hole) from inside a tool + - what else? dunno ## References diff --git a/mkdocs/administrators/architecture.md b/mkdocs/production/administrators/architecture.md similarity index 97% rename from mkdocs/administrators/architecture.md rename to mkdocs/production/administrators/architecture.md index 7a9a97534..c9dc149ea 100644 --- a/mkdocs/administrators/architecture.md +++ b/mkdocs/production/administrators/architecture.md @@ -36,7 +36,7 @@ The Admin Portal connects to the core using `localhost` through the port exposed ## Logging -All the log messages are printed on the standard output and log level can be configured with [`LOG_LEVEL`](env-variables.md#log_level) environment variables. You can check logging system documentation [here](../technical/plugins/logging.md). +All the log messages are printed on the standard output and log level can be configured with [`LOG_LEVEL`](env-variables.md#log_level) environment variables. You can check logging system documentation [here](../../plugins/logging.md). ## Configuration @@ -44,7 +44,7 @@ Some options of the Core can be customized using [environment variables](env-var ## Compatible Models -The cat is agnostic, meaning You can attach your preferred llm and embedder model/provider. The Cat supports the most used ones, but you can increase the number of models/providers by [plugins](/technical/plugins/hooks/#__tabbed_1_5), here is a list of the main ones: +The cat is agnostic, meaning You can attach your preferred llm and embedder model/provider. The Cat supports the most used ones, but you can increase the number of models/providers by [plugins](../../plugins/hooks.md/#__tabbed_1_5), here is a list of the main ones: 1. OpenAI and Azure OpenAI 2. Cohere diff --git a/mkdocs/administrators/env-variables.md b/mkdocs/production/administrators/env-variables.md similarity index 100% rename from mkdocs/administrators/env-variables.md rename to mkdocs/production/administrators/env-variables.md diff --git a/mkdocs/technical/advanced/api_auth.md b/mkdocs/production/advanced/api_auth.md similarity index 100% rename from mkdocs/technical/advanced/api_auth.md rename to mkdocs/production/advanced/api_auth.md diff --git a/mkdocs/technical/advanced/contributing.md b/mkdocs/production/advanced/contributing.md similarity index 100% rename from mkdocs/technical/advanced/contributing.md rename to mkdocs/production/advanced/contributing.md diff --git a/mkdocs/technical/advanced/memory_backup.md b/mkdocs/production/advanced/memory_backup.md similarity index 100% rename from mkdocs/technical/advanced/memory_backup.md rename to mkdocs/production/advanced/memory_backup.md diff --git a/mkdocs/technical/advanced/tests.md b/mkdocs/production/advanced/tests.md similarity index 100% rename from mkdocs/technical/advanced/tests.md rename to mkdocs/production/advanced/tests.md diff --git a/mkdocs/technical/advanced/user_system.md b/mkdocs/production/advanced/user_system.md similarity index 82% rename from mkdocs/technical/advanced/user_system.md rename to mkdocs/production/advanced/user_system.md index 32f1ee967..dec51a500 100644 --- a/mkdocs/technical/advanced/user_system.md +++ b/mkdocs/production/advanced/user_system.md @@ -1,8 +1,8 @@ # 👥 User System The Cat provides a basic user management system that allows having separated memories for each user. -The user system affects only the [working memory](../../conceptual/memory/working_memory.md) and -the [episodic memory](../../conceptual/memory/long_term_memory.md). +The user system affects only the [working memory](../../framework/cat-components/memory/working_memory.md) and +the [episodic memory](../../framework/cat-components/memory/long_term_memory.md). The other memories are shared among users. More in details, the websocket client indicates the current `user_id` by calling the `ws://localhost:1865/ws/{user_id}` endpoint. @@ -10,7 +10,7 @@ The Cat uses such `user_id` to retrieve the user's working memory and to store t !!! Note Please, note that the user management system works only when using a custom client. - Its usage is not intended from the [admin](../basics/admin/admin-interface.md) interface, + Its usage is not intended from the [admin](../../technical/basics/admin/admin-interface.md) interface, which, by default, uses `user_id = "user"`. ## Example @@ -23,7 +23,7 @@ and [Typescript](https://www.npmjs.com/package/ccat-api), that allow exploiting === "Python" ```python import cheshire_cat_api as ccat - + cat_client = ccat.CatClient() # Send a message specifying the user_id @@ -40,7 +40,3 @@ and [Typescript](https://www.npmjs.com/package/ccat-api), that allow exploiting cat.send('Hello my friend!!', 'user05'); ``` - - - - diff --git a/mkdocs/technical/clientlib/clientlib-csharp.md b/mkdocs/production/clientlib/clientlib-csharp.md similarity index 100% rename from mkdocs/technical/clientlib/clientlib-csharp.md rename to mkdocs/production/clientlib/clientlib-csharp.md diff --git a/mkdocs/technical/clientlib/clientlib-php.md b/mkdocs/production/clientlib/clientlib-php.md similarity index 100% rename from mkdocs/technical/clientlib/clientlib-php.md rename to mkdocs/production/clientlib/clientlib-php.md diff --git a/mkdocs/technical/clientlib/clientlib-python.md b/mkdocs/production/clientlib/clientlib-python.md similarity index 97% rename from mkdocs/technical/clientlib/clientlib-python.md rename to mkdocs/production/clientlib/clientlib-python.md index 21d4f0086..05f25dd00 100644 --- a/mkdocs/technical/clientlib/clientlib-python.md +++ b/mkdocs/production/clientlib/clientlib-python.md @@ -13,7 +13,7 @@ To add the client to your project, install it with pip: pip install cheshire_cat_api ``` -Then, you can import the base class like this: +Then, you can import the base class like this: ```python import cheshire_cat_api as ccat @@ -134,7 +134,7 @@ from cheshire_cat_api.models.body_upload_url import BodyUploadUrl # a URL requires structuring the body like this body_upload_url = BodyUploadUrl( - url="https://cheshire-cat-ai.github.io/docs/conceptual/cheshire_cat/rabbit_hole/" + url="https://cheshire-cat-ai.github.io/docs/cat-components/cheshire_cat/rabbit_hole/" ) # then you can make the request as follows @@ -183,4 +183,4 @@ response = cat_client.memory.wipe_collections() | `rabbit_hole` | `POST` | | | | | `POST` | | | | | `POST` | | | -| | `GET` | | | \ No newline at end of file +| | `GET` | | | diff --git a/mkdocs/technical/clientlib/clientlib-ruby.md b/mkdocs/production/clientlib/clientlib-ruby.md similarity index 100% rename from mkdocs/technical/clientlib/clientlib-ruby.md rename to mkdocs/production/clientlib/clientlib-ruby.md diff --git a/mkdocs/technical/clientlib/clientlib-typescript.md b/mkdocs/production/clientlib/clientlib-typescript.md similarity index 100% rename from mkdocs/technical/clientlib/clientlib-typescript.md rename to mkdocs/production/clientlib/clientlib-typescript.md diff --git a/mkdocs/use-cases/discord-bot.md b/mkdocs/production/use-cases/discord-bot.md similarity index 100% rename from mkdocs/use-cases/discord-bot.md rename to mkdocs/production/use-cases/discord-bot.md diff --git a/mkdocs/use-cases/main-product.md b/mkdocs/production/use-cases/main-product.md similarity index 100% rename from mkdocs/use-cases/main-product.md rename to mkdocs/production/use-cases/main-product.md diff --git a/mkdocs/use-cases/main-product.png b/mkdocs/production/use-cases/main-product.png similarity index 100% rename from mkdocs/use-cases/main-product.png rename to mkdocs/production/use-cases/main-product.png diff --git a/mkdocs/use-cases/side-car.md b/mkdocs/production/use-cases/side-car.md similarity index 100% rename from mkdocs/use-cases/side-car.md rename to mkdocs/production/use-cases/side-car.md diff --git a/mkdocs/use-cases/side-car.png b/mkdocs/production/use-cases/side-car.png similarity index 100% rename from mkdocs/use-cases/side-car.png rename to mkdocs/production/use-cases/side-car.png diff --git a/mkdocs/plugins-registry/installing-plugin.md b/mkdocs/quickstart/installing-plugin.md similarity index 100% rename from mkdocs/plugins-registry/installing-plugin.md rename to mkdocs/quickstart/installing-plugin.md diff --git a/mkdocs/quickstart/play-with-the-cat.md b/mkdocs/quickstart/play-with-the-cat.md index ad6989ae8..858bd57a6 100644 --- a/mkdocs/quickstart/play-with-the-cat.md +++ b/mkdocs/quickstart/play-with-the-cat.md @@ -83,8 +83,4 @@ This example explains the **Raw** use of the Cat APIs, however there are convini #### More Info -[`Developers -> Client Libraries`](../technical/clientlib/clientlib-python.md) - -## Next Step - -In the [next step](./interact-using-api.md), you will learn how to interact with the Cat by API. +[`Developers -> Client Libraries`](../production/clientlib/clientlib-python.md) diff --git a/mkdocs/quickstart/prepare-plugin.md b/mkdocs/quickstart/prepare-plugin.md index c0b0f814b..62cf856bf 100644 --- a/mkdocs/quickstart/prepare-plugin.md +++ b/mkdocs/quickstart/prepare-plugin.md @@ -4,8 +4,8 @@ Plugins are packages of `Tools` and `Hooks`. You don't distribute a `Tool` or a `Hook` directly, you will distribute a Plugin containing them. ## Creating the Plugin -In this step, we will prepare an empty plugin and in the next steps we will insert a `Tool` and a `Hook` inside it. +In this step, we will prepare an empty plugin and in the next steps we will insert a `Tool` and a `Hook` inside it. To create a plugin just create a new folder in `core/cat/plugins/`, for our first plugin the folder name will be `poetic_sock_seller`. @@ -32,13 +32,16 @@ The `plugin.json` file contains plugin's title and description, and is useful in The `poetic_sock_seller.py` file will contain `Tools` and `Hooks` source code and can be left completely empty for this step. ## Activating the Plugin + Now, go to the `Plugin` tab of the Admin Portal. Your empty plugin will be there, activate it: ![Alt text](../assets/img/quickstart/prepare-plugin/activate-plugins.png) #### More Info -[Developers → Plugins Reference → Plugin](../technical/plugins/plugins.md) + +[Developers → Plugins Reference → Plugin](../plugins/plugins.md) ## Next Step -In the [next step](./writing-tool.md), you will learn how to create your first `Tool`. \ No newline at end of file + +In the [next step](./writing-tool.md), you will learn how to create your first `Tool`. diff --git a/mkdocs/quickstart/stopping-the-cat.md b/mkdocs/quickstart/stopping-the-cat.md index b5c671efb..08806088b 100644 --- a/mkdocs/quickstart/stopping-the-cat.md +++ b/mkdocs/quickstart/stopping-the-cat.md @@ -9,4 +9,4 @@ docker compose down ``` We want to remind you that Long-Term Memory is a locally persisted memory. -When you restart the Cat, all conversation history and uploaded documents will still be there. \ No newline at end of file +When you restart the Cat, all conversation history and uploaded documents will still be there. diff --git a/mkdocs/quickstart/writing-hook.md b/mkdocs/quickstart/writing-hook.md index e39e9c820..49d0c2603 100644 --- a/mkdocs/quickstart/writing-hook.md +++ b/mkdocs/quickstart/writing-hook.md @@ -8,7 +8,7 @@ The attached code will be invoked during the flow's execution and can modify the At the moment, if you ask the Cat “who are you?”, he will present himself as the Cheshire Cat AI. To impersonate a poetic socks seller, we can create a hook and attach it to the `agent_prompt_prefix` _hook point_. -TODO: "hook point" what is this? "hook definition"? +TODO: "hook point" what is this? "hook definition"? ```python from cat.mad_hatter.decorators import hook @@ -24,14 +24,17 @@ You are an expert in socks, and you reply with exactly one rhyme. ``` ## Testing the Hook + Now, let’s ask again “who are you?” and for our favorite socks color: ![Alt text](../assets/img/quickstart/write-hook/marvin-sockseller.png) ## Explaining the code step by step + ```python from cat.mad_hatter.decorators import hook ``` + Let’s import from the Cat the hook decorator. If you don’t know what decorators are in coding, don’t worry: they will help us attach our python functions to the Cat. The `mad_hatter` is the Cat component that manages and runs plugins. @@ -46,13 +49,16 @@ You are an expert in socks, and you reply with exactly one rhyme. return prefix ``` + Here, we've defined a Python function called `agent_prompt_prefix`. It takes `cat` as an argument and is decorated with `@hook`. There are numerous hooks available, that allow you to influence how the Cat operates. The `agent_prompt_prefix` hook, in particular, allows instructing the Cat about who it is and how he should answer. #### More Info -[Developers → Plugins Reference → Hooks](../technical/plugins/hooks.md) + +[Developers → Plugins Reference → Hooks](../plugins/hooks.md) ## Next Step -In the [next step](./stopping-the-cat.md), you will learn how to `stop the cat`. \ No newline at end of file + +In the [next step](./stopping-the-cat.md), you will learn how to `stop the cat`. diff --git a/mkdocs/quickstart/writing-tool.md b/mkdocs/quickstart/writing-tool.md index abb4aede5..289820aea 100644 --- a/mkdocs/quickstart/writing-tool.md +++ b/mkdocs/quickstart/writing-tool.md @@ -1,10 +1,11 @@ # Writing the first Tool Tools are Python functions called by the LLM to execute actions. -They are made of two parts: the first one contains instructions that explain the LLM when and how to call function; +They are made of two parts: the first one contains instructions that explain the LLM when and how to call function; the second one contains the actual code to execute. ## Creating the Tool + Now, let’s get down to business. A real socks sales representative offers a quantity of socks, with many colors and corresponding price. Let’s say a customer wants to know the price for socks of a specific color. @@ -29,22 +30,25 @@ def socks_prices(color, cat): ``` ## Testing the Tool + Now, let’s ask for our favorite socks color: ![Alt text](../assets/img/quickstart/write-tool/ask-price-socks.png) ## Why the response? + By clicking on the question mark next to the answer, you can understand what prompted the Cat to provide the response. In this case, you can see that our tool "socks_prices" was used: ![Alt text](../assets/img/quickstart/write-tool/why-the-response.png) ## Explaining the code step by step + ```python from cat.mad_hatter.decorators import tool ``` -Let’s import the tool decorator from the Cat. +Let’s import the tool decorator from the Cat. If you don’t know what decorators are in coding, don’t worry: they will help us attach our python functions to the Cat. The `mad_hatter` is the Cat component that manages and runs plugins. @@ -84,7 +88,7 @@ What is indeed interesting is that, in a tool, you can connect your AI to any se Imagine turning on and off the light in your room, searching an e-commerce or writing an email. The only limit is your fantasy 😀. -## WatchFiles detected changes... reloading... +## WatchFiles detected changes... reloading When changes to the plugin's source code are detected, the Cat automatically restarts. Feel free to make changes within the code and observe the results. @@ -95,7 +99,9 @@ Sometimes debugging can be necessary. Please refer to the `Developers -> Debugging` section for more information. #### More Info -[Developers → Plugins Reference → Tools](../technical/plugins/tools.md) + +[Developers → Plugins Reference → Tools](../plugins/tools.md) ## Next Step + In the [next step](./writing-hook.md), you will learn how to create your first `Hook`. diff --git a/mkdocs/technical/basics/admin/admin-interface.md b/mkdocs/technical/basics/admin/admin-interface.md index 3ecc5e083..5b40d9f3b 100644 --- a/mkdocs/technical/basics/admin/admin-interface.md +++ b/mkdocs/technical/basics/admin/admin-interface.md @@ -15,7 +15,7 @@ The frontend interface of The Cheshire Cat can be accessed via `localhost:1865/admin`. This interface provides you with an easy-to-use chat that acts as a playground and can be used to interact with your application. -The Cat core uses a static build of the admin, +The Cat core uses a static build of the admin, source code can be found [here](https://github.com/cheshire-cat-ai/admin-vue). The home page of the Admin interface is where it possible to chat with the Cat. @@ -55,8 +55,8 @@ at the bottom left the source of the memory and on the bottom right the upload t ![Flash button](../../../assets/img/admin_screenshots/modal_home.png){ width="150" } -1. **Prompt settings**: allows customizing the main prompt [prefix](../../../conceptual/prompts/main_prompt.md#prefix). +1. **Prompt settings**: allows customizing the main prompt [prefix](../../../cat-components/prompts/main_prompt.md#prefix). 2. **Upload memories**: allows uploading memories in the format of JSON files. 3. **Upload url**: allows uploading a web page in memory providing an url. 4. **Upload file**: allows uploading a file in memory. Supported formats are `.txt`, `.pdf` and `.md`. -5. **Clear conversation**: clear the current conversation and delete the conversation history in the [working memory](../../../conceptual/memory/working_memory.md). \ No newline at end of file +5. **Clear conversation**: clear the current conversation and delete the conversation history in the [working memory](../../../cat-components/memory/working_memory.md). diff --git a/mkdocs/technical/basics/admin/memory.md b/mkdocs/technical/basics/admin/memory.md index 6146c66fc..ef254adc3 100644 --- a/mkdocs/technical/basics/admin/memory.md +++ b/mkdocs/technical/basics/admin/memory.md @@ -1,6 +1,6 @@ # Memory -The Memory page allows interacting with the Cat's [long term memory](../../../conceptual/memory/long_term_memory.md). +The Memory page allows interacting with the Cat's [long term memory](../../../cat-components/memory/long_term_memory.md). Specifically, it is possible to query the vector collections and retrieve a custom number of similar memories, wipe the collections or delete individual memories. @@ -10,8 +10,8 @@ In short, t-SNE embeds the memory points projecting them on a 2D plane such that similar points live close to each other. Namely, the most similar memories to the query are the closest points to the red one. Reducing the dimensionality of memories is necessary -since memories are stored in the [vector memory](../../../conceptual/memory/vector_memory.md) collections -in the form of multidimensional [points](../../../conceptual/memory/vector_memory.md) +since memories are stored in the [vector memory](../../../cat-components/memory/vector_memory.md) collections +in the form of multidimensional [points](../../../cat-components/memory/vector_memory.md) (e.g. points with 1536 dimensions) and for this reason cannot be plotted. ![Memory page](../../../assets/img/admin_screenshots/memory.png) @@ -35,7 +35,7 @@ Clicking on it opens a [side panel](#show-more-button) with detailed information ![Flash button](../../../assets/img/admin_screenshots/memory_details.png){ width="300" } -1. **Embedder**: this tab tells what's the [embedder](../../../conceptual/llm.md#embedding-model) in use. +1. **Embedder**: this tab tells what's the [embedder](../../../cat-components/llm.md#embedding-model) in use. 2. **Memory buttons**: these buttons allow switching between the lists of every memory collection. 3. **Memory item**: these elements give information about every the retrieved memories. In green there is the similarity score with the query; below the memory content; @@ -53,4 +53,3 @@ In green there is the similarity score with the query; below the memory content; ## References [^1]: Van der Maaten, L., & Hinton, G. (2008). Visualizing data using t-SNE. Journal of machine learning research, 9(11). - diff --git a/mkdocs/technical/basics/admin/settings.md b/mkdocs/technical/basics/admin/settings.md index 479290df9..0b9ce0319 100644 --- a/mkdocs/technical/basics/admin/settings.md +++ b/mkdocs/technical/basics/admin/settings.md @@ -1,6 +1,6 @@ # Settings -The settings page allows managing the settings of the [language models](../../../conceptual/llm.md) and other general settings. +The settings page allows managing the settings of the [language models](../../../cat-components/llm.md) and other general settings. ![Settings](../../../assets/img/admin_screenshots/settings.png) @@ -9,4 +9,4 @@ One LLM should always be configured otherwise it is not possible to chat. 2. **Embedder**: the *configure* button opens the side panel to configure your preferred LLM. By default, the Cat sets the embedder having the same vendor of the LLM you configured. When this is not available, the Cat uses an embedder that generate random numbers to embed the text. -3. **Toggle sound**: the toggle allows turning on/off the sound when the Cat sends a message. \ No newline at end of file +3. **Toggle sound**: the toggle allows turning on/off the sound when the Cat sends a message.