Metadata-Version: 2.4
Name: cellsistant
Version: 0.1.0
Summary: AI Agent sidebar panel for JupyterLab.
Project-URL: Homepage, https://github.com/p4ulbr4dl3y/cellsistant
Project-URL: Bug Tracker, https://github.com/p4ulbr4dl3y/cellsistant/issues
Project-URL: Repository, https://github.com/p4ulbr4dl3y/cellsistant.git
Author: p4ulbr4dl3y
License: BSD 3-Clause License
        
        Copyright (c) 2023, Project Jupyter Contributors
        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: ai,jupyter,jupyterlab,jupyterlab-extension,langchain,openrouter
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: jupyter-server>=2.0.0
Description-Content-Type: text/markdown

# JupyterLab AI Agent

AI Agent sidebar panel for JupyterLab with LLM integration and tool calling capabilities.

## Features

- AI-powered chat assistant integrated into JupyterLab sidebar
- Tool calling for direct interaction with notebooks and files
- Support for OpenAI-compatible APIs (OpenRouter, Ollama, LocalAI)
- Vision capabilities for analyzing cell output images
- Long-term memory for persisting project information
- Streaming responses for real-time feedback
- Configurable tool categories and permissions

![JupyterLab AI Agent Demo](Recording_2026-03-20_23-12-10_hq.gif)

## Requirements

- Python 3.9+
- Node.js 18+
- JupyterLab 4.x

## Installation

### From Source

```bash
# Clone the repository
git clone https://github.com/p4ulbr4dl3y/cellsistant.git
cd cellsistant

# Install Python dependencies
pip install -e .

# Install Node.js dependencies
npm install

# Build the extension
npm run build

# Install the extension in JupyterLab
jupyter labextension install .

# Restart JupyterLab
jupyter lab
```

### Development Installation

```bash
# Install in editable mode
pip install -e .

# Build in development mode
npm run build

# Enable watch mode for auto-rebuild
npm run watch
```

## Configuration

Access settings via **Settings > AI Agent** in JupyterLab menu.

### API Configuration

| Parameter | Description | Default |
|-----------|-------------|---------|
| `base_url` | API endpoint URL | `https://openrouter.ai/api/v1` |
| `api_key` | Authentication API key | (empty) |
| `model` | Model identifier | `google/gemini-2.0-flash:free` |
| `temperature` | Response creativity (0-2) | `0.3` |
| `max_tokens` | Maximum tokens in response | `0` (unlimited) |

### Example Configurations

**OpenRouter:**
```json
{
  "base_url": "https://openrouter.ai/api/v1",
  "api_key": "sk-or-...",
  "model": "google/gemini-2.0-flash:free"
}
```

**Ollama (Local):**
```json
{
  "base_url": "http://localhost:11434/v1",
  "api_key": "",
  "model": "llama3.1"
}
```

**OpenAI:**
```json
{
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-...",
  "model": "gpt-4o"
}
```

## Available Tools

### Notebook Tools

- `create_cell` - Create a new code or markdown cell
- `update_cell` - Update cell content
- `delete_cell` - Delete a cell
- `get_cell_content` - Get cell source code
- `get_notebook_content` - Get full notebook structure
- `execute_cell` - Execute a code cell
- `get_cell_output` - Get cell execution output (text, images, HTML)
- `analyze_image` - Analyze images from cell output using vision AI

### File Tools

- `read_file` - Read text file contents
- `write_file` - Create or overwrite a file
- `list_directory` - List directory contents
- `delete_file` - Delete a file or empty directory
- `rename_file` - Rename or move a file
- `create_notebook` - Create a new Jupyter notebook

### Search Tools

- `find_in_notebook` - Search text across all cells
- `replace_in_cell` - Replace text in a specific cell

### Shell Tools

- `run_shell` - Execute shell commands (with security restrictions)

### Package Tools

- `install_package` - Install Python packages via pip/conda
- `list_packages` - List installed packages

### Memory Tools

- `remember` - Save information to long-term memory
- `recall` - Search saved memories
- `list_memories` - List all saved memories
- `forget` - Delete a memory entry

## Development

### Build Commands

```bash
# Full production build
npm run build:prod

# Development build
npm run build

# TypeScript compilation only
npm run build:lib

# Watch mode for development
npm run watch
```

### Testing

```bash
# Run TypeScript tests (Jest)
npm test

# Run Python tests (pytest)
pytest cellsistant/tests/
```

### Linting and Formatting

```bash
# All linters (Python + TypeScript)
npm run lint:all

# Python only
npm run lint:python        # Check
npm run lint:python:fix    # Check and fix
npm run format:python      # Format

# TypeScript only
npm run lint               # All checks
npm run eslint             # ESLint
npm run prettier           # Prettier
npm run stylelint          # Stylelint
```

## Security

### Blocked Shell Commands

The following commands are blocked for safety:

- Destructive: `rm -rf /`, `rm -rf ~`, `mkfs`, `dd if=`
- System: `shutdown`, `reboot`, `halt`, `poweroff`
- Permissions: `chmod -R 777 /`, `chown -R`
- Network: `nc -l`, `ncat`, `socat`
- Mining: `xmrig`, `minerd`, `cpuminer`

### Resource Limits

- Maximum command execution time: 60 seconds
- Maximum output size: 100 KB
- Maximum memory per process: 512 MB
- Maximum child processes: 50

## API Endpoints

The server extension provides the following endpoints:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/ai-agent/chat` | POST | Send message and get response |
| `/ai-agent/chat/stream` | POST | SSE streaming response |
| `/ai-agent/shell` | POST | Execute shell command |
| `/ai-agent/history` | GET | List chat history |
| `/ai-agent/history/{id}` | GET/DELETE | Get/delete specific chat |
| `/ai-agent/history/{id}/export` | GET | Export chat |
| `/ai-agent/memory` | GET | List memory entries |
| `/ai-agent/memory/save` | POST | Save to memory |
| `/ai-agent/memory/search` | GET | Search memory |
| `/ai-agent/settings` | GET | Get settings |
| `/ai-agent/settings/update` | POST | Update settings |
| `/ai-agent/settings/test` | POST | Test API connection |
| `/ai-agent/analyze-image` | POST | Analyze image with vision AI |

## Troubleshooting

### Extension Not Loading

```bash
# Check extension installation
jupyter labextension list

# Check server extension
jupyter server extension list

# Rebuild extension
jupyter labextension build .
```

### Debug Mode

```bash
# Start JupyterLab with debug logging
jupyter lab --debug
```

### Clear Build Artifacts

```bash
npm run clean:all
npm run build
```

## License

BSD-3-Clause License. See LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `npm test` and `pytest`
5. Submit a pull request

## Acknowledgments

- JupyterLab Extension API
- OpenAI Tool Calling API
- LangChain
