.. container::

   .. figure:: Documentation/Images/Screenshots/ErrorPage.png
      :alt: Error page screenshot

      Error page screenshot

   .. rubric:: TYPO3 extension ``solver``
      :name: typo3-extension-solver

   | |Coverage| |Maintainability| |Tests| |CGL| |Release| |License|
   | |Version| |Downloads| |Supported TYPO3 versions| |Extension
     stability| |Slack|

   📦 \ `Packagist <https://packagist.org/packages/eliashaeussler/typo3-solver>`__
   \| 🐥 \ `TYPO3 extension
   repository <https://extensions.typo3.org/extension/solver>`__ \|
   💾 \ `Repository <https://github.com/eliashaeussler/typo3-solver>`__
   \| 🐛 \ `Issue
   tracker <https://github.com/eliashaeussler/typo3-solver/issues>`__

An extension for TYPO3 CMS to solve exceptions with AI generated
solutions. It uses the `OpenAI PHP
client <https://github.com/openai-php/client>`__ to send a prompt to a
configured model and uses the responded completion as solution. Several
completion attributes (model, tokens, temperature, number of
completions) are configurable. It also provides a console command to
solve problems from command line.

🚀 Features
----------

-  Extended exception handler with AI generated solutions
-  Configurable AI completion attributes (model, tokens, temperature,
   number of completions)
-  Caching integration for solved problems
-  Command to solve problems from command line
-  Customizable solution providers and prompts
-  Compatible with TYPO3 11.5 LTS and 12.2

🔥 Installation
--------------

Via Composer:

.. code:: bash

   composer require eliashaeussler/typo3-solver

Or download the zip file from `TYPO3 extension repository
(TER) <https://extensions.typo3.org/extension/solver>`__.

📂 Configuration
---------------

API key
~~~~~~~

You need an `API key <https://platform.openai.com/account/api-keys>`__
to perform requests at OpenAI. Once generated, the key must be
configured in the extension configuration.

Extension configuration
~~~~~~~~~~~~~~~~~~~~~~~

The following extension configuration is available:

+---------+-----------------------------------+-----------------------+
| Configu | Description                       | Default value         |
| ration  |                                   |                       |
+=========+===================================+=======================+
| ``provi | FQCN of the solution provider     | ```EliasHaeussler\Typ |
| der``   |                                   | o3Solver\Solution\Pro |
|         |                                   | vider\OpenAISolutionP |
|         |                                   | rovider`` <Classes/Pr |
|         |                                   | oblemSolving/Solution |
|         |                                   | /Provider/OpenAISolut |
|         |                                   | ionProvider.php>`__   |
+---------+-----------------------------------+-----------------------+
| ``promp | FQCN of the prompt generator      | ```EliasHaeussler\Typ |
| t``     |                                   | o3Solver\Prompt\Defau |
|         |                                   | ltPrompt`` <Classes/P |
|         |                                   | roblemSolving/Solutio |
|         |                                   | n/Prompt/DefaultPromp |
|         |                                   | t.php>`__             |
+---------+-----------------------------------+-----------------------+
| ``ignor | Comma-separated list of exception | –                     |
| edCodes | codes to ignore                   |                       |
| ``      |                                   |                       |
+---------+-----------------------------------+-----------------------+
| ``api.k | `API key <#api-key>`__ for OpenAI | –                     |
| ey``    | requests                          |                       |
+---------+-----------------------------------+-----------------------+
| ``attri | `OpenAI                           | ``text-davinci-003``  |
| butes.m | model <https://platform.openai.co |                       |
| odel``  | m/docs/models>`__                 |                       |
|         | to use (see `List available       |                       |
|         | models <#list-available-models>`_ |                       |
|         | _                                 |                       |
|         | to show a list of available       |                       |
|         | models)                           |                       |
+---------+-----------------------------------+-----------------------+
| ``attri | `Maximum number of                | ``300``               |
| butes.m | tokens <https://platform.openai.c |                       |
| axToken | om/docs/api-reference/completions |                       |
| s``     | /create#completions/create-max_to |                       |
|         | kens>`__                          |                       |
|         | to use per request                |                       |
+---------+-----------------------------------+-----------------------+
| ``attri | `Temperature <https://platform.op | ``0.5``               |
| butes.t | enai.com/docs/api-reference/compl |                       |
| emperat | etions/create#completions/create- |                       |
| ure``   | temperature>`__                   |                       |
|         | to use for completion requests    |                       |
|         | (must be a value between ``0``    |                       |
|         | and ``1``)                        |                       |
+---------+-----------------------------------+-----------------------+
| ``attri | `Number of                        | ``1``                 |
| butes.n | completions <https://platform.ope |                       |
| umberOf | nai.com/docs/api-reference/comple |                       |
| Complet | tions/create#completions/create-n |                       |
| ions``  | >`__                              |                       |
|         | to generate for each prompt       |                       |
+---------+-----------------------------------+-----------------------+
| ``cache | Lifetime in seconds of the        | ``86400`` (1 day)     |
| .lifeti | solutions cache (use ``0`` to     |                       |
| me``    | disable caching)                  |                       |
+---------+-----------------------------------+-----------------------+

⚡ Usage
-------

Exception handler
~~~~~~~~~~~~~~~~~

The extension provides a modified debug exception handler in
```Error/AiSolverExceptionHandler`` <Classes/Error/AiSolverExceptionHandler.php>`__.
It can be activated in the system configuration (aka
``LocalConfiguration.php``):

.. code:: php

   # config/system/settings.php

   return [
       'SYS' => [
           'debugExceptionHandler' => 'EliasHaeussler\\Typo3Solver\\Error\\AiSolverExceptionHandler',
       ],
   ];

Once configured, the exception handler tries to provide a solution for
the current exception and shows it on the exception page.

Solve a problem on the command line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Next to the exception handler integration, one can also explicitly solve
problems using the provided console command ``solver:solve``.

.. code:: bash

   vendor/bin/typo3 solver:solve <problem> [--code=CODE] [--file=FILE] [--line=LINE] [--refresh] [--json]

The following input parameters are available:

+------------+---------------------------------------------------------+
| Parameter  | Description                                             |
+============+=========================================================+
| ``problem` | The exception message to solve                          |
| `          |                                                         |
+------------+---------------------------------------------------------+
| ``--code`` | Optional exception code                                 |
| ,          |                                                         |
| ``-c``     |                                                         |
+------------+---------------------------------------------------------+
| ``--file`` | Optional file where the exception occurs                |
| ,          |                                                         |
| ``-f``     |                                                         |
+------------+---------------------------------------------------------+
| ``--line`` | Optional line number within the given file              |
| ,          |                                                         |
| ``-l``     |                                                         |
+------------+---------------------------------------------------------+
| ``--refres | Refresh a cached solution (requests a new solution and  |
| h``,       | ignores the cached solution)                            |
| ``-r``     |                                                         |
+------------+---------------------------------------------------------+
| ``--json`` | Print solution as JSON                                  |
| ,          |                                                         |
| ``-j``     |                                                         |
+------------+---------------------------------------------------------+

List available models
~~~~~~~~~~~~~~~~~~~~~

The command ``solver:list-models`` can be used to list all available
models for the configured OpenAI API key.

.. code:: bash

   vendor/bin/typo3 solver:list-models

💡 All available models are listed in the `OpenAI
documentation <https://platform.openai.com/docs/models>`__.

Flush solution cache
~~~~~~~~~~~~~~~~~~~~

Every solution is cached to reduce the amount of requests sent by the
OpenAI client. In order to flush the solution cache or remove single
cache entries, the command ``solver:cache:flush`` cam be used.

.. code:: bash

   vendor/bin/typo3 solver:cache:flush [<identifier>]

The following input parameters are available:

============== ========================================================
Parameter      Description
============== ========================================================
``identifier`` Optional cache identifier to remove a single cache entry
============== ========================================================

💎 Credits
---------

The extension icon (“lightbulb-on”) is a modified version of the
original
```actions-lightbulb-on`` <https://typo3.github.io/TYPO3.Icons/icons/actions/actions-lightbulb-on.html>`__
icon from TYPO3 core. In addition, the icons
```actions-calendar`` <https://typo3.github.io/TYPO3.Icons/icons/actions/actions-calendar.html>`__,
```actions-cpu`` <https://typo3.github.io/TYPO3.Icons/icons/actions/actions-cpu.html>`__,
```actions-debug`` <https://typo3.github.io/TYPO3.Icons/icons/actions/actions-debug.html>`__
and
```actions-exclamation-triangle-alt`` <https://typo3.github.io/TYPO3.Icons/icons/actions/actions-exclamation-triangle-alt.html>`__
from TYPO3 core are used. All icons are originally licensed under `MIT
License <https://github.com/TYPO3/TYPO3.Icons/blob/main/LICENSE>`__.

This project is highly inspired by the article
```Fix your Laravel exceptions with AI`` <https://beyondco.de/blog/ai-powered-error-solutions-for-laravel>`__
by `Marcel Pociot <https://pociot.dev/>`__.

In addition, I’d like to thank `Nuno Maduro <https://nunomaduro.com/>`__
and all contributors of the
```openai-php/client`` <https://github.com/openai-php/client>`__ library
for this beautiful piece of code.

⭐ License
---------

This project is licensed under `GNU General Public License 2.0 (or
later) <LICENSE.md>`__.

.. |Coverage| image:: https://codecov.io/gh/eliashaeussler/typo3-solver/branch/main/graph/badge.svg?token=fj60tJlnHW
   :target: https://codecov.io/gh/eliashaeussler/typo3-solver
.. |Maintainability| image:: https://api.codeclimate.com/v1/badges/1dd3e21a767e5ffb03cf/maintainability
   :target: https://codeclimate.com/github/eliashaeussler/typo3-solver/maintainability
.. |Tests| image:: https://github.com/eliashaeussler/typo3-solver/actions/workflows/tests.yaml/badge.svg
   :target: https://github.com/eliashaeussler/typo3-solver/actions/workflows/tests.yaml
.. |CGL| image:: https://github.com/eliashaeussler/typo3-solver/actions/workflows/cgl.yaml/badge.svg
   :target: https://github.com/eliashaeussler/typo3-solver/actions/workflows/cgl.yaml
.. |Release| image:: https://github.com/eliashaeussler/typo3-solver/actions/workflows/release.yaml/badge.svg
   :target: https://github.com/eliashaeussler/typo3-solver/actions/workflows/release.yaml
.. |License| image:: http://poser.pugx.org/eliashaeussler/typo3-solver/license
   :target: LICENSE.md
.. |Version| image:: https://shields.io/endpoint?url=https://typo3-badges.dev/badge/solver/version/shields
   :target: https://extensions.typo3.org/extension/solver
.. |Downloads| image:: https://shields.io/endpoint?url=https://typo3-badges.dev/badge/solver/downloads/shields
   :target: https://extensions.typo3.org/extension/solver
.. |Supported TYPO3 versions| image:: https://shields.io/endpoint?url=https://typo3-badges.dev/badge/solver/typo3/shields
   :target: https://extensions.typo3.org/extension/solver
.. |Extension stability| image:: https://shields.io/endpoint?url=https://typo3-badges.dev/badge/solver/stability/shields
   :target: https://extensions.typo3.org/extension/solver
.. |Slack| image:: https://img.shields.io/badge/slack-%23ext--solver-4a154b?logo=slack
   :target: https://typo3.slack.com/archives/C04Q3440HS6