Jupyter AI Magics

2.31.7 · active · verified Thu Apr 16

Jupyter AI Magics provides AI capabilities directly within Jupyter notebooks and JupyterLab via convenient line (`%ai`) and cell (`%%ai`) magics. It integrates with various Large Language Models (LLMs) from different providers (e.g., OpenAI, Anthropic, Ollama, Hugging Face). The current version is 2.31.7, and releases are frequent, often bi-weekly, to add new features, fix bugs, and expand LLM integrations.

Common errors

```
ModuleNotFoundError: No module named 'jupyter_ai'
```
cause The `jupyter-ai-magics` package or its core dependency `jupyter-ai` is not installed, or the Jupyter environment is not correctly configured to find it.

fix `pip install jupyter-ai-magics` in the same Python environment that your Jupyter server is running from. If already installed, try restarting your Jupyter kernel.
```
MagicsProviderError: No model selected. Please select a model using '%ai_provider <provider_id>' or '%ai --model <model_id>'
```
cause No LLM provider is configured (e.g., missing API key for OpenAI) or a specific model was not selected for the magic command.

fix Set the required API key as an environment variable (e.g., `os.environ['OPENAI_API_KEY'] = 'sk-...'`) and ensure it's available before loading the magics, or explicitly specify the model in the command, e.g., `%ai openai:gpt-3.5-turbo "..."`.
```
SyntaxError: invalid syntax (when running %load_ext jupyter_ai in a .py file)
```
cause IPython magic commands (like `%load_ext`) are being executed in a standard Python script (.py file) where they are not recognized.

fix Run the code within a Jupyter notebook cell, JupyterLab, or an IPython interactive session. Magic commands are not part of standard Python syntax.
```
openai.AuthenticationError: Incorrect API key provided: You must provide your OpenAI secret key...
```
cause The OpenAI API key provided is incorrect, expired, or missing the `sk-` prefix, or the environment variable is not set correctly.

fix Verify your `OPENAI_API_KEY` environment variable is set with a valid and active key obtained from your OpenAI dashboard. Ensure it starts with `sk-`.

Warnings

gotcha LLM Provider Configuration Required: Jupyter AI needs valid API keys (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY) or a running local server (e.g., Ollama) to function. Without proper configuration, magic commands will fail with errors like 'No model selected' or 'AuthenticationError'.
Fix: Set required API keys as environment variables before loading the magics, or ensure your local LLM server is running and accessible. Refer to the official documentation for specific provider setup instructions.
gotcha Kernel Restart After Installation/Config Changes: Sometimes, after installing `jupyter-ai-magics` or modifying LLM provider configurations (especially environment variables), you may need to restart your Jupyter kernel for the magics to be properly recognized and activated.
Fix: If magics are not found or configuration changes don't take effect, try restarting the Jupyter kernel (Kernel -> Restart Kernel... in JupyterLab/Notebook).
breaking Changes to Model Naming and Provider Aliases: Early versions had slightly different provider identifiers or model names. As the project evolves, these names can be updated or new providers added, potentially breaking older scripts that hardcode specific model strings.
Fix: Always use `%ai list` to verify available providers and models. Update your scripts to use the current naming conventions or, for robustness, abstract model names where possible.
gotcha Magics Only Work in Jupyter Environments: The `%ai` and `%%ai` commands are IPython magics and will only execute correctly within a Jupyter notebook, JupyterLab, or IPython shell. Attempting to run them in a standard Python script will result in a `SyntaxError`.
Fix: Ensure you are running your code within a Jupyter or IPython environment. For programmatic LLM interaction outside of Jupyter, use the underlying LLM client libraries directly (e.g., `openai` Python package).

Install

pip install jupyter-ai-magics Install package

Imports

AiMagics
wrong:
```
import jupyter_ai_magics
```
correct:
```
from jupyter_ai_magics.magics import AiMagics
```
While AiMagics is the class providing the functionality, users typically load the magics in a Jupyter cell using `%load_ext jupyter_ai` rather than directly importing this class via Python.

Quickstart

This quickstart demonstrates how to set up environment variables for LLM providers (e.g., OpenAI), load the Jupyter AI magics extension in a Jupyter notebook cell, and then use both the line (`%ai`) and cell (`%%ai`) magics to interact with a Large Language Model. Ensure you have the necessary LLM client libraries installed (e.g., `pip install openai`) and valid API keys or a running local LLM server.

import os

# --- In a Jupyter notebook cell ---

# 1. Set your API key as an environment variable.
#    For OpenAI: uncomment the line below and replace 'sk-YOUR_OPENAI_API_KEY'
# os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'sk-dummy-for-quickstart-test')

#    For local models like Ollama, ensure the server is running:
#    e.g., in your terminal: `ollama run mistral`

# 2. Load the Jupyter AI magics extension.
#    This makes the %ai and %%ai commands available in your notebook.
# %load_ext jupyter_ai

# 3. (Optional) List available providers and models
# %ai list

# 4. Use the %ai line magic for single-line prompts.
#    Replace 'openai:gpt-3.5-turbo' with your desired model and provider.
# %ai openai:gpt-3.5-turbo "What is the capital of France?"

# 5. Use the %%ai cell magic for multi-line prompts.
#    The prompt is the content of the cell after the magic.
# %%ai openai:gpt-3.5-turbo
# Write a short poem about the benefits of learning Python.
# It should be 4 lines long and rhyme AABB.

view raw JSON →