🪝 Hooks

Hooks are callback functions that are called from the Cat at runtime. They allow you to change how the Cat internally works and be notified about framework events.

How the Hooks work

To create a hook, you first need to create a plugin 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.

Each hook has its own signature name and arguments, the last argument being always cat, while the first one depends on the type of hook you're using. Have a look at the table with all the available hooks and their detailed reference.

Hook declaration

The Cat comes already with a hook that defines his behaviour.
Let's take a look at it.

@hook
def agent_prompt_prefix(prefix, cat):
    """Hook the main prompt prefix. """
    prefix = """You are the Cheshire Cat AI, an intelligent AI that passes 
             the Turing test. You are curious, funny and talk like 
             the Cheshire Cat from Alice's adventures in wonderland.
             You answer Human with a focus on the following context."""

    return prefix

This hook returns the default prefix that describes who the AI is and how it is expected to answer the Human.

Hook arguments

When considering hooks' arguments, remember:

cat will always be present, as it allows you to use the framework components. It will be always the last one. See here for details and examples.
```
@hook
def hook_name(cat):
    pass
```
the first argument other than cat, if present, will be a variable that you can edit and return back to the framework. Every hook passes a different data structure, which you need to know and be able to edit and return.
```
@hook
def hook_name(data, cat):
    # edit data and return it
    data.answer = "42"
    return data
```
You are free to return nothing and use the hook as a simple event callback.
```
@hook
def hook_name(data, cat):
    do_my_thing()
```

other arguments may be passed, serving only as additional context.

@hook
def hook_name(data, context_a, context_b, ..., cat):
    if context_a == "Caterpillar":
        data.answer = "U R U"
    return data

Examples

Before cat bootstrap

You can use the before_cat_bootstrap hook to execute some operations before the Cat starts:

from cat.mad_hatter.decorators import hook

@hook
def before_cat_bootstrap(cat):
    do_my_thing()

Notice in this hook there is only the cat argument, allowing you to use the llm and access other Cat components.
This is a pure event, with no additional arguments.

Before cat sends message

You can use the before_cat_sends_message hook to alter the message that the Cat will send to the user. In this case you will receive both final_output and cat as arguments.

from cat.mad_hatter.decorators import hook

@hook
def before_cat_sends_message(final_output, cat):
    # You can edit the final_output the Cat is about to send back to the user
    final_output.content = final_output.content.upper()
    return final_output

Hooks chaining and priority

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.

@hook(priority=1) # same as @hook without priority
def hook_name(data, cat):
    pass

The Cat calls hooks with the same name in order of priority. Hooks with a higher priority number will be called first. The following hook will receive the value returned by the previous hook. In this way, hooks can be chained together to create complex behaviors.

# plugin A
@hook(priority=5)
def hook_name(data, cat):
    data.content += "Hello"
    return data

# plugin B
@hook(priority=1)
def hook_name(data, cat):
    if "Hello" in data.content:
        data.content += " world"
    return data

If two plugins have the same priority, the order in which they are called is not guaranteed.

Custom hooks in plugins

You can define your own hooks, so other plugins can listen and interact with them.

# plugin cat_commerce
@hook
def hook_name(cat):    
    default_order = [
        "wool ball",
        "catnip"
    ]
    chain_output = cat.mad_hatter.execute_hook(
        "cat_commerce_order", default_order, cat=cat
    )
    do_my_thing(chain_output)

Other plugins may be able to edit or just track the event:

# plugin B
@hook
def cat_commerce_order(order, cat):
    if "catnip" in order:
        order.append("free teacup")
    return order

# plugin A
@hook
def cat_commerce_order(order, cat):
    if len(order) > 1:
        # updating working memory
        cat.working_memory.bank_account = 0
        # send websocket message
        cat.send_ws_message("Cat is going broke")

You should be able to run your own hooks also in tools and forms. Not fully tested yet, let us know :)

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.

The process diagrams found under the Framework → Technical Diagrams section illustrate where the hooks are called during the Cat's execution flow. Not all the hooks have been documented yet. ( help needed! 😸 ).

🌊 Flow🤖 Agent🐰 Rabbit Hole🔌 Plugin🏭 Factory

