grokbook 0.1.0__tar.gz

grokbook-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Jeffrey Pansa
+
+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.

grokbook-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: grokbook
+Version: 0.1.0
+Summary: Interactive notebook server for learning computer science
+Author-email: Marco Jeffrey Pansa <marco-jeffrey@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/marco-jeffrey/grokbook
+Project-URL: Repository, https://github.com/marco-jeffrey/grokbook
+Project-URL: Issues, https://github.com/marco-jeffrey/grokbook/issues
+Keywords: notebook,jupyter,ipython,datastar,sse,reactive,education
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: Jupyter
+Classifier: Environment :: Web Environment
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stario==2.3.0
+Requires-Dist: jupyter-client>=8.0.0
+Requires-Dist: ipykernel>=6.25.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: watchfiles>=1.1.1
+Requires-Dist: markdown-it-py[linkify,plugins]>=4.0.0
+Requires-Dist: fastmcp>=3.1.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: tqdm>=4.67.3
+Requires-Dist: typer>=0.15.0
+Dynamic: license-file
+
+# grokbook
+
+Interactive notebook server for learning computer science. Works like Jupyter — code cells, markdown, persistent IPython kernels — with a built-in MCP server so AI tutors can create and manage notebooks for you.
+
+## Install
+
+Requires **Python 3.14+** and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/marco-jeffrey/grokbook.git
+cd grokbook
+uv sync
+```
+
+## Usage
+
+```bash
+grokbook
+```
+
+That's it. Opens the notebook UI on [localhost:8080](http://localhost:8080) and the MCP server on port 8081. A welcome notebook is created on first run.
+
+### Custom kernel environment
+
+By default, grokbook uses its own Python for the kernel. To use a separate environment with your libraries:
+
+```bash
+# Create an env with your packages
+mkdir /tmp/my-env && cd /tmp/my-env
+uv init && uv add pandas numpy matplotlib ipykernel
+
+# Start grokbook with that env
+grokbook serve --python /tmp/my-env/.venv/bin/python
+```
+
+### Remote access (Tailscale / LAN)
+
+By default, grokbook binds to `127.0.0.1` (localhost only). To access from other machines:
+
+```bash
+grokbook serve --host 0.0.0.0
+```
+
+Both the notebook server and MCP server bind to all interfaces. Access from another machine at `http://<ip>:8080`.
+
+> **Warning**: Grokbook executes arbitrary Python code. Do not expose it to untrusted networks.
+
+### CLI reference
+
+```
+grokbook                          # Start everything (default)
+grokbook serve [OPTIONS]          # Start notebook + MCP servers
+  --host TEXT                     # Bind address (default: 127.0.0.1)
+  --port, -p INT                  # Notebook server port (default: 8080)
+  --mcp-port INT                  # MCP server port (default: 8081)
+  --python PATH                   # Python interpreter for kernels
+  --db PATH                       # Database file (default: ~/.grokbook/grokbook.db)
+  --allow-code-execution          # Enable execute/kernel tools in MCP
+
+grokbook mcp [OPTIONS]            # MCP server standalone (stdio, for Claude Desktop)
+  --allow-code-execution          # Enable execute/kernel tools
+```
+
+## MCP Integration
+
+On startup, grokbook prints an MCP config block you can paste directly into Claude Desktop or LM Studio:
+
+```json
+{
+  "mcpServers": {
+    "grokbook": {
+      "command": "grokbook",
+      "args": ["mcp", "--allow-code-execution"],
+      "env": {
+        "GROKBOOK_API_URL": "http://localhost:8080/api"
+      }
+    }
+  }
+}
+```
+
+Omit `--allow-code-execution` to restrict the MCP server to read/write operations only (no code execution).
+
+The `grokbook mcp` command runs in stdio mode for Claude Desktop. For HTTP-based MCP clients (LM Studio, remote agents), the built-in MCP server on port 8081 is already running when you start `grokbook serve`.
+
+**Always available**: `list_notebooks`, `get_notebook`, `create_notebook`, `rename_notebook`, `duplicate_notebook`, `list_projects`, `create_project`, `rename_project`, `move_notebook`, `create_cell`, `insert_cell`, `read_cell`, `write_cell`, `delete_cell`, `move_cell`, `duplicate_cell`, `change_cell_type`, `clear_output`, `clear_all_outputs`
+
+**With `--allow-code-execution`**: `execute_cell`, `run_all_cells`, `kernel_status`, `restart_kernel`, `get_variables`, `interrupt_kernel`
+
+To enable code execution via MCP:
+
+```bash
+grokbook serve --allow-code-execution
+```
+
+## Features
+
+- **Code cells** with streaming execution, rich output (images, HTML, SVG, pandas tables)
+- **Markdown cells** with GitHub-flavored rendering
+- **Persistent IPython kernels** — one per notebook, variables carry over between cells
+- **Keyboard-driven** — Vim-like command/edit modes (j/k, a/b, dd, Shift+Enter)
+- **Import/export** Jupyter `.ipynb` files
+- **Variables inspector** panel
+- **Dark/light theme**, wide mode, autocomplete, signature tooltips
+- **Live sync** across browser tabs via SSE
+
+## Keyboard Shortcuts
+
+Grokbook uses two modes, inspired by Vim:
+
+**Command mode** (press `Escape` to enter):
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Navigate between cells |
+| `Enter` | Edit selected cell |
+| `a` / `b` | Insert cell above / below |
+| `m` | Convert to markdown |
+| `y` | Convert to code |
+| `dd` | Delete cell |
+| `Cmd+Shift+Up/Down` | Move cell up / down |
+
+**Edit mode** (press `Enter` or click a cell):
+
+| Key | Action |
+|-----|--------|
+| `Shift+Enter` | Execute cell, move to next |
+| `Cmd+Enter` / `Ctrl+Enter` | Execute cell, stay in place |
+| `Escape` | Back to command mode |
+| `Tab` / `Shift+Tab` | Indent / dedent |
+
+### Vim mode
+
+Enable Vim keybindings from the editor settings panel (gear icon). When active:
+
+- Full Vim motions in code cells (normal, insert, visual modes)
+- `jk` is mapped to `Escape` in insert mode for quick mode switching
+- Block cursor in normal mode, line cursor in insert mode
+
+## Architecture
+
+```
+Browser ──SSE──▶ Stario server (:8080) ──ZMQ──▶ IPython kernel
+   │                  │
+   │  Datastar        │  SQLite (~/.grokbook/grokbook.db)
+   │  (reactive       │
+   │   signals)       ├── REST API (/api)
+   │                  │
+   ▼                  ▼
+ DOM patches      MCP server (:8081)
+ via SSE          (FastMCP, for LLM agents)
+```
+
+## License
+
+MIT

