mrmd-python 0.3.0__tar.gz

mrmd_python-0.3.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Runtime assets (generated)
+.mrmd-assets/
+
+# OS
+.DS_Store
+Thumbs.db

mrmd_python-0.3.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: mrmd-python
+Version: 0.3.0
+Summary: Python runtime server implementing the MRMD Runtime Protocol (MRP)
+Author: mrmd contributors
+License: MIT
+Keywords: ipython,mrmd,mrp,notebook,runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: black>=25.12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: ipython>=8.0.0
+Requires-Dist: jedi>=0.19.0
+Requires-Dist: sse-starlette>=2.0.0
+Requires-Dist: starlette>=0.40.0
+Requires-Dist: uvicorn>=0.32.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: format
+Requires-Dist: black>=24.0.0; extra == 'format'
+Description-Content-Type: text/markdown
+
+# mrmd-python
+
+Independent Python runtime for MRMD notebooks. Runs as a daemon process with full GPU memory isolation.
+
+## Features
+
+- **Independent daemon process** - survives if parent dies, variables persist
+- **GPU memory isolation** - kill daemon to release VRAM (critical for vLLM)
+- **Auto venv detection** - uses current venv or `VIRTUAL_ENV`
+- **Registry-based discovery** - find runtimes via `~/.mrmd/runtimes/`
+- **Full MRP protocol** - execute, completions, inspect, variables, streaming
+
+## Installation
+
+```bash
+# With uv
+uv pip install mrmd-python
+
+# Or run directly without installing
+uvx mrmd-python
+```
+
+## Quick Start
+
+```bash
+# Start a daemon runtime (auto-detects venv)
+mrmd-python
+
+# The daemon runs in background. Use the API:
+curl http://localhost:PORT/mrp/v1/capabilities
+
+# List running runtimes
+mrmd-python --list
+
+# Kill when done (releases GPU memory)
+mrmd-python --kill default
+```
+
+## CLI Reference
+
+```bash
+# Start daemon
+mrmd-python                     # Start with ID "default"
+mrmd-python --id vllm           # Start with custom ID
+mrmd-python --venv /path/venv   # Use specific venv
+mrmd-python --port 8000         # Use specific port
+
+# Management
+mrmd-python --list              # List all running runtimes
+mrmd-python --info ID           # Get runtime details
+mrmd-python --kill ID           # Kill a runtime
+mrmd-python --kill-all          # Kill all runtimes
+
+# Development
+mrmd-python --foreground        # Run in foreground (no daemon)
+```
+
+## Virtual Environment Detection
+
+When `--venv` is not specified, mrmd-python auto-detects:
+
+1. Current venv (if running inside one via `sys.prefix`)
+2. `VIRTUAL_ENV` environment variable
+3. Falls back to system Python
+
+## API Endpoints
+
+All endpoints at `/mrp/v1/`:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/capabilities` | GET | Runtime info and features |
+| `/sessions` | GET/POST | List/create sessions |
+| `/sessions/{id}` | GET/DELETE | Get/destroy session |
+| `/execute` | POST | Run code |
+| `/execute/stream` | POST | Run code with SSE streaming |
+| `/complete` | POST | Get completions |
+| `/inspect` | POST | Get symbol documentation |
+| `/hover` | POST | Get hover tooltip |
+| `/variables` | POST | List user variables |
+| `/variables/{name}` | POST | Get variable details |
+| `/is_complete` | POST | Check if code is complete |
+| `/format` | POST | Format code with black |
+
+## Architecture
+
+```
+~/.mrmd/
+├── runtimes/
+│   └── {id}.json    # Registry: pid, port, url, venv, cwd
+└── logs/
+    └── {id}.log     # Daemon logs
+```
+
+Each runtime is a fully independent process:
+- Double-forked daemon (survives parent death)
+- Own IPython shell with persistent variables
+- HTTP server on auto-assigned port
+- Registered in `~/.mrmd/runtimes/` for discovery
+
+## GPU Memory Management
+
+For vLLM and other GPU workloads, memory is only released when the process dies:
+
+```bash
+# Load model in runtime
+mrmd-python --id vllm
+# ... use the model ...
+
+# Release GPU memory
+mrmd-python --kill vllm
+```
+
+## Programmatic Usage
+
+```python
+from mrmd_python import create_app
+import uvicorn
+
+# Create app (daemon_mode=True for use inside daemon)
+app = create_app(
+    cwd="/path/to/project",
+    venv="/path/to/venv",
+    daemon_mode=True,
+)
+uvicorn.run(app, host="localhost", port=8000)
+```
+
+## Protocol
+
+See [PROTOCOL.md](../mrmd-editor/PROTOCOL.md) for the full MRP specification.

mrmd_python-0.3.0/README.md

@@ -0,0 +1,131 @@
+# mrmd-python
+
+Independent Python runtime for MRMD notebooks. Runs as a daemon process with full GPU memory isolation.
+
+## Features
+
+- **Independent daemon process** - survives if parent dies, variables persist
+- **GPU memory isolation** - kill daemon to release VRAM (critical for vLLM)
+- **Auto venv detection** - uses current venv or `VIRTUAL_ENV`
+- **Registry-based discovery** - find runtimes via `~/.mrmd/runtimes/`
+- **Full MRP protocol** - execute, completions, inspect, variables, streaming
+
+## Installation
+
+```bash
+# With uv
+uv pip install mrmd-python
+
+# Or run directly without installing
+uvx mrmd-python
+```
+
+## Quick Start
+
+```bash
+# Start a daemon runtime (auto-detects venv)
+mrmd-python
+
+# The daemon runs in background. Use the API:
+curl http://localhost:PORT/mrp/v1/capabilities
+
+# List running runtimes
+mrmd-python --list
+
+# Kill when done (releases GPU memory)
+mrmd-python --kill default
+```
+
+## CLI Reference
+
+```bash
+# Start daemon
+mrmd-python                     # Start with ID "default"
+mrmd-python --id vllm           # Start with custom ID
+mrmd-python --venv /path/venv   # Use specific venv
+mrmd-python --port 8000         # Use specific port
+
+# Management
+mrmd-python --list              # List all running runtimes
+mrmd-python --info ID           # Get runtime details
+mrmd-python --kill ID           # Kill a runtime
+mrmd-python --kill-all          # Kill all runtimes
+
+# Development
+mrmd-python --foreground        # Run in foreground (no daemon)
+```
+
+## Virtual Environment Detection
+
+When `--venv` is not specified, mrmd-python auto-detects:
+
+1. Current venv (if running inside one via `sys.prefix`)
+2. `VIRTUAL_ENV` environment variable
+3. Falls back to system Python
+
+## API Endpoints
+
+All endpoints at `/mrp/v1/`:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/capabilities` | GET | Runtime info and features |
+| `/sessions` | GET/POST | List/create sessions |
+| `/sessions/{id}` | GET/DELETE | Get/destroy session |
+| `/execute` | POST | Run code |
+| `/execute/stream` | POST | Run code with SSE streaming |
+| `/complete` | POST | Get completions |
+| `/inspect` | POST | Get symbol documentation |
+| `/hover` | POST | Get hover tooltip |
+| `/variables` | POST | List user variables |
+| `/variables/{name}` | POST | Get variable details |
+| `/is_complete` | POST | Check if code is complete |
+| `/format` | POST | Format code with black |
+
+## Architecture
+
+```
+~/.mrmd/
+├── runtimes/
+│   └── {id}.json    # Registry: pid, port, url, venv, cwd
+└── logs/
+    └── {id}.log     # Daemon logs
+```
+
+Each runtime is a fully independent process:
+- Double-forked daemon (survives parent death)
+- Own IPython shell with persistent variables
+- HTTP server on auto-assigned port
+- Registered in `~/.mrmd/runtimes/` for discovery
+
+## GPU Memory Management
+
+For vLLM and other GPU workloads, memory is only released when the process dies:
+
+```bash
+# Load model in runtime
+mrmd-python --id vllm
+# ... use the model ...
+
+# Release GPU memory
+mrmd-python --kill vllm
+```
+
+## Programmatic Usage
+
+```python
+from mrmd_python import create_app
+import uvicorn
+
+# Create app (daemon_mode=True for use inside daemon)
+app = create_app(
+    cwd="/path/to/project",
+    venv="/path/to/venv",
+    daemon_mode=True,
+)
+uvicorn.run(app, host="localhost", port=8000)
+```
+
+## Protocol
+
+See [PROTOCOL.md](../mrmd-editor/PROTOCOL.md) for the full MRP specification.

