.. include:: /Includes.rst.txt .. _configuration: ============= Configuration ============= LLM provider setup ================== The Cowriter extension uses the :ref:`nr-llm extension ` for LLM provider configuration. Configure your preferred provider in the :ref:`nr-llm backend module `. Supported providers ------------------- * **OpenAI** - GPT-5.x series, o-series reasoning models * **Anthropic Claude** - Claude 4.5 Opus, Sonnet, Haiku * **Google Gemini** - Gemini 3 Pro, Flash * **OpenRouter** - Access to 100+ models from multiple providers * **Mistral** - Mistral Large, Medium, and open models * **Groq** - Ultra-fast inference with Llama, Mixtral Configuration steps ------------------- 1. Navigate to :guilabel:`Admin Tools` > :guilabel:`LLM Management` 2. Add a provider (e.g., OpenAI with your API key) 3. Create a model configuration 4. Create an LLM configuration and set it as default .. tip:: See the :ref:`nr-llm provider configuration ` for detailed provider configuration options. RTE configuration ================= There are two ways to configure the CKEditor integration: Option 1: Using the shipped preset ---------------------------------- If you don't have a custom RTE configuration, point the RTE at the preset this extension registers: 1. Go to your root page 2. Open :guilabel:`Page Properties` > :guilabel:`Page TSconfig` 3. Add this line: .. code-block:: typoscript RTE.default.preset = cowriter The preset is inherited by every page below, and brings all four toolbar items with it. .. figure:: /Images/pagetsconfig.png :alt: Page TSconfig configuration in TYPO3 v14 :class: with-border with-shadow The Page TSconfig field with ``RTE.default.preset = cowriter``. Option 2: Custom RTE configuration ---------------------------------- If you have your own RTE configuration file (:file:`your_ext/Configuration/RTE/YourConfig.yaml`), add the Cowriter module: .. code-block:: yaml editor: config: importModules: - { module: '@netresearch/t3_cowriter/cowriter', exports: ['Cowriter'] } toolbar: items: - cowriter - cowriterVision - cowriterTranslate - cowriterTemplates The four toolbar items are: ``cowriter`` Main dialog — task-based content generation with preview ``cowriterVision`` Generate image alt text via LLM vision analysis ``cowriterTranslate`` Inline translation dropdown (10 languages) ``cowriterTemplates`` Open the Cowriter dialog with a task pre-selected .. tip:: You can include only the toolbar items you need. For example, if you only want the main dialog and translation, omit ``cowriterVision`` and ``cowriterTemplates``. .. warning:: An explicit ``toolbar.items`` list REPLACES the toolbar, it does not add to it. Importing the module and then listing only ``cowriter`` gives you exactly one button — the other three are registered but have nowhere to appear. If buttons are missing, check this list before suspecting the extension. Task configuration ================== The Cowriter dialog shows :ref:`tasks ` from the nr-llm extension with ``category = 'content'``. Default tasks (Improve, Summarize, Extend, Fix Grammar, Translate EN/DE) are seeded during installation. Adding custom tasks ------------------- 1. Navigate to :guilabel:`Admin Tools` > :guilabel:`LLM Management` 2. Create a new task record with ``category = 'content'`` 3. Set a descriptive name and identifier 4. Write a prompt template using ``{{input}}`` as the placeholder for user content .. code-block:: text :caption: Example prompt template Rewrite the following text in a more engaging tone, suitable for a marketing audience. Output ONLY the rewritten text without explanations. {{input}} .. tip:: Tasks can have their own LLM configuration. If a task has no configuration assigned, the request's configuration or the default configuration is used as fallback. .. _configuration-field-suggestions: Field suggestions ================= The fields that get the :ref:`Suggest values with AI ` button are set in the extension configuration (:guilabel:`Admin Tools` > :guilabel:`Settings` > :guilabel:`Extension Configuration` > ``t3_cowriter``): .. confval:: fieldSuggestions.fields :name: t3-cowriter-fieldSuggestions-fields :type: string :default: ``pages.seo_title,pages.description,pages.keywords,pages.slug`` Comma-separated list of ``table.field``. Only single-line text fields, plain-text areas (no rich text) and slug fields are supported. A field that does not exist is skipped, so ``pages.seo_title`` only gets the button when the system extension ``seo`` is installed. An empty value switches the button off. .. confval:: fieldSuggestions.count :name: t3-cowriter-fieldSuggestions-count :type: int :default: ``3`` How many suggestions the button asks for, from 1 to 5. The server treats it as the upper bound: a request for more is answered with this many. The list is extension configuration rather than page TSconfig because the button is added to the TCA, which is the same for the whole installation. After changing either setting, flush the caches so the TCA is rebuilt. Rate limiting ============= The Cowriter enforces a rate limit of 20 requests per minute per backend user. When the limit is exceeded, the API returns HTTP 429 with a ``Retry-After`` header. Security considerations ======================= The Cowriter extension routes all LLM requests through the TYPO3 backend, ensuring that: * API keys are never exposed to the frontend * All requests are authenticated via TYPO3's backend session * Error conditions are logged for debugging .. warning:: Always configure your LLM provider's API key in the backend. Never expose API keys in frontend JavaScript or client-accessible files. Troubleshooting =============== Translation not working ----------------------- If the translate button shows "Translation failed", check: 1. An LLM provider is configured and marked as default in :guilabel:`Admin Tools` > :guilabel:`LLM Management` 2. The provider's API key is valid and not expired 3. The provider supports the ``translation`` feature 4. Check the TYPO3 system log for detailed error messages No tasks in dropdown -------------------- If the Tasks dropdown shows "No tasks configured": 1. Navigate to :guilabel:`Admin Tools` > :guilabel:`LLM Management` > :guilabel:`Tasks` 2. Create at least one task with ``category = 'content'`` 3. Make sure the task record is not hidden or deleted 4. Reload the page in the browser to refresh the task list API key rejected ---------------- If you see "The LLM provider rejected the API key": 1. Check the provider configuration in the LLM module 2. Verify the API key is correct and has not been revoked 3. Some providers require specific permissions or billing setup Rate limit exceeded ------------------- The Cowriter allows 20 requests per minute per backend user. If you hit the limit, wait a moment and try again. The ``Retry-After`` response header indicates when the limit resets.