### Before Bootstrap Hook for Initialization

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

Use the `before_cat_bootstrap` hook to execute code just before the Cat agent starts. This is suitable for scheduling jobs or performing initial setup tasks.

```python
# Run code before the Cat boots
@hook
def before_cat_bootstrap(cat):
    print("Cat is waking up... schedule jobs here if needed")
```

--------------------------------

### Run Plugin Setup Script

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/plugins-registry/publishing-plugin.md

Execute the setup script after cloning the plugin template repository to clean up files and rename them as needed.

```bash
python setup.py
```

--------------------------------

### Customizing Endpoint Path and Tags

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/endpoints.md

Customize the endpoint's path using `prefix` and organize documentation with `tags`. This example uses a GET request.

```python
@endpoint.get(path="/joke", prefix="/random", tags=["Useful Stuff"])
def random_joke():
    return 42
```

--------------------------------

### Restore Cheshire Cat AI Installation

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/administrators/backups-updates.md

Use these commands to restore a backed-up installation. Ensure you navigate to the folder containing your compose.yml file and volumes before executing.

```bash
cd <folder>
docker compose pull
docker compose up -d
```

--------------------------------

### Install Dependencies

Source: https://github.com/cheshire-cat-ai/docs/blob/main/README.md

Installs project dependencies using pip. Ensure Python 3.8+ and Pip 20+ are installed.

```bash
pip install -r requirements.txt
```

--------------------------------

### Start Docker Containers

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/advanced/contributing.md

Run this command to start the Cheshire Cat AI services using Docker Compose. The first run may take several minutes to build the Docker image.

```bash
docker compose up
```

--------------------------------

### Basic Custom Endpoint

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/endpoints.md

This example shows how to add a simple GET endpoint with no input and no authentication.

```APIDOC
## GET /new

### Description
A basic endpoint that returns a simple string.

### Method
GET

### Endpoint
/custom/new

### Request Example
None

### Response
#### Success Response (200)
- **response** (string) - The string "meooow"
```

--------------------------------

### Example agent_allowed_tools Hook

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks-reference/agent/agent_allowed_tools.md

This example demonstrates how to add a specific tool, 'blasting_hacking_tool', to the list of allowed tools for the agent. You can modify the 'allowed_tools' set to include or exclude tools based on your needs.

```python
from cat.mad_hatter.decorators import hook

@hook  # default priority = 1
def agent_allowed_tools(allowed_tools, cat):
    # let's assume there is a tool we always want to give the agent
    # add the tool name in the list of allowed tools
    allowed_tools.add("blasting_hacking_tool")

    return allowed_tools
```

--------------------------------

### Plugin Activated Hook Example

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks.md

Example of how to use the `activated` hook to ingest a URL into memory when a plugin is enabled. Requires the `plugin` decorator and `CheshireCat` instance.

```python
from cat.mad_hatter.decorators import plugin
from cat.looking_glass.cheshire_cat import CheshireCat

ccat = CheshireCat()

@plugin
def activated(plugin):
    # Upload an url in the memory when the plugin is activated
    url = "https://cheshire-cat-ai.github.io/docs/technical/plugins/hooks/"
    ccat.rabbit_hole.ingest_file(stray=ccat, file=url)
```

--------------------------------

### Add a Simple GET Endpoint

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/endpoints.md

Create a basic GET endpoint with no input or authentication. Access it via `/custom/new`.

```python
from cat.mad_hatter.decorators import endpoint

@endpoint.get("/new")
def my_endpoint():
    return "meooow"
```

--------------------------------

### Custom Endpoint Example

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/plugins.md

This example demonstrates how to define a new GET endpoint using the @endpoint decorator. The endpoint will be available at /custom/new and can be used to extend the REST API.

```APIDOC
## GET /custom/new

### Description
Allows users to define custom GET endpoints for the Cheshire Cat AI REST API. This endpoint serves as an example of how to extend the API's functionality.

### Method
GET

### Endpoint
/custom/new

### Parameters
This endpoint does not define any specific parameters in the provided example.

### Request Example
GET /custom/new

### Response
#### Success Response (200)
- **response** (string) - A simple string response, e.g., "meooow".

#### Response Example
"meooow"
```

--------------------------------

### Run Plugin Setup Script

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/plugins-registry/plugin-from-template.md

Execute the setup.py script within your cloned plugin directory to customize the plugin's name and configuration.

```shell
cd poetic_sock_seller
python setup.py
```

--------------------------------

### Langchain Document Example

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks-reference/rabbit-hole/before_rabbithole_insert_memory.md

An example of a Langchain Document object.

```python
doc = Document(page_content="So Long, and Thanks for All the Fish", metadata={})
```

