Tool Specification: ipython (Base Chat)

Tool Specification: ipython (Base Chat)

Overview

Python execution environment for Base Chat. Same core functionality as OK Computer but with different constraints.

JSON Schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Python code to execute"
    },
    "restart": {
      "type": "boolean",
      "default": false,
      "description": "Restart kernel (clears all state)"
    }
  },
  "required": ["code"]
}

Architectural Position

IPython is the primary computation engine providing stateful execution with memory persistence across calls. Unlike shell's fresh sessions, IPython maintains variable state.

Kernel Architecture

Process Model

Kernel Server (FastAPI :8888)
    ↓
Jupyter Kernel (ZeroMQ)
    ↓
IPython Kernel (PID 300+)
    ↓
Execution Namespace (persistent)

Communication Flow

1. Tool invocation with code string
2. FastAPI routing via kernel_server.py
3. ZMQ dispatch to IPython kernel
4. Code execution
5. Result capture (stdout, display, errors)
6. JSON response to model

State Persistence

What Persists

• Global variables
• Imported modules
• Function/class definitions
• matplotlib configuration

What Does Not Persist

• File descriptors (auto-closed)
• Network connections
• Subprocess objects

Reset Mechanism

restart=True clears everything. Kernel reset endpoint: POST :8888/kernel/reset

Library Ecosystem

Pre-installed Stack

• pandas (data manipulation)
• numpy (numerical computing)
• torch 2.8.0 (PyTorch, CPU only)
• matplotlib (visualization)
• Pillow (image processing)
• OpenCV (computer vision)
• sqlite3 (database)

Skill-Specific Patterns

DOCX: Meta-Programming

Python generates C# code that generates documents:

cs_template = f'using DocumentFormat.OpenXml...'
with open('/tmp/Program.cs', 'w') as f:
    f.write(cs_template)

XLSX: Direct Manipulation

Direct Excel manipulation via openpyxl:

from openpyxl import Workbook
wb = Workbook()
ws['A1'] = '=SUM(B:B)'  # Formula injection
wb.save('output.xlsx')

PDF: Source Generation

Generate markup for external renderer:

html = f'<html>...{content}...</html>'
with open('/tmp/input.html', 'w') as f:
    f.write(html)

WebApp: Code Generation

Generate TypeScript for external build:

component = f'export function...'
# Written via write_file tool

Data Processing

Pandas Workflow

import pandas as pd
df = pd.read_csv('data.csv')
summary = df.groupby('category').sum()
summary.to_csv('output.csv')

NumPy Computation

import numpy as np
arr = np.random.randn(1000000)
mean = np.mean(arr)

Visualization

Matplotlib Integration

Automatic display without plt.show():

import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.plot(x, y)  # Auto-displayed

Image Processing

Pillow

from PIL import Image
img = Image.open('photo.jpg')
img = img.resize((800, 600))
img.save('output.png')

OpenCV

import cv2
img = cv2.imread('photo.jpg')
edges = cv2.Canny(img, 100, 200)

Constraints

Hard Limits

• Network access blocked
• 4GB RAM limit
• 30s execution timeout
• No persistent storage outside output dirs

Package Installation

pip install works but packages lost on kernel restart.

Summary

IPython is the cognitive engine:

• Direct manipulation (openpyxl, lxml)
• Code generation (C#, LaTeX, HTML, TSX)
• Data processing (pandas, numpy)
• Visualization (matplotlib)
• Image processing (Pillow, OpenCV)

Stateful execution enables multi-turn workflows.

Differences from OK Computer

Usage

Identical to OK Computer mshtools-ipython:

ipython(code="print('Hello')")

System Integration

• Kernel: Same jupyter_kernel.py backend
• Control: kernel_server.py:8888
• Libraries: Same pre-installed packages (PyTorch, pandas, etc.)
• Network: Same restrictions (blocked)