Metadata-Version: 2.4
Name: jupyter-agent
Version: 2025.6.102
Summary: 调用LLM实现Jupyter代码的自动生成、执行、调试等功能
Author: viewstar000
License: MIT
Project-URL: Homepage, https://github.com/viewstar000/jupyter-agent
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ipython
Requires-Dist: nbformat
Requires-Dist: ipynbname
Requires-Dist: openai
Requires-Dist: traitlets
Requires-Dist: pyyaml
Requires-Dist: jinja2
Requires-Dist: pydantic
Dynamic: license-file

# jupyter-agent

[EN](#en)

调用LLM实现Jupyter代码的自动生成、执行、调试等功能

## 特性

- 提供`%%bot`指令，在juyter环境中，通过调用LLM实现代码生成、执行、调试等能力
- 支持调用OpenAI兼容API，实现LLM相关的功能

## 安装

```bash
# 激活目标环境(视情况选择)
source /path/to/target_env/bin/activate

pip install jupyter-agent
```

## 源码打包安全（Build）

```bash
# 下载代码
git clone https://github.com/yourusername/jupyter-agent.git
cd jupyter-agent

# 安装打包环境
virtualenv .venv
source .venv/bin/activate
pip install build

# 编译打包
python -m build

# 退出打包环境
deactivate

# 激活目标环境
source /path/to/target_env/bin/activate

# 安装编译好的wheel包
pip install /path/to/jupyter-agent/dist/jupyter_agent-xxxx-py3-none-any.whl
```

## 安装Vscode插件（可选）

下载地址：[jupyter-agent-extension](https://marketplace.visualstudio.com/items?itemName=viewstar000.jupyter-agent-extension)

## 使用方法

安装完成后，启动Jupyter环境（兼容Vscode的Notebook编译器）

### 全局配置

```python
# 加载扩展的Magic命令
%load_ext jupyter_agent.bot_magics

# 设置模型调用的API地址，不同的Agent可以调用不同的模型，这里以调用lmstudio本地部署的模型为例
%config BotMagics.default_api_url = 'http://127.0.0.1:1234/v1'
%config BotMagics.default_api_key = 'API_KEY'
%config BotMagics.default_model_name = 'qwen3-30b-a3b' 
%config BotMagics.coding_model_name = 'devstral-small-2505-mlx'

# 设置当前Notebook的路径，由于vscode中运行里无法自动获取到该路径，需要手工指定
%config BotMagics.notebook_path = globals()["__vsc_ipynb_file__"]

# 设置是否保存任务数据到Metadata，只有Vscode中安装了jupyter-agent-extension后才支持
%config BotMagics.support_save_meta = True
```

### 全局任务规划

```python
%%bot -P

# 全局目标
...
```

全局任务规划会解析用户输入的prompt，生成具体的执行计划，后续的%%bot指令会以该计划为蓝本自动生成每个步骤（子任务）的代码。

![docs/image-global-prompt.png](https://raw.githubusercontent.com/viewstar000/jupyter-agent/refs/heads/main/docs/image-global-prompt.png)
![docs/image-global-plan.png](https://raw.githubusercontent.com/viewstar000/jupyter-agent/refs/heads/main/docs/image-global-plan.png)

### 生成并执行子任务代码

```python
%% bot [-s stage]

# generated code ...
```

在完成全局任务规划后，开始执行子任务时，只需要新建一个cell，输入并执行`%%bot`命令，如下图：

![docs/image-task-empty.png](https://raw.githubusercontent.com/viewstar000/jupyter-agent/refs/heads/main/docs/image-task-empty.png)

> 注：由于cell magic命令无法直接定位当前cell，需要通过cell的内容进行匹配，因此首次执行%%bot命令时，需要在cell中额外添加一些随机字符

接下来工具会调用相应的agent自动生成并执行相应步骤的代码，如下图：

![docs/image-task-executing.png](https://raw.githubusercontent.com/viewstar000/jupyter-agent/refs/heads/main/docs/image-task-executing.png)

一个cell中只会执行全局计划中的一个步骤，当前步骤执行完成后，需要手工新建一个cell并重复上述过程，直到完成全局目标完成（此时工具不会再生成新代码）

在子任务执行的过程中，默认情况下每一个环节工具都会给出如下图的确认提示，可跟据实际情况输入相应的选项，或直接回车确认继续执行下一环节。

![docs/image-task-confirm.png](https://raw.githubusercontent.com/viewstar000/jupyter-agent/refs/heads/main/docs/image-task-confirm.png)

更详细用法可参考[示例Notebook](https://github.com/viewstar000/jupyter-agent/blob/main/examples/data_loader.ipynb)

## 贡献

欢迎提交 issue 或 pull request 参与贡献。

## 许可证

本项目基于 [MIT License](./LICENSE) 开源。

Copyright (c) 2025 viewstar000

---

## EN

Implementing jupyter code planning, generation and execution for tasks using LLMs.

## Features

- Support `%%bot` magic command, you can use it to work on task planning, code generation, execution and debugging.
- Support OpenAI Compatible API to call LLMs.

## Installation

```bash
# Activate the virtual environment
source /path/to/target_env/bin/activate

pip install jupyter-agent
```

## Build from Source

```bash
# Clone the repository
git clone https://github.com/viewstar000/jupyter-agent.git
cd jupyter-agent

# Install the build environment
virtualenv .venv
source .venv/bin/activate
pip install build

# Build the package
python -m build

# Deactivate the virtual environment
deactivate

# Activate the Target virtual environment
source /path/to/target_env/bin/activate

# Install the package
pip install /path/to/jupyter-agent/dist/jupyter_agent-xxxx-py3-none-any.whl
```

## Install Vscode Extension

[Download](https://marketplace.visualstudio.com/items?itemName=viewstar000.jupyter-agent-extension)

## Usage

After installing `jupyter-agent` and `jupyter-agent-extension`, you can use `%%bot` magic command to work on task planning, code generation and execution.

First create or open a notebook in Vscode, create a new cell, enter and execute the following commands:

```python
# Load the Magic commands of the extension
%load_ext jupyter_agent.bot_magics

# Set the API address of the model to be called, different Agents can call different models, here we call the model deployed locally in lmstudio
%config BotMagics.default_api_url = 'http://127.0.0.1:1234/v1'
%config BotMagics.default_api_key = 'API_KEY'
%config BotMagics.default_model_name = 'qwen3-30b-a3b' 
%config BotMagics.coding_model_name = 'devstral-small-2505-mlx'

# Set the path of the current Notebook, which cannot be automatically obtained in vscode when running, you need to manually specify
%config BotMagics.notebook_path = globals()["__vsc_ipynb_file__"]

# Set whether to save task data to Metadata, only Vscode installed with jupyter-agent-extension supports
%config BotMagics.support_save_meta = True
```

Now, you can use the `%%bot` command to work on task rules and code generation.

### Perform global task planning

```python
%%bot -P

# Global Goal

...
```

Global task planning will analyze the user input prompt and generate a detailed execution plan, subsequent `%%bot` commands will generate code for each step (subtask) automatically.

![docs/image-global-prompt.png](https://raw.githubusercontent.com/viewstar000/jupyter-agent/refs/heads/main/docs/image-global-prompt.png)
![docs/image-global-plan.png](https://raw.githubusercontent.com/viewstar000/jupyter-agent/refs/heads/main/docs/image-global-plan.png)

### Generate and execute subtask code

```python
%%bot [-s stage]

# generated code ...
```

After global task planning, the tool will generate code for each subtask, and you can use the `%%bot` command to invoke the corresponding agent to generate the code and execute it.

![docs/image-task-empty.png](https://raw.githubusercontent.com/viewstar000/jupyter-agent/refs/heads/main/docs/image-task-empty.png)

> **Note:** The `%%bot` cell magic can not locate the empty cell, you must enter the `%%bot` command with some random text in the cell to trigger the magic command.

After generating code for a subtask, the tool will call the corresponding agent to generate the code, and then execute it.

![docs/image-task-confirm.png](https://raw.githubusercontent.com/viewstar000/jupyter-agent/refs/heads/main/docs/image-task-confirm.png)

For more details, please refer to [example notebook](https://github.com/viewstar000/jupyter-agent/blob/main/examples/data_loader.ipynb)

## Contributing

Welcome to submit issues or pull requests to participate in contributions.

## License

This project is based on the [MIT License](https://github.com/viewstar000/jupyter-agent-extension/blob/main/LICENSE) open source.

Copyright (c) 2025 viewstar000
