cellsistant 0.1.0

AI Agent sidebar panel for JupyterLab.

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

Requirements

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

Installation

From Source

# 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

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

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

Ollama (Local):

{
  "base_url": "http://localhost:11434/v1",
  "api_key": "",
  "model": "llama3.1"
}

OpenAI:

{
  "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

# 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

# Run TypeScript tests (Jest)
npm test

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

Linting and Formatting

# 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

# Check extension installation
jupyter labextension list

# Check server extension
jupyter server extension list

# Rebuild extension
jupyter labextension build .

Debug Mode

# Start JupyterLab with debug logging
jupyter lab --debug

Clear Build Artifacts

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