pyreplab 0.1.0__tar.gz

pyreplab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zhimin Zou
+
+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.

pyreplab-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: pyreplab
+Version: 0.1.0
+Summary: Persistent Python REPL for LLM CLI tools
+Author: Zhimin Zou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/protostatis/pyreplab
+Project-URL: Repository, https://github.com/protostatis/pyreplab
+Keywords: repl,llm,cli,persistent,data-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Interpreters
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pyreplab
+
+Persistent Python REPL for LLM CLI tools.
+
+LLM coding CLIs (Claude Code, Copilot CLI, etc.) can't maintain a persistent Python session — each bash command runs in a fresh process. For large datasets, reloading on every query is impractical. pyreplab fixes this.
+
+## How it works
+
+A background Python process sits in memory with a persistent namespace. You write `.py` files with `#%%` cell blocks, then execute cells by reference. No ports, no sockets, no dependencies.
+
+## Quick start
+
+Write a `.py` file with `#%%` cell blocks — in your editor, or let an LLM write it:
+
+```python
+# analysis.py
+
+#%% Load
+import pandas as pd
+df = pd.read_csv("data.csv")
+print(df.shape)
+
+#%% Explore
+print(df.describe())
+
+#%% Top rows
+print(df.head(20))
+```
+
+Then run cells:
+
+```bash
+pyreplab start --workdir /path/to/project   # start (auto-detects .venv/)
+pyreplab run analysis.py:0                  # Load data
+pyreplab run analysis.py:1                  # Explore (df still loaded)
+pyreplab run analysis.py:2                  # Top rows (no reload)
+pyreplab stop
+```
+
+## CLI reference
+
+```
+pyreplab <command> [args]
+
+  start [opts]        Start the REPL (opts passed to pyreplab.py)
+  run file.py         Run all #%% cells in file
+  run file.py:N       Run cell N from file (0-indexed)
+  run 'code'          Run inline code
+  run                 Read code from stdin
+  stop                Stop the current session
+  stop-all            Stop all active sessions
+  ps                  List all active sessions with PID, uptime, memory
+  status              Check if REPL is running
+  clean               Remove session files
+```
+
+## Server options
+
+```
+python pyreplab.py [options]
+
+  --session-dir DIR    Session directory (default: /tmp/pyreplab)
+  --workdir DIR        Working directory for the REPL
+  --venv PATH          Path to virtualenv (auto-detects .venv/ in workdir)
+  --conda [ENV]        Activate conda env (default: base)
+  --no-conda           Disable conda auto-detection
+  --timeout SECS       Per-command timeout (default: 30)
+  --max-output CHARS   Hard cap on output size (default: 100000)
+  --max-rows N         Pandas display rows (default: 50)
+  --max-cols N         Pandas display columns (default: 20)
+  --poll-interval SECS Poll interval (default: 0.05)
+```
+
+## Environment detection
+
+pyreplab automatically detects and activates Python environments so your project packages are available. Detection follows a priority order — the first match wins:
+
+| Priority | Source | How it's found |
+|----------|--------|----------------|
+| 1 | `--venv PATH` | Explicit flag |
+| 2 | `.venv/` in workdir | Auto-detected |
+| 3 | `--conda [ENV]` | Explicit flag |
+| 4 | Conda base | Auto-detected fallback |
+
+If a project has a `.venv/`, that always takes precedence over conda. If no `.venv/` exists, pyreplab falls back to conda's base environment (giving you numpy, pandas, scipy, etc. out of the box). Use `--no-conda` to disable the fallback.
+
+### Virtual environments (venv, uv, virtualenv)
+
+```bash
+# Auto-detect .venv/ in workdir (most common)
+pyreplab start --workdir /path/to/project
+
+# Explicit path to any virtualenv
+pyreplab start --venv /path/to/.venv
+```
+
+Works with `uv venv`, `python -m venv`, or any standard virtualenv.
+
+### Conda environments
+
+```bash
+# Auto-detect: if no .venv/, conda base is used automatically
+pyreplab start --workdir /path/to/project
+
+# Explicit: force conda base
+pyreplab start --conda
+
+# Named conda env
+pyreplab start --conda myenv
+
+# Disable conda fallback (bare Python only)
+pyreplab start --no-conda
+```
+
+Conda base is found by checking, in order:
+1. `$CONDA_PREFIX` (set when a conda env is active)
+2. `$CONDA_EXE` (e.g. `~/miniconda3/bin/conda` → derives `~/miniconda3`)
+3. Common install paths: `~/miniconda3`, `~/anaconda3`, `~/miniforge3`, `~/mambaforge`, `/opt/conda`
+
+Named envs resolve to `<conda_base>/envs/<name>`.
+
+## Session isolation
+
+Each `--workdir` gets its own isolated session — separate process, namespace, and files. No clashing between projects.
+
+```bash
+# Two projects, two sessions
+pyreplab start --workdir ~/projects/project-a
+pyreplab start --workdir ~/projects/project-b
+
+# See what's running
+pyreplab ps
+# SESSION                      PID     UPTIME   MEM    DIR
+# project-a_a1b2c3d4           12345   5m30s    57MB   /tmp/pyreplab/project-a_a1b2c3d4
+# project-b_e5f6g7h8           12346   2m15s    43MB   /tmp/pyreplab/project-b_e5f6g7h8
+
+# Commands auto-resolve to the right session based on cwd
+cd ~/projects/project-a && pyreplab run analysis.py:0
+cd ~/projects/project-b && pyreplab run analysis.py:0
+
+# Stop everything
+pyreplab stop-all
+```
+
+## Display limits
+
+Output is automatically truncated for LLM-friendly sizes:
+
+| Library | Setting | Default |
+|---------|---------|---------|
+| pandas | max_rows | 50 |
+| pandas | max_columns | 20 |
+| pandas | max_colwidth | 80 chars |
+| numpy | threshold | 100 elements |
+
+Override with `--max-rows` and `--max-cols`. The `--max-output` flag is a hard character cap that truncates at line boundaries, keeping both head and tail.
+
+## Protocol
+
+**cmd.py** (client writes):
+```python
+#%% id: unique-id
+import pandas as pd
+df = pd.read_csv("big.csv")
+print(df.shape)
+```
+
+The first line is a `#%%` cell header with an optional command ID. The rest is plain Python — no escaping, no JSON encoding.
+
+**output.json** (pyreplab writes):
+```json
+{"stdout": "(1000, 5)\n", "stderr": "", "error": null, "id": "unique-id"}
+```
+
+Files are written atomically (write `.tmp`, then `os.rename`). The `id` field prevents reading stale output.
+
+## Install
+
+```bash
+git clone https://github.com/anthropics/pyreplab.git
+cd pyreplab
+```
+
+Make `pyreplab` available on your PATH (pick one):
+
+```bash
+# Option 1: symlink (recommended)
+ln -s "$(pwd)/pyreplab" /usr/local/bin/pyreplab
+
+# Option 2: add directory to PATH
+echo 'export PATH="'$(pwd)':$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Verify:
+
+```bash
+pyreplab start --workdir .
+pyreplab run 'print("hello")'
+pyreplab stop
+```
+
+### Using with Claude Code
+
+Append the agent instructions to Claude Code's system prompt:
+
+```bash
+claude --append-system-prompt-file /path/to/pyreplab/AGENT_PROMPT.md
+```
+
+Or add them to your project's `CLAUDE.md` so they're loaded automatically in every session.
+
+## Tests
+
+```bash
+bash test_pyreplab.sh    # 14 tests: basic execution, persistence, errors, display limits, cells, stdin
+bash test_agent.sh     # 10-step agent walkthrough: loads data, analyzes, reaches a conclusion
+```
+
+## Requirements
+
+Python 3.9+. Zero dependencies — stdlib only.

pyreplab-0.1.0/README.md

@@ -0,0 +1,222 @@
+# pyreplab
+
+Persistent Python REPL for LLM CLI tools.
+
+LLM coding CLIs (Claude Code, Copilot CLI, etc.) can't maintain a persistent Python session — each bash command runs in a fresh process. For large datasets, reloading on every query is impractical. pyreplab fixes this.
+
+## How it works
+
+A background Python process sits in memory with a persistent namespace. You write `.py` files with `#%%` cell blocks, then execute cells by reference. No ports, no sockets, no dependencies.
+
+## Quick start
+
+Write a `.py` file with `#%%` cell blocks — in your editor, or let an LLM write it:
+
+```python
+# analysis.py
+
+#%% Load
+import pandas as pd
+df = pd.read_csv("data.csv")
+print(df.shape)
+
+#%% Explore
+print(df.describe())
+
+#%% Top rows
+print(df.head(20))
+```
+
+Then run cells:
+
+```bash
+pyreplab start --workdir /path/to/project   # start (auto-detects .venv/)
+pyreplab run analysis.py:0                  # Load data
+pyreplab run analysis.py:1                  # Explore (df still loaded)
+pyreplab run analysis.py:2                  # Top rows (no reload)
+pyreplab stop
+```
+
+## CLI reference
+
+```
+pyreplab <command> [args]
+
+  start [opts]        Start the REPL (opts passed to pyreplab.py)
+  run file.py         Run all #%% cells in file
+  run file.py:N       Run cell N from file (0-indexed)
+  run 'code'          Run inline code
+  run                 Read code from stdin
+  stop                Stop the current session
+  stop-all            Stop all active sessions
+  ps                  List all active sessions with PID, uptime, memory
+  status              Check if REPL is running
+  clean               Remove session files
+```
+
+## Server options
+
+```
+python pyreplab.py [options]
+
+  --session-dir DIR    Session directory (default: /tmp/pyreplab)
+  --workdir DIR        Working directory for the REPL
+  --venv PATH          Path to virtualenv (auto-detects .venv/ in workdir)
+  --conda [ENV]        Activate conda env (default: base)
+  --no-conda           Disable conda auto-detection
+  --timeout SECS       Per-command timeout (default: 30)
+  --max-output CHARS   Hard cap on output size (default: 100000)
+  --max-rows N         Pandas display rows (default: 50)
+  --max-cols N         Pandas display columns (default: 20)
+  --poll-interval SECS Poll interval (default: 0.05)
+```
+
+## Environment detection
+
+pyreplab automatically detects and activates Python environments so your project packages are available. Detection follows a priority order — the first match wins:
+
+| Priority | Source | How it's found |
+|----------|--------|----------------|
+| 1 | `--venv PATH` | Explicit flag |
+| 2 | `.venv/` in workdir | Auto-detected |
+| 3 | `--conda [ENV]` | Explicit flag |
+| 4 | Conda base | Auto-detected fallback |
+
+If a project has a `.venv/`, that always takes precedence over conda. If no `.venv/` exists, pyreplab falls back to conda's base environment (giving you numpy, pandas, scipy, etc. out of the box). Use `--no-conda` to disable the fallback.
+
+### Virtual environments (venv, uv, virtualenv)
+
+```bash
+# Auto-detect .venv/ in workdir (most common)
+pyreplab start --workdir /path/to/project
+
+# Explicit path to any virtualenv
+pyreplab start --venv /path/to/.venv
+```
+
+Works with `uv venv`, `python -m venv`, or any standard virtualenv.
+
+### Conda environments
+
+```bash
+# Auto-detect: if no .venv/, conda base is used automatically
+pyreplab start --workdir /path/to/project
+
+# Explicit: force conda base
+pyreplab start --conda
+
+# Named conda env
+pyreplab start --conda myenv
+
+# Disable conda fallback (bare Python only)
+pyreplab start --no-conda
+```
+
+Conda base is found by checking, in order:
+1. `$CONDA_PREFIX` (set when a conda env is active)
+2. `$CONDA_EXE` (e.g. `~/miniconda3/bin/conda` → derives `~/miniconda3`)
+3. Common install paths: `~/miniconda3`, `~/anaconda3`, `~/miniforge3`, `~/mambaforge`, `/opt/conda`
+
+Named envs resolve to `<conda_base>/envs/<name>`.
+
+## Session isolation
+
+Each `--workdir` gets its own isolated session — separate process, namespace, and files. No clashing between projects.
+
+```bash
+# Two projects, two sessions
+pyreplab start --workdir ~/projects/project-a
+pyreplab start --workdir ~/projects/project-b
+
+# See what's running
+pyreplab ps
+# SESSION                      PID     UPTIME   MEM    DIR
+# project-a_a1b2c3d4           12345   5m30s    57MB   /tmp/pyreplab/project-a_a1b2c3d4
+# project-b_e5f6g7h8           12346   2m15s    43MB   /tmp/pyreplab/project-b_e5f6g7h8
+
+# Commands auto-resolve to the right session based on cwd
+cd ~/projects/project-a && pyreplab run analysis.py:0
+cd ~/projects/project-b && pyreplab run analysis.py:0
+
+# Stop everything
+pyreplab stop-all
+```
+
+## Display limits
+
+Output is automatically truncated for LLM-friendly sizes:
+
+| Library | Setting | Default |
+|---------|---------|---------|
+| pandas | max_rows | 50 |
+| pandas | max_columns | 20 |
+| pandas | max_colwidth | 80 chars |
+| numpy | threshold | 100 elements |
+
+Override with `--max-rows` and `--max-cols`. The `--max-output` flag is a hard character cap that truncates at line boundaries, keeping both head and tail.
+
+## Protocol
+
+**cmd.py** (client writes):
+```python
+#%% id: unique-id
+import pandas as pd
+df = pd.read_csv("big.csv")
+print(df.shape)
+```
+
+The first line is a `#%%` cell header with an optional command ID. The rest is plain Python — no escaping, no JSON encoding.
+
+**output.json** (pyreplab writes):
+```json
+{"stdout": "(1000, 5)\n", "stderr": "", "error": null, "id": "unique-id"}
+```
+
+Files are written atomically (write `.tmp`, then `os.rename`). The `id` field prevents reading stale output.
+
+## Install
+
+```bash
+git clone https://github.com/anthropics/pyreplab.git
+cd pyreplab
+```
+
+Make `pyreplab` available on your PATH (pick one):
+
+```bash
+# Option 1: symlink (recommended)
+ln -s "$(pwd)/pyreplab" /usr/local/bin/pyreplab
+
+# Option 2: add directory to PATH
+echo 'export PATH="'$(pwd)':$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Verify:
+
+```bash
+pyreplab start --workdir .
+pyreplab run 'print("hello")'
+pyreplab stop
+```
+
+### Using with Claude Code
+
+Append the agent instructions to Claude Code's system prompt:
+
+```bash
+claude --append-system-prompt-file /path/to/pyreplab/AGENT_PROMPT.md
+```
+
+Or add them to your project's `CLAUDE.md` so they're loaded automatically in every session.
+
+## Tests
+
+```bash
+bash test_pyreplab.sh    # 14 tests: basic execution, persistence, errors, display limits, cells, stdin
+bash test_agent.sh     # 10-step agent walkthrough: loads data, analyzes, reaches a conclusion
+```
+
+## Requirements
+
+Python 3.9+. Zero dependencies — stdlib only.

pyreplab-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "pyreplab"
+version = "0.1.0"
+description = "Persistent Python REPL for LLM CLI tools"
+requires-python = ">=3.9"
+dependencies = []
+license = "MIT"
+readme = "README.md"
+authors = [{name = "Zhimin Zou"}]
+keywords = ["repl", "llm", "cli", "persistent", "data-analysis"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Interpreters",
+]
+
+[project.urls]
+Homepage = "https://github.com/protostatis/pyreplab"
+Repository = "https://github.com/protostatis/pyreplab"
+
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["pyreplab"]
+script-files = ["pyreplab"]