Metadata-Version: 2.5
Name: runcell
Version: 0.2.7
Summary: AI Agent for Jupyter - Turn Jupyter into an AI IDE for data science
Project-URL: homepage, https://www.runcell.dev
Author-email: Elwynn Chen <elwynn.c@kanaries.net>
License: Copyright (c) 2025, Runcell, Kanaries Data Inc., Elwynn Chen
        All rights reserved.
License-File: LICENSE
Keywords: jupyter,jupyterlab,jupyterlab-extension
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: aiohttp
Requires-Dist: beautifulsoup4<5,>=4.9
Requires-Dist: httpx<1,>=0.27
Requires-Dist: jupyter-server
Requires-Dist: jupyter-server-documents==0.2.6
Requires-Dist: markdownify<2,>=1.2.2
Requires-Dist: mcp<2,>=1.28.1
Requires-Dist: openai
Requires-Dist: packaging>=21
Requires-Dist: pillow<13,>=11.2.1
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: python-dotenv
Requires-Dist: pyyaml<7,>=6
Requires-Dist: resvg-py<0.4,>=0.3.3
Requires-Dist: rfc3986-validator<0.2,>=0.1.1
Requires-Dist: rfc8785<0.2,>=0.1.4
Requires-Dist: tomli<3,>=2; python_version < '3.11'
Requires-Dist: websockets
Description-Content-Type: text/markdown

# runcell

RunCell is an AI-powered JupyterLab extension for working with notebooks, code, and data more efficiently inside JupyterLab.

It allow you to use LLM like Claude/GPT/Gemini, etc to analysis your notebooks and work in your jupyter lab env.

## Requirements

- JupyterLab 4.4 or newer

## Installation

Install RunCell from PyPI:

```bash
pip install runcell
```

Then start JupyterLab as usual:

```bash
jupyter lab
```

## Non-interactive Agent runtime (preview)

Python programs can call the same headless workspace Agent runtime directly:

```python
import asyncio

from runcell_agent_runtime import (
    AgentRunRequest,
    AgentRuntime,
    AgentRuntimeConfig,
    resolve_runtime_credential,
)


async def main():
    runtime = AgentRuntime(
        AgentRuntimeConfig(
            workspace_root="/absolute/workspace",
            remote_backend_url="https://service.runcell.dev",
            credential=resolve_runtime_credential(),
        )
    )
    handle = await runtime.start(AgentRunRequest("Inspect this workspace"))
    result = await handle.result(timeout_seconds=900)
    print(result.assistant_text)


asyncio.run(main())
```

Non-Python programs can use the machine-only one-shot process adapter. It reads
one JSON object from stdin and writes one JSON result line to stdout; diagnostics
go to stderr.

```bash
python -m runcell_agent_runtime <<'JSON'
{
  "api_version": 1,
  "workspace_root": "/absolute/workspace",
  "remote_backend_url": "https://service.runcell.dev",
  "message": "Reply with exactly: pong",
  "result_timeout_seconds": 900,
  "permission_preferences": {"global_mode": "ask_every_time"}
}
JSON
```

Authentication uses `RUNCELL_AGENT_USER_TOKEN` when explicitly set, otherwise
the existing RunCell OAuth token store (normally `~/.d5m/tokens/current.json`).
The token never belongs in the stdin JSON or command arguments.

`result_timeout_seconds` limits the wait after the run starts; it is not a full
process or Agent wall-clock limit. If the run reaches a permission request,
times out, or pauses for credits, the adapter reports that state and attempts to
cancel the process-local run before exiting. Use explicit permission preferences
for unattended write operations.

## Local Agent Development

From `packages/d5m-ai`, use the dev agent process manager to run the local development stack:

```bash
yarn dev:agent:start
```

This starts four long-running processes:

- `server`: `../../d5m_ai_server/venv/bin/python run_d5m_server.py` from the repo root when that backend venv exists, otherwise `venv/bin/python run_d5m_server.py`
- `jupyter`: `venv/bin/jupyter lab --LabApp.extension_manager=readonly`
- `watch`: `yarn watch`
- `tailwind`: `npx @tailwindcss/cli -i ./style/tailwind.css -o ./style/tailwindDist.css --watch=always`

The manager writes logs and PID files under `.dev-agent/`, which is ignored by git:

```text
.dev-agent/logs/server.log
.dev-agent/logs/jupyter.log
.dev-agent/logs/watch.log
.dev-agent/logs/tailwind.log
.dev-agent/pids/*.pid
```

Useful commands:

```bash
yarn dev:agent:status
yarn dev:agent:logs
yarn dev:agent:logs:follow
yarn dev:agent:restart:server
yarn dev:agent:restart:jupyter
yarn dev:agent:stop
```

To send a single Agent V2 task through the Jupyter proxy without driving the UI:

```bash
yarn dev:agent:send --message "Create a new notebook with a simple scatter plot" --allow-tools
```

This calls the local-only `POST /api/d5m_ai/v2/agent/dev/send` endpoint. The
response is JSON with `request_id`, session/job metadata, streamed events,
assistant text, tool calls, tool outputs, and any notebooks created via
`create_notebook`. Pass `--notebook path/to/file.ipynb` to make an existing
notebook the active target. The same request id is forwarded to the remote
Agent V2 server so Jupyter and server logs can be correlated.

## Learn More

For documentation, product updates, and the latest setup information, visit [www.runcell.dev](https://www.runcell.dev).
