Add documentation about the Qiskit Code Assistant (#1931)

1st draft for documentation about the Qiskit Code Assistant. Should fix
#1930

Considerations:
- Rough draft, feel free to edit or give any feedback
- I'm not sure if we should split the documentation in 2 parts: one for
JupyterLab extension and another one for the VSCode extension
- I'm not sure the where the Qiskit Code Assistant should be placed in
the TOC
- I added content that depends on #1918

---------

Co-authored-by: Rebecca Dimock <[email protected]>
Co-authored-by: Rebecca Dimock <[email protected]>
Co-authored-by: Eric Arellano <[email protected]>

docs/guides/_toc.json

@@ -476,9 +476,26 @@
               "url": "/guides/serverless-port-code"
             }
           ]
+        },
+        {
+          "title": "Qiskit Code Assistant",
+          "children": [
+            {
+              "title": "Qiskit Code Assistant overview",
+              "url": "/guides/qiskit-code-assistant"
+            },
+            {
+              "title": "Use Qiskit Code Assistant in JupyterLab",
+              "url": "/guides/qiskit-code-assistant-jupyterlab"
+            },
+            {
+              "title": "Use Qiskit Code Assistant in VSCode",
+              "url": "/guides/qiskit-code-assistant-vscode"
+            }
+          ]
         }
       ],
       "collapsible": false
     }
   ]
-}
+}

docs/guides/qiskit-code-assistant-jupyterlab.mdx