--------------------------------

### Example Document Structure

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks-reference/rabbit-hole/before_rabbithole_splits_text.md

Illustrates the structure of a Langchain Document object before it is processed.

```python
docs = List[Document(page_content="This is a very long document before being split", metadata={})]
```

--------------------------------

### Custom Endpoint with Authentication

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/endpoints.md

This example demonstrates adding a GET endpoint that requires authentication and authorization using `check_permissions` and utilizes the `StrayCat` instance to invoke the LLM.

```APIDOC
## GET /joke

### Description
An endpoint that tells a joke, protected by authentication and authorization. It uses the StrayCat instance to call the LLM.

### Method
GET

### Endpoint
/custom/joke

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **response** (string) - A joke generated by the LLM.
```

--------------------------------

### Example of Custom Key Addition

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks-reference/flow/before_cat_reads_message.md

Demonstrates adding a custom key to the message JSON, which can be used for storing arbitrary data.

```json
{
    "text": "Hello Cheshire Cat!",
    "custom_key": True
}
```

--------------------------------

### Install Cheshire Cat AI with Docker Compose

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

Deploy the Cheshire Cat using Docker. Configure LLM and embedder via the Admin Portal at localhost:1865/admin.

```yaml
# compose.yml
services:
  cheshire-cat-core:
    image: ghcr.io/cheshire-cat-ai/core:latest
    container_name: cheshire_cat_core
    env_file:
      - .env
    ports:
      - 1865:80
    volumes:
      - ./static:/app/cat/static
      - ./plugins:/app/cat/plugins
      - ./data:/app/cat/data
    restart: unless-stopped
```

```bash
# Start the Cat
docker compose up -d

# Check logs
docker compose logs -f

# Stop
docker compose down
```

--------------------------------

### Example Hooks

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

Demonstrates how to use the @hook decorator to intercept and modify agent behavior at various stages. Includes examples for modifying messages before sending, providing fast replies, executing code before bootstrap, and restricting tool usage.

```APIDOC
## Hooks

Hooks allow plugins to intercept and modify the agent's behavior at specific points.

### `before_cat_sends_message` Hook

Intercepts and modifies the response just before it is sent to the user.

```python
@hook
def before_cat_sends_message(message, cat):
    # Rephrase the answer using the LLM
    message["content"] = cat.llm(f"Rephrase in ALL CAPS: {message['content']}")
    return message
```

### `agent_fast_reply` Hook

Intercepts incoming messages to provide a short-circuit reply without running the full agent.

```python
@hook
def agent_fast_reply(fast_reply, cat):
    user_text = cat.working_memory.user_message_json.text
    # Classify intent without running the full agent
    intent = cat.classify(user_text, labels=["greeting", "question", "other"])
    if intent == "greeting":
        fast_reply["output"] = "Meooow! Hello there, dear."
        return fast_reply
    return fast_reply  # returning empty fast_reply falls through to the full agent
```

### `before_cat_bootstrap` Hook

Executes code just before the Cat boots up, useful for scheduling jobs.

```python
@hook
def before_cat_bootstrap(cat):
    print("Cat is waking up... schedule jobs here if needed")
```

### `agent_allowed_tools` Hook

Restricts which tools the agent can use.

```python
@hook
def agent_allowed_tools(allowed_tools, cat):
    # Only expose safe tools
    return [t for t in allowed_tools if t.name in ["socks_prices", "get_the_time"]]
```

## Hook Priority and Chaining

Multiple plugins can implement the same hook. They execute serially from highest `priority` to lowest, each receiving the value returned by the previous hook.

```python
# plugin_a.py — runs first (priority=5)
@hook(priority=5)
def before_cat_sends_message(message, cat):
    message["content"] = message["content"] + " 🐱"
    return message

# plugin_b.py — runs second (priority=1, default)
@hook
def before_cat_sends_message(message, cat):
    # message["content"] already has "🐱" appended from plugin_a
    if "error" in message["content"].lower():
        message["content"] = "Something went wrong, dear. " + message["content"]
    return message
```
```

--------------------------------

### Clone Plugin Repository

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/plugins-registry/plugin-from-template.md

Clone the plugin template repository into your Cat's plugins folder to start local development.

```shell
cd core/cat/plugins
git clone https://github.com/[your_account_name]/poetic_sock_seller.git
```

--------------------------------

### Update Cheshire Cat AI Installation Process

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/administrators/backups-updates.md

Follow these steps to update your Cheshire Cat AI installation. This involves stopping the current instance, updating the image tag in `compose.yml`, pulling the new image, and restarting the service.