mrmd_python-0.3.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "mrmd-python"
+version = "0.3.0"
+description = "Python runtime server implementing the MRMD Runtime Protocol (MRP)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "mrmd contributors" }]
+keywords = ["notebook", "ipython", "runtime", "mrmd", "mrp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+    "starlette>=0.40.0",
+    "uvicorn>=0.32.0",
+    "sse-starlette>=2.0.0",
+    "ipython>=8.0.0",
+    "jedi>=0.19.0",
+    "black>=25.12.0",
+    "httpx>=0.27.0",  # For daemon runtime HTTP client
+]
+
+[project.optional-dependencies]
+format = ["black>=24.0.0"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+mrmd-python = "mrmd_python.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mrmd_python"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mrmd_python-0.3.0/src/mrmd_python/__init__.py

@@ -0,0 +1,16 @@
+"""
+mrmd-python: Python runtime server implementing the MRMD Runtime Protocol (MRP)
+
+Usage:
+    mrmd-python [--host HOST] [--port PORT] [--cwd DIR]
+
+Or programmatically:
+    from mrmd_python import create_app
+    app = create_app()
+"""
+
+from .server import create_app, MRPServer
+from .worker import IPythonWorker
+
+__version__ = "0.1.0"
+__all__ = ["create_app", "MRPServer", "IPythonWorker", "__version__"]

mrmd_python-0.3.0/src/mrmd_python/cli.py

@@ -0,0 +1,225 @@
+"""
+mrmd-python CLI
+
+Independent Python runtime for MRMD notebooks.
+
+Usage:
+    # Start a daemon runtime (default)
+    mrmd-python
+    mrmd-python --id my-session --venv /path/to/venv
+
+    # Management commands
+    mrmd-python --list              # List running runtimes
+    mrmd-python --kill my-session   # Kill a runtime
+    mrmd-python --kill-all          # Kill all runtimes
+    mrmd-python --info my-session   # Get runtime info
+
+    # Development/debugging
+    mrmd-python --foreground        # Run in foreground (no daemon)
+
+    # Using with uvx (no install needed)
+    uvx mrmd-python
+    uvx mrmd-python --list
+"""
+
+import argparse
+import json
+import os
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="mrmd-python",
+        description="Independent Python runtime for MRMD notebooks",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  mrmd-python                     Start default runtime (daemon mode)
+  mrmd-python --id vllm           Start runtime named 'vllm'
+  mrmd-python --venv ~/.venv/ml   Use specific virtual environment
+  mrmd-python --list              List all running runtimes
+  mrmd-python --kill vllm         Kill the 'vllm' runtime
+  mrmd-python --foreground        Run in foreground (for debugging)
+
+Virtual Environment Detection:
+  If --venv is not specified, mrmd-python auto-detects:
+  1. Current venv (if running inside one)
+  2. VIRTUAL_ENV environment variable
+  3. Falls back to system Python
+
+Using with uvx (no install needed):
+  uvx mrmd-python                 Start default runtime
+  uvx mrmd-python --list          List runtimes
+""",
+    )
+
+    # Runtime configuration
+    parser.add_argument(
+        "--id",
+        default="default",
+        help="Runtime ID (default: 'default')",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=0,
+        help="Port to bind to (0 = auto-assign)",
+    )
+    parser.add_argument(
+        "--venv",
+        default=None,
+        help="Virtual environment path (auto-detected if not specified)",
+    )
+    parser.add_argument(
+        "--cwd",
+        default=None,
+        help="Working directory (default: current directory)",
+    )
+    parser.add_argument(
+        "--assets-dir",
+        default=None,
+        help="Directory for saving assets like plots",
+    )
+
+    # Execution mode
+    parser.add_argument(
+        "--foreground",
+        action="store_true",
+        help="Run in foreground instead of daemon mode",
+    )
+
+    # Management commands
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help="List all running runtimes",
+    )
+    parser.add_argument(
+        "--kill",
+        metavar="ID",
+        help="Kill a runtime by ID",
+    )
+    parser.add_argument(
+        "--kill-all",
+        action="store_true",
+        help="Kill all running runtimes",
+    )
+    parser.add_argument(
+        "--info",
+        metavar="ID",
+        help="Get detailed info about a runtime",
+    )
+
+    args = parser.parse_args()
+
+    # Import daemon functions (lazy import for fast --help)
+    from .runtime_daemon import (
+        list_runtimes,
+        kill_runtime,
+        read_runtime_info,
+        is_runtime_alive,
+        spawn_daemon,
+        run_daemon,
+    )
+
+    # Handle management commands
+    if args.list:
+        runtimes = list_runtimes()
+        if not runtimes:
+            print("No runtimes running")
+            print("\nStart one with: mrmd-python")
+        else:
+            print(f"{'ID':<20} {'STATUS':<8} {'PID':<10} {'PORT':<8} {'URL'}")
+            print("-" * 80)
+            for rt in runtimes:
+                status = "ALIVE" if rt.get("alive") else "DEAD"
+                print(f"{rt['id']:<20} {status:<8} {rt.get('pid', '-'):<10} {rt.get('port', '-'):<8} {rt.get('url', '-')}")
+        return
+
+    if args.kill:
+        if kill_runtime(args.kill):
+            print(f"Killed runtime '{args.kill}'")
+        else:
+            print(f"Runtime '{args.kill}' not found or already dead")
+        return
+
+    if args.kill_all:
+        runtimes = list_runtimes()
+        if not runtimes:
+            print("No runtimes to kill")
+            return
+        killed = 0
+        for rt in runtimes:
+            if kill_runtime(rt["id"]):
+                print(f"Killed '{rt['id']}'")
+                killed += 1
+        print(f"\nKilled {killed} runtime(s)")
+        return
+
+    if args.info:
+        info = read_runtime_info(args.info)
+        if info:
+            info["alive"] = is_runtime_alive(args.info)
+            print(json.dumps(info, indent=2))
+        else:
+            print(f"Runtime '{args.info}' not found")
+        return
+
+    # Determine venv
+    venv = args.venv
+    if not venv:
+        # Auto-detect venv
+        if sys.prefix != sys.base_prefix:
+            venv = sys.prefix
+        else:
+            venv = os.environ.get("VIRTUAL_ENV", sys.prefix)
+
+    # Determine cwd
+    cwd = args.cwd or os.getcwd()
+
+    # Check if runtime already exists
+    existing = read_runtime_info(args.id)
+    if existing and is_runtime_alive(args.id):
+        print(f"Runtime '{args.id}' is already running:")
+        print(f"  URL:  {existing.get('url')}")
+        print(f"  PID:  {existing.get('pid')}")
+        print(f"  venv: {existing.get('venv')}")
+        print(f"\nTo kill it: mrmd-python --kill {args.id}")
+        return
+
+    if args.foreground:
+        # Run in foreground (blocking, for debugging)
+        print(f"Starting mrmd-python in foreground mode...")
+        print(f"  ID:   {args.id}")
+        print(f"  venv: {venv}")
+        print(f"  cwd:  {cwd}")
+        print(f"  port: {args.port or 'auto'}")
+        print(f"\nPress Ctrl+C to stop\n")
+        run_daemon(args.id, args.port, venv, cwd, args.assets_dir)
+    else:
+        # Spawn daemon (non-blocking)
+        print(f"Starting mrmd-python daemon...")
+        info = spawn_daemon(
+            runtime_id=args.id,
+            port=args.port,
+            venv=venv,
+            cwd=cwd,
+            assets_dir=args.assets_dir,
+        )
+        print(f"""
+Runtime '{info['id']}' started:
+  URL:  {info['url']}
+  PID:  {info['pid']}
+  venv: {info['venv']}
+  cwd:  {info['cwd']}
+
+Management:
+  mrmd-python --list          List all runtimes
+  mrmd-python --info {info['id']:<8} Get runtime info
+  mrmd-python --kill {info['id']:<8} Kill this runtime
+""")
+
+
+if __name__ == "__main__":
+    main()