grokbook-0.1.0/README.md

@@ -0,0 +1,156 @@
+# grokbook
+
+Interactive notebook server for learning computer science. Works like Jupyter — code cells, markdown, persistent IPython kernels — with a built-in MCP server so AI tutors can create and manage notebooks for you.
+
+## Install
+
+Requires **Python 3.14+** and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/marco-jeffrey/grokbook.git
+cd grokbook
+uv sync
+```
+
+## Usage
+
+```bash
+grokbook
+```
+
+That's it. Opens the notebook UI on [localhost:8080](http://localhost:8080) and the MCP server on port 8081. A welcome notebook is created on first run.
+
+### Custom kernel environment
+
+By default, grokbook uses its own Python for the kernel. To use a separate environment with your libraries:
+
+```bash
+# Create an env with your packages
+mkdir /tmp/my-env && cd /tmp/my-env
+uv init && uv add pandas numpy matplotlib ipykernel
+
+# Start grokbook with that env
+grokbook serve --python /tmp/my-env/.venv/bin/python
+```
+
+### Remote access (Tailscale / LAN)
+
+By default, grokbook binds to `127.0.0.1` (localhost only). To access from other machines:
+
+```bash
+grokbook serve --host 0.0.0.0
+```
+
+Both the notebook server and MCP server bind to all interfaces. Access from another machine at `http://<ip>:8080`.
+
+> **Warning**: Grokbook executes arbitrary Python code. Do not expose it to untrusted networks.
+
+### CLI reference
+
+```
+grokbook                          # Start everything (default)
+grokbook serve [OPTIONS]          # Start notebook + MCP servers
+  --host TEXT                     # Bind address (default: 127.0.0.1)
+  --port, -p INT                  # Notebook server port (default: 8080)
+  --mcp-port INT                  # MCP server port (default: 8081)
+  --python PATH                   # Python interpreter for kernels
+  --db PATH                       # Database file (default: ~/.grokbook/grokbook.db)
+  --allow-code-execution          # Enable execute/kernel tools in MCP
+
+grokbook mcp [OPTIONS]            # MCP server standalone (stdio, for Claude Desktop)
+  --allow-code-execution          # Enable execute/kernel tools
+```
+
+## MCP Integration
+
+On startup, grokbook prints an MCP config block you can paste directly into Claude Desktop or LM Studio:
+
+```json
+{
+  "mcpServers": {
+    "grokbook": {
+      "command": "grokbook",
+      "args": ["mcp", "--allow-code-execution"],
+      "env": {
+        "GROKBOOK_API_URL": "http://localhost:8080/api"
+      }
+    }
+  }
+}
+```
+
+Omit `--allow-code-execution` to restrict the MCP server to read/write operations only (no code execution).
+
+The `grokbook mcp` command runs in stdio mode for Claude Desktop. For HTTP-based MCP clients (LM Studio, remote agents), the built-in MCP server on port 8081 is already running when you start `grokbook serve`.
+
+**Always available**: `list_notebooks`, `get_notebook`, `create_notebook`, `rename_notebook`, `duplicate_notebook`, `list_projects`, `create_project`, `rename_project`, `move_notebook`, `create_cell`, `insert_cell`, `read_cell`, `write_cell`, `delete_cell`, `move_cell`, `duplicate_cell`, `change_cell_type`, `clear_output`, `clear_all_outputs`
+
+**With `--allow-code-execution`**: `execute_cell`, `run_all_cells`, `kernel_status`, `restart_kernel`, `get_variables`, `interrupt_kernel`
+
+To enable code execution via MCP:
+
+```bash
+grokbook serve --allow-code-execution
+```
+
+## Features
+
+- **Code cells** with streaming execution, rich output (images, HTML, SVG, pandas tables)
+- **Markdown cells** with GitHub-flavored rendering
+- **Persistent IPython kernels** — one per notebook, variables carry over between cells
+- **Keyboard-driven** — Vim-like command/edit modes (j/k, a/b, dd, Shift+Enter)
+- **Import/export** Jupyter `.ipynb` files
+- **Variables inspector** panel
+- **Dark/light theme**, wide mode, autocomplete, signature tooltips
+- **Live sync** across browser tabs via SSE
+
+## Keyboard Shortcuts
+
+Grokbook uses two modes, inspired by Vim:
+
+**Command mode** (press `Escape` to enter):
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Navigate between cells |
+| `Enter` | Edit selected cell |
+| `a` / `b` | Insert cell above / below |
+| `m` | Convert to markdown |
+| `y` | Convert to code |
+| `dd` | Delete cell |
+| `Cmd+Shift+Up/Down` | Move cell up / down |
+
+**Edit mode** (press `Enter` or click a cell):
+
+| Key | Action |
+|-----|--------|
+| `Shift+Enter` | Execute cell, move to next |
+| `Cmd+Enter` / `Ctrl+Enter` | Execute cell, stay in place |
+| `Escape` | Back to command mode |
+| `Tab` / `Shift+Tab` | Indent / dedent |
+
+### Vim mode
+
+Enable Vim keybindings from the editor settings panel (gear icon). When active:
+
+- Full Vim motions in code cells (normal, insert, visual modes)
+- `jk` is mapped to `Escape` in insert mode for quick mode switching
+- Block cursor in normal mode, line cursor in insert mode
+
+## Architecture
+
+```
+Browser ──SSE──▶ Stario server (:8080) ──ZMQ──▶ IPython kernel
+   │                  │
+   │  Datastar        │  SQLite (~/.grokbook/grokbook.db)
+   │  (reactive       │
+   │   signals)       ├── REST API (/api)
+   │                  │
+   ▼                  ▼
+ DOM patches      MCP server (:8081)
+ via SSE          (FastMCP, for LLM agents)
+```
+
+## License
+
+MIT

