Jupyter AI

Common errors

• ModuleNotFoundError: No module named 'langchain'

  cause Jupyter AI v3.0.0 and later versions have deprecated and removed Langchain in favor of LiteLLM for all LLM integrations.
  fix If you were previously relying on Langchain for custom model setups, you need to migrate your configuration to LiteLLM. Ensure you are running Jupyter AI v3.0.0+ and LiteLLM is correctly installed (it's a core dependency).

• Command '%%ai' not found or 'jupyter_ai' server extension not found.

  cause The Jupyter AI server extension or magic commands were not loaded or enabled correctly, or the Jupyter server was not restarted after installation.
  fix Ensure `jupyter-ai` is installed (`pip install jupyter-ai`), and restart your JupyterLab server. Verify the extension is enabled using `jupyter labextension list` and `jupyter server extension list`. If issues persist, try `jupyter lab build`.

• Error: Missing API key for model provider 'openai' (or another provider). Please set the OPENAI_API_KEY environment variable.

  cause The selected LLM provider requires an API key that has not been set in the environment variables or configured within JupyterLab's settings.
  fix Set the required API key as an environment variable (e.g., `export OPENAI_API_KEY="your_key_here"` in your shell before starting JupyterLab) or configure it via the JupyterLab settings editor under the Jupyter AI section in the UI.

• Permission denied: Agent tried to write file 'example.py'.

  cause A Jupyter AI agent attempted to perform an action (e.g., file write, command execution) that requires user approval under the new tool call permissions system in v3.0.0.
  fix Look for a prompt in the JupyterLab UI (often in the chat panel or a pop-up dialog) asking for permission to execute the action. You must explicitly approve or deny the action for the agent to proceed.

Warnings

• breaking Jupyter AI v3.0.0 introduces significant breaking changes, including a complete overhaul of the agent architecture via the Agent Client Protocol (ACP) and a migration from Langchain to LiteLLM for LLM integration.
  Fix: Review the official Jupyter AI v3.0.0 documentation and migration guides. Existing codebases or configurations relying on Langchain providers will need to be updated to use LiteLLM. Agent interactions will follow the new ACP model, which may require adjustments to prompts or expectations.
• breaking The internal LLM integration framework changed from Langchain to LiteLLM in v3.0.0beta6 (which carried into v3.0.0 stable). Any custom integrations or model configurations built specifically on Langchain will no longer work.
  Fix: Reconfigure your LLM providers and models according to LiteLLM's conventions. Consult LiteLLM documentation for details on setting up credentials and models. Remove any explicit Langchain dependencies from your environment if they were only for Jupyter AI.
• gotcha Jupyter AI agents in v3.0.0 now require explicit user permission for tool calls that modify the filesystem or execute commands within JupyterLab (e.g., writing files, running terminal commands).
  Fix: Be aware that agent actions might pause, awaiting your approval in the JupyterLab UI (often in the chat panel or a pop-up dialog). This is a security feature; monitor the agent's output and approve/deny actions as prompted.
• gotcha The Dask dashboard, which shows progress for '/learn' calls, is disabled by default starting from v2.31.7. This is intended to avoid unintended resource usage in production environments.
  Fix: If you need to monitor Dask activity for development or debugging, enable it by starting your Jupyter server with `--AiExtension.enable_dask_dashboard=True`. The dashboard will typically be available on port `8787`.

Install

• pip install jupyter-ai Install core package
• jupyter labextension list Verify JupyterLab extension (look for @jupyter-ai/jupyter-ai enabled)
• jupyter server extension list Verify Jupyter server extension (look for jupyter_ai enabled)

Imports

• AiMagics

  from jupyter_ai_magics import AiMagics

  Jupyter AI is primarily used via the JupyterLab UI and magic commands (e.g., `%%ai`). Direct programmatic import of its core functionality like `AiMagics` is less common for end-users, but can be used by developers or for advanced scripting to interact with the magic commands programmatically.

Quickstart

To use Jupyter AI, ensure it's installed and your JupyterLab server is running. You primarily interact with Jupyter AI through its dedicated chat interface in the JupyterLab sidebar or directly within notebook cells using magic commands (e.g., `%%ai`). Most LLM providers require an API key, which should be set as an environment variable before launching JupyterLab or configured via JupyterLab's settings. The example demonstrates loading magic commands, listing models, and basic usage for code generation and agent interaction.

import os

# Before starting JupyterLab, set your API key for a model provider.
# Example for OpenAI:
# os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_KEY')
# For other providers like Anthropic:
# os.environ['ANTHROPIC_API_KEY'] = os.environ.get('ANTHROPIC_API_KEY', 'YOUR_ANTHROPIC_KEY')

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

# (Optional) Explicitly load the AI magic commands, though often loaded automatically
# %load_ext jupyter_ai_magics

# List available models and providers
# %%ai list

# Use a model for code generation
# %%ai chatgpt -f code
# Create a Python function to calculate the Nth Fibonacci number recursively.

# Use an agent to interact with Jupyter (requires agent-capable model like Claude, Gemini)
# %%ai claude -m anthropic.claude-3-haiku-20240307-v1:0
# Write a simple Python script to list files in the current directory and save it as 'list_files.py'.
# Note: Agent actions that modify files or execute commands will prompt for approval in the UI.

# --- Using the Jupyter AI chat interface: ---
# 1. Open the 'Jupyter AI' panel in the left sidebar of JupyterLab.
# 2. Select a model provider and model from the dropdowns.
# 3. Start a conversation or ask for assistance with your notebook content.