Metadata-Version: 2.4
Name: jupyter_ai_tools
Version: 0.5.1
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Requires-Dist: jupyter-server<3,>=1.6
Requires-Dist: jupyter-ydoc<4.0.0,>=3.0.0
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: 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/workflows/Build/badge.svg)](https://github.com/jupyter-ai-contrib/jupyter-ai-tools/actions/workflows/build.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:

### 📁 File System Tools (`fs_toolkit`)

- `read`: Read file contents from the filesystem
- `edit`: Edit file contents with search and replace functionality
- `write`: Write content to a file
- `search_and_replace`: Search and replace text patterns in files
- `glob`: Find files matching a glob pattern
- `grep`: Search for text patterns within file contents
- `ls`: List directory contents

### 🧠 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 cell ID from its index position
- `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

### ⚙️ Code Execution Tools (`exec_toolkit`)

- `bash`: Execute bash commands in the system shell

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

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