jupyter_ai_tools

jupyter_ai_tools is a Jupyter Server extension that exposes a collection of powerful, agent-friendly tools for interacting with notebooks and Git repositories. It is designed for use by AI personas (like those in Jupyter AI) to programmatically modify notebooks, manage code cells, and interact with version control systems.

---

✨ Features

This extension provides runtime-discoverable tools compatible with OpenAI-style function calling or MCP tool schemas. These tools can be invoked by agents to:

🧠 YNotebook Tools

• read_cell: Return the full content of a cell by index
• read_notebook: Return all cells as a JSON-formatted list
• add_cell: Insert a blank cell at a specific index
• delete_cell: Remove a cell and return its contents
• write_to_cell: Overwrite the content of a cell with new source
• get_max_cell_index: Return the last valid cell index

🌀 Git Tools

• git_clone: Clone a Git repo into a given path
• git_status: Get the working tree status
• git_log: View recent commit history
• git_add: Stage files (individually or all)
• git_commit: Commit staged changes with a message
• git_push: Push local changes to a remote branch
• git_pull: Pull remote updates
• git_get_repo_root_from_notebookpath: Find the Git root from a notebook path

These tools are ideal for agents that assist users with code editing, version control, or dynamic notebook interaction.

---

🔧 Creating Collaborative Tools

For developers building AI tools that need collaborative awareness, jupyter_ai_tools provides a collaborative_tool decorator that automatically enables real-time collaboration features.

This decorator enables other users in the same Jupyter environment to see when your AI tool is actively working on shared notebooks, improving the collaborative experience.

from jupyter_ai_tools.utils import collaborative_tool

# Define user information
user_info = {
    "name": "Alice",
    "color": "var(--jp-collaborator-color1)",
    "display_name": "Alice Smith"
}

# Apply collaborative awareness to your tool
@collaborative_tool(user=user_info)
async def my_notebook_tool(file_path: str, content: str):
    """Your tool implementation here"""
    # Tool automatically sets user awareness for:
    # - Global awareness system (all users can see Alice is active)
    # - Notebook-specific awareness (for .ipynb files)
    return f"Processed {file_path}"

---

Requirements

• Jupyter Server

Install

To install the extension, execute:

pip install jupyter_ai_tools

Uninstall

To remove the extension, execute:

pip uninstall jupyter_ai_tools

Troubleshoot

If you are seeing the frontend extension, but it is not working, check that the server extension is enabled:

jupyter server extension list

Contributing

Development install

# Clone the repo to your local environment
# Change directory to the jupyter_ai_tools directory
# Install package in development mode - will automatically enable
# The server extension.
pip install -e .

You can watch the source directory and run your Jupyter Server-based application at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension. For example, when running JupyterLab:

jupyter lab --autoreload

If your extension does not depend a particular frontend, you can run the server directly:

jupyter server --autoreload

Running Tests

Install dependencies:

pip install -e ".[test]"

Development uninstall

pip uninstall jupyter_ai_tools

Packaging the extension

See RELEASE