```bash
# enter the installation folder
cd <folder>

# stop the cat
docker compose down

# change the tag in `compose.yml`

# update image
docker compose pull

# start the cat
docker compose up -d
```

--------------------------------

### Chained hook execution example (Plugin A)

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks.md

Example of a hook with a higher priority (5) that appends text. It demonstrates how hooks can modify data sequentially.

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

--------------------------------

### Custom Endpoint with Path and Tags

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/endpoints.md

This example demonstrates how to customize the endpoint's path and assign tags for documentation grouping.

```APIDOC
## GET /joke

### Description
A custom endpoint with a specified path prefix and tags for documentation.

### Method
GET

### Endpoint
/random/joke

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **response** (integer) - Returns the integer 42.
```

--------------------------------

### Example of before_agent_starts Hook

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks-reference/agent/before_agent_starts.md

This hook can be used to modify the agent's input, for example, by summarizing the chat history before it's passed to the agent. Ensure the `hook` decorator is imported from `cat.mad_hatter.decorators`.

```python
from cat.mad_hatter.decorators import hook

@hook  # default priority = 1
def before_agent_starts(agent_input, cat):
    # create a compressor and summarize the conversation history
    compressed_history = cat.llm(f"Make a concise summary of the following: {agent_input['chat_history']}")
    agent_input["chat_history"] = compressed_history
    
    return agent_input
```

--------------------------------

### StrayCat Agent Fast Reply Example

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

An example hook demonstrating various StrayCat functionalities: direct LLM calls, text classification, accessing memory, sending WebSocket notifications, and embedding queries.

```python
from cat.mad_hatter.decorators import hook, tool

@hook
def agent_fast_reply(fast_reply, cat):
    user_msg = cat.working_memory.user_message_json.text

    # Direct LLM call
    answer = cat.llm("Translate to pirate speak: " + user_msg)

    # Classify text
    intent = cat.classify(user_msg, labels={
        "buy": ["I want to buy", "purchase", "order"],
        "help": ["help me", "support", "I need assistance"]
    })

    # Access episodic/declarative memory hits
    docs = cat.working_memory.declarative_memories
    if not docs:
        fast_reply["output"] = "I have no relevant documents for that."
        return fast_reply

    # Send a WebSocket notification to the user
    cat.send_notification("Processing your request...")

    # Embed a string into vector space
    vector = cat.embedder.embed_query("some text")

    # Stringify chat history for custom prompt use
    history_str = cat.stringify_chat_history()

    fast_reply["output"] = answer
    return fast_reply
```

--------------------------------

### Chained hook execution example (Plugin B)

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks.md

Example of a hook with a lower priority (1) that conditionally appends text based on the output of a previous hook. This illustrates chaining.

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

--------------------------------

### before_agent_starts Hook

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks-reference/agent/before_agent_starts.md

This hook allows reading and editing the agent input before it starts. It receives the agent_input dictionary and the cat instance.

```APIDOC
## `before_agent_starts` Hook

### Description
Prepare the agent input before it starts. This hook allows reading and editing the agent input.

### Arguments
- **agent_input** (dict) - The information that is about to be passed to the agent.
- **cat** ([StrayCat](../../../framework/cat-components/cheshire_cat/stray_cat.md)) - Cheshire Cat instance, allows you to use the framework components.

### Agent Input Structure
The `agent_input` dictionary has the following structure:
```json
{
    "input": "user's message",
    "episodic_memory": "strings with documents recalled from memories",
    "declarative_memory": "declarative memory content",
    "chat_history": "conversation history content",
    "tools_output": "output from tools"
}
```

### Return
- **agent_input** (dict) - The modified agent input.

### Example
```python
from cat.mad_hatter.decorators import hook

@hook
def before_agent_starts(agent_input, cat):
    # create a compressor and summarize the conversation history
    compressed_history = cat.llm(f"Make a concise summary of the following: {agent_input['chat_history']}")
    agent_input["chat_history"] = compressed_history
    
    return agent_input
```
```

--------------------------------

### Start Cheshire Cat Service in Detached Mode

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/quickstart/installation-configuration.md

Command to start the Cheshire Cat Docker service in the background. Use the --detach or -d flag to prevent the terminal from being locked.

```bash
docker compose up -d
```

--------------------------------

### before_cat_bootstrap Hook Signature and Example

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks-reference/lifecycle/before_cat_bootstrap.md

This hook is executed before the Cat has finished instantiating its components. It receives the Cheshire Cat instance as an argument, allowing interaction with framework components. It does not return any value.

```APIDOC
## `before_cat_bootstrap` Hook

### Description
Intervene before the Cat has instantiated its components. This hook is executed in the middle of plugins and natural language objects loading.

### Arguments
- `cat` (StrayCat): Cheshire Cat instance, allows you to use the framework components.

### Return
This function does not return any value.

### Example
```python
from cat.mad_hatter.decorators import hook

