aimagics

Installation

Install latest from the GitHub repository:

$ pip install git+https://github.com/adrische/aimagics.git

or from conda

$ conda install -c adrische aimagics

or from pypi

$ pip install aimagics

Setup

1. Load the package

After installation, you can load the package in Jupyter and ipython with

%load_ext aimagics

Whether the package has been loaded can be checked with

from IPython import get_ipython
get_ipython().extension_manager.loaded

{'IPython.extensions.storemagic', 'aimagics'}

‘aimagics’ should appear in the output.

2. Set LLM API key

You should set your environment API key to your favorite LLM provider. The default model is

AIMagics().model

'openrouter/openai/gpt-oss-120b'

so the environment key needed is OPENROUTER_API_KEY.

All LiteLLM models are compatible.

3. Turn auto save on

The package works by retrieving the current notebook from disk. To always get the current state, it is recommended to turn auto save on. This is the default in jupyter notebooks, and can be toggled in vscode via Show and Run Commands > File: Toggle Auto Save.

Usage

The package exposes two commands: %ai and %%ai. These are so-called ‘line’ and ‘cell magics’ and can be used as follows:

Line magic

The command %ai processes what comes after on the same line as request to the LLM:

%ai What is aimagics?

aimagics is a Python package and IPython extension that brings Large Language Model (LLM) capabilities directly into Jupyter notebooks via magic commands.

Key Features:

• Magic Commands: Offers %ai (line magic) and %%ai (cell magic) to interact with models directly within code cells.
• Context-Aware: Reads the current notebook state from disk to provide context-aware responses to your code and markdown.
• Broad Model Support: Built on LiteLLM, allowing you to connect to OpenRouter, OpenAI, Anthropic, and dozens of other LLM providers.

Cell magic

The command %%ai processes what comes after it on the same line, but also what is in the same cell below it:

%%ai Why does the following code fail?
1/0

Answer

1/0

fails because it raises a ZeroDivisionError. In Python (and mathematics), division by zero is undefined, so attempting to compute 1 / 0 triggers this exception:

ZeroDivisionError: division by zero

To avoid the error, ensure the denominator is never zero, e.g.:

denominator = 2  # any non‑zero value
result = 1 / denominator

By default, the entire notebook up to and including the calling cell is included in the prompt as context.

Configuration

The possible configuration options can be viewed with

%config AIMagics

AIMagics(Magics) options
----------------------
AIMagics.model=<Unicode>
    Provider/model to be used.
    Current: 'openrouter/openai/gpt-oss-120b'
AIMagics.system_prompt=<Unicode>
    The system prompt prepended to any prompt and context.
    Current: "You are a helpful assistant living inside a user's Jupyter notebook. \n        Use markdown syntax for styling your responses.\n        Keep your responses brief and to the point.\n"

For example, you can change the model with

%config AIMagics.model = "openrouter/google/gemini-3.8-flash"

%ai what model are you?

I am Gemini (specifically configured as openrouter/google/gemini-3.8-flash), a large language model trained by Google.

Documentation

Documentation can be found hosted on this GitHub repository’s pages. Additionally you can find package manager specific guidelines on conda and pypi respectively.

Acknowledgements

This repository would not be possible without the FastAI / AnswerAI open source packages, in particular FastLLM. AnswerAI even have a dedicated platform for notebooks with AI integration: SolveIt.

There are a number of packages implementing basically the same ideas (just much better):

• AnswerDotAI/ai-jup An extension for Jupyter Lab
• AnswerDotAI/ipyai An extension of IPython in the terminal
• https://nathancooper.io/blog/2026-08-10-ipython-is-all-you-need An excellent blog post implementing these ideas much better for ipython.

During the finishing stages I also found https://pypi.org/project/aimagic/ on PyPi, which is basically what I am implementing here, even with the same syntax and the same name, just for Jupyter (relying on Javascript to get the cells for context).