Configuration

Global Options

Configure the AI provider, API keys, model, temperature and more.

Properties

The Kirby Copilot plugin can be configured globally in the config.php file of your Kirby project. All options are nested under the johannschopplich.copilot key.

config.php
return [
    'johannschopplich.copilot' => [
        // Customize Kirby Copilot
    ]
];

All possible options have reasonable defaults. Only if you want to change the default behavior, you need to add the option to your configuration.

The following list contains all available options:

provider String

The provider option defines the AI model provider that will be used to generate content across all Copilot sections. The plugin supports two providers:

  • openai (default)
  • mistral

By default, the openai provider is used. To change the provider, you can use the following configuration:

config.php
return [
    'johannschopplich.copilot' => [
        'provider' => 'mistral'
    ]
];
We will add support for other AI providers if there is enough demand.

providers Array

apiKey String

The providers option holds the configuration for each AI provider, such as the AI model to use for text generation. A valid API key is required for Kirby Copilot to make requests to the AI provider.

You can get an API key for GPT models by registering for the OpenAI API.

No API key is provided by default. Please be sure to add your API key to the configuration:

config.php
return [
    'johannschopplich.copilot' => [
        'providers' => [
            'openai' => [
                'apiKey' => 'YOUR_API_KEY'
            ]
        ]
    ]
];
It is highly recommended to create API keys for each Kirby project (and client), because the AI requests are sent from the client-side and could be abused by malicious users.

model String

The model option defines the provider model used to generate content. In the case of OpenAI, the default configuration uses the gpt-4o model:

config.php
return [
    'johannschopplich.copilot' => [
        'providers' => [
            'openai' => [
                'model' => 'gpt-4o'
            ]
        ]
    ]
];

Migrating to Kirby Copilot v1.6+
As of April 2024, OpenAI has added vision capabilities to the GPT-4 Turbo model. Following this change, the configuration for the OpenAI provider has been simplified to only include the model name.To update your configuration from Kirby Copilot v1.5 and earlier to the latest version, reduce the model configuration to only include the model name:

return [
    'johannschopplich.copilot' => [
        'providers' => [
            'openai' => [
-                'model' => [
-                    'default' => 'gpt-4-turbo-preview',
-                    'vision' => 'gpt-4-vision-preview'
-                ]
+                'model' => 'gpt-4-turbo'
            ]
        ]
    ]
];

For example, if you prefer the cheaper but less accurate gpt-3.5 model, you can change the default model:

config.php
return [
    'johannschopplich.copilot' => [
        'providers' => [
            'openai' => [
                'model' => 'gpt-3.5-turbo'
            ]
        ]
    ]
];
If you disable context files per blueprint, the vision model will never be used.

baseUrl String

The optional baseUrl option applies to the Mistral provider and lets you define the base URL of a custom Mistral API instance.

temperature Float

The temperature option defines the randomness of the generated content. The higher the temperature, the more random the generated content will be.

The default value is 0.5.

If you want the model to be more creative, you can increase the temperature:

config.php
return [
    'johannschopplich.copilot' => [
        'temperature' => 0.8
    ]
];

maxGenerationTokens Integer

The maxGenerationTokens option defines the maximum number of tokens that will be generated by the GPT model.

The default value is 1024.

If you want to generate an unlimited number of tokens, you can set the option to null.

config.php
return [
    'johannschopplich.copilot' => [
        'maxGenerationTokens' => null
    ]
];

systemPrompt String

The systemPrompt is probably the most important configuration option besides the model. It is the structural foundation of the generated content and complements the prompt that is provided by the user (userPrompt section property).

While the user prompt is intended to instruct the GPT model what to generate, the system prompt is intended to instruct the GPT model how to structure the generated content.

If you don't provide a systemPrompt, the plugin will use the following default prompt:

Provide responses in HTML format, including only the content that would go inside the <body> tags. Do not include the <head> section or any other parts of a full HTML document structure.
The system prompt can be overriden per blueprint in the section properties.

Note that the system prompt above works well for generating blocks or writer content, but it is not suitable for generating plain text content. If you want to generate plain text content, you should provide a system prompt that is suitable for plain text content:

config.php
return [
    'johannschopplich.copilot' => [
        'systemPrompt' => 'Provide responses in plain text without markup.'
    ]
];

blocksUpdateThrottle Integer

The blocksUpdateThrottle option defines the number of milliseconds that the plugin will wait before updating the blocks field with new generated content.

The default value is 250. Any value below 50 will be capped to 50.

A minimum throttle interval is required to avoid performance issues, because the HTML to blocks conversion is done via an internal API route.

Full Configuration Example

As a reference, below are all possible configuration options with their default values:

config.php
return [
    'johannschopplich.copilot' => [
        'provider' => 'openai',
        'providers' => [
            'openai' => [
                'model' => 'gpt-4o',
                'apiKey' => 'YOUR_API_KEY'
            ]
        ],
        'temperature' => 0.5,
        'maxGenerationTokens' => 1024,
        'systemPrompt' => 'Provide responses in HTML format, including only the content that would go inside the <body> tags. Do not include the <head> section or any other parts of a full HTML document structure.',
        'blocksUpdateThrottle' => 250
    ]
];