@hook  # default priority = 1
def before_cat_bootstrap(cat):
    # do whatever here
```
```

--------------------------------

### Tool Decorator Options

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/tools.md

Configuration options for the @tool decorator, including `return_direct` for immediate user response and `examples` for LLM prompt enhancement.

```python
@tool(
    # Choose whether tool output goes straight to the user,
    #  or is reelaborated from the agent with another contextual prompt.
    return_direct : bool = False

    # Examples of user sentences triggering the tool.
    examples : List[str] = []
)

```

--------------------------------

### VSCode launch.json for Docker Run

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/debugging/vscode.md

Configuration for VSCode's launch.json when debugging a Cat instance run with 'docker run'. Adjust 'localRoot' and 'remoteRoot' based on your setup.

```json
{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Remote Attach to Cat",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}/",
                    "remoteRoot": "/app/cat"
                }
            ],
            "justMyCode": true
        }
    ]
  
}
```

--------------------------------

### Define and execute custom hooks

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks.md

This example shows how to define a custom hook (`cat_commerce_order`) in one plugin and then execute it from another plugin using `cat.mad_hatter.execute_hook`. This enables inter-plugin communication.

```python
# plugin cat_commerce
@hook
def before_cat_reads_message(msg, 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)
```

--------------------------------

### Custom Endpoint with Input/Output Models

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/endpoints.md

This example shows a POST endpoint that accepts Pydantic models for input and returns a Pydantic model for output, providing automatic validation and documentation.

```APIDOC
## POST /topic-joke

### Description
An endpoint that generates a joke based on a provided topic and language, returning the joke and user ID. It uses Pydantic models for input and output validation.

### Method
POST

### Endpoint
/custom/topic-joke

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **topic** (string) - Required - The topic for the joke.
- **language** (string) - Required - The language for the joke.

### Request Example
```json
{
  "topic": "mozzarella",
  "language": "italian"
}
```

### Response
#### Success Response (200)
- **joke** (string) - The generated joke.
- **user_id** (string) - The ID of the current user.

#### Response Example
```json
{
  "joke": "Perché la mozzarella non va mai in palestra? \n\nPerché ha paura di sciogliersi!",
  "user_id": "user"
}
```
```

--------------------------------

### Set Environment Variables for Authentication

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/auth/authentication.md

Configure these environment variables in your .env file to secure your Cat installation. Ensure Docker is loading your .env file.

```bash
CCAT_API_KEY=a-very-long-and-alphanumeric-secret
CCAT_API_KEY_WS=another-very-long-and-alphanumeric-secret
CCAT_JWT_SECRET=yet-another-very-long-and-alphanumeric-secret
```

--------------------------------

### Set HTTP API Key

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/auth/authentication.md

Example of setting the CCAT_API_KEY environment variable to secure HTTP endpoints. Access will be denied without this key.

```bash
CCAT_API_KEY=meow
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/cheshire-cat-ai/docs/blob/main/README.md

Launches a local, non-static instance of the documentation website for development and preview.

```bash
mkdocs serve
```

```bash
python -m mkdocs serve
```

--------------------------------

### Authenticated GET Endpoint with Enum Permissions

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/endpoints.md

An alternative to the previous example, using `AuthResource` and `AuthPermission` enums for specifying permissions, which are validated automatically.

```python
from cat.mad_hatter.decorators import endpoint
from cat.auth.permissions import AuthResource, AuthPermission, check_permissions

@endpoint.get("/joke")
def joke(cat=check_permissions(AuthResource.CONVERSATION, AuthPermission.WRITE)):
    
    # invoking the LLM!
    return cat.llm("Tell me a short joke.")
```

--------------------------------

### Procedures Prompt Template

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/framework/cat-components/prompts/instructions.md

This template defines the structure for the Procedures Agent's reasoning output. It includes available actions, the required JSON format, and placeholders for tools and examples.

```python
TOOL_PROMPT = """Create a JSON with the correct "action" and "action_input" to help the Human.
You can use one of these actions:
{tools}
- "no_action": Use this action if no relevant action is available. Input is always null.

## The JSON must have the following structure:

{{
    "action": // str - The name of the action to take, should be one of [{tool_names}, "no_action"]
    "action_input": // str or null - The input to the action according to its description
}}

{examples}
"""
```

--------------------------------

### Navigate to the Project Directory

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/advanced/contributing.md

Change your current directory to the newly cloned repository folder.

```bash
cd cheshire-cat
```

--------------------------------

### Build Static Documentation

Source: https://github.com/cheshire-cat-ai/docs/blob/main/README.md

Generates a static version of the documentation website. The output is placed in the '/docs' directory. This process is automated via GitHub Actions but can be run locally.

```bash
mkdocs build
```

```bash
python -m mkdocs build
```

--------------------------------

### Use LLM via StrayCat Instance

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/framework/cat-components/cheshire_cat/stray_cat.md

Access the LLM directly through the 'cat' instance within a hook to generate responses. This example shows how to get a joke in German.

```python
from cat.mad_hatter.decorators import hook