grokbook-0.1.0/grokbook/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m grokbook`."""
+
+from grokbook.cli import app
+
+app()

grokbook-0.1.0/grokbook/_server.py

@@ -0,0 +1,109 @@
+"""Server bootstrap and runner — shared by main.py (dev) and cli.py (production)."""
+
+import asyncio
+import os
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from stario import Relay, RichTracer, Stario
+from stario.http.server import Server
+from stario.http.writer import CompressionConfig
+from stario.telemetry.core import Span
+
+from grokbook.api import api_router
+from grokbook.db import Database
+from grokbook import envs
+from grokbook.handlers import app_router
+from grokbook.kernel import KernelPool
+
+
+def make_bootstrap(db_path: Path, python_path: str | None = None):
+    @asynccontextmanager
+    async def bootstrap(app: Stario, span: Span):
+        nonlocal python_path
+        db = await Database.connect(str(db_path))
+
+        # Create welcome notebook on first run
+        from grokbook.welcome import ensure_welcome_notebook
+
+        await ensure_welcome_notebook(db)
+
+        # Discover available Python environments (uv + kernelspecs + cwd .venv)
+        await envs.refresh()
+
+        # Auto-pick a default interpreter if --python wasn't supplied
+        if python_path is None:
+            default_env = await envs.pick_default(cwd=Path.cwd())
+            if default_env is not None:
+                python_path = default_env.path
+                if not default_env.has_ipykernel:
+                    print(f"Installing ipykernel into {default_env.name}…")
+                    ok = False
+                    async for kind, line in envs.install_ipykernel(default_env.path):
+                        if kind == "done":
+                            ok = line == "ok"
+                            if not ok:
+                                print(f"  WARNING: {line}")
+                        else:
+                            print(f"  {line}")
+                    if ok:
+                        await envs.refresh()
+                    else:
+                        print("  Kernel will start, but ipykernel import may fail.")
+                print(f"Using kernel: {default_env.name} ({default_env.path})")
+
+        pool = KernelPool(default_python_path=python_path)
+        relay: Relay[str] = Relay()
+
+        static_dir = Path(__file__).parent / "static"
+        app.assets("/static", static_dir, name="static")
+
+        app.mount("/api", api_router(db, pool, relay))
+        app.mount("/", app_router(db, pool, relay))
+
+        try:
+            yield
+        finally:
+            await pool.shutdown_all()
+            await db.close()
+
+    return bootstrap
+
+
+def run_server(
+    host: str = "127.0.0.1",
+    port: int = 8080,
+    db_path: Path = Path("nb.db"),
+    python_path: str | None = None,
+    mcp_host: str | None = None,
+    mcp_port: int = 8081,
+) -> None:
+    """Start the grokbook server, optionally with MCP server. Blocks until Ctrl+C."""
+
+    async def _run() -> None:
+        server = Server(
+            make_bootstrap(db_path, python_path),
+            RichTracer(),
+            host=host,
+            port=port,
+            compression=CompressionConfig(zstd_level=-1),
+        )
+
+        if mcp_host is not None:
+            # Run both notebook server and MCP HTTP server concurrently
+            os.environ["GROKBOOK_API_URL"] = f"http://127.0.0.1:{port}/api"
+            from grokbook.mcp_server import mcp
+
+            await asyncio.gather(
+                server.run(),
+                mcp.run_async(
+                    "streamable-http",
+                    host=mcp_host,
+                    port=mcp_port,
+                    show_banner=False,
+                ),
+            )
+        else:
+            await server.run()
+
+    asyncio.run(_run())

grokbook-0.1.0/grokbook/ansi.py

@@ -0,0 +1,80 @@
+"""Convert ANSI escape sequences to HTML spans."""
+
+import re
+
+_ANSI_RE = re.compile(r"\x1b\[([0-9;]*)m")
+
+_FG_COLORS = {
+    30: "#6e7681", 31: "#ff7b72", 32: "#7ee787", 33: "#d29922",
+    34: "#79c0ff", 35: "#d2a8ff", 36: "#a5d6ff", 37: "#c9d1d9",
+    90: "#8b949e", 91: "#ffa198", 92: "#9be9a8", 93: "#e3b341",
+    94: "#a5d6ff", 95: "#d2a8ff", 96: "#b6e3ff", 97: "#f0f6fc",
+}
+
+_BG_COLORS = {
+    40: "#6e7681", 41: "#ff7b72", 42: "#7ee787", 43: "#d29922",
+    44: "#79c0ff", 45: "#d2a8ff", 46: "#a5d6ff", 47: "#c9d1d9",
+    100: "#8b949e", 101: "#ffa198", 102: "#9be9a8", 103: "#e3b341",
+    104: "#a5d6ff", 105: "#d2a8ff", 106: "#b6e3ff", 107: "#f0f6fc",
+}
+
+
+def ansi_to_html(text: str) -> str:
+    """Convert ANSI escape sequences in text to HTML with inline styles.
+
+    Returns HTML string with <span style="..."> tags. The output is
+    intended to be wrapped in SafeString() for rendering.
+    All non-ANSI text is HTML-escaped.
+    """
+    import html as _html
+
+    result = []
+    pos = 0
+    span_open = False
+    current_styles: dict[str, str] = {}
+
+    for match in _ANSI_RE.finditer(text):
+        # Append text before this escape sequence (HTML-escaped)
+        if match.start() > pos:
+            result.append(_html.escape(text[pos:match.start()]))
+        pos = match.end()
+
+        codes_str = match.group(1)
+        if not codes_str:
+            codes = [0]
+        else:
+            codes = [int(c) for c in codes_str.split(";") if c]
+
+        for code in codes:
+            if code == 0:
+                current_styles.clear()
+            elif code == 1:
+                current_styles["font-weight"] = "bold"
+            elif code == 3:
+                current_styles["font-style"] = "italic"
+            elif code == 4:
+                current_styles["text-decoration"] = "underline"
+            elif code in _FG_COLORS:
+                current_styles["color"] = _FG_COLORS[code]
+            elif code in _BG_COLORS:
+                current_styles["background-color"] = _BG_COLORS[code]
+
+        # Close previous span if open
+        if span_open:
+            result.append("</span>")
+            span_open = False
+
+        # Open new span if we have styles
+        if current_styles:
+            style = ";".join(f"{k}:{v}" for k, v in current_styles.items())
+            result.append(f'<span style="{style}">')
+            span_open = True
+
+    # Append remaining text
+    if pos < len(text):
+        result.append(_html.escape(text[pos:]))
+
+    if span_open:
+        result.append("</span>")
+
+    return "".join(result)