Metadata-Version: 2.3
Name: jupyter_ai_agent
Version: 0.2.0
Project-URL: Home, https://github.com/datalayer/jupyter-ai-agent
Author-email: Datalayer <info@datalayer.io>
License: BSD 3-Clause License
        
        Copyright (c) 2024, Datalayer
        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.
        
        ---
        
        This library reuse part of Jupyter Server code licensed under BSD 3-Clause License
        Source: https://github.com/jupyter-server/jupyter_server/blame/v2.12.0/jupyter_server/services/kernels/connection/base.py
        
        This library reuse part of traitlets code licensed under BSD 3-Clause License
        Source: https://github.com/ipython/traitlets/blob/v5.14.3/traitlets/log.py
Keywords: Jupyter
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: jupyter-kernel-client
Requires-Dist: jupyter-nbmodel-client
Requires-Dist: langchain
Requires-Dist: langchain-openai
Requires-Dist: python-dotenv
Provides-Extra: example
Requires-Dist: jupyter-server-ydoc; extra == 'example'
Provides-Extra: lint
Requires-Dist: mdformat-gfm>=0.3.5; extra == 'lint'
Requires-Dist: mdformat>0.7; extra == 'lint'
Requires-Dist: ruff; extra == 'lint'
Provides-Extra: test
Requires-Dist: ipykernel; extra == 'test'
Requires-Dist: jupyter-server<3,>=1.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

<!--
  ~ Copyright (c) 2023-2024 Datalayer, Inc.
  ~
  ~ BSD 3-Clause License
-->

[![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io)

[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)

[![Github Actions Status](https://github.com/datalayer/jupyter-ai-agent/workflows/Build/badge.svg)](https://github.com/datalayer/jupyter-ai-agent/actions/workflows/build.yml)
[![PyPI - Version](https://img.shields.io/pypi/v/jupyter-ai-agent)](https://pypi.org/project/jupyter-ai-agent)

# 🪐 🤖 Jupyter AI Agent

*Use Jupyter AI Agent, an AI Agent equipped with tools like 'execute', 'insert_cell', and more, to transform your Jupyter Notebooks into an intelligent, interactive workspace!*

![Jupyter AI Agent](https://assets.datalayer.tech/jupyter-ai-agent/ai-agent-jupyterlab.gif)

```
Jupyter AI Agent <---> JupyterLab
    |            (RTC)
 JNC+JKC

- JNC https://github.com/datalayer/jupyter-nbmodel-client
- JKC https://github.com/datalayer/jupyter-kernel-client
- RTC Real Time Collaboration
```

Jupyter AI Agent empowers **AI** models to **interact** with and **modify Jupyter Notebooks**. The model is equipped with tools such as adding code cells, inserting markdown cells, executing code, enabling it to modify the notebook comprehensively based on user instructions. This agent is **innovative** as it is designed to **operate on the entire notebook**, not just at the cell level, enabling more comprehensive and seamless modifications.

This powerful functionality is made possible through [jupyter-nbmodel-client](https://github.com/datalayer/jupyter-nbmodel-client) and [jupyter-kernel-client](https://github.com/datalayer/jupyter-kernel-client), enabling interaction with Jupyter notebooks and kernels.

> [!WARNING] 
> jupyter-nbmodel-client and jupyter-kernel-client are experimental and under active development. 
> Unexepected behavior such as ["Panic Exception"](https://github.com/datalayer/jupyter-nbmodel-client/issues/12) may occur.

[LangChain agent framework](https://python.langchain.com/v0.1/docs/modules/agents/how_to/custom_agent/) is used to manage the interactions between the AI model and the tools.

> [!IMPORTANT] 
> Jupyter AI Agent currently only supports models from Azure OpenAI.

## Install

To install Jupyter AI Agent, execute:

```bash
pip install jupyter_ai_agent
```

## Usage

### Example 1: JupyterLab

![Jupyter AI Agent](https://assets.datalayer.tech/jupyter-ai-agent/ai-agent-jupyterlab.gif)

The Jupyter AI Agent can directly interact with JupyterLab and the modifications made by the Jupyter AI Agent can be seen in real-time thanks to [Jupyter real time collaboration](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html).

```
Jupyter AI Agent <---> JupyterLab
    |            (RTC)
JNC+JKC

- JNC https://github.com/datalayer/jupyter-nbmodel-client
- JKC https://github.com/datalayer/jupyter-kernel-client
- RTC Real Time Collaboration
```

First, make sure you have JupyterLab installed:

```bash
pip install jupyterlab
```

Then, start JupyterLab:

```bash
jupyter lab
```
Then, make sure you have a `.env` file with the following content:

```bash
OPENAI_API_VERSION = ...
AZURE_OPENAI_ENDPOINT = ...
AZURE_OPENAI_API_KEY = ...
```

To use the Jupyter AI Agent, execute the following:

```python
azure_deployment_name = "gpt-4o-mini" # for example
server_url = "http://localhost:8888" # for example, typical when using JupyterLab
token = "..." # your JupyterLab token
notebook_path = "..." # the path to the notebook you want the Jupyter AI Agent to modify

input = '''
Scrape historical stock price data for Apple from Yahoo Finance. 
The data should include columns like Date, Open, High, Low, Close, and Volume. 
After scraping, visualize the data with a line chart showing the closing prices over time.
''' # the input to the Jupyter AI Agent

ask_agent(server_url, token, azure_deployment_name, notebook_path, input)
```

## Uninstall

To uninstall the agent, execute:

```bash
pip uninstall jupyter_ai_agent
```

## Contributing

### Development install

```bash
# Clone the repo to your local environment
# Change directory to the jupyter_ai_agent directory
# Install package in development mode - will automatically enable
# The server extension.
pip install -e ".[test,lint,typing]"
```

### Running Tests

Install dependencies:

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

To run the python tests, use:

```bash
pytest
```

### Development uninstall

```bash
pip uninstall jupyter_ai_agent
```

### Packaging the extension

See [RELEASE](RELEASE.md)