@hook
def agent_fast_reply(reply, cat):
    prompt = "Say a joke in german"
    reply["output"] = cat.llm(prompt)
    return reply

```

--------------------------------

### Set CCAT_CORE_HOST Environment Variable

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/administrators/env-variables.md

Configure the host address for the Cheshire Cat Core. This is used by the Admin Portal to establish a connection. For example, set `CCAT_CORE_HOST=mywebsite.com` if your installation is served on `mywebsite.com`.

```dotenv
CCAT_CORE_HOST=mywebsite.com
```

--------------------------------

### Create a Simple Tool

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/tools.md

Define a basic tool with the `@tool` decorator. Ensure the docstring clearly explains input requirements for the LLM. Input is always a string and needs parsing.

```python
from cat.mad_hatter.decorators import tool

@tool
def convert_currency(tool_input, cat):
    """Useful to convert currencies. This tool converts euro (EUR) to dollars (USD).
     Input is an integer or floating point number."""
    
    # Define fixed rate of change
    rate_of_change = 1.07
    
    # Parse input
    eur = float(tool_input)

    # Compute USD
    usd = eur * rate_of_change

    return usd
```

--------------------------------

### Run All Tests

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/administrators/tests.md

Execute the entire test suite for the Cheshire Cat AI project. Ensure you are in the same directory as your Cat instance before running.

```bash
docker compose run --rm cheshire-cat-core python -m pytest --color=yes .
```

--------------------------------

### Add Authenticated GET Endpoint with LLM Call

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/endpoints.md

Create a GET endpoint that requires authentication and uses the LLM to generate a joke. The `cat` object provides access to framework functionalities.

```python
from cat.mad_hatter.decorators import endpoint
from cat.auth.permissions import check_permissions

@endpoint.get("/joke")
def joke(cat=check_permissions("CONVERSATION", "WRITE")):
    
    # invoking the LLM!
    return cat.llm("Tell me a short joke.")
```

--------------------------------

### Qdrant Environment Variables for .env file

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/administrators/docker-compose.md

Environment variables to configure the Cheshire Cat core to connect to a Qdrant server. Specify the host, port, and optionally an API key.

```bash
# Qdrant server
CCAT_QDRANT_HOST=cheshire_cat_vector_memory # <url of the cluster>
CCAT_QDRANT_PORT=6333 # <port of the cluster, usually 6333>
CCAT_QDRANT_API_KEY="" # optional <api-key>
```

--------------------------------

### Docker Compose for Production Stack

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

Defines services for Cheshire Cat AI core, Ollama, Qdrant, and Caddy. Ensure .env file is configured for Qdrant host and port, and HTTPS proxy mode.

```yaml
services:

  cheshire-cat-core:
    image: ghcr.io/cheshire-cat-ai/core:latest
    container_name: cheshire_cat_core
    depends_on: [ollama, qdrant]
    env_file: .env
    expose: [80]
    volumes: 
      - ./cat/static:/app/cat/static
      - ./cat/plugins:/app/cat/plugins
      - ./cat/data:/app/cat/data
    restart: unless-stopped

  ollama:
    image: ollama/ollama:latest
    container_name: ollama_cat
    volumes: [./ollama:/root/.ollama]
    expose: [11434]
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  qdrant:
    image: qdrant/qdrant:latest
    container_name: cheshire_cat_vector_memory
    expose: [6333]
    volumes: [./qdrant/storage:/qdrant/storage]
    restart: unless-stopped

  caddy:
    image: caddy:latest
    depends_on: [cheshire-cat-core]
    ports: ["80:80", "443:443", "443:443/udp"]
    volumes: 
      - ./caddy/Caddyfile:/etc/caddy/Caddyfile
      - ./caddy/data:/data
    restart: unless-stopped
```

--------------------------------

### Implement Pizza Order Form

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/forms.md

Create a custom Form by inheriting from CatForm and decorating it with @form. This includes defining the form's description, the Pydantic model, start/stop examples for LLM guidance, and the submission logic.

```python
import requests
from pydantic import BaseModel
from cat.experimental.form import CatForm, CatFormState, form