@@ -0,0 +1,128 @@
+---
+title: Use the Qiskit Code Assistant in JupyterLab
+description: How to install, use, and configure the Qiskit Code Assistant in JupyterLab.
+---
+
+# Use the Qiskit Code Assistant in JupyterLab
+
+Learn how to install, use, configure, and uninstall the official Qiskit Code Assistant extension in JupyterLab.
+
+<Admonition type="note" title="Notes">
+    - This is an experimental feature available only to IBM Quantum&trade; Premium Plan users.
+    - The Qiskit Code Assistant is in preview release status and is subject to change.
+    - If you have feedback or want to contact the developer team, use the [Qiskit Slack Workspace channel](https://qiskit.enterprise.slack.com/archives/C07LYA6PL83) or the related public GitHub repositories.
+</Admonition>
+
+
+<video title="A user uses the Qiskit Code Assistant in JupyterLab. The user has a comment in the code to get the available backends for their account in IBM Quantum, the Qiskit Code Assistant gives a code suggestion to get the available backends. The user executes the code, gets the available backends in IBM Quantum Platform for the current account. The user asks the Qiskit Code Assistant to generate the code to get the T1, T2 and other properties for the qubit 1 in the device ibm_brisbane. The assistant gives a code suggestion. The user runs the suggested code and gets the desired output." className="max-w-auto h-auto" controls>
+  <source src="/videos/guides/qiskit-code-assistant/demo-JupyterLab-t1t2-granite-8b-qiskit-short.mp4" type="video/mp4"></source>
+</video>
+
+## Install the JupyterLab extension
+To install the [JupyterLab extension](https://github.com/Qiskit/qiskit-code-assistant-jupyterlab), run the following command from a terminal:
+
+```sh
+pip install qiskit-code-assistant-jupyterlab
+```
+
+After installing the extension, start JupyterLab:
+
+```sh
+jupyter lab
+```
+
+The extension loads automatically and is listed on the bottom of the JupyterLab window.
+
+![Screenshot of the bar on the bottom of JupyterLab.](/images/guides/qiskit-code-assistant/jupyterlab-selected-model.png)
+
+Refer to the [JupyterLab documentation.](https://jupyterlab.readthedocs.io/en/latest/) for help working with JupyterLab
+
+## Configure extension settings
+
+It is recommended that you edit the following JupyterLab settings by going to Settings -> Settings Editor:
+
+- Click **Inline Completer**, find "Show widget" and choose **Always**.  This means that the the inline completer widget will always be shown so you can cycle through and select a completion item.
+
+- Click **Code Completion** and increase the value for "Default timeout for a provider." to `10000` or 10 seconds. The default value is 1 second, but the Qiskit Code Assistant API might take longer than this to find a suggstion. This setting only applies to the standard context menu that is invoked with `Tab`. The inline completer has a default of 10 seconds.
+
+Other settings you might want to change:
+
+- Keyboard shortcuts can be changed from Settings > Settings Editor > Keyboard Shortcuts.
+
+- You can change the IBM Quantum API token to use in the JupyterLab command palette. To do that, type `Alt` + `Shift` + `C`, search for `qiskit`, select the **Qiskit Code Assistant: Set IBM Quantum API token** command, and paste in your token.
+
+- [Advanced] To change the instance of the Qiskit Code Assistant Service that the extension should use, edit the Qiskit Code Assistant `serviceUrl` setting.
+
+- [Advanced] Keyboard shortcuts can be changed by searching for `completer` in the Keyboard Shortcuts settings (Settings -> Settings Editor -> Keyboard Shortcuts) and adding new shortcuts for the relevant commands.
+
+## Get started using the Qiskit Code Assistant extension for JupyterLab
+
+### Authentication and setup
+
+After installing the extension, it tries to authenticate you. By default, the package tries to authenticate to IBM Quantum services with the defined Qiskit API token, and uses your token from the `QISKIT_IBM_TOKEN` environment variable or from the file `~/.qiskit/qiskit-ibm.json` (under the section `default-ibm-quantum`). If you need help configuring your account, follow the instructions in [Set up to use IBM Quantum Platform.](/guides/setup-channel#set-up-to-use-ibm-quantum-platform)
+
+By default, the extension uses the `granite-8b-qiskit` model, which is listed in the Model Picker in the bottom status bar.
+
+![The bottom status bar is shown, with `granite-8b-qiskit` listed.](/images/guides/qiskit-code-assistant/vscode-selected-model.png)
+
+The first time you use the `granite-8b-qiskit` model a modal opens, listing some major restrictions that you should be aware of when using the model. Clicking `Accept` will accept the disclaimer and enable the model for code generation.
+
+![The window that opens upon first use contains restrictions tha must be accepted.](/images/guides/qiskit-code-assistant/eula.png)
+
+### Generate Code
+
+While you develop your code using Qiskit, you can ask to the Qiskit Code Assistant to help you. In general, the assistant suggests better code as response to Python comments or docstrings, but you can use the assistant anywhere in your file.
+
+In JupyterLab, there are two ways to use the code autocompletion: inline or in a context menu.
+
+Inline autocomplettion can be triggered by using the following key strokes:
+
+- `Alt` + `.` or `Alt` + `\` runs autocomplete at the current cursor location.
+- `Alt` + `[` and `Alt` + `]` can be used to cycle through the list of suggestions if there are
+  more than one.
+- `Alt` + `Tab` or `Alt` + `END` accepts the suggested code and inserts it at the current
+  cursor location.
+
+Additionally, after the assistant runs, you can use the buttons on the widget to cycle or accept the suggestion:
+
+![The popup pane with buttons is shown.](/images/guides/qiskit-code-assistant/jupyterlab-inline-complete.png)
+
+<Admonition type="note">
+The service can sometimes take a few seconds to return a suggestion, you can see when the service is working by checking the status bar.
+</Admonition>
+
+Jupyterlab also includes a traditional suggestion context menu. Use the `Tab` key to run and display the context menu.
+
+The context menu includes suggestions from JupyterLab in addition to the Qiskit Code Assistant suggestions. The context menu also sanitizes and trims the suggestions, making it less useful for reviewing the code suggestion before inserting it.
+
+![The context menu is shown, with suggested code from Qiskit, as well as suggestions from JupyterLab.](/images/guides/qiskit-code-assistant/jupyterlab-tab-complete.png)
+
+## Uninstall the JupyterLab extension
+
+
+To remove the Qiskit Code Assistant extension from JupyterLab, run:
+
+```bash
+pip uninstall qiskit_code_assistant_jupyterlab
+```
+
+## Troubleshooting
+
+If you are seeing the frontend extension but it is not working, check that the server
+extension is enabled:
+
+```bash
+jupyter server extension list
+```
+
+If the server extension is installed and enabled, but you are not seeing the frontend
+extension, check the frontend extension is installed:
+
+```bash
+jupyter labextension list
+```
+
+
+## Contribute to the JupyterLab extension
+
+The code for this extension is publicly available and open source. Check it out in [GitHub.](https://github.com/Qiskit/qiskit-code-assistant-jupyterlab)

docs/guides/qiskit-code-assistant-vscode.mdx

@@ -0,0 +1,93 @@
+---
+title: Use the Qiskit Code Assistant in VSCode
+description: How to install, use, and configure the Qiskit Code Assistant in Visual Studio Code (VSCode).
+---
+
+# Use the Qiskit Code Assistant in Visual Studio Code
+
+Learn how to install, use, configure and uninstall the official Qiskit Code Assistant extension in Visual Studio Code (VSCode).
+
+<Admonition type="note" title="Notes">
+    - This is an experimental feature available only to IBM Quantum&trade; Premium Plan users.
+    - The Qiskit Code Assistant is in preview release status and is subject to change.
+    - If you have feedback or want to contact the developer team, use the [Qiskit Slack Workspace channel](https://qiskit.enterprise.slack.com/archives/C07LYA6PL83) or the related public GitHub repositories.
+</Admonition>
+
+
+<video title="A user uses the Qiskit Code Assistant in Visual Studio Code. The user has previous imports and a function definition called get_random_linear_function, with a docstring defining what the function should do. After typing the Ctrl and . keys, the Qiskit Code Assistant autocompletes the function with the code to generate a random linear function using Numpy and Qiskit. The video ends with the user executing the code generated and getting a matrix representing a random linear function in the terminal." className="max-w-auto h-auto" controls>
+  <source src="/videos/guides/qiskit-code-assistant/demo-Vscode-RandomLinearFunction_8b-qiskit.mp4" type="video/mp4"></source>
+</video>
+
+## Install the VSCode extension
+
+To install the [VSCode extension](https://github.com/Qiskit/qiskit-code-assistant-vscode), follow these steps:
+
+1. Launch VS Code.
+1. Click the Extensions icon in the left toolbar.
+1. Search for `qiskit-vscode`
+1. Find "Qiskit Code Assistant" and click **Install**.
+
+The extension is also available through the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=qiskit.qiskit-vscode).
+
+After installing, reload the extension/IDE (typically, VSCode will prompt you to do this automatically). When it's ready, you will see "Qiskit Code Assistant" listed on the bottom of the VS Code window:
+
+![Qiskit Code Assistant is shown on the bottom of the VS Code window.](/images/guides/qiskit-code-assistant/vscode-selected-model.png)
+
+## Configure extension settings
+
+The following settings can be configured:
+
+- To change keyboard shortcuts, open the Keyboard Shortcuts settings (`Cmd/Ctrl+Shift+P` -> `Preferences: Open Keyboard Shortcuts`) and search for `qiskit-vscode`.
+
+- You can change the IBM Quantum API token to use in the VSCode command palette. To do that, type `Cmd/Ctrl+Shift+P`, search for `qiskit`, select the **Qiskit Code Assistant: Set IBM Quantum API token** command, and paste your IBM Quantum API token.
+
+- [Advanced] To change the instance of the Qiskit Code Assistant Service that the extension should use, go to File > Preferences > Settings > User Settings and edit the `Qiskit Code Assistant: Url`.
+
+## Get started using the Qiskit Code Assistant extension for VSCode
+
+
+### Authentication and setup
+
+After installing the extension, it tries to authenticate you. By default, the package tries to authenticate to IBM Quantum services with the defined Qiskit API token, and uses your token from the `QISKIT_IBM_TOKEN` environment variable or from the file `~/.qiskit/qiskit-ibm.json` (under the section `default-ibm-quantum`). If you need help configuring your account, follow the instructions in [Set up to use IBM Quantum Platform.](/guides/setup-channel#set-up-to-use-ibm-quantum-platform)
+
+By default, the extension uses the `granite-8b-qiskit` model, which is listed in the Model Picker in the bottom status bar.
+
+![The bottom status bar is shown, with `granite-8b-qiskit` listed.](/images/guides/qiskit-code-assistant/vscode-selected-model.png)
+
+The first time you use the `granite-8b-qiskit` model, a modal opens listing some major restrictions that you should be aware of when using the model. Clicking `Accept` will accept the disclaimer and enable the model for code generation.
+
+![The window that opens upon first use contains restrictions tha must be accepted.](/images/guides/qiskit-code-assistant/eula.png)
+
+### Generate Code
+After accepting the EULA, you can open a new file and start coding. To get a code suggestion, type `Ctrl` + `.` as shown:
+
+![A code suggestion is shown.  The suggested code is in grey.](/images/guides/qiskit-code-assistant/vscode-inline-suggestion.png)
+
+Press the `Tab` key to accept the model-generated suggestion or press the `ESC` key to reject it.
+
+<Admonition type="tip" title="Tips for working with code suggestions">
+- Type `Ctrl` + `.` again to generate additional suggestions.
+- When a suggestion is shown, you can use `Alt/Option` + `]` and `Alt/Option + `[` to cycle forward and backward, respectively, through the suggestions (if available).
+- You can hover the cursor over the suggestion to use the pop-up toolbar to cycle through the suggestions, as shown:
+  ![The toolbar that pops up if you hover over suggested code is shown.](/images/guides/qiskit-code-assistant/vscode-inline-suggestion-toolbar.png)
+</Admonition>
+
+## Uninstall the VSCode extension
+
+To remove the Qiskit Code Assistant from VSCode, follow these steps:
+
+1. Launch Visual Studio Code.
+1. Click the Extensions icon.
+1. Search for `qiskit-vscode`.
+1. Click **Uninstall** for the "Qiskit Code Assistant".
+
+
+## Troubleshooting
+
+If you are not seeing the extension status bar in VSCode, check that the extension is installed and enabled under the extensions tab.
+
+If the extension is installed and enabled, but cannot select a model, verify that your current API Token has been added and the `Qiskit Code Assistant: Url` is properly set.
+
+## Contribute to the VSCode extension
+
+The code for this official extension is publicly available and open source. Check it out in [github.](https://github.com/Qiskit/qiskit-code-assistant-vscode)

docs/guides/qiskit-code-assistant.mdx

@@ -0,0 +1,76 @@
+---
+title: Qiskit Code Assistant
+description: Learn how to use Qiskit Code Assistant, a generative AI code assistant.
+---
+
+# Qiskit Code Assistant
+
+The Qiskit Code Assistant aims to make quantum computing more accessible to new Qiskit adopters and to improve the coding experience for current users. It is a generative AI code assistant powered by [watsonx](https://www.ibm.com/products/watsonx-ai). It is trained using millions of text tokens from Qiskit SDK v1.x, years of Qiskit code examples and IBM Quantum™ features. The Qiskit Code Assistant can help your quantum development workflow by offering LLM-generated suggestions based on [IBM Granite 8B Code,](https://www.ibm.com/products/watsonx-ai/foundation-models) which incorporate the latest features and functionalities from IBM®.
+
+<Admonition type="note" title="Notes">
+    - This is an experimental feature available only to IBM Quantum Premium Plan users.
+    - The Qiskit Code Assistant is in preview release status and is subject to change.
+    - If you have feedback or want to contact the developer team, use the [Qiskit Slack Workspace channel](https://qiskit.enterprise.slack.com/archives/C07LYA6PL83) or the related public GitHub repositories.
+</Admonition>
+
+<video title="A user uses the Qiskit Code Assistant in JupyterLab. The user has a comment in the code to get the available backends for their account in IBM Quantum. The Qiskit Code Assistant gives a code suggestion to get the available backends. The user executes the code, gets the available backends in IBM Quantum Platform for the current account. The user ask to the Qiskit Code Assistant to generate the code to get the T1, T2 and other properties for the qubit 1 in the device ibm_brisbane. The assistant gives a code suggestion. The user runs the suggested code and gets the desired output." className="max-w-auto h-auto" controls>
+  <source src="/videos/guides/qiskit-code-assistant/demo-JupyterLab-t1t2-granite-8b-qiskit-short.mp4" type="video/mp4"></source>
+</video>
+
+## Features
+
+The following features are included in the [Visual Studio Code](https://code.visualstudio.com/) (VSCode) and [JupyterLab.](https://jupyterlab.readthedocs.io/en/latest/) extensions:
+
+* Accelerates Qiskit code generation by leveraging generative AI based on the `granite-8b-qiskit` model.
+* Allows abstract and specific prompts to generate recommendations.
+* Presents suggestions that you can review, accept, or reject.
+* Supports Python code and Jupyter notebook files.
+* Includes guardrails to avoid answering questions that represent a potential risk for users, such as hateful speech.
+
+For instructions to integrate Qiskit Code Assistant directly into your development environment, follow the instructions in the appropriate topic:
+- [JupyterLab](/guides/qiskit-code-assistant-jupyterlab)
+- [VSCode](/guides/qiskit-code-assistant-vscode)
+
+## The Large Language Model (LLM) behind the Qiskit Code Assistant
+
+To provide code suggestions, the Qiskit Code Assistant uses a Large Language Model (LLM). In this case, the Qiskit Code Assistant relies on the model `granite-8b-qiskit`, built on the IBM [granite-8b-code model.](https://github.com/ibm-granite/granite-code-models) The `granite-8b-qiskit` model improves the `granite-8b-code` model's code generation capabilities for Qiskit through extended pretraining and fine-tuning it on high-quality Qiskit data, as well as Python commits and chat. For more information about the IBM Granite models family, refer to [Granite Code Models: A Family of Open Foundation Models for Code Intelligence.](https://arxiv.org/abs/2405.04324) For more details about the `granite-.*-qiskit` models, see [Qiskit Code Assistant: Training LLMs for generating Quantum Computing Code.](https://arxiv.org/abs/2405.19495)
+
+The model `granite-8b-qiskit` model is expected to be open source soon.
+
+## The Qiskit HumanEval benchmark
+
+To test the `granite-8b-qiskit` model, we are creating, in collaboration with Qiskit Advocates and experts, a new execution-based benchmark called Qiskit HumanEval (QHE). This benchmark is similar to [HumanEval](https://arxiv.org/abs/2107.03374), including multiple challenging code problems to solve, all based on the official Qiskit libraries.
+
+The benchmark is composed of approximately 150 tests, each one made from a function definition, followed by a docstring that details the task the model is required to solve. Each example also includes a reference canonical solution, as well as unit tests, to evaluate the correctness of the generated solutions. There are three levels of difficulty for tests: basic, intermediate, and difficult.
+
+
+The dataset for the Qiskit HumanEval is expected to be open source soon.
+
+
+## More information and citations
+
+To learn more about the Qiskit Code Assistant or the Qiskit HumanEval and cite it in your scientific publications, review these recommended citations:
+
+```
+@misc{2405.19495,
+Author = {Nicolas Dupuis and Luca Buratti and Sanjay Vishwakarma and Aitana Viudes Forrat and David Kremer and Ismael Faro and Ruchir Puri and Juan Cruz-Benito},
+Title = {Qiskit Code Assistant: Training LLMs for generating Quantum Computing Code},
+Year = {2024},
+Eprint = {arXiv:2405.19495},
+}
+```
+
+```
+@misc{2406.14712,
+Author = {Sanjay Vishwakarma and Francis Harkins and Siddharth Golecha and Vishal Sharathchandra Bajpe and Nicolas Dupuis and Luca Buratti and David Kremer and Ismael Faro and Ruchir Puri and Juan Cruz-Benito},
+Title = {Qiskit HumanEval: An Evaluation Benchmark For Quantum Code Generative Models},
+Year = {2024},
+Eprint = {arXiv:2406.14712},
+}
+```
+
+## Next steps
+
+<Admonition type="tip" title="Recommendations">
+  Install and use the official [JupyterLab](/guides/qiskit-code-assistant-jupyterlab) or [VSCode](/guides/qiskit-code-assistant-vscode) extensions.
+</Admonition>