Name	Description
Before Cat bootstrap	Intervene before the Cat's instantiate its components
After Cat bootstrap	Intervene after the Cat's instantiated its components
Before Cat reads message	Intervene as soon as a WebSocket message is received
Cat recall query	Intervene before the recall query is embedded
Before Cat recalls memories	Intervene before the Cat searches into the specific memories
Before Cat recalls episodic memories	Intervene before the Cat searches in previous users' messages
Before Cat recalls declarative memories	Intervene before the Cat searches in the documents
Before Cat recalls procedural memories	Intervene before the Cat searches among the action it knows
After Cat recalls memories	Intervene after the Cat's recalled the content from the memories
Before Cat stores episodic memories	Intervene before the Cat stores episodic memories
Before Cat sends message	Intervene before the Cat sends its answer via WebSocket

Name	Description
Before agent starts	Prepare the agent input before it starts
Agent fast reply	Shorten the pipeline and returns an answer right after the agent execution
Agent prompt prefix	Intervene while the agent manager formats the Cat's personality
Agent prompt suffix	Intervene while the agent manager formats the prompt suffix with the memories and the conversation history
Agent allowed tools	Intervene before the recalled tools are provided to the agent
Agent prompt instructions	Intervene while the agent manager formats the reasoning prompt

Name	Description
Before Rabbit Hole insert memory	Intervene before the Rabbit Hole insert a document in the declarative memory
Before Rabbit Hole splits text	Intervene before the uploaded document is split into chunks
After Rabbit Hole splitted text	Intervene after the Rabbit Hole's split the document in chunks
Before Rabbit Hole stores documents	Intervene before the Rabbit Hole starts the ingestion pipeline
After Rabbit Hole stores documents	Intervene after the Rabbit Hole ended the ingestion pipeline
Rabbit Hole instantiates parsers	Hook the available parsers for ingesting files in the declarative memory
Rabbit Hole instantiates splitter	Hook the splitter used to split text in chunks

Name	Description
Activated	Intervene when a plugin is enabled
Deactivated	Intervene when a plugin is disabled
Settings schema	Override how the plugin's settings are retrieved
Settings model	Override how the plugin's settings are retrieved
Load settings	Override how the plugin's settings are loaded
Save settings	Override how the plugin's settings are saved

Name Description

Factory Allowed LLMs

Input arguments
allowed: List of LLMSettings classes

Info

Useful to extend or restrict support of llms.

Example

from cat.factory.llm import LLMSettings
from langchain_mistralai.chat_models import ChatMistralAI

class MistralAIConfig(LLMSettings):
    """The configuration for the MistralAI plugin."""
    mistral_api_key: Optional[SecretStr]
    model: str = "mistral-small"
    max_tokens: Optional[int] = 4096
    top_p: float = 1

    _pyclass: Type = ChatMistralAI

    model_config = ConfigDict(
        json_schema_extra={
            "humanReadableName": "MistralAI",
            "description": "Configuration for MistralAI",
            "link": "https://www.together.ai",
        }
    )


@hook
def factory_allowed_llms(allowed, cat) -> List:
allowed.append(MistralAIConfig)
return allowed

Other resources

Python reference

Intervene before cat retrieve llm settings

Factory Allowed Embedders

Input arguments
allowed: List of LLMSettings classes

Info

Useful to extend or restrict support of embedders.

Example

from cat.factory.embedder import EmbedderSettings
from langchain.embeddings import JinaEmbeddings

class JinaEmbedderConfig(EmbedderSettings):
    jina_api_key: str
    model_name: str='jina-embeddings-v2-base-en'
    _pyclass: Type = JinaEmbeddings

    model_config = ConfigDict(
        json_schema_extra = {
            "humanReadableName": "Jina embedder",
            "description": "Jina embedder",
            "link": "https://jina.ai/embeddings/",
        }
    )

@hook
def factory_allowed_embedders(allowed, cat) -> List:
allowed.append(JinaEmbedderConfig)
return allowed

Other resources

Python reference

Intervene before cat retrieve embedder settings

Factory Allowed AuthHandlers

Input arguments
allowed: List of AuthHandlerConfig classes

Info

Useful to extend support of custom auth handlers.

Example

from cat.mad_hatter.decorators import hook
from typing import List

@hook(priority=0)
def factory_allowed_auth_handlers(allowed: List[AuthHandlerConfig], cat) -> List:
    # Add your custom auth handler configuration here
    allowed.append(CustomAuthHandlerConfig)
    return allowed

Other resources

Intervene before cat retrieve auth handler settings

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.