Metadata-Version: 2.5
Name: jupyter_ai_tools
Version: 0.8.0a0
Summary: A suite of tools for AI agents in Jupyter
Project-URL: Home, https://github.com/jupyter-ai-contrib/jupyter-ai-tools
Author-email: Project Jupyter <jupyter@googlegroups.com>, Abigayle Mercer <abigaylemercer@gmail.com>
License: BSD 3-Clause License
        
        Copyright (c) 2025, Project Jupyter
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: Extension,Jupyter
Classifier: Framework :: Jupyter
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: jupyter-server<3,>=1.6
Requires-Dist: jupyter-ydoc
Requires-Dist: jupyterlab-ai-commands>=0.4.0
Requires-Dist: jupyterlab-commands-toolkit>=0.3.1
Requires-Dist: nbclient
Requires-Dist: pycrdt
Provides-Extra: lint
Requires-Dist: black>=22.6.0; extra == 'lint'
Requires-Dist: mdformat-gfm>=0.3.5; extra == 'lint'
Requires-Dist: mdformat>=0.7.16; extra == 'lint'
Requires-Dist: mypy>=0.990; extra == 'lint'
Requires-Dist: pydantic>=1.10; extra == 'lint'
Requires-Dist: ruff>=0.0.156; extra == 'lint'
Requires-Dist: types-jsonschema; extra == 'lint'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: rtc
Requires-Dist: jupyterlab-notebook-awareness; extra == 'rtc'
Provides-Extra: test
Requires-Dist: mcp>=1.0; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-jupyter[server]>=0.6; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Provides-Extra: typing
Requires-Dist: mypy>=0.990; extra == 'typing'
Description-Content-Type: text/markdown

# jupyter_ai_tools

[![Github Actions Status](https://github.com/jupyter-ai-contrib/jupyter-ai-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/jupyter-ai-contrib/jupyter-ai-tools/actions/workflows/ci.yml)

**`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:

### 🧠 Notebook Tools (`nb_toolkit`)

- `read_notebook`: Read entire notebook contents as markdown
- `read_cell`: Read a specific notebook cell by index
- `add_cell`: Add a new cell to a notebook
- `insert_cell`: Insert a cell at a specific index in the notebook
- `delete_cell`: Remove a cell from the notebook
- `edit_cell`: Modify a cell's content
- `get_cell_id_from_index`: Get a cell ID from its one-based number shown in JupyterLab
- `create_notebook`: Create a new Jupyter notebook

### 🌀 Git Tools (`git_toolkit`)

- `git_clone`: Clone a Git repository to a specified path
- `git_status`: Get the current working tree status
- `git_log`: View recent commit history
- `git_pull`: Pull changes from remote repository
- `git_push`: Push local changes to remote branch
- `git_commit`: Commit staged changes with a message
- `git_add`: Stage files for commit (individually or all)
- `git_get_repo_root`: Get the root directory of the Git repository

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.

```python
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:

```bash
pip install jupyter_ai_tools
```

## Without a JupyterLab web client

Without a real-time collaboration provider, the notebook tools run in the JupyterLab
frontend through [jupyterlab-ai-commands](https://github.com/jupyter-ai-contrib/jupyterlab-ai-commands).
The write tools save the notebook after an edit, so the file on disk matches the notebook
in JupyterLab. When the save fails, for example because the file also changed on disk,
the result of the tool has a `save_error`.
When no JupyterLab tab is open, nothing holds a live model of the notebook, so the
read and write tools (`read_notebook`, `add_cell`, `insert_cell`, `delete_cell`,
`edit_cell`, ...) read and edit the notebook file on disk instead. The result of a
write tool then says that the edit went to the file on disk.

`run_cell` and `run_all_cells` with a `file_path` run the cells in a kernel on the
server, and write the outputs to the notebook file on disk. They use the kernel of the
notebook session, and start a session if there is none. JupyterLab connects to the same
kernel when it opens the notebook.

With `write_outputs=False`, `run_cell` and `run_all_cells` run the cells in the kernel of
the notebook and return the outputs, without a change to the notebook. This works with
or without a web client, and with or without RTC. The kernel state changes, but
JupyterLab does not show the run.

A kernel that these tools start keeps running after the run, as a kernel that
JupyterLab starts does.

The tools that need the user interface (`select_cell`, `get_active_notebook`,
`get_active_cell_id`, `open_file`, and `run_cell` or `run_all_cells` without a
`file_path`) return the error of `jupyterlab-commands-toolkit`, which asks to open
JupyterLab in a web browser.

## Uninstall

To remove the extension, execute:

```bash
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:

```bash
jupyter server extension list
```

## Contributing

### Development install

```bash
# 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:

```bash
jupyter lab --autoreload
```

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

```bash
jupyter server --autoreload
```

### Running Tests

Install dependencies:

```bash
pip install -e ".[test]"
```

### Development uninstall

```bash
pip uninstall jupyter_ai_tools
```

### Packaging the extension

See [RELEASE](RELEASE.md)