class PizzaOrder(BaseModel):
    pizza_type: str
    phone: str
    address: str


@form
class PizzaForm(CatForm):
    description = "Pizza Order"
    model_class = PizzaOrder
    start_examples = [
        "order a pizza!",
        "I want pizza"
    ]
    stop_examples = [
        "stop pizza order",
        "not hungry anymore",
    ]
    ask_confirm = True

    def submit(self, form_data):

        # Fake API call to order the pizza
        response = requests.post(
            "https://fakecallpizza/order",
            json={
                "pizza_type": form_data["pizza_type"],
                "phone": form_data["phone"],
                "address": form_data["address"]
            }
        )
        response.raise_for_status()
        
        time = response.json()["estimated_time"]

        # Return a message to the conversation with the order details and estimated time
        return {
            "output": f"Pizza order on its way: {form_data}. Estimated time: {time}"
        }
```

--------------------------------

### Overriding Agent Personality Hook (Scooby Doo Example)

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/plugins.md

Modifies the agent's default personality and behavior by overriding the `agent_prompt_prefix` hook. This example sets the AI to act like Scooby Doo.

```python
from cat.mad_hatter.decorators import hook

@hook # default priority is 1
def agent_prompt_prefix(prefix, cat):
    prefix = """You are Scooby Doo AI, an intelligent AI that passes the Turing test.
                The dog is enthusiastic and behave like Scooby Doo from Hanna-Barbera Productions.
                You answer Human using tools and context."""
    return prefix
```

--------------------------------

### Clone the Cheshire Cat AI Repository

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/advanced/contributing.md

Use this command to clone the main repository to your local machine.

```bash
git clone https://github.com/cheshire-cat-ai/core.git cheshire-cat
```

--------------------------------

### Get All Jobs

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/framework/cat-components/cheshire_cat/white_rabbit.md

Fetches a list of all currently scheduled jobs.

```APIDOC
## get_jobs()

### Description
Returns a list of all scheduled jobs.

### Parameters
None

### Returns
- **List[Dict[str, str]]** - A list of job details.
```

--------------------------------

### Get Job by ID

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/framework/cat-components/cheshire_cat/white_rabbit.md

Retrieves the details of a specific job using its unique identifier.

```APIDOC
## get_job(job_id: str)

### Description
Retrieves a job by its ID.

### Parameters
#### Path Parameters
- **job_id** (str) - Required - The ID of the job.

### Returns
- **Dict[str, str]** - Job details or None if not found.
```

--------------------------------

### Import Logging System

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/logging.md

Import the logging system from the cat.log module.

```python
from cat.log import log
```

--------------------------------

### schedule_interval_job

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/framework/cat-components/cheshire_cat/white_rabbit.md

Schedules a job to run at regular intervals. Allows specifying start and end dates for the interval.

```APIDOC
## schedule_interval_job(job, job_id: str = None, start_date: datetime = None, end_date: datetime = None, days=0, hours=0, minutes=0, seconds=0, **kwargs)

### Description
Schedules a job to run at regular intervals.

### Parameters
#### Path Parameters
- `job` (function) - Required - The function to be executed.
- `job_id` (str) - Optional - The ID of the job.
- `start_date` (datetime) - Optional - The start date of the job.
- `end_date` (datetime) - Optional - The end date of the job.
- `days` (int) - Optional - Number of days for the interval.
- `hours` (int) - Optional - Number of hours for the interval.
- `minutes` (int) - Optional - Number of minutes for the interval.
- `seconds` (int) - Optional - Number of seconds for the interval.
- `**kwargs` - Additional arguments for the job function.

### Returns
- `str` - The job ID.
```

--------------------------------

### Tool Logic for Price Lookup

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/quickstart/writing-tool.md

Implement the core logic of the tool, such as checking a dictionary for prices based on the input color and returning the corresponding price or a message if the color is not found.

```python
prices = {
    "black": 5,
    "white": 10,
    "pink": 50,
}

if color not in prices.keys():
    return f"No {color} socks"
else:
    return f"{prices[color]} €" 
