aimagics

LLM access from within Jupyter notebooks via line and cell magic commands

Installation

This package can be installed with pip via

$ pip install aimagics

Setup

1. Load the package

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

%load_ext aimagics

or with

import 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 pypi respectively.

Use cases

Interactive coding

You can just ask away with %ai your question, the LLM will get the relevant context and can provide targeted answers. Good for iterative programming, studying, etc. See the screenshot above.

Interactive document reading

Code along with technical documents. By importing and splitting documents into Jupyter cells, you can read step-by-step and ask and try out code as you go.

A possible workflow is to get documents (e.g., websites) to markdown format with Jina,

https://r.jina.ai/www.the-website-you-want.com

then add markdown cells with

from aimagics.utils import add_cells, split_markdown
md = """[copy paste from Jina]"""
add_cells(split_markdown(md))

If you want to start from a notebook that has been prepopulated with cells from a markdown file, there are options such as Jupytext to convert a markdown file to ipynb that you can use as a starting point.

For example, you can translate an existing markdown file to ipynb such that each section gets its own cell by

jupytext --to ipynb --opt split_at_heading=true file.md

Features

Automatic code-cell insertion

LLM answers containing fenced code blocks (with ```) are automatically extracted and inserted as code cells below the LLM reply:

%ai how to reverse a list in one line?

Answer

[See code cell 1 below]

# Code cell 1
rev = lst[::-1]          # slice reversal
# or
rev = list(reversed(lst))  # using built‑in reversed()

AGENTS.md

If it exists in the same folder as the current notebook, the file AGENTS.md is being appended to the LLM call.

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):

During the finishing stages I also found https://pypi.org/project/aimagic/ on PyPi, which is also a package by AnswerAI and 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).