diff --git a/docs/source/_static/bedrock-chat-basemodel.png b/docs/source/_static/bedrock-chat-basemodel.png index 5dd261a4a..286d69971 100644 Binary files a/docs/source/_static/bedrock-chat-basemodel.png and b/docs/source/_static/bedrock-chat-basemodel.png differ diff --git a/docs/source/_static/bedrock-model-access.png b/docs/source/_static/bedrock-model-access.png index b3325d484..545050acb 100644 Binary files a/docs/source/_static/bedrock-model-access.png and b/docs/source/_static/bedrock-model-access.png differ diff --git a/docs/source/_static/bedrock-model-select.png b/docs/source/_static/bedrock-model-select.png index 93fc52f94..a9004297d 100644 Binary files a/docs/source/_static/bedrock-model-select.png and b/docs/source/_static/bedrock-model-select.png differ diff --git a/docs/source/_static/chat-at-mention.png b/docs/source/_static/chat-at-mention.png new file mode 100644 index 000000000..425be64c3 Binary files /dev/null and b/docs/source/_static/chat-at-mention.png differ diff --git a/docs/source/_static/chat-attach-file.png b/docs/source/_static/chat-attach-file.png new file mode 100644 index 000000000..89d86eac8 Binary files /dev/null and b/docs/source/_static/chat-attach-file.png differ diff --git a/docs/source/_static/chat-explain-code-output.png b/docs/source/_static/chat-explain-code-output.png index a7367ff75..6c81c3325 100644 Binary files a/docs/source/_static/chat-explain-code-output.png and b/docs/source/_static/chat-explain-code-output.png differ diff --git a/docs/source/_static/chat-generate-command-response.png b/docs/source/_static/chat-generate-command-response.png index 5e17aca3a..f0d41b64f 100644 Binary files a/docs/source/_static/chat-generate-command-response.png and b/docs/source/_static/chat-generate-command-response.png differ diff --git a/docs/source/_static/chat-generate-input.png b/docs/source/_static/chat-generate-input.png index 12d8747a7..6a03d819e 100644 Binary files a/docs/source/_static/chat-generate-input.png and b/docs/source/_static/chat-generate-input.png differ diff --git a/docs/source/_static/chat-history-context-1.png b/docs/source/_static/chat-history-context-1.png index 3bf0ec16d..60986174c 100644 Binary files a/docs/source/_static/chat-history-context-1.png and b/docs/source/_static/chat-history-context-1.png differ diff --git a/docs/source/_static/chat-history-context-2.png b/docs/source/_static/chat-history-context-2.png index 4b7e14332..6bef56810 100644 Binary files a/docs/source/_static/chat-history-context-2.png and b/docs/source/_static/chat-history-context-2.png differ diff --git a/docs/source/_static/chat-interface-selection.png b/docs/source/_static/chat-interface-selection.png index ab34503d8..3dab54989 100644 Binary files a/docs/source/_static/chat-interface-selection.png and b/docs/source/_static/chat-interface-selection.png differ diff --git a/docs/source/_static/chat-interface.png b/docs/source/_static/chat-interface.png new file mode 100644 index 000000000..2e39603c6 Binary files /dev/null and b/docs/source/_static/chat-interface.png differ diff --git a/docs/source/_static/chat-new.png b/docs/source/_static/chat-new.png new file mode 100644 index 000000000..09872e89f Binary files /dev/null and b/docs/source/_static/chat-new.png differ diff --git a/docs/source/_static/chat-newchat.png b/docs/source/_static/chat-newchat.png new file mode 100644 index 000000000..f6303eb1f Binary files /dev/null and b/docs/source/_static/chat-newchat.png differ diff --git a/docs/source/_static/chat-prompt.png b/docs/source/_static/chat-prompt.png new file mode 100644 index 000000000..c1afd4c5c Binary files /dev/null and b/docs/source/_static/chat-prompt.png differ diff --git a/docs/source/_static/chat-replace-selection-input.png b/docs/source/_static/chat-replace-selection-input.png index 3df29978b..2c94b307b 100644 Binary files a/docs/source/_static/chat-replace-selection-input.png and b/docs/source/_static/chat-replace-selection-input.png differ diff --git a/docs/source/_static/chat-response.png b/docs/source/_static/chat-response.png new file mode 100644 index 000000000..42c0624b8 Binary files /dev/null and b/docs/source/_static/chat-response.png differ diff --git a/docs/source/_static/chat-second.png b/docs/source/_static/chat-second.png new file mode 100644 index 000000000..c45d5b193 Binary files /dev/null and b/docs/source/_static/chat-second.png differ diff --git a/docs/source/_static/chat-ydoc.png b/docs/source/_static/chat-ydoc.png new file mode 100644 index 000000000..cf8c6079d Binary files /dev/null and b/docs/source/_static/chat-ydoc.png differ diff --git a/docs/source/_static/fix-error-cell-selected.png b/docs/source/_static/fix-error-cell-selected.png index a8e2d0b82..c22ea65d4 100644 Binary files a/docs/source/_static/fix-error-cell-selected.png and b/docs/source/_static/fix-error-cell-selected.png differ diff --git a/docs/source/_static/fix-response.png b/docs/source/_static/fix-response.png index 0127af325..88113e674 100644 Binary files a/docs/source/_static/fix-response.png and b/docs/source/_static/fix-response.png differ diff --git a/docs/source/_static/jupyter-ai-screenshot.png b/docs/source/_static/jupyter-ai-screenshot.png index 7d84aee2d..fe85412e5 100644 Binary files a/docs/source/_static/jupyter-ai-screenshot.png and b/docs/source/_static/jupyter-ai-screenshot.png differ diff --git a/docs/source/_static/jupyternaut-settings-api-keys.png b/docs/source/_static/jupyternaut-settings-api-keys.png new file mode 100644 index 000000000..e8ad38d2a Binary files /dev/null and b/docs/source/_static/jupyternaut-settings-api-keys.png differ diff --git a/docs/source/_static/jupyternaut-settings-model-parameters.png b/docs/source/_static/jupyternaut-settings-model-parameters.png new file mode 100644 index 000000000..5f1004598 Binary files /dev/null and b/docs/source/_static/jupyternaut-settings-model-parameters.png differ diff --git a/docs/source/_static/jupyternaut-settings.png b/docs/source/_static/jupyternaut-settings.png new file mode 100644 index 000000000..7219771f8 Binary files /dev/null and b/docs/source/_static/jupyternaut-settings.png differ diff --git a/docs/source/_static/magics-alias-usage.png b/docs/source/_static/magics-alias-usage.png new file mode 100644 index 000000000..a3dd4a24d Binary files /dev/null and b/docs/source/_static/magics-alias-usage.png differ diff --git a/docs/source/_static/magics-dealias.png b/docs/source/_static/magics-dealias.png new file mode 100644 index 000000000..ea90880fd Binary files /dev/null and b/docs/source/_static/magics-dealias.png differ diff --git a/docs/source/_static/magics-example-openai.png b/docs/source/_static/magics-example-openai.png new file mode 100644 index 000000000..fdd53b932 Binary files /dev/null and b/docs/source/_static/magics-example-openai.png differ diff --git a/docs/source/_static/magics-format-code.png b/docs/source/_static/magics-format-code.png new file mode 100644 index 000000000..126493325 Binary files /dev/null and b/docs/source/_static/magics-format-code.png differ diff --git a/docs/source/_static/magics-list-all.png b/docs/source/_static/magics-list-all.png new file mode 100644 index 000000000..5ce02d822 Binary files /dev/null and b/docs/source/_static/magics-list-all.png differ diff --git a/docs/source/_static/magics-list-any-provider.png b/docs/source/_static/magics-list-any-provider.png new file mode 100644 index 000000000..7b1dd434a Binary files /dev/null and b/docs/source/_static/magics-list-any-provider.png differ diff --git a/docs/source/_static/magics-list-help.png b/docs/source/_static/magics-list-help.png new file mode 100644 index 000000000..7ddf47f65 Binary files /dev/null and b/docs/source/_static/magics-list-help.png differ diff --git a/docs/source/_static/magics-list.png b/docs/source/_static/magics-list.png new file mode 100644 index 000000000..1a39ccc54 Binary files /dev/null and b/docs/source/_static/magics-list.png differ diff --git a/docs/source/_static/magics-set-alias.png b/docs/source/_static/magics-set-alias.png new file mode 100644 index 000000000..d46c5552e Binary files /dev/null and b/docs/source/_static/magics-set-alias.png differ diff --git a/docs/source/_static/notebook-chat.png b/docs/source/_static/notebook-chat.png new file mode 100644 index 000000000..ada9001b0 Binary files /dev/null and b/docs/source/_static/notebook-chat.png differ diff --git a/docs/source/_static/ollama-settings.png b/docs/source/_static/ollama-settings.png index 89833b614..605dfd3d5 100644 Binary files a/docs/source/_static/ollama-settings.png and b/docs/source/_static/ollama-settings.png differ diff --git a/docs/source/contributors/index.md b/docs/source/contributors/index.md index 9858d16c8..c36bfda05 100644 --- a/docs/source/contributors/index.md +++ b/docs/source/contributors/index.md @@ -9,7 +9,7 @@ If you would like to build applications that enhance Jupyter AI, please see the Maintainers of Jupyter AI have adopted principles that contributors should also follow. These principles, which build on top of [the Zen of Python](https://peps.python.org/pep-0020/), are intended to earn users' trust by keeping their data under their control. The following list is non-exhaustive; maintainers have discretion to interpret and revise these principles. 1. Jupyter AI is **vendor-agnostic**. Jupyter AI does not discriminate between available models, and gives users a choice of model providers. A feature in Jupyter AI may be specific to one model or model provider if it cannot be used with other models or providers. -2. Jupyter AI **only responds to an explicit prompt**; it does not watch files and it does not send prompts automatically. Any change that watches user files must be opt-in only. +2. Jupyter AI **only responds to an explicit prompt**; it does not watch files and it does not send prompts automatically. Any change that watches user files must be opt-in only. One form of opt-in is users building agentic personas that undertake non-deterministic actions, including sending prompts to other personas or agents, managing the file system, etc. 3. Jupyter AI is **transparent** with its chat prompts. The chat interface and magic commands use system messages and prompt templates that are open source, so that users know what gets sent to language models. 4. Jupyter AI is **traceable**; users know when it has been used to generate content. When Jupyter AI generates a notebook, the notebook says that it was generated by Jupyter AI. When a user runs a Jupyter AI magic command in a notebook, output cells say, in their metadata, that they were generated by Jupyter AI. 5. Jupyter AI uses a **human-centered design**. The chat interface should look and feel like chat applications that are generally available. The magic commands should look and work like other IPython magic commands. Settings screens should be used minimally, and wherever they are used, they should be readable and understandable, even for users not fluent in the user interface language. @@ -18,13 +18,13 @@ Issues and pull requests that violate the above principles may be declined. If y ## Prerequisites -You can develop Jupyter AI on any system that can run a supported Python version up to and including 3.12, including recent Windows, macOS, and Linux versions. +You can develop Jupyter AI on any system that can run a supported Python version up to and including 3.13, including recent Windows, macOS, and Linux versions. You should have the newest supported version of JupyterLab installed. You will need [a supported version of node.js](https://github.com/nodejs/release#release-schedule) to use Jupyter AI. -## Automatic development setup (recommended) + + +## Development Setup + +In v3, Jupyter AI is no longer a monorepo. The various components of Jupyter AI are modularized as submodules in the [`jupyter-ai-contrib`](https://github.com/jupyter-ai-contrib) org under various repositories. These are Jupyter extensions that are desined to enable humans and AI to collaborate together. The `jupyter-ai` repository is installed with all the submodules. + +The following repositories are stable, i.e., this means the repos are, or are quickly becoming, stable and ready for production use. + +- [jupyter-ai-chat-commands](https://github.com/jupyter-ai-contrib/jupyter-ai-chat-commands) - Default set of chat commands in Jupyter AI +- [jupyter-ai-jupyternaut](https://github.com/jupyter-ai-contrib/jupyter-ai-jupyternaut) - Package which provides the Jupyternaut, the default AI persona, in Jupyter AI +- [jupyter-ai-litellm](https://github.com/jupyter-ai-contrib/jupyter-ai-litellm) - LiteLLM based model abstraction for Jupyter AI +- [jupyter-ai-persona-manager](https://github.com/jupyter-ai-contrib/jupyter-ai-persona-manager) - The core manager & registry for AI personas in Jupyter AI +- [jupyter-ai-router](https://github.com/jupyter-ai-contrib/jupyter-ai-router) - The core routing layer used in Jupyter AI to process chat messages +- [jupyter-ai-tools](https://github.com/jupyter-ai-contrib/jupyter-ai-tools) - Jupyter Server extension that exposes a collection of powerful, agent-friendly tools for interacting with notebooks and Git repositories +- [jupyter-server-documents](https://github.com/jupyter-ai-contrib/jupyter-server-documents) - Server side document handling with improved output handling and kernel management/status. +- [jupyter-server-mcp](https://github.com/jupyter-ai-contrib/jupyter-server-mcp) - An MCP interface/extension for Jupyter Server +- [jupyterlab-diff](https://github.com/jupyter-ai-contrib/jupyterlab-diff) - JupyterLab commands to show cell and file diffs +- [jupyter-ai-magic-commands](https://github.com/jupyter-ai-contrib/jupyter-ai-chat-commands) - The code for handling the `%ai` and `%%ai` magic commands in Jupyter notebooks. + +These repositories are experimental and under active development: + +- [jupyter-ai-claude-code](https://github.com/jupyter-ai-contrib/jupyter-ai-claude-code) - A Jupyter AI persona for Claude Code +- [jupyter-ai-personas](https://github.com/jupyter-ai-contrib/jupyter-ai-personas) - AI Personas for Jupyter AI +- [jupyter-ai-demos](https://github.com/jupyter-ai-contrib/jupyter-ai-demos) - A set of demos for new features of Jupyter AI +- [jupyter-floating-chat](https://github.com/jupyter-ai-contrib/jupyter-floating-chat) - A jupyterlab extension to add a floating chat input +- [jupyter-server-ai-tools](https://github.com/jupyter-ai-contrib/jupyter-server-ai-tools) - A Jupyter Server extension for discovering tools across extensions. +- [jupyterlab-cell-input-footer](https://github.com/jupyter-ai-contrib/jupyterlab-cell-input-footer) - JupyterLab Plugin that provides a cell input footer +- [jupyterlab-commands-toolkit](https://github.com/jupyter-ai-contrib/jupyterlab-commands-toolkit) - JupyterLab commands as an AI Toolkit +- [jupyterlab-document-collaborators](https://github.com/jupyter-ai-contrib/jupyterlab-document-collaborators) - A JupyterLab extension for showing collaborators at the top of a document + +- [jupyterlab-magic-wand](https://github.com/jupyter-ai-contrib/jupyterlab-magic-wand) - An in-cell AI assistant for JupyterLab notebooks +- [jupyterlab-notebook-awareness](https://github.com/jupyter-ai-contrib/jupyterlab-notebook-awareness) - Track current notebook and active cell in JupyterLab's awareness +- [jupyterlab-ai-commands](https://github.com/jupyter-ai-contrib/jupyterlab-ai-commands) - A set of JupyterLab commands for use with AI agents + +### Dev install using `just` and `uv` + +[jupyter-ai-devrepo](https://github.com/dlqqq/jupyter-ai-devrepo) is a "developer repo" intended for Jupyter AI contributors. This facilitates installing Jupyter AI along with all its submodules with a small number of steps. By cloning the repo and following the steps below, you can have an editable developer installation of all Jupyter AI subpackages. + +#### 0. Clone the repo + +``` +git clone --recurse-submodules +cd jupyter-ai-devrepo/ +``` + +#### 1. Install root dependencies + +This monorepo requires `git`, `uv`, and `just`. Use `homebrew` to install these if you do not have them installed. + +No dedicated Python environment is required because `uv` automatically manages a local venv. + +If you use `conda`/`mamba`/`micromamba`, you can run the following commands to +install these dependencies into the `base` environment: + +```sh +{conda,mamba,micromamba} activate base +{conda,mamba,micromamba} install uv just +# make sure to activate the `base` environment before working in this repo +``` + +Otherwise, you can use your OS's package manager. For example, on macOS: + +```sh +brew install uv just +``` + +#### 2. Pull in latest changes + +This command switches to the `main` branch on every submodule and pulls from it. + +``` +just sync +``` + +If you do not have your RSA key set up to access GitHub from the CLI, you will be prompted to authenticate yourself on GitHub for each of the subpackages as they get cloned into the `jupyter-ai-devrepo` folder. + +#### 3. Install all packages + +This command automatically installs each of the packages in editable mode. + +``` +just install +``` + +#### 4. Start JupyterLab + +Start JupyterLab by running: + +``` +just start +``` + +This command will always run `uv run jupyter lab` from the root of this devrepo, +even if your current directory is inside of a submodule. + +#### Useful commands + +- `just start`: start JupyterLab + + - `Ctrl + Z` + `kill -9 %1` stops JupyterLab in case `Ctrl + C` does not work + +- `just sync`: switch to `main` in all submodules and pull in all upstream changes + +- `just build-all`: build all frontend assets in every submodule + +- `just install`: perform an editable, developer installation of all packages + +- `just uninstall`: uninstall everything (useful for testing the `just` commands) + +- `just uninstall && just install`: re-install everything (useful for fixing a broken venv) ## Building documentation -The `./scripts/dev-setup.sh` should automatically install the documentation +The `just install` script should automatically install the documentation dependencies. You will need to install [pandoc](https://pandoc.org/) as well. You can install [pandoc from the conda-forge channel](https://anaconda.org/conda-forge/pandoc): ``` @@ -144,7 +253,6 @@ conda install -c conda-forge pandoc Otherwise have a look at pandoc's [installation instructions](https://pandoc.org/installing.html). - To build the documentation locally, run ``` @@ -160,19 +268,18 @@ choice to easily view your local documentation build. After making any changes, make sure to rebuild the documentation locally via `make html`, and then refresh your browser to verify the changes visually. - -## Development uninstall + ## Testing -### Integration / E2E tests +### Integration / E2E tests (**TO BE UPDATED**) This extension uses Playwright for the integration / E2E tests (user-level tests). More precisely, the JupyterLab helper @@ -182,12 +289,12 @@ test the extension in JupyterLab. Install test dependencies (needed only once): ```sh -cd ./packages/jupyter-ai/ui-tests/ +cd ./packages//ui-tests/ jlpm install jlpm playwright install ``` -Tests involve snapshot comparisons against a reference snapshots generated by the Github CI. If you are using an OS other than Linux, you will need to generate local snapshots before running the tests locally for the first time. To do this, execute the command: +Tests involve snapshot comparisons against reference snapshots generated by the Github CI. If you are using an OS other than Linux, you will need to generate local snapshots before running the tests locally for the first time. To do this, execute the command: ```sh cd ./packages/jupyter-ai/ui-tests/ diff --git a/docs/source/index.md b/docs/source/index.md index b2ce5061e..687426036 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,30 +1,90 @@ -# Jupyter AI +# Jupyter AI v3 Welcome to Jupyter AI, which brings generative AI to Jupyter. Jupyter AI provides a user-friendly and powerful way to explore generative AI models in notebooks and improve your productivity in JupyterLab and the Jupyter Notebook. More specifically, Jupyter AI offers: -* An `%%ai` magic that turns the Jupyter notebook into a reproducible generative AI playground. +- A native chat UI in JupyterLab that enables you to work with generative AI as a conversational assistant, and also enables interaction with the active notebook. +- An `%%ai` magic that turns the Jupyter notebook into a reproducible generative AI playground. This works anywhere the IPython kernel runs (JupyterLab, Jupyter Notebook, Google Colab, VSCode, etc.). -* A native chat UI in JupyterLab that enables you to work with generative AI as a conversational assistant. -* Support for a wide range of generative model providers and models - (AI21, Anthropic, Cohere, Gemini, Hugging Face, MistralAI, OpenAI, SageMaker, NVIDIA, etc.). +- Support for a wide range of generative model providers and models + (AI21, Amazon, Anthropic, Cohere, Gemini, Hugging Face, MistralAI, OpenAI, NVIDIA, etc.). +- Multiple editable chat threads are available, each thread saved to a separate Jupyter server document with extension `.chat`. +- Real time collaboration (RTC) is enabled in both chat and Jupyter notebook, if cloud deployments support it. +- Support for hundreds of LLMs from many additional providers. +- Chat personas with agentic capabilities, with a default `Jupyternaut` persona. + +Below is the look and feel of Jupyter AI v3. You can see the chat panel on the left and the notebooks on the right. The chat panel shows the Jupyternaut persona responding to prompts in the chat, as well as interacting with the code as context from the notebook on the right. The right panel shows the use of the `%%ai` magics commands. A screenshot of Jupyter AI showing the chat interface and the magic commands ## JupyterLab support -**Each major version of Jupyter AI supports *only one* major version of JupyterLab.** Jupyter AI 1.x supports +**Each major version of Jupyter AI supports _only one_ major version of JupyterLab.** Jupyter AI 1.x supports JupyterLab 3.x, and Jupyter AI 2.x supports JupyterLab 4.x. The feature sets of versions 1.0.0 and 2.0.0 -are the same. We will maintain support for JupyterLab 3 for as long as it remains maintained. +are the same. We will maintain support for JupyterLab 3 for as long as it remains maintained. Jupyter AI v3 supports JupyterLab 4.x. The `main` branch of Jupyter AI targets the newest supported major version of JupyterLab. All new features and most bug fixes will be committed to this branch. Features and bug fixes will be backported to work on JupyterLab 3 only if developers determine that they will add sufficient value. **We recommend that JupyterLab users who want the most advanced Jupyter AI functionality upgrade to JupyterLab 4.** +## Quickstart + +It is best to install `jupyter-ai` in an environment. Use [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) to create an environment that uses Python 3.13 and the latest version of JupyterLab: + + $ conda create -n jupyter-ai python=3.13 jupyterlab + $ conda activate jupyter-ai + +To install both the `%%ai` magic and the JupyterLab extension, you can run: + + $ pip install jupyter-ai== + +Choose the version number, the latest version is `3.0.0b9`. + +For an installation with all related packages, use: + + $ pip install "jupyter-ai[all]"== + +To start Jupyter AI in Jupyter Lab, run + +``` +jupyter lab +``` + +You should see an interface similar to the one above. Use the `+ Chat` button in the chat panel to open a chat thread and enter prompts. In the chat box enter `@` to see a list of personas, and you can select one before entering your query. + +To connect a LLM for use in your chat threads you can select the `Settings` dropdown menu, select `Jupyternaut settings` in it to see the settings panel, in which you can select a chat model, specify model parameters if needed, and also add API keys for using LLMs that require it. + +To use `uv` instead of `pip`: + +Create a virtual environment with `uv` in any folder: + +``` +uv venv --python 3.13 +``` + +Activate the environment: + +``` +source .venv/bin/activate +``` + +Install with + +``` +uv pip install "jupyter-ai[all]"== +``` + +Run with + +``` +jupyter lab +``` + ## Contents ```{toctree} diff --git a/docs/source/users/bedrock.md b/docs/source/users/bedrock.md index 8bcce8a57..6a6ab295f 100644 --- a/docs/source/users/bedrock.md +++ b/docs/source/users/bedrock.md @@ -2,34 +2,38 @@ [(Return to the Chat Interface page)](index.md#amazon-bedrock-usage) -Bedrock supports many language model providers such as AI21 Labs, Amazon, Anthropic, Cohere, Meta, and Mistral AI. To use the base models from any supported provider make sure to enable them in Amazon Bedrock by using the AWS console. You should also select embedding models in Bedrock in addition to language completion models if you intend to use retrieval augmented generation (RAG) on your documents. +Bedrock supports many language model providers such as Amazon, Anthropic, Arcee AI, AutoGluon, BRIA AI, Camb.ai, Cohere, DeepSeek, Google, HuggingFace, IBM, Inception, Liquid AI, Meta, Mistral AI, Moonshot, NVIDIA, OpenAI, Qwen, Stability, Writer, etc., this is a sample of the many providers that are available. To use the base models from any supported provider make sure to enable them in Amazon Bedrock by using the AWS console. You should also select embedding models in Bedrock in addition to language completion models if you intend to use retrieval augmented generation (RAG) on your documents. Go to Amazon Bedrock and select `Model Access` as shown here: Screenshot of the left panel in the AWS console where Bedrock model access is provided. -Click through on `Model Access` and follow the instructions to grant access to the models you wish to use, as shown below. Make sure to accept the end user license (EULA) as required by each model. You may need your system administrator to grant access to your account if you do not have authority to do so. +Click through on `Model Catalog` to see all the available models. Serverless foundation models are now automatically enabled across all AWS commercial regions when first invoked in your account, so you can start using them instantly. You no longer need to manually activate model access through this page. Note that for Anthropic models, some first-time users may need to submit use case details before they can access the model. For serverless models served from AWS Marketplace, a user with AWS Marketplace permissions must invoke the model once to enable it account-wide. After this one-time enablement, all users can access the model without needing these permissions. + +Account administrators retain full control over model access through [IAM policies](https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html) and [Service Control Policies](https://aws.amazon.com/blogs/security/unlock-new-possibilities-aws-organizations-service-control-policy-now-supports-full-iam-language/) to restrict model access as needed. + +To get started, simply select a model from the Model catalog and open it in the playground or invoke the model using the [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) or [Converse API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) operations. Note that for Anthropic models, some first-time users may need to submit use case details before they can access the model. Review our documentation for the complete list of available models. + +All Bedrock serverless foundation model EULAs can be accessed [here](https://aws.amazon.com/legal/bedrock/third-party-models/). EULAs can also be accessed from the model details page in the Model catalog. Screenshot of the Bedrock console where models may be selected. -You should also select embedding models in addition to language completion models if you intend to use retrieval augmented generation (RAG) on your documents. - -You may now select a chosen Bedrock model from the drop-down menu box title `Completion model` in the chat interface. If RAG is going to be used then pick an embedding model that you chose from the Bedrock models as well. An example of these selections is shown below: +You may now select a chosen Bedrock model from the drop-down menu box titled `Chat model` in the Jupyternaut settings tab (via the `Settings` dropdown). An example of the bedrock provider models is shown: Screenshot of the Jupyter AI chat panel where the base language model and embedding model is selected. If your provider requires an API key, please enter it in the box that will show for that provider. Make sure to click on `Save Changes` to ensure that the inputs have been saved. -Bedrock also allows custom models to be trained from scratch or fine-tuned from a base model. Jupyter AI enables a custom model to be called in the chat panel using its `arn` (Amazon Resource Name). A fine-tuned model will have your 12-digit customer number in the ARN: + [(Return to the Chat Interface page)](index.md#amazon-bedrock-usage) diff --git a/docs/source/users/index.md b/docs/source/users/index.md index 750960332..7c9a90424 100644 --- a/docs/source/users/index.md +++ b/docs/source/users/index.md @@ -11,72 +11,56 @@ please see the {doc}`developer's guide `. ## Prerequisites You can run Jupyter AI on any system that can run a supported Python version -from 3.9 to 3.12, including recent Windows, macOS, and Linux versions. Python +from 3.9 to 3.13, including recent Windows, macOS, and Linux versions. Python 3.8 support is also available in Jupyter AI v2.29.1 and below. -If you use `conda`, you can install Python 3.12 in your environment by running: +If you use `conda`, you can install Python 3.13 in your environment by running: ``` -conda install python=3.12 +conda install python=3.13 ``` -The `jupyter_ai` package, which provides the lab extension and user interface in -JupyterLab, depends on JupyterLab 4. If upgrading to JupyterLab 4 is not -possible in your environment, you should install `jupyter_ai` v1.x instead. -See "Installation" for more details. - -:::{attention} -:name: jupyter-lab-3-end-of-maintenance -JupyterLab 3 reached its end of maintenance date on May 15, 2024. As a result, we will not backport new features to the v1 branch supporting JupyterLab 3. Fixes for critical issues will still be backported until December 31, 2024. If you are still using JupyterLab 3, we strongly encourage you to **upgrade to JupyterLab 4 as soon as possible**. For more information, see [JupyterLab 3 end of maintenance](https://blog.jupyter.org/jupyterlab-3-end-of-maintenance-879778927db2) on the Jupyter Blog. -::: +The `jupyter_ai` package, which provides the lab extension and user interface in JupyterLab, depends on JupyterLab 4. You can install JupyterLab using `pip` or `conda`. 1. via `pip`: ``` -# change 4.0 to 3.0 if you need JupyterLab 3 -pip install jupyterlab~=4.0 +pip install jupyterlab ``` 2. via `conda`: ``` -# change 4.0 to 3.0 if you need JupyterLab 3 conda config --add channels conda-forge conda config --set channel_priority strict -conda install jupyterlab~=4.0 +conda install jupyterlab ``` -You can also use Jupyter AI in Jupyter Notebook 7.2+. To install Jupyter Notebook 7.2: +You can also use Jupyter AI in Jupyter Notebook 7.5+. To install Jupyter Notebook 7.5: 1. via `pip`: ``` -pip install notebook~=7.2 +pip install notebook~=7.5 ``` 2. via `conda`: + ``` -conda install notebook~=7.2 +conda install notebook~=7.5 ``` :::{note} -To activate the chat interface in Jupyter Notebook, click on "View > Left sidebar > Show Jupyter AI Chat". +To activate the chat interface in Jupyter Notebook, click on "View > Left sidebar > Show Jupyter AI Chat". You will see the chat panel as shown below. ::: -The `jupyter_ai_magics` package, which provides exclusively the IPython magics, -does not depend on JupyterLab or `jupyter_ai`. You can install -`jupyter_ai_magics` without installing `jupyterlab` or `jupyter_ai`. -If you have both `jupyter_ai_magics` and `jupyter_ai` installed, you should -have the same version of each, to avoid errors. +Screen shot of the chat settings interface with Juptyter notebook -Jupyter AI internally uses Pydantic v1 and should work with either Pydantic -version 1 or version 2. For compatibility, developers using Pydantic V2 -should import classes using the `pydantic.v1` package. See the -[LangChain Pydantic migration plan](https://python.langchain.com/docs/guides/pydantic_compatibility) -for advice about how developers should use `v1` to avoid mixing v1 and v2 -classes in their code. +The `jupyter-ai-magic-commands` package, which provides the IPython magics, is automatically installed as a dependency when installing `jupyter_ai`. ## Installation @@ -88,73 +72,81 @@ clobbering Python packages in your existing Python environment. To do so, install [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) -and create an environment that uses Python 3.12 and the latest version of +and create an environment that uses Python 3.13 and the latest version of JupyterLab: - $ conda create -n jupyter-ai python=3.12 jupyterlab + $ conda create -n jupyter-ai python=3.13 jupyterlab $ conda activate jupyter-ai -You can now choose how to install Jupyter AI. + -1. Quick installation via `pip` (recommended) -2. Minimal installation via `pip` -3. Minimal installation via `conda` +### Installation via `pip` -### Quick installation via `pip` (recommended) +To install both the `%%ai` magic and the JupyterLab extension, you can run: -If you want to install both the `%%ai` magic and the JupyterLab extension, you can run: + $ pip install jupyter-ai== - $ pip install 'jupyter-ai[all]' +Choose the version number, the latest version is `3.0.0b9`. Then, restart JupyterLab. This will install every optional dependency, which provides access to all models currently supported by `jupyter-ai`. -If you are not using JupyterLab and you only want to install the Jupyter AI -`%%ai` magic, you can run: +For an installation with all related packages, use: - $ pip install 'jupyter-ai-magics[all]' - -`jupyter-ai` depends on `jupyter-ai-magics`, so installing `jupyter-ai` -automatically installs `jupyter-ai-magics`. + $ pip install "jupyter-ai[all]"== :::{warning} :name: quoting-cli-arguments -If running the above commands result in an error like `zsh: no matches found: jupyter-ai[all]`, this is because the `jupyter-ai[all]` argument must be surrounded by single or double quotes. Some shells reserve square brackets for pattern matching, so arguments containing square brackets must be quoted. +If running the above commands without quotes results in an error like `zsh: no matches found: jupyter-ai[all]`, this is because the `jupyter-ai[all]` argument must be surrounded by single or double quotes. Some shells reserve square brackets for pattern matching, so arguments containing square brackets must be quoted. ::: +### Installation via `uv` -### Minimal installation via `pip` +Create a virtual environment with `uv` in any folder: -Most model providers in Jupyter AI require a specific dependency to be installed -before they are available for use. These are called _provider dependencies_. -Provider dependencies are optional to Jupyter AI, meaning that Jupyter AI can be -installed with or without any provider dependencies installed. If a provider -requires a dependency that is not installed, its models are not listed in the -user interface which allows you to select a language model. +``` +uv venv --python 3.13 +``` -To perform a minimal installation via `pip` without any provider dependencies, -omit the `[all]` optional dependency group from the package name: +Activate the environment: ``` -pip install jupyter-ai +source .venv/bin/activate ``` -By selectively installing provider dependencies, you can control which models -are available in your Jupyter AI environment. +Install with + +``` +uv pip install "jupyter-ai[all]"== +``` -For example, to install Jupyter AI with only added support for Anthropic models, run: +Run with ``` -pip install jupyter-ai langchain-anthropic +jupyter lab ``` -For more information on model providers and which dependencies they require, see -[the model provider table](https://jupyter-ai.readthedocs.io/en/latest/users/index.html#model-providers). +### Additional dependencies -### Minimal installation via `conda` +Most model providers in Jupyter AI require a specific dependency to be installed +before they are available for use. These are called _provider dependencies_. +Provider dependencies are optional to Jupyter AI, meaning that Jupyter AI can be +installed with or without any or some provider dependencies installed. If a provider +requires a dependency that is not installed, its models are not listed in the +user interface which allows you to select a language model. + +For example, to install Jupyter AI with added support for AWS Bedrock models, run: + +``` +pip install boto3 +``` + +For more information on model providers and which dependencies (if any) they require, see the LiteLLM documentation for [providers](https://docs.litellm.ai/docs/providers). + + ## Uninstallation @@ -182,69 +174,49 @@ If you installed Jupyter AI using `pip`, to remove the extension, run: $ pip uninstall jupyter-ai -or - - $ pip uninstall jupyter-ai-magics - -If you installed Jupyter AI using `conda`, you can remove it by running: +If you installed `jupyter-ai` in a conda environment you can eliminate the environment by first deactivating it and then running - $ conda remove jupyter-ai - -or +``` +conda remove -n jupyter-ai --all +``` - $ conda remove jupyter-ai-magics +When prompted, simply relace "Y" to proceed. ## Model providers -Jupyter AI supports a wide range of model providers and models. To use Jupyter AI with a particular provider, you must install its Python packages and set its API key (or other credentials) in your environment or in the chat interface. +Jupyter AI supports a wide range of model providers and models. Access to the various providers is undertaken using the [LiteLLM](https://docs.litellm.ai/) interface, which enables hundreds of models. You can select the model to be used in the chat interface from the `Settings` tab -> `Jupyternaut Settings`, where you can see the models by typing in a search string. -Jupyter AI supports the following model providers: +Chat settings interface with Juptyter Lab -| Provider | Provider ID | Environment variable(s) | Python package(s) | -|------------------------------|----------------------|----------------------------|-------------------------------------------| -| AI21 | `ai21` | `AI21_API_KEY` | `ai21` | -| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | `langchain-anthropic` | -| Anthropic (chat) | `anthropic-chat` | `ANTHROPIC_API_KEY` | `langchain-anthropic` | -| Bedrock | `bedrock` | N/A | `langchain-aws` | -| Bedrock (chat) | `bedrock-chat` | N/A | `langchain-aws` | -| Bedrock (custom/provisioned) | `bedrock-custom` | N/A | `langchain-aws` | -| Cohere | `cohere` | `COHERE_API_KEY` | `langchain-cohere` | -| ERNIE-Bot | `qianfan` | `QIANFAN_AK`, `QIANFAN_SK` | `qianfan` | -| Gemini | `gemini` | `GOOGLE_API_KEY` | `langchain-google-genai` | -| GPT4All | `gpt4all` | N/A | `gpt4all` | -| Hugging Face Hub | `huggingface_hub` | `HUGGINGFACEHUB_API_TOKEN` | `huggingface_hub`, `ipywidgets`, `pillow` | -| MistralAI | `mistralai` | `MISTRAL_API_KEY` | `langchain-mistralai` | -| NVIDIA | `nvidia-chat` | `NVIDIA_API_KEY` | `langchain_nvidia_ai_endpoints` | -| Ollama | `ollama` | N/A | `langchain-ollama` | -| OpenAI | `openai` | `OPENAI_API_KEY` | `langchain-openai` | -| OpenAI (chat) | `openai-chat` | `OPENAI_API_KEY` | `langchain-openai` | -| SageMaker endpoint | `sagemaker-endpoint` | N/A | `langchain-aws` | +The LiteLLM interface does not show _all_ available models and you can see the [full list of providers and models](https://docs.litellm.ai/docs/providers) online. -The environment variable names shown above are also the names of the settings keys used when setting up the chat interface. -If multiple variables are listed for a provider, **all** must be specified. +To use Jupyter AI with a particular provider, you must set its API key (or other credentials) in the Jupyternaut settings, as needed. The names of the API keys are available from the LiteLLM documentation for each provider. -To use the Bedrock models, you need access to the Bedrock service, and you will need to authenticate via [boto3](https://github.com/boto/boto3). For more information, see the [Amazon Bedrock Homepage](https://aws.amazon.com/bedrock/). +Chat settings interface with Juptyter Lab -You need the `pillow` Python package to use Hugging Face Hub's text-to-image models. +In the same interface it is also possible to set model parameters. This is a new feature in v3. -You can find a list of Hugging Face's models at [https://huggingface.co/models](https://huggingface.co/models). +Chat settings interface with Juptyter Lab -To use NVIDIA models, create a free account with the [NVIDIA NGC service](https://catalog.ngc.nvidia.com/), which hosts AI solution catalogs, containers, models, and more. Navigate to Catalog > [AI Foundation Models](https://catalog.ngc.nvidia.com/ai-foundation-models), and select a model with an API endpoint. Click "API" on the model's detail page, and click "Generate Key". Save this key, and set it as the environment variable `NVIDIA_API_KEY` to access any of the model endpoints. +Here are some examples of additional packages that may be installed as needed: -SageMaker endpoint names are created when you deploy a model. For more information, see -["Create your endpoint and deploy your model"](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-deployment.html) -in the SageMaker documentation. +- To use the Bedrock models, you need access to the Bedrock service, and you will need to authenticate via [boto3](https://github.com/boto/boto3), which also needs to be installed, as mentioned previously. For more information, see the [Amazon Bedrock Homepage](https://aws.amazon.com/bedrock/). -To use SageMaker's models, you will need to authenticate via -[boto3](https://github.com/boto/boto3). +- You need the `pillow` Python package to use Hugging Face Hub's text-to-image models. -For example, to use OpenAI models, use the chat interface settings panel to choose the OpenAI language model: +- You can find a list of Hugging Face's models at [https://huggingface.co/models](https://huggingface.co/models). -Screen shot of the chat settings interface with language model dropdown open +- To use NVIDIA models, create a free account with the [NVIDIA NGC service](https://catalog.ngc.nvidia.com/), which hosts AI solution catalogs, containers, models, and more. Navigate to Catalog > [AI Foundation Models](https://catalog.ngc.nvidia.com/ai-foundation-models), and select a model with an API endpoint. Click "API" on the model's detail page, and click "Generate Key". Save this key, and set it as the environment variable `NVIDIA_API_KEY` to access any of the model endpoints. -Then, enter your API key in the 'API Keys' section. +- SageMaker endpoint names are created when you deploy a model. For more information, see + ["Create your endpoint and deploy your model"](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-deployment.html) + in the SageMaker documentation. To use SageMaker's models, you will also need to be authenticated via [boto3](https://github.com/boto/boto3). :::{attention} :name: open-ai-cost @@ -264,43 +236,94 @@ The chat interface sends data to generative AI models hosted by third parties. P Once you have started JupyterLab, click the new "chat" icon in the left side panel to open the chat interface. You can right-click on the panel icon and move it to the other side, if you prefer. -Screen shot of the setup interface +Screen shot of the chat interface -The first time you open the chat interface, Jupyter AI will ask you which models you want to use as a language model and as an embedding model. Once you have made your selections, the UI may display text boxes for one or more settings keys. +Make sure you have chosen a language model by going to `Settings` -> `Jupyternaut settings` as shown in the Model Providers section above. You can also enter the model paramaters as well as the related API keys if necessary. -:::{admonition} Language models and embedding models -:class: tip -:name: language-models-and-embedding-models -Users may select a language model and, optionally, an embedding model. You should select one of each so that you can use the full functionality of the chat interface. +A **language model** responds to users' messages in the chat panel using **Personas**. The default Persona is `Jupyternaut`. It accepts a prompt and produces a response. Language models are typically _pre-trained_; they are ready to use, but their training sets are biased and incomplete, and users need to be aware of their biases when they use the chat interface. Here is an example of a new chat. Click on `+Chat` at the top left of the chat panel and name a new chat in the following window that will pop up: -A **language model** responds to users' messages in the chat panel. It accepts a prompt and produces a response. Language models are typically *pre-trained*; they are ready to use, but their training sets are biased and incomplete, and users need to be aware of their biases when they use the chat interface. +Screen shot of the new chat -An **embedding model** is used when [learning and asking about local data](#learning-about-local-data). These models can transform your data, including documents and source code files, into vectors that can help Jupyter AI compose prompts to language models. +Enter the name of the chat and see the chat appear in the chat panel: -Your language model and your embedding model do not need to be provided by the same vendor, but you will need authentication credentials for each model provider that you use. -::: +Screen shot of the new chat +You can then @-mention the Persona in the chat prompt area as shown and issue a prompt to the persona. -Screen shot of the setup interface, showing model selections and key +Screen shot of the chat persona -Before you can use the chat interface, you need to provide your API keys for the model providers that you have selected. Paste or type your keys into the boxes provided. +To compose a message, type it in the text box at the bottom of the chat interface and press ENTER to send it. You can press SHIFT+ENTER to add a new line. (These are the default keybindings; you can change them in the chat settings pane.) Once you have sent a message, you should see a response from Jupyternaut, the Jupyter AI chatbot persona. -Screen shot of the setup interface, showing model selections and key populated +Screen shot of the chat prompt -Once you have set all the necessary keys, click the "back" (left arrow) button in the upper-left corner of the Jupyter AI side panel. The chat interface now appears, with a help menu of available `/` (slash) commands, and you can ask a question using the message box at the bottom. +And then we get a response: -Screen shot of the initial chat interface. +Screen shot of the new chat response + +You can also see the `Delete` button shown alongside the prompt if you need to clear up the chat; there is a similar button in the response area as well. + +All the chat content is stored in a file named `.chat` where an entire record of the chat is maintained as a Jupyter Server document. This persistent chat is also used as context memory when invoking the LLM from the chat. You can also open the chat file and see its contents as shown here. + +Screen shot of the chat doc + +You can remove the chat by simply deleting its `.chat` file. + +Additional chat streams may be started as well, mimicking chat channels in social media applications. For example, create a second chat using the `+ Chat` button: + +Screen shot of the second chat + +## Attaching context to the prompt + +The chat panel also allows adding a flat file as context as shown. You can see how to use the drop-down to select your chat stream and then select a file followed by a prompt. The example below shows a python file and the chat explains it. + +Screen shot of using a file as context + +You can also attach files using the paperclip icon in the chat window. + +## Additional details about the chat interface + + -Screen shot of an example "Hello world" message sent to Jupyternaut, who responds with "Hello world, how are you today?" + class="screenshot" /> --> The chat backend remembers the last two exchanges in your conversation and passes them to the language model. You can ask follow up questions without repeating information from your previous conversations. Here is an example of a chat conversation with a follow up question: #### Initial question + Screen shot of an example coding question sent to Jupyternaut, who responds with the code and explanation. +We see that Jupyter AI not only created the code, but it also added it to a notebook. Then, it asked if it would be allowed to run the code in the notebook, and when it was prompted to do so, it ran the code and returned the answers. + #### Follow-up question + +Next, you can ask that the function be extended. The function is updated and executed as shown: + Screen shot of an example follow up question sent to Jupyternaut, who responds with the improved code and explanation. - ### Amazon Bedrock Usage Jupyter AI enables use of language models hosted on [Amazon Bedrock](https://aws.amazon.com/bedrock/) on AWS. Ensure that you have authentication to use AWS using the `boto3` SDK with credentials stored in the `default` profile. Guidance on how to do this can be found in the [`boto3` documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html). For details on enabling model access in your AWS account, using cross-region inference, or invoking custom/provisioned models, please see our dedicated documentation page on [using Amazon Bedrock in Jupyter AI](bedrock.md). - ### OpenRouter and OpenAI Interface Usage -Jupyter AI enables use of language models accessible through [OpenRouter](https://openrouter.ai)'s unified interface. Examples of models that may be accessed via OpenRouter are: [Deepseek](https://openrouter.ai/deepseek/deepseek-chat), [Qwen](https://openrouter.ai/qwen/), [mistral](https://openrouter.ai/mistralai/), etc. OpenRouter enables usage of any model conforming to the OpenAI API. +Jupyter AI enables use of language models accessible through [OpenRouter](https://openrouter.ai)'s unified interface. Examples of models that may be accessed via OpenRouter are: [Deepseek](https://openrouter.ai/deepseek/deepseek-chat), [Qwen](https://openrouter.ai/qwen/), [Mistral](https://openrouter.ai/mistralai/), etc. OpenRouter enables usage of any model conforming to the OpenAI API. In the `Chat model` area in `Jupyternaut settings` choose `openrouter/` to see all the models from this provider. -Likewise, for many models, you may directly choose the OpenAI provider in Jupyter AI instead of OpenRouter in the same way. +Likewise, for many models, you may directly choose the OpenAI provider in Jupyter AI instead of OpenRouter in the same way. In the `Chat model` area in `Jupyternaut settings` choose `openai/` to see all the models from this provider. -For details on enabling model access via the AI Settings and using models via OpenRouter or OpenAI, please see the dedicated documentation page on using [OpenRouter and OpenAI providers in Jupyter AI](openrouter.md). + - -### SageMaker endpoints usage + -### GPT4All usage (early-stage) + ### Ollama usage -To get started, follow the instructions on the [Ollama website](https://ollama.com/) to set up `ollama` and download the models locally. To select a model, enter the model name in the settings panel, for example `deepseek-coder-v2`. You can see all locally available models with `ollama list`. +To get started, follow the instructions on the [Ollama website](https://ollama.com/) to set up `ollama` and download the models locally. To select a model, enter the model name in the settings panel, for example `deepseek-coder-v2`. You can see all locally available models with `ollama list`. For the Ollama models to be available to JupyterLab-AI, your Ollama server _must_ be running. You can check that this is the case by calling `ollama serve` at the terminal, and should see something like: @@ -451,29 +477,30 @@ $ ollama serve Error: listen tcp 127.0.0.1:11434: bind: address already in use ``` +This indicates that Ollama is running on its default port number, 11434. + In some platforms (e.g. macOS or Windows), there may also be a graphical user interface or application that lets you start/stop the Ollama server from a menu. -:::{tip} -If you don't see Ollama listed as a model provider in the Jupyter-AI configuration box, despite confirming that your Ollama server is active, you may be missing the [`langchain-ollama` python package](https://pypi.org/project/langchain-ollama/) that is necessary for Jupyter-AI to interface with Ollama, as indicated in the [model providers](#model-providers) section above. + By default, Ollama is served on `127.0.0.1:11434` (locally on port `11434`), so Jupyter AI expects this by default. If you wish to use a remote Ollama server with a different IP address or a local Ollama server on a different port number, you have to configure this in advance. -To configure this in the chat, set the "Base API URL" field in the AI settings page to your Ollama server's custom IP address and port number: +To configure this in Jupyternaut settings, set the `api_base` paremeter field in the Model parameters section to your Ollama server's custom IP address and port number: Screenshot of the settings panel with Ollama on non-default port. - -To configure this in the magic commands, you should set the `OLLAMA_HOST` environment variable to the your Ollama server's custom IP address and port number (assuming you chose 11000) in a new code cell: +To configure this in the magic commands, you should set the `OLLAMA_HOST` environment variable to the your Ollama server's custom IP address and port number (assuming you chose 10000) in a new code cell: ``` %load_ext jupyter_ai_magics -os.environ["OLLAMA_HOST"] = "http://localhost:11000" +os.environ["OLLAMA_HOST"] = "http://localhost:10000" ``` After running that cell, the AI magic command can then be used like so: @@ -501,16 +528,18 @@ Review your model provider's cost policy before making large requests. After highlighting a portion of your notebook, check "Include selection" in the chat panel, type your message, and then send your message. Your outgoing message will include your selection. Screen shot of JupyterLab with Jupyter AI's chat panel active. A Python function is selected, the user has "What does this code do?" as their prompt, and the user has chosen to include the selection with their message. Below your message, you will see Jupyternaut's response. Screen shot of Jupyter AI's chat panel, showing an answer to the question asked above. -You can copy Jupyternaut's response to the clipboard so that you can paste it into your notebook, or into any other application. You can also choose to replace the selection with Jupyternaut's response by clicking "Replace selection" before you send your message. +You can copy Jupyternaut's response to the clipboard so that you can paste it into your notebook, or into any other application. You can also choose to replace the selection with Jupyternaut's response by clicking "Replace selection" before you send your message. The generated response can also be copied to a cell above or below the active cell. This is is shown below. :::{warning} :name: replace-selection @@ -520,23 +549,28 @@ you run it. ::: Screen shot of Jupyter AI with a Python function selected, the user having typed "Rewrite this function to be iterative, not recursive" as their prompt, and with the user having chosen to include the selection with their message and to replace the selection with the response. After Jupyternaut sends a response, your notebook will be updated immediately with the response replacing the selection. You can also see the response in the chat panel. ### Generating a new notebook -You can use Jupyter AI to generate an entire notebook from a text prompt. To get started, open the chat panel, and send it a message starting with `/generate`. +You can use Jupyter AI to generate an entire notebook from a text prompt. To get started, open the chat panel, and send it a message asking it to generate a new notebook to do what you request. Screen shot of a prompt reading "/generate A demonstration of how to use Matplotlib" in Jupyter AI Generating a notebook can take a substantial amount of time, so Jupyter AI will respond to your message immediately while it works. You can continue to ask it other questions in the meantime. +When Jupyter AI is done generating your notebook, it will open the notebook in JupyterLab and ask you to link it with the kernel to run it. Here is the response to the prompt above: + Screen shot of Jupyternaut responding to a generate message with a message that it is working on a notebook. :::{note} @@ -547,8 +581,6 @@ as you would normally. Do not shut your JupyterLab instance down while Jupyter AI is working. ::: -When Jupyter AI is done generating your notebook, it will send you another message with the filename that it generated. You can then open this file using the file browser. - :::{warning} :name: generated-notebook Generated notebooks may contain errors and may have unintended side effects when @@ -556,7 +588,7 @@ you run the code contained in them. Please review all generated code carefully before you run it. ::: -### Learning about local data + ### Fixing a code cell with an error -The `/fix` command can be used to fix any code cell with an error output in a -Jupyter notebook file. To start, type `/fix` into the chat input. Jupyter AI -will then prompt you to select a cell with error output before sending the -request. +You can drag a cell with an error into the chat box and ask Jupyternaut to fix it. + + Screenshot of a code cell with error output selected. -After this, the Send button to the right of the chat input will be enabled, and -you can use your mouse or keyboard to send `/fix` to Jupyternaut. The code cell -and its associated error output are included in the message automatically. When -complete, Jupyternaut will reply with suggested code that should fix the error. -You can use the action toolbar under each code block to quickly replace the -contents of the failing cell. +After this, the Send button to the right of the chat input will be enabled, and you can use your mouse or keyboard to send this to Jupyternaut. The code cell and its associated error output are included in the message automatically. When complete, Jupyternaut will update the notebook with the corrected code. Screenshot of a response from `/fix`, with the "Replace active cell" action hovered. - + class="screenshot" style="max-width:95%" /> ### Additional chat commands -To start a new conversation, use the `/clear` command. This will clear the chat panel and reset the model's memory. +To start a new conversation, simply use the `+ Chat` button at the top left of the chat panel. + +To delete elements of the chat you can use the "trash" icon on the right of the chat prompt or the chat response in the chat panel. The "trash" icon will appear when you mouse over any prompt or response. You may delete either the prompt or the response, or both. These will be removed from the chat panel as well as the underlying `.chat` Jupyter server document. If you want to delete the entire chat, you can just delete the relevant `.chat` file in your folder. ## The `%ai` and `%%ai` magic commands Jupyter AI can also be used in notebooks via Jupyter AI magics. This section provides guidance on how to use Jupyter AI magics effectively. The examples in -this section are based on the [Jupyter AI example notebooks](https://github.com/jupyterlab/jupyter-ai/blob/main/examples/). +this section cover a range of commands that may be used with the `%ai%` and `%%ai` magics. If you already have `jupyter_ai` installed, the magics package -`jupyter_ai_magics` is installed automatically. Otherwise, run +`jupyter_ai_magic_commands` is installed automatically. The code for the magics is in the `jupyter-ai-magic-commands` [repository](https://github.com/jupyter-ai-contrib/jupyter-ai-magic-commands). It can be installed separately using the command: - pip install jupyter_ai_magics - -in your terminal to install the magics package. +``` +pip install jupyter-ai-magic-commands +``` Before you send your first prompt to an AI model, load the IPython extension by running the following code in a notebook cell or IPython shell: ``` -%load_ext jupyter_ai_magics +%load_ext jupyter_ai_magic_commands ``` This command should not produce any output. @@ -710,14 +735,14 @@ This command should not produce any output. :::{note} If you are using remote kernels, such as in Amazon SageMaker Studio, the above command will throw an error. You will need to install the magics package -on your remote kernel separately, even if you already have `jupyter_ai_magics` +on your remote kernel separately, even if you already have `jupyter_ai_magic_commands` installed in your server's environment. In a notebook, run ``` %pip install jupyter_ai_magics ``` -and re-run `%load_ext jupyter_ai_magics`. +and re-run `%load_ext jupyter_ai_magic_commands`. ::: Once the extension has loaded, you can run `%%ai` cell magic commands and @@ -725,37 +750,74 @@ Once the extension has loaded, you can run `%%ai` cell magic commands and You can also pass `--help` as an argument to any line magic command (for example, `%ai list --help`) to learn about what the command does and how to use it. +### Listing available models + +Jupyter AI also includes multiple subcommands, which may be invoked via the +`%ai` _line_ magic. Jupyter AI uses subcommands to provide additional utilities +in notebooks while keeping the same concise syntax for invoking a language model. + +The `%ai list` subcommand prints a list of available providers and models. Some +providers explicitly define a list of supported models in their API. However, +other providers, like Hugging Face Hub, lack a well-defined list of available +models. In such cases, it's best to consult the provider's upstream +documentation. The [Hugging Face website](https://huggingface.co/) includes a +list of models, for example. To get help: + +Screenshot of magics help for the list attribute. + +Optionally, you can specify a provider ID as a positional argument to `%ai list` +to get all models provided by one provider. For example, `%ai list openai` will +display only models provided by the `openai` provider. +To see all the available providers run (the top of the list is shown): + ### Choosing a provider and model The `%%ai` cell magic allows you to invoke a language model of your choice with -a given prompt. The model is identified with a **global model ID**, which is a string with the -syntax `:`, where `` is the ID of the -provider and `` is the ID of the model scoped to that provider. -The prompt begins on the second line of the cell. +a given prompt. The model is identified with a **global model ID**, which is a string with the syntax `:`, where `` is the ID of the provider and `` is the ID of the model scoped to that provider. + +Screenshot of magics list of all providers. + +To see all the models for a given provider: -For example, to send a text prompt to the provider `anthropic` and the model ID -`claude-v1.2`, enter the following code into a cell and run it: +Screenshot of magics list for a selected provider. + +And to list all available models: + +Screenshot of magics list of all models. + +### Invoking magics + +The prompt begins on the second line of the cell. For example, to send a text prompt to the provider `bedrock` and the model ID `anthropic.claude-3-5-haiku-20241022-v1:0`, enter the following code into a cell and run it: ``` -%%ai anthropic:claude-v1.2 -Write a poem about C++. +%%ai bedrock/anthropic.claude-3-5-haiku-20241022-v1:0 +What is the capital of France? ``` -We currently support the following language model providers: +The response is: -- `ai21` -- `anthropic` -- `anthropic-chat` -- `bedrock` -- `bedrock-chat` -- `bedrock-custom` -- `cohere` -- `huggingface_hub` -- `nvidia-chat` -- `ollama` -- `openai` -- `openai-chat` -- `sagemaker-endpoint` +```text +The capital of France is Paris. +``` + +Another example using a different provider: + +Screenshot of magics example. ### Configuring a default model @@ -780,24 +842,7 @@ c.AiMagics.initial_language_model = "anthropic:claude-v1.2" The location of `ipython_config.py` file is documented in [IPython configuration reference](https://ipython.readthedocs.io/en/stable/config/intro.html). -### Listing available models - -Jupyter AI also includes multiple subcommands, which may be invoked via the -`%ai` *line* magic. Jupyter AI uses subcommands to provide additional utilities -in notebooks while keeping the same concise syntax for invoking a language model. - -The `%ai list` subcommand prints a list of available providers and models. Some -providers explicitly define a list of supported models in their API. However, -other providers, like Hugging Face Hub, lack a well-defined list of available -models. In such cases, it's best to consult the provider's upstream -documentation. The [Hugging Face website](https://huggingface.co/) includes a -list of models, for example. - -Optionally, you can specify a provider ID as a positional argument to `%ai list` -to get all models provided by one provider. For example, `%ai list openai` will -display only models provided by the `openai` provider. - -### Abbreviated syntax + ### Formatting the output @@ -860,6 +905,13 @@ A function that computes the lowest common multiples of two integers, and a function that runs 5 test cases of the lowest common multiple function ``` +Another code example: + +Screenshot of magics formatting output. + ### Configuring the amount of history to include in the context By default, two previous Human/AI message exchanges are included in the context of the new prompt. @@ -1035,11 +1087,33 @@ c.AiMagics.aliases = { The location of `ipython_config.py` file is documented in [IPython configuration reference](https://ipython.readthedocs.io/en/stable/config/intro.html). -### Using magic commands with SageMaker endpoints +Here are some examples of using aliases. You can shorten the magics in the first line of each cell by setting a much shorter alias as shown below: + +Screenshot of magics set alias. + +Usage of the alias is shown here: + +Screenshot of magics usage of alias. + +You can remove the alias above with the `dealias` command: + +Screenshot of magics usage of alias. + + ## Configuration @@ -1102,26 +1177,29 @@ These values are offered as a starting point for users, so they don't have to se the selections they make in the settings panel will take precedence over these values. Specify default language model + ```bash -jupyter lab --AiExtension.initial_language_model=bedrock-chat:anthropic.claude-v2 +jupyter lab --AiExtension.initial_language_model=bedrock/anthropic.claude-3-5-haiku-20241022-v1:0 ``` -Specify default embedding model + Specify default API keys + ```bash jupyter lab --AiExtension.default_api_keys={'OPENAI_API_KEY': 'sk-abcd'} ``` - ### Blocklisting providers This configuration allows for blocking specific providers in the settings panel. @@ -1184,10 +1262,10 @@ unpacked and passed as-is to the provider class. #### Configuring as a startup option In this sample, the `bedrock` provider will be created with the value for -`model_kwargs` when `ai21.j2-mid-v1` model is selected. +`model_kwargs` when `bedrock/anthropic.claude-3-5-haiku-20241022-v1:0` model is selected. ```bash -jupyter lab --AiExtension.model_parameters bedrock:ai21.j2-mid-v1='{"model_kwargs":{"maxTokens":200}}' +jupyter lab --AiExtension.model_parameters bedrock/anthropic.claude-3-5-haiku-20241022-v1:0='{"model_kwargs":{"maxTokens":200}}' ``` Note the usage of single quotes surrounding the dictionary to escape the double @@ -1199,11 +1277,10 @@ BedrockProvider(model_kwargs={"maxTokens":200}, ...) ``` Here is another example, where `anthropic` provider will be created with the -values for `max_tokens` and `temperature`, when `claude-2` model is selected. - +values for `max_tokens` and `temperature`, when `bedrock/anthropic.claude-3-5-haiku-20241022-v1:0` model is selected. ```bash -jupyter lab --AiExtension.model_parameters anthropic:claude-2='{"max_tokens":1024,"temperature":0.9}' +jupyter lab --AiExtension.model_parameters bedrock/anthropic.claude-3-5-haiku-20241022-v1:0='{"max_tokens":1024,"temperature":0.9}' ``` The above will result in the following LLM class to be generated. @@ -1218,8 +1295,8 @@ command-line, you can append them as additional arguments to ```bash jupyter lab \ ---AiExtension.model_parameters bedrock:ai21.j2-mid-v1='{"model_kwargs":{"maxTokens":200}}' \ ---AiExtension.model_parameters anthropic:claude-2='{"max_tokens":1024,"temperature":0.9}' +--AiExtension.model_parameters bedrock/anthropic.claude-3-5-haiku-20241022-v1:0='{"model_kwargs":{"maxTokens":200}}' \ +--AiExtension.model_parameters openai/gpt-4.1='{"max_tokens":1024,"temperature":0.9}' ``` However, for more complex configuration, we highly recommend that you specify @@ -1230,20 +1307,20 @@ following section. This configuration can also be specified in a config file in json format. -Here is an example for configuring the `bedrock` provider for `ai21.j2-mid-v1` +Here is an example for configuring the `bedrock` provider for `bedrock/anthropic.claude-3-5-haiku-20241022-v1:0` model. ```json { - "AiExtension": { - "model_parameters": { - "bedrock:ai21.j2-mid-v1": { - "model_kwargs": { - "maxTokens": 200 - } - } + "AiExtension": { + "model_parameters": { + "bedrock/anthropic.claude-3-5-haiku-20241022-v1:0": { + "model_kwargs": { + "maxTokens": 200 } + } } + } } ``` diff --git a/docs/source/users/openrouter.md b/docs/source/users/openrouter.md deleted file mode 100644 index 4261297b8..000000000 --- a/docs/source/users/openrouter.md +++ /dev/null @@ -1,75 +0,0 @@ -# Using OpenRouter or OpenAI Interfaces in Jupyter AI - -[(Return to the Chat Interface page)](index.md#openrouter-usage) - -For models that are compatible with the OpenAI library, Jupyter AI provides configuration via OpenRouter. By supporting the configuration of parameters such as the api_key, base_url, and model, various large model services compatible with the OpenAI library call methods can be used. For more details on OpenRouter as a unified interface for LLMs, see https://openrouter.ai/. - -As an example, we walk through the steps needed to use models from [Deepseek](https://www.deepseek.com) via the OpenRouter provider. If you do not have `langchain-openai` installed, please install it and restart JupyterLab. This is necessary as it provides the SDK for accessing any OpenAI API. - -First, navigate to the `AI Settings` pane via the AI settings button in `v2` or via the dropdown in `v3` of Jupyter AI, as shown below: - -Screenshot of the dropdown where AI Settings is chosen and it opens tab in Jupyter AI where models are selected. - -Second, select the `OpenRouter :: *` model provider in the Jupyter AI settings. If you don't see this, please verify that you have installed `langchain-openai` and that you are using `jupyter_ai>=2.24.0`. Be sure to restart JupyterLab after upgrading or installing either package. - -Jupyter AI's settings page with the OpenRouter provider selected is shown below: - -Screenshot of the tab in Jupyter AI where OpenRouter model access is selected. - -Type in the model name and the API base URL corresponding to the model you wish to use. For Deepseek, you should use `https://api.deepseek.com` as the API base URL, and use `deepseek-chat` as the local model ID. - -If you have an OpenRouter account and wish to use their API and URL, it is also possible using the OpenRouter provider in Jupyter AI, as shown here: - -Screenshot of the tab in Jupyter AI where OpenRouter model access is selected with its own API and URL. - -If you are using OpenRouter for the first time it will also require entering the `OPENROUTER_API_KEY`. If you have used OpenRouter before with a different model provider, you will need to update the API key. After doing this, click "Save Changes" at the bottom to save your settings. - -You should now be able to use Deepseek! An example of usage is shown next: - -Screenshot of chat using Deepseek via the OpenRouter provider. - -In a similar manner, models may also be invoked directly using the OpenAI provider interface in Jupyter AI. First, you can choose the OpenAI provider and then enter in the model ID, as shown on the OpenAI [models page](https://platform.openai.com/docs/models). An example is shown below: - -Screenshot of chat using gpt-4o via the OpenAI provider. - -DeepSeek models may be used via the same interface, if the base API url is provided: - -Screenshot of chat using deepseek via the OpenAI provider. - -For DeepSeek models, enter the DeepSeek API for the OpenAI API key. - -Models deployed using vLLM may be used in a similar manner: - -Screenshot of chat using vllm via the OpenAI provider. - -Usage of models using vLLM and their deployment is discussed [here](vllm.md). - -For embedding models from OpenAI, you can generically choose them using the AI Settings interface as well: - -Screenshot of embedding use via the OpenAI provider. - -[(Return to the Chat Interface page)](index.md#openrouter-usage) diff --git a/docs/source/users/vllm.md b/docs/source/users/vllm.md index 4fda2bb56..577a38a79 100644 --- a/docs/source/users/vllm.md +++ b/docs/source/users/vllm.md @@ -8,13 +8,14 @@ To use `vLLM` via `OpenRouter` as described below you will need to upgrade to `jupyter-ai >= 2.29.1`. ::: - Depending on your hardware set up you will install `vLLM` using these [instructions](https://docs.vllm.ai/en/latest/getting_started/installation/index.html). It is best to install it in a dedicated python environment. Once it is installed you may start serving any model with the command: + ```python vllm serve ``` + As an example, the deployment of the `Phi-3-mini-4k-instruct` model is shown below, with checks to make sure it is up and running: :8000/v1` -Start up Jupyter AI and update the AI Settings as follows (notice that we are using [OpenRouter](openrouter.md) as the provider, which is a unified interface for LLMs based on OpenAI's API interface): +Therefore, to use a model from a vLLM server, make sure to type in the model id in the Jupyternaut settings and also add the URL into the `base_api` model parameter (in the same way as shown for Ollama above). + + [(Return to the Chat Interface page)](index.md#vllm-usage) diff --git a/pyproject.toml b/pyproject.toml index 9ac326c8f..1eefac1cc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,6 +23,7 @@ classifiers = [ "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", ] dynamic = ["version"]