```

--------------------------------

### Log Critical Message

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/logging.md

Example of logging a message at the CRITICAL level. This message will appear if CCAT_LOG_LEVEL is CRITICAL or lower.

```python
log.critical(f'user message: {user_message_json["text"]}')
```

--------------------------------

### Log Error Message

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/logging.md

Example of logging a message at the ERROR level. This message will appear if CCAT_LOG_LEVEL is ERROR or lower.

```python
log.error(f'user message: {user_message_json["text"]}')
```

--------------------------------

### Configure all Secrets in .env

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/production/auth/authentication.md

Set all necessary secrets in the .env file for comprehensive security, including API keys for HTTP and WebSocket, and the JWT secret.

```bash
CCAT_API_KEY=meow
CCAT_API_KEY_WS=meow_ws
CCAT_JWT_SECRET=meow_jwt
```

--------------------------------

### Log Warning Message

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/logging.md

Example of logging a message at the WARNING level. This message will appear if CCAT_LOG_LEVEL is WARNING or lower.

```python
log.warning(f'user message: {user_message_json["text"]}')
```

--------------------------------

### Log Info Message

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/logging.md

Example of logging a message at the INFO level. This message will appear if CCAT_LOG_LEVEL is INFO or lower.

```python
log.info(f'user message: {user_message_json["text"]}')
```

--------------------------------

### Log Debug Message

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/logging.md

Example of logging a message at the DEBUG level. This message will only appear if CCAT_LOG_LEVEL is set to DEBUG.

```python
log.debug(f'user message: {user_message_json["text"]}')
```

--------------------------------

### before_cat_bootstrap

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks.md

This hook is part of the 'Lifecycle' group and is executed before the Cheshire Cat application bootstrap process begins.

```APIDOC
## before_cat_bootstrap

### Description
Executes logic before the Cheshire Cat application bootstrap process starts.

### Method Signature
`before_cat_bootstrap()`

### Parameters
This hook has no input arguments.

### Returns
None. This hook is for executing actions before bootstrapping.
```

--------------------------------

### White Rabbit - Start Quote Feed Job

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

Schedules an interval job to periodically send random motivational quotes.

```APIDOC
## start_quote_feed Tool

### Description
Starts a feed that sends a random motivational quote at regular intervals. Quotes are scraped from `quotes.toscrape.com`.

### Method
`start_quote_feed(interval, cat)`

### Parameters
- **interval** (int): The interval in seconds between sending quotes.
- **cat**: The `StrayCat` interface.

### Response
- **string**: A confirmation message including the job ID.

### Usage Example
```python
from cat.mad_hatter.decorators import tool
import requests, re, random

@tool(return_direct=True)
def start_quote_feed(interval, cat):
    """Send a random motivational quote at regular intervals. Input is interval in seconds."""
    def scrape_and_send():
        resp = requests.get("http://quotes.toscrape.com/")
        quotes = re.findall(r'<span class="text" itemprop="text">(.*?)</span>', resp.text)
        if quotes:
            cat.send_ws_message(random.choice(quotes), msg_type="chat")

    job_id = cat.white_rabbit.schedule_interval_job(scrape_and_send, seconds=int(interval))
    return f"Quote feed started every {interval}s. Job ID: {job_id}"
```
```

--------------------------------

### Declare Plugin Dependencies

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/dependencies.md

Add a `requirements.txt` file to your plugin's root folder to specify required Python packages. Use version specifiers like `>=` for minimal requirements.

```txt
pycrypto>=2.6.1
```

--------------------------------

### Accessing Plugin Settings in a Tool

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

Demonstrates how to access plugin settings within a tool function using `cat.mad_hatter.get_plugin().load_settings()`. Handles cases where settings might not be configured.

```python
# Access settings inside a tool or hook:
@tool(return_direct=True)
def my_tool(query, cat):
    """Useful to look something up. Input is the search query."""
    settings = cat.mad_hatter.get_plugin().load_settings()
    api_key    = settings.get("api_key", "")
    max_res    = settings.get("max_results", 5)
    mood       = settings.get("bot_mood", "happy")

    if not api_key:
        return "Plugin not configured. Set API key in the admin panel."
    # ... use api_key, max_res, mood
    return f"Found results (mood={mood})"
```

--------------------------------

### Example WebSocket Message Payload

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks-reference/flow/before_cat_sends_message.md

This illustrates the structure of a typical JSON dictionary sent to the WebSocket client, including content and reasoning.

```json
{
    "type": "chat",  # type of websocket message, a chat message will appear as a text bubble in the chat
    "user_id": "user_1",  # id of the client to which the message is to be sent
    "content": "Meeeeow",  # the Cat's answer
    "why": {
        "input": "Hello Cheshire Cat!",  # user's input
        "intermediate_steps": cat_message.get("intermediate_steps"),  # list of tools used to provide the answer
        "memory": {
            "episodic": episodic_report,  # lists of documents retrieved from the memories
            "declarative": declarative_report,
            "procedural": procedural_report,
        }
    }
}
```

--------------------------------

### Environment Variables Reference for Production

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

Provides a comprehensive list of environment variables for configuring the Cheshire Cat AI runtime in a production environment, covering network, security, vector database, and debugging settings.

```bash
# .env — full production example

# --- Network ---
CCAT_CORE_HOST=mycat.example.com          # public hostname for Admin Portal
CCAT_CORE_PORT=1865                        # listening port (default 1865 = year Alice was published)
CCAT_CORE_USE_SECURE_PROTOCOLS=true        # true when behind HTTPS/WSS reverse proxy
CCAT_CORS_ALLOWED_ORIGINS=https://app.example.com  # restrict CORS origins
CCAT_HTTPS_PROXY_MODE=true                 # enable when Nginx/Caddy is terminating TLS

# --- Security ---
CCAT_API_KEY=a-very-long-alphanumeric-http-secret
CCAT_API_KEY_WS=another-very-long-alphanumeric-ws-secret
CCAT_JWT_SECRET=yet-another-very-long-jwt-secret
CCAT_JWT_ALGORITHM=HS256
CCAT_JWT_EXPIRE_MINUTES=1440

# --- Vector DB (external Qdrant) ---
CCAT_QDRANT_HOST=cheshire_cat_vector_memory
CCAT_QDRANT_PORT=6333
CCAT_QDRANT_API_KEY=qdrant-api-key

# --- Debug ---
CCAT_DEBUG=false          # disable hot-reload in production
CCAT_LOG_LEVEL=WARNING    # DEBUG | INFO | WARNING | ERROR | CRITICAL
```

--------------------------------

### White Rabbit - Nightly Update Check Hook

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

Schedules a cron job to run a nightly update check after the system has started.

```APIDOC
## after_cat_bootstrap Hook

### Description
This hook is executed after the Cat framework has finished bootstrapping. It is used here to schedule a nightly cron job for checking updates.

### Cron Job Scheduling
Schedules a job named `nightly_update_check` to run daily at 02:00.

```python
from cat.mad_hatter.decorators import hook

@hook
def after_cat_bootstrap(cat):
    def check_updates():
        # custom update logic here
        pass

    cat.white_rabbit.schedule_cron_job(
        check_updates,
        job_id="nightly_update_check",
        hour=2,
        minute=0
    )
```
```

--------------------------------

### Environment Variables for Production Stack

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

Add these variables to your .env file to configure the Cheshire Cat AI core service to connect to Qdrant and enable HTTPS proxy mode.

```bash
# .env additions for this stack
CCAT_QDRANT_HOST=cheshire_cat_vector_memory
CCAT_QDRANT_PORT=6333
CCAT_HTTPS_PROXY_MODE=true
```

--------------------------------

### Plugin Activation Hook

Source: https://context7.com/cheshire-cat-ai/docs/llms.txt

The `activated` hook is called when a plugin is enabled. This example ingests a URL from the plugin's settings into declarative memory.

```python
from cat.mad_hatter.decorators import plugin

# Assuming MySettings is defined elsewhere and loaded via settings_model()
@plugin
def activated(plugin):
    from cat.looking_glass.cheshire_cat import CheshireCat
    ccat = CheshireCat()
    settings = ccat.mad_hatter.get_plugin().load_settings()
    url = settings.get("welcome_url")
    if url:
        ccat.rabbit_hole.ingest_file(stray=ccat, file=url)
```

--------------------------------

### Summarize and Add Documents with `before_rabbithole_stores_documents` Hook

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/hooks-reference/rabbit-hole/before_rabbithole_stores_documents.md

Use this hook to process groups of documents, generate summaries, and append them to the original list before storage. Ensure the `Document` class and `cat.llm` are available in the scope.

```python
from cat.mad_hatter.decorators import hook

@hook  # default priority = 1
def before_rabbithole_stores_documents(docs, cat):
    # summarize group of 5 documents and add them along original ones
    summaries = []
    for n, i in enumerate(range(0, len(docs), 5)):
        # Get the text from groups of docs and join to string
        group = docs[i: i + 5]
        group = list(map(lambda d: d.page_content, group))
        text_to_summarize = "\n".join(group)

        # Summarize and add metadata
        summary = cat.llm(f"Provide a concide summary of the following: {group}")
        summary = Document(page_content=summary)
        summary.metadata["is_summary"] = True
        summaries.append(summary)
    
    return docs.extend(summaries)
```

--------------------------------

### Change Default Splitter

Source: https://github.com/cheshire-cat-ai/docs/blob/main/mkdocs/plugins/examples.md

Allows customization of the text splitter used by the RabbitHole, for example, to use an HTML splitter with specific chunking parameters.

```python
from cat.mad_hatter.decorators import hook

@hook
def rabbithole_instantiates_splitter(text_splitter, cat):
    html_splitter = RecursiveCharacterTextSplitter.from_language(
        language=Language.HTML, chunk_size=60, chunk_overlap=0
    )
    return html_splitter
```