jupyter_ai_tutor

A JupyterLab extension to add an AI-powered tutor assistant to Notebooks.

a screencast showing an example with jupyter-ai-tutor

It currently relies on jupyter-ai-jupyternaut (<0.1) for the agent, it needs to be installed (pip install jupyter_ai_tutor[server]).

Once Jupyterlab started, the model must be configured via the menu Settings>Jupyternaut settings (model and API key) or its configuration file. See Jupyternaut documentation for details about setting up the agent.

How it works

Each code cell in a notebook gets an Explain Code button in its toolbar
Clicking it opens a chat panel on the right side and sends the following context to the AI:

• The cell source code and its kernel language
• Any error output produced by the cell (traceback included)
• Preceding code cells and markdown cell (up to the previous markdown cell), used as the exercise description
• An optional reference_solution (multiline string) and evaluation_criteria (multiline string) stored in the cell metadata

The AI replies using a configurable system prompt (TUTOR.md) that shapes its pedagogical behavior. By default the extension looks for a TUTOR.md file walking up from the notebook's directory to the server root, so different courses or folders can each have their own tutor persona.

Configuration

TUTOR

The extension can be configured via jupyter_server_config.py (or any traitlets CLI config):

c.JupyterAITutorApp.discover_tutor_md = True   # default
c.JupyterAITutorApp.tutor_md = ""              # default (uses built-in TUTOR.md)
c.JupyterAITutorApp.debug = False              # default

Jupyternaut

The default model and API key used with Jupyternaut agent can be setup via jupyter_server_config.py (or any traitlets CLI config):

c.AiExtension.initial_language_model=mistral/devstral-latest
c.AiExtension.default_api_keys={'MISTRAL_API_KEY': '***'}

It is also possible to configure your custom model directly via the JupyterNaut configuration file ~/.local/share/jupyter/jupyter_ai/config.json, for example

{
    "model_provider_id": "openai/qwen-3.6-35b-instruct",
    "embeddings_provider_id": null,
    "completions_model_provider_id": null,
    "api_keys": {},
    "send_with_shift_enter": false,
    "fields": {
        "openai/qwen-3.6-35b-instruct": {
            "api_base": "<your custom API base>"
        }
    },
    "embeddings_fields": {},
    "completions_fields": {}
}

The related secret (OPENAI_API_KEY in that case) should be stored in a .env file at the jupyter lab root:

OPENAI_API_KEY="<my openai key>"

Requirements

• JupyterLab >= 4.0.0
• jupyter-ai-jupyternaut (currently the only agent compatible)

Install

To install the extension, execute:

pip install jupyter_ai_tutor[server]

Uninstall

To remove the extension, execute:

pip uninstall jupyter_ai_tutor

Contributing

If you would like to contribute to this extension, please refer to the Contributing Guide.

AI Coding Assistant Support

This project includes an AGENTS.md file with coding standards and best practices for JupyterLab extension development. The file follows the AGENTS.md standard for cross-tool compatibility.

Compatible AI Tools

AGENTS.md works with AI coding assistants that support the standard, including Cursor, GitHub Copilot, Windsurf, Aider, and others. For a current list of compatible tools, see the AGENTS.md standard. This project also includes symlinks for tool-specific compatibility:

• CLAUDE.md → AGENTS.md (for Claude Code)

• GEMINI.md → AGENTS.md (for Gemini Code Assist)

Other conventions you might encounter:

• .cursorrules - Cursor's YAML/JSON format (Cursor also supports AGENTS.md natively)
• CONVENTIONS.md / CONTRIBUTING.md - For CodeConventions.ai and GitHub bots
• Project-specific rules in JetBrains AI Assistant settings

All tool-specific files should be symlinks to AGENTS.md as the single source of truth.

What's Included

The AGENTS.md file provides guidance on:

• Code quality rules and file-scoped validation commands
• Naming conventions for packages, plugins, and files
• Coding standards (TypeScript)
• Development workflow and debugging
• Common pitfalls and how to avoid them

Customization

You can edit AGENTS.md to add project-specific conventions or adjust guidelines to match your team's practices. The file uses plain Markdown with Do/Don't patterns and references to actual project files.

Note: AGENTS.md is living documentation. Update it when you change conventions, add dependencies, or discover new patterns. Include AGENTS.md updates in commits that modify workflows or coding standards.