// Copyright (C) 2024 Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial

/*!
    \page creator-qtaiassistant.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-ai

    \title Use Qt AI Assistant

    Qt AI Assistant is a coding assistant. When connected to a Large Language
    Model (LLM), it auto-completes your code, gives expert coding advice,
    suggests code fixes, as well as writes test cases and code documentation.

    \image {qtaiassistant-codecompletion.webp} {Automatic Code Completion}

    Qt AI Assistant is available for selected commercial Qt developer
    license holders. For more information on licensing, select \uicontrol Compare
    in \l{Qt pricing}.

    To learn the basics of Qt AI Assistant, take the
    \l {Qt Academy: Getting Started With Qt AI Assistant} course.

    \note The LLM itself is not in scope of the Qt AI Assistant. You need to
    connect to a third-party LLM and agree to the terms and conditions, as well
    as to the acceptable use policy of the LLM provider. By using Qt AI Assistant,
    you agree to \l{Terms & Conditions - Qt Development Framework}.

    Qt AI Assistant is currently experimental and powered by generative AI. Check
    all suggestions to make sure that they are fit for use in your project.

    \note Install and load the Qt AI Assistant extension to use it.

    \section1 Install Qt AI Assistant

    To load the Qt AI Assistant extension from the web:

    \list 1
        \li Go to the \uicontrol Extensions mode.
            \image {qtcreator-extension-mode.webp} {AI Assistant in Extensions mode}
        \li Select \uicontrol {Use external repository}.
        \li Select \uicontrol {AI Assistant}.
        \li Select \uicontrol Install.
    \endlist

    \section1 Enable code syntax highlighting in the inline chat window

    To enable code syntax highlighting in the inline chat window, go to
    \preferences > \uicontrol {Text Editor} > \uicontrol {Generic Highlighter},
    and then select \uicontrol {Download Definitions}.
    \image {qtcreator-syntax-highlighter.png} {Generic Highlighter tab in Text Editor preferences}
    For more information, see \l{Download highlight definitions}.

    \section1 Install and use Ollama

    To use LLMs running locally on your computer with the Qt AI Assistant extension,
    install Ollama. You can run models available from the Ollama selection as well
    as custom models that you add to Ollama.

    \section2 Run models on Ollama

    To run models, enter:

    \code
    ollama run <model-name>
    \endcode

    For example:

    \code
    ollama run codellama:7b-code
    \endcode

    \section2 Supported models from Ollama

    You can use the following models directly from Ollama:

    \list
        \li \c codellama:7b-code
        \li \c deepseek-coder-v2:lite
        \li \c gpt-oss:20b
        \li \c theqtcompany/codellama-7b-qml
        \li \c theqtcompany/codellama-13b-qml
    \endlist

    \section2 Custom models

    For custom models, follow the specific installation instructions for that mode.
    You can use the following custom models:

    \list
        \li \l{codellama:7b-code-qml}
        \li \l{codellama:13b-code-qml}
    \endlist

    \section1 Connect to an LLM

    You can connect to the following LLMs:

    \list
        \li Code Llama 13B QML (for Qt 6, running in a cloud deployment of your choice)
        \li Code Llama 13B (for Qt 5, running in a cloud deployment of your choice)
        \li Codestral (provided by Mistral)
        \li Claude 4.0 Sonnet (provided by Anthropic, remember that you
            need to have a token-based billing payment method configured for your
            \l{Anthropic account}.
        \li Claude 4.5 Sonnet (provided by Anthropic, remember that you
            need to have a token-based billing payment method configured for your
            \l{Anthropic account}.
        \li GPT 5 (provided by OpenAI, remember that you need to have a
            token-based billing payment method configured for your \l{OpenAI account}.
        \li DeepSeek V3.2 (provided by DeepSeek)
        \li Code Llama 13B QML through Ollama (running locally on your computer)
        \li Code Llama 7B QML through Ollama (running locally on your computer)
        \li Code Llama 7B through Ollama (running locally on your computer)
    \endlist

    To connect to an LLM:

    \list 1
        \li Go to \preferences > \uicontrol {AI Assistant} > \uicontrol General.
            \image {qtcreator-preferences-qtaiassistant-general.webp} {General tab in AI Assistant preferences}
        \li In \uicontrol LLM, select the LLM.
        \li In \uicontrol {Authentication token}, enter the API authentication
            key for the LLM.
    \endlist

    To connect to multiple LLMs and switch between them for different use cases:

    \list 1
        \li Go to \preferences > \uicontrol {AI Assistant} > \uicontrol Advanced.
            \image {qtcreator-preferences-qtaiassistant-advanced.webp} {Advanced tab in AI Assistant preferences}
        \li Select an LLM for each configurable use case.
        \li In \uicontrol {Model Configuration}, enter the API authentication
            token and server URL of each LLM. For more information on where to
            get the access information, see the third-party LLM provider documentation.
    \endlist

    \section1 Automatic code-completion

    Qt AI Assistant can help you write code by suggesting what to write next.
    It prompts the LLM to make one code suggestion when you stop typing.

    To accept the entire suggestion, select the \key Tab key.

    To accept parts of the suggestions, select \key {Alt+Right}.

    To dismiss the suggestion, select \key Esc or navigate to another position in
    the code editor.

    To interact with Qt AI Assistant using the mouse, hover over the suggestion.

    \image {qtaiassistant-codecompletionbar.webp} {Code completion tool bar when hovering over a suggestion}

    When you hover over a suggestion, you can accept parts of the suggested code
    snippet word-by-word or line-by-line.

    To close the code completion bar, select the \key Esc key or move the cursor
    to another position.

    To select the model for code completion, go to \preferences >
    \uicontrol {AI Assistant} > \uicontrol General.

    In \uicontrol General, you can also turn auto-completion of code on or off
    globally for all projects. Qt AI Assistant consumes a significant number of
    tokens from the LLM. To cut costs, turn off the auto-completion feature when
    not needed, and use keyboard shortcuts for code completion.

    \section1 Complete code from the keyboard

    To trigger code suggestions manually, select \key {Ctrl+'}.

    \section1 Enter prompts and smart commands

    In an inline prompt window in the text editor, you can prompt the assistant
    to implement your requests in human language, ask questions, or execute
    \e {smart commands}. To open the chat, select \key {Ctrl+Shift+A}.
    Alternatively, to open the inline prompt window, you can select code
    and then select \inlineimage {icons/ai-assistant.png} {AI Assistant}.

    To close the inline prompt window, select \key Esc or
    \inlineimage {icons/close.png} {Close}.

    To go to Qt AI Assistant preferences from the inline prompt window, select
    \imagesettings (\uicontrol {Preferences}). There, you can set the model
    to use for prompts and code reviews.

    \section2 Request suggestions using human language

    To request suggestions using human language, enter your requests into the
    input field. If you have highlighted code, the AI assistant adds it as
    context to the prompt. Qt AI Assistant shows a suggestion that you can
    copy to the clipboard by selecting \uicontrol Copy in the inline prompt
    window.

    \section2 Request code review

    To review code with Qt AI Assistant:

    \list 1
        \li Highlight code in the code editor.
        \li Open the inline prompt window.
        \li Select the \uicontrol {/review} smart command.
    \endlist

    Qt AI Assistant reviews the code and suggests improvements. It uses
    \l {qmllint}{QML Lint} to review QML code if \uicontrol {Enable QML linter}
    is on in \preferences > \uicontrol {AI Assistant} > \uicontrol General.

    \section2 Request test cases in Qt Test syntax

    To write test cases with Qt AI Assistant:

    \list 1
        \li Highlight code in the code editor.
        \li Open the inline prompt window.
        \li Select the \uicontrol {/qtest} smart command.
    \endlist

    Qt AI Assistant generates a test case in \l{Qt Test} format that you can copy
    and paste to your \l{Create Qt tests}{Qt test project}.

    To run the generated \l{Qt Test} cases, configure your \c CMakeLists.txt files
    and \c main.cpp file.

    \section3 Configure the main project \c CMakeLists.txt

    \list 1
        \li Define your module as both a library and a QML module. The URI value
        determines the import name used in TestCase scripts:
        \code
        qt_add_library({module_name} STATIC)
        qt_add_qml_module({module_name}
            URI {module_name}
            VERSION 1.0
            QML_FILES
                    Main.qml
        )
        \endcode
        \li Add the auto-generated plugin to your target's link libraries. The
        plugin name follows the pattern \e <module_name>plugin:
        \code
        target_link_libraries({project}
            PRIVATE Qt6::Quick {module_nameplugin}
        )
        \endcode
        \li Add \c QML_IMPORT_PATH at the end of the file to ensure the QML engine
        can locate your module:
        \code
        set(QML_IMPORT_PATH ${CMAKE_BINARY_DIR} CACHE STRING "" FORCE)
        \endcode
    \endlist

    \section3 Configure the test project \c CMakeLists.txt

    Link the plugin to your test target (\e test_directory):

    \code
    target_link_libraries({test_directory} PRIVATE Qt${QT_VERSION_MAJOR}::QuickTest {module_nameplugin})
    \endcode

    \section3 Configure the main project \c main.cpp

    To load your QML component from the registered module, use \c loadFromModule():

    \code
    engine.loadFromModule("{module_name}", "Main");
    \endcode

    \section3 Configure external test projects

    If the test project is outside the main project:

    \list 1
        \li Add the main project as a subdirectory in the test project \c CMakeLists.txt:
        \code
        add_subdirectory(../{main_project_directory} ${CMAKE_BINARY_DIR}/{main_project_directory})
        \endcode
        \li Set the QML import path so Qt can find the module:
        \code
        set_target_properties({test_directory} PROPERTIES
            QT_QML_IMPORT_PATH "${CMAKE_BINARY_DIR}/{main_project_directory}"
        )
        \endcode
    \endlist

    Rebuild the projects.

    \section2 Request code documentation in Markdown format

    To create code documentation:

    \list 1
        \li Highlight code in the code editor.
        \li Open the inline prompt window.
        \li Select the \uicontrol {/doc} smart command.
    \endlist

    Qt AI Assistant generates code documentation in a format that you can copy
    and paste to your documentation file.

    \section2 Request fixing of code

    To request a fix to your code:

    \list 1
        \li Highlight code in the code editor.
        \li Open the inline prompt window.
        \li Select the \uicontrol {/fix} smart command.
        \li Optionally, apply the changes to the code.
    \endlist

    Qt AI Assistant suggests a fix that you can apply to your code.

    \section2 Request explaining of code

    To request an explanation of existing code:

    \list 1
        \li Highlight code in the code editor.
        \li Open the inline prompt window.
        \li Select the \uicontrol {/explain} smart command.
    \endlist

    Qt AI Assistant provides an explanation of the highlighted code.

    \section2 Add inline comments

    To add inline comments to existing code with Qt AI Assistant:

    \list 1
        \li Highlight code in the code editor.
        \li Open the inline prompt window.
        \li Select the \uicontrol {/inlinecomments} smart command.
        \li Optionally, apply the comments to your code.
    \endlist

    Qt AI Assistant adds inline comments that you can apply to your code.

    \sa {Install extensions}, {Activate extensions}, {Use AI}{How to: Use AI}
*/
