jupyter-jcli 0.1.0__tar.gz

jupyter_jcli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release & Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish -t ${{ secrets.PYPI_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

jupyter_jcli-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra test
+
+      - name: Run tests
+        run: uv run pytest -v

jupyter_jcli-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.venv/
+__pycache__/
+*.egg-info/

jupyter_jcli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tttpob
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jupyter_jcli-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: jupyter-jcli
+Version: 0.1.0
+Summary: CLI tool for LLM agents to operate Jupyter Lab servers
+Author-email: tttpob <i@tpob.io>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: click>=8
+Requires-Dist: jupyter-kernel-client>=0.7.3
+Requires-Dist: jupyter-server-client
+Requires-Dist: nbformat>=5
+Provides-Extra: test
+Requires-Dist: ipykernel; extra == 'test'
+Requires-Dist: jupyter-server<3,>=2; extra == 'test'
+Requires-Dist: matplotlib; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# jupyter-jcli
+
+CLI tool for LLM agents to operate Jupyter Lab servers.
+
+j-cli enables AI agents (and humans) to remotely control Jupyter servers — execute code in kernels, manage sessions, and write outputs back to notebooks, all from the command line.
+
+## Installation
+
+```bash
+# from source
+uv sync
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```bash
+# set connection (or pass via -s / -t flags)
+export JCLI_JUPYTER_SERVER_URL=http://localhost:8888
+export JCLI_JUPYTER_SERVER_TOKEN=your-token
+
+# check connectivity
+j-cli healthcheck
+
+# create a session and execute code
+j-cli session create --kernel python3 --name my-session
+j-cli exec <session_id> --code "print('hello world')"
+```
+
+## Commands
+
+### Global Options
+
+| Flag | Description |
+|------|-------------|
+| `-s`, `--server-url` | Jupyter server URL (env: `JCLI_JUPYTER_SERVER_URL`, default: `http://localhost:8888`) |
+| `-t`, `--token` | Auth token (env: `JCLI_JUPYTER_SERVER_TOKEN`) |
+| `-j`, `--json` | Output as JSON for programmatic use |
+| `--version` | Show version |
+
+### `healthcheck`
+
+Check server connectivity and running kernel count.
+
+```bash
+j-cli healthcheck
+```
+
+### `kernelspec list`
+
+List available kernel specifications.
+
+```bash
+j-cli kernelspec list
+```
+
+### `session`
+
+```bash
+j-cli session create --kernel python3 --name my-session
+j-cli session list
+j-cli session kill <session_id>
+```
+
+### `kernel`
+
+```bash
+j-cli kernel interrupt <session_id>
+j-cli kernel restart <session_id>
+```
+
+### `exec`
+
+Execute code in a kernel session. Supports inline code, py:percent files, and Jupyter notebooks.
+
+```bash
+# inline code
+j-cli exec <session_id> --code "import pandas as pd; df = pd.read_csv('data.csv'); df.head()"
+
+# execute from py:percent file
+j-cli exec <session_id> --file analysis.py
+
+# execute specific cells from a notebook
+j-cli exec <session_id> --file notebook.ipynb --cell 0:3
+
+# execute a single cell
+j-cli exec <session_id> --file notebook.ipynb --cell 5
+```
+
+**Cell spec formats** (0-indexed):
+
+| Spec | Meaning |
+|------|---------|
+| `3` | Cell 3 only |
+| `3:7` | Cells 3, 4, 5, 6 |
+| `3:` | Cell 3 to end |
+| `:5` | Cells 0 through 4 |
+
+**Notebook writeback**: When executing from a file, outputs are automatically written back to the paired `.ipynb` file. For `analysis.py`, j-cli looks for `analysis.ipynb` in the same directory.
+
+## Py:Percent Format
+
+j-cli supports the [py:percent](https://jupytext.readthedocs.io/en/latest/formats-scripts.html#the-percent-format) format — plain Python files with cell markers:
+
+```python
+# ---
+# jupyter:
+#   kernelspec:
+#     name: python3
+# ---
+
+# %%
+import numpy as np
+
+# %%
+x = np.random.randn(100)
+print(x.mean())
+```
+
+## Development
+
+```bash
+# install with test dependencies
+uv sync --extra test
+
+# run tests (requires a real Jupyter server, started automatically by fixtures)
+uv run pytest -v
+```
+
+## License
+
+MIT

jupyter_jcli-0.1.0/README.md

@@ -0,0 +1,133 @@
+# jupyter-jcli
+
+CLI tool for LLM agents to operate Jupyter Lab servers.
+
+j-cli enables AI agents (and humans) to remotely control Jupyter servers — execute code in kernels, manage sessions, and write outputs back to notebooks, all from the command line.
+
+## Installation
+
+```bash
+# from source
+uv sync
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```bash
+# set connection (or pass via -s / -t flags)
+export JCLI_JUPYTER_SERVER_URL=http://localhost:8888
+export JCLI_JUPYTER_SERVER_TOKEN=your-token
+
+# check connectivity
+j-cli healthcheck
+
+# create a session and execute code
+j-cli session create --kernel python3 --name my-session
+j-cli exec <session_id> --code "print('hello world')"
+```
+
+## Commands
+
+### Global Options
+
+| Flag | Description |
+|------|-------------|
+| `-s`, `--server-url` | Jupyter server URL (env: `JCLI_JUPYTER_SERVER_URL`, default: `http://localhost:8888`) |
+| `-t`, `--token` | Auth token (env: `JCLI_JUPYTER_SERVER_TOKEN`) |
+| `-j`, `--json` | Output as JSON for programmatic use |
+| `--version` | Show version |
+
+### `healthcheck`
+
+Check server connectivity and running kernel count.
+
+```bash
+j-cli healthcheck
+```
+
+### `kernelspec list`
+
+List available kernel specifications.
+
+```bash
+j-cli kernelspec list
+```
+
+### `session`
+
+```bash
+j-cli session create --kernel python3 --name my-session
+j-cli session list
+j-cli session kill <session_id>
+```
+
+### `kernel`
+
+```bash
+j-cli kernel interrupt <session_id>
+j-cli kernel restart <session_id>
+```
+
+### `exec`
+
+Execute code in a kernel session. Supports inline code, py:percent files, and Jupyter notebooks.
+
+```bash
+# inline code
+j-cli exec <session_id> --code "import pandas as pd; df = pd.read_csv('data.csv'); df.head()"
+
+# execute from py:percent file
+j-cli exec <session_id> --file analysis.py
+
+# execute specific cells from a notebook
+j-cli exec <session_id> --file notebook.ipynb --cell 0:3
+
+# execute a single cell
+j-cli exec <session_id> --file notebook.ipynb --cell 5
+```
+
+**Cell spec formats** (0-indexed):
+
+| Spec | Meaning |
+|------|---------|
+| `3` | Cell 3 only |
+| `3:7` | Cells 3, 4, 5, 6 |
+| `3:` | Cell 3 to end |
+| `:5` | Cells 0 through 4 |
+
+**Notebook writeback**: When executing from a file, outputs are automatically written back to the paired `.ipynb` file. For `analysis.py`, j-cli looks for `analysis.ipynb` in the same directory.
+
+## Py:Percent Format
+
+j-cli supports the [py:percent](https://jupytext.readthedocs.io/en/latest/formats-scripts.html#the-percent-format) format — plain Python files with cell markers:
+
+```python
+# ---
+# jupyter:
+#   kernelspec:
+#     name: python3
+# ---
+
+# %%
+import numpy as np
+
+# %%
+x = np.random.randn(100)
+print(x.mean())
+```
+
+## Development
+
+```bash
+# install with test dependencies
+uv sync --extra test
+
+# run tests (requires a real Jupyter server, started automatically by fixtures)
+uv run pytest -v
+```
+
+## License
+
+MIT

jupyter_jcli-0.1.0/jupyter_jcli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

jupyter_jcli-0.1.0/jupyter_jcli/__main__.py

@@ -0,0 +1,3 @@
+from jupyter_jcli.cli import main
+
+main()

jupyter_jcli-0.1.0/jupyter_jcli/cli.py

@@ -0,0 +1,72 @@
+"""jcli — CLI tool for LLM agents to operate Jupyter Lab servers."""
+
+import os
+from urllib.parse import urlparse
+
+import click
+
+from jupyter_jcli.config import get_server_url, get_token
+
+
+def _ensure_no_proxy(server_url: str) -> None:
+    """Ensure local server URLs bypass HTTP proxy."""
+    host = urlparse(server_url).hostname or ""
+    if host in ("127.0.0.1", "localhost", "::1"):
+        no_proxy = os.environ.get("no_proxy", os.environ.get("NO_PROXY", ""))
+        if host not in no_proxy:
+            new = f"{no_proxy},{host}" if no_proxy else host
+            os.environ["no_proxy"] = new
+            os.environ["NO_PROXY"] = new
+
+
+class Context:
+    """Shared context passed to all commands."""
+
+    def __init__(self, server_url: str, token: str | None, use_json: bool):
+        self.server_url = server_url
+        self.token = token
+        self.use_json = use_json
+
+
+pass_ctx = click.make_pass_decorator(Context)
+
+
+@click.group()
+@click.option(
+    "--server-url", "-s", default=None,
+    help="Jupyter server URL (env: JCLI_JUPYTER_SERVER_URL, default: http://localhost:8888)",
+)
+@click.option(
+    "--token", "-t", default=None,
+    help="Jupyter server token (env: JCLI_JUPYTER_SERVER_TOKEN)",
+)
+@click.option(
+    "--json", "-j", "use_json", is_flag=True, default=False,
+    help="Output as JSON instead of human-readable text",
+)
+@click.version_option(package_name="jcli")
+@click.pass_context
+def main(ctx, server_url, token, use_json):
+    """CLI tool for LLM agents to operate Jupyter Lab servers."""
+    resolved_url = get_server_url(server_url)
+    _ensure_no_proxy(resolved_url)
+    ctx.ensure_object(dict)
+    ctx.obj = Context(
+        server_url=resolved_url,
+        token=get_token(token),
+        use_json=use_json,
+    )
+
+
+# Import and register command groups
+from jupyter_jcli.commands.healthcheck import healthcheck  # noqa: E402
+from jupyter_jcli.commands.kernelspec import kernelspec  # noqa: E402
+from jupyter_jcli.commands.session import session  # noqa: E402
+from jupyter_jcli.commands.kernel_cmd import kernel  # noqa: E402
+from jupyter_jcli.commands.exec_cmd import exec_cmd  # noqa: E402
+
+main.add_command(healthcheck)
+main.add_command(kernelspec)
+main.add_command(session)
+main.add_command(kernel)
+main.add_command(exec_cmd, name="exec")

jupyter_jcli-0.1.0/jupyter_jcli/commands/exec_cmd.py

@@ -0,0 +1,128 @@
+"""jcli exec — execute code or cells from files."""
+
+import click
+
+from jupyter_jcli.cli import Context, pass_ctx
+from jupyter_jcli.output import emit, emit_error
+from jupyter_jcli.executor import process_outputs, format_outputs_human
+from jupyter_jcli.notebook_writer import write_outputs_to_notebook
+
+
+@click.command("exec")
+@click.argument("session_id")
+@click.option("--code", "-c", default=None, help="Code to execute directly")
+@click.option("--file", "-f", "file_path", default=None, help="Path to .py or .ipynb file")
+@click.option("--cell", default=None, help="Cell spec: 3, 3:7, 3:, :5 (0-indexed)")
+@click.option("--timeout", default=300, type=int, help="Execution timeout in seconds")
+@pass_ctx
+def exec_cmd(ctx: Context, session_id: str, code: str | None, file_path: str | None, cell: str | None, timeout: int):
+    """Execute code in a kernel session.
+
+    Either --code or --file (with --cell) must be provided.
+    When using --file, outputs are automatically written back to the paired .ipynb.
+    """
+    if not code and not file_path:
+        emit_error("PARSE_ERROR", "Either --code or --file must be provided", ctx.use_json)
+
+    try:
+        from jupyter_jcli.server import get_kernel_id_for_session
+
+        kernel_id = get_kernel_id_for_session(ctx.server_url, session_id, ctx.token)
+    except Exception as e:
+        emit_error("SESSION_NOT_FOUND", str(e), ctx.use_json)
+        return  # unreachable but helps type checker
+
+    # Direct code execution
+    if code:
+        _exec_code(ctx, kernel_id, code, timeout)
+        return
+
+    # File-based execution
+    _exec_file(ctx, kernel_id, file_path, cell, timeout)
+
+
+def _exec_code(ctx: Context, kernel_id: str, code: str, timeout: int):
+    """Execute inline code."""
+    try:
+        from jupyter_jcli.kernel import execute_code
+
+        result = execute_code(ctx.server_url, ctx.token, kernel_id, code, timeout)
+        raw_outputs = result.get("outputs", [])
+        outputs = process_outputs(raw_outputs)
+
+        if ctx.use_json:
+            emit({"status": "ok", "outputs": outputs}, use_json=True)
+        else:
+            text = format_outputs_human(outputs)
+            if text:
+                emit({"_human": text}, use_json=False)
+
+    except Exception as e:
+        emit_error("EXECUTION_ERROR", str(e), ctx.use_json)
+
+
+def _exec_file(ctx: Context, kernel_id: str, file_path: str, cell_spec: str | None, timeout: int):
+    """Execute cells from a file."""
+    try:
+        from jupyter_jcli.parser import parse_file, parse_cell_spec
+        from jupyter_jcli.kernel import kernel_connection
+
+        parsed = parse_file(file_path)
+
+        # Determine which cells to execute
+        code_cells = [c for c in parsed.cells if c.cell_type == "code"]
+        if cell_spec:
+            indices = parse_cell_spec(cell_spec, len(parsed.cells))
+            selected = [c for c in parsed.cells if c.index in indices and c.cell_type == "code"]
+        else:
+            selected = code_cells
+
+        if not selected:
+            emit_error("PARSE_ERROR", "No code cells found to execute", ctx.use_json)
+
+        cell_results = []
+        all_outputs_human = []
+
+        with kernel_connection(ctx.server_url, ctx.token, kernel_id) as kernel:
+            for cell in selected:
+                result = kernel.execute(cell.source, timeout=timeout)
+                raw_outputs = result.get("outputs", [])
+                outputs = process_outputs(raw_outputs)
+
+                cell_results.append({
+                    "cell_index": cell.index,
+                    "source_preview": cell.source[:80].replace("\n", " "),
+                    "outputs": outputs,
+                    "raw_outputs": raw_outputs,
+                    "execution_count": result.get("execution_count"),
+                })
+
+                if not ctx.use_json:
+                    all_outputs_human.append(f"--- cell {cell.index} ---")
+                    text = format_outputs_human(outputs)
+                    if text:
+                        all_outputs_human.append(text)
+
+        # Write back to notebook
+        notebook_updated = None
+        ipynb_path = parsed.paired_ipynb
+        if ipynb_path:
+            notebook_updated = write_outputs_to_notebook(ipynb_path, cell_results)
+
+        if ctx.use_json:
+            # Remove raw_outputs from JSON output (they're internal)
+            for cr in cell_results:
+                del cr["raw_outputs"]
+            data = {"status": "ok", "cells": cell_results}
+            if notebook_updated:
+                data["notebook_updated"] = notebook_updated
+            emit(data, use_json=True)
+        else:
+            if notebook_updated:
+                all_outputs_human.append(f"\nNotebook updated: {notebook_updated}")
+            emit({"_human": "\n".join(all_outputs_human)}, use_json=False)
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        emit_error("EXECUTION_ERROR", str(e), ctx.use_json)

jupyter_jcli-0.1.0/jupyter_jcli/commands/healthcheck.py

@@ -0,0 +1,27 @@
+"""jcli healthcheck — check if Jupyter server is reachable."""
+
+import click
+
+from jupyter_jcli.cli import Context, pass_ctx
+from jupyter_jcli.output import emit, emit_error
+
+
+@click.command()
+@pass_ctx
+def healthcheck(ctx: Context):
+    """Check if the Jupyter server is reachable."""
+    try:
+        from jupyter_jcli.server import healthcheck as do_healthcheck
+
+        info = do_healthcheck(ctx.server_url, ctx.token)
+        emit(
+            {
+                "status": "ok",
+                "version": info["version"],
+                "kernels_running": info["kernels_running"],
+                "_human": f"OK  Jupyter server v{info['version']}  {info['kernels_running']} kernel(s) running",
+            },
+            use_json=ctx.use_json,
+        )
+    except Exception as e:
+        emit_error("CONNECTION_FAILED", f"Cannot reach Jupyter server at {ctx.server_url}: {e}", ctx.use_json)

jupyter_jcli-0.1.0/jupyter_jcli/commands/kernel_cmd.py

@@ -0,0 +1,47 @@
+"""jcli kernel — kernel interrupt/restart."""
+
+import click
+
+from jupyter_jcli.cli import Context, pass_ctx
+from jupyter_jcli.output import emit, emit_error
+
+
+@click.group()
+def kernel():
+    """Manage kernels (interrupt, restart)."""
+
+
+@kernel.command("interrupt")
+@click.argument("session_id")
+@pass_ctx
+def interrupt(ctx: Context, session_id: str):
+    """Interrupt a running kernel by session ID."""
+    try:
+        from jupyter_jcli.server import get_kernel_id_for_session, interrupt_kernel
+
+        kernel_id = get_kernel_id_for_session(ctx.server_url, session_id, ctx.token)
+        interrupt_kernel(ctx.server_url, kernel_id, ctx.token)
+        emit(
+            {"status": "ok", "_human": f"Interrupted kernel {kernel_id} (session {session_id})"},
+            use_json=ctx.use_json,
+        )
+    except Exception as e:
+        emit_error("KERNEL_NOT_FOUND", str(e), ctx.use_json)
+
+
+@kernel.command("restart")
+@click.argument("session_id")
+@pass_ctx
+def restart(ctx: Context, session_id: str):
+    """Restart a kernel by session ID."""
+    try:
+        from jupyter_jcli.server import get_kernel_id_for_session, restart_kernel
+
+        kernel_id = get_kernel_id_for_session(ctx.server_url, session_id, ctx.token)
+        restart_kernel(ctx.server_url, kernel_id, ctx.token)
+        emit(
+            {"status": "ok", "_human": f"Restarted kernel {kernel_id} (session {session_id})"},
+            use_json=ctx.use_json,
+        )
+    except Exception as e:
+        emit_error("KERNEL_NOT_FOUND", str(e), ctx.use_json)

jupyter_jcli-0.1.0/jupyter_jcli/commands/kernelspec.py

@@ -0,0 +1,33 @@
+"""jcli kernelspec — kernel spec management."""
+
+import click
+
+from jupyter_jcli.cli import Context, pass_ctx
+from jupyter_jcli.output import emit, emit_error
+
+
+@click.group()
+def kernelspec():
+    """Manage kernel specifications."""
+
+
+@kernelspec.command("list")
+@pass_ctx
+def list_specs(ctx: Context):
+    """List available kernel specs."""
+    try:
+        from jupyter_jcli.server import list_kernelspecs
+
+        specs = list_kernelspecs(ctx.server_url, ctx.token)
+
+        if ctx.use_json:
+            emit({"kernelspecs": specs}, use_json=True)
+        else:
+            # Table format
+            lines = [f"{'NAME':<20} {'DISPLAY_NAME':<20} {'LANGUAGE':<10}"]
+            for s in specs:
+                lines.append(f"{s['name']:<20} {s['display_name']:<20} {s['language']:<10}")
+            emit({"_human": "\n".join(lines)}, use_json=False)
+
+    except Exception as e:
+        emit_error("CONNECTION_FAILED", str(e), ctx.use_json)