{"id":9057,"library":"jupyter-ai-magics","title":"Jupyter AI Magics","description":"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.","status":"active","version":"2.31.7","language":"en","source_language":"en","source_url":"https://github.com/jupyterlab/jupyter-ai","tags":["jupyter","ai","llm","magic","notebook","jupyterlab","openai","ollama","anthropic"],"install":[{"cmd":"pip install jupyter-ai-magics","lang":"bash","label":"Install package"}],"dependencies":[{"reason":"Core Jupyter AI functionality and backend logic.","package":"jupyter-ai","optional":false},{"reason":"Required to use OpenAI models (e.g., GPT-3.5, GPT-4).","package":"openai","optional":true},{"reason":"Required to use Anthropic models (e.g., Claude).","package":"anthropic","optional":true},{"reason":"Used internally for LLM integrations, often pulled as a dependency of jupyter-ai.","package":"langchain","optional":false}],"imports":[{"note":"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.","wrong":"import jupyter_ai_magics","symbol":"AiMagics","correct":"from jupyter_ai_magics.magics import AiMagics"}],"quickstart":{"code":"import os\n\n# --- In a Jupyter notebook cell ---\n\n# 1. Set your API key as an environment variable.\n#    For OpenAI: uncomment the line below and replace 'sk-YOUR_OPENAI_API_KEY'\n# os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'sk-dummy-for-quickstart-test')\n\n#    For local models like Ollama, ensure the server is running:\n#    e.g., in your terminal: `ollama run mistral`\n\n# 2. Load the Jupyter AI magics extension.\n#    This makes the %ai and %%ai commands available in your notebook.\n# %load_ext jupyter_ai\n\n# 3. (Optional) List available providers and models\n# %ai list\n\n# 4. Use the %ai line magic for single-line prompts.\n#    Replace 'openai:gpt-3.5-turbo' with your desired model and provider.\n# %ai openai:gpt-3.5-turbo \"What is the capital of France?\"\n\n# 5. Use the %%ai cell magic for multi-line prompts.\n#    The prompt is the content of the cell after the magic.\n# %%ai openai:gpt-3.5-turbo\n# Write a short poem about the benefits of learning Python.\n# It should be 4 lines long and rhyme AABB.\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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'.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If magics are not found or configuration changes don't take effect, try restarting the Jupyter kernel (Kernel -> Restart Kernel... in JupyterLab/Notebook).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"< 2.0 (minor changes continue across major versions)"},{"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).","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'jupyter_ai'"},{"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 \"...\"`.","cause":"No LLM provider is configured (e.g., missing API key for OpenAI) or a specific model was not selected for the magic command.","error":"MagicsProviderError: No model selected. Please select a model using '%ai_provider <provider_id>' or '%ai --model <model_id>'"},{"fix":"Run the code within a Jupyter notebook cell, JupyterLab, or an IPython interactive session. Magic commands are not part of standard Python syntax.","cause":"IPython magic commands (like `%load_ext`) are being executed in a standard Python script (.py file) where they are not recognized.","error":"SyntaxError: invalid syntax (when running %load_ext jupyter_ai in a .py file)"},{"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-`.","cause":"The OpenAI API key provided is incorrect, expired, or missing the `sk-` prefix, or the environment variable is not set correctly.","error":"openai.AuthenticationError: Incorrect API key provided: You must provide your OpenAI secret key..."}]}