llmess 0.1.0__tar.gz

llmess-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+
+      - name: Install build dependencies
+        run: python3 -m pip install build --user
+
+      - name: Build package
+        run: python3 -m build
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/llmess
+    permissions:
+      id-token: write  # Required for OIDC trusted publishing
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

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

@@ -0,0 +1,50 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest
+          pip install -e .
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff
+        run: ruff check src/ tests/

llmess-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editor files
+*.swp
+*.swo
+*~
+.idea/
+.vscode/
+
+# OS files
+.DS_Store
+Thumbs.db

llmess-0.1.0/LICENSE

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

llmess-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: llmess
+Version: 0.1.0
+Summary: A less pager that uses LLMs to hallucinate infinite file continuations
+Project-URL: Homepage, https://github.com/tgies/llmess
+Project-URL: Repository, https://github.com/tgies/llmess
+Author: tgies
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,humor,less,llm,pager
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# llmess
+
+Some files end too early. Some files don't contain what you're looking for.
+
+`llmess` is a `less` pager that addresses both issues:
+
+- When you scroll past the end of a file, an LLM generates more content.
+- When you search for a term that doesn't exist, the LLM generates content containing it.
+
+Works with any model supported by the [`llm`](https://llm.datasette.io/) CLI.
+
+## Installation
+
+### Prerequisites
+
+You need the [`llm`](https://llm.datasette.io/) CLI tool installed and configured:
+
+```bash
+# Install llm
+pipx install llm
+
+# Install plugins for your preferred provider
+llm install llm-openrouter  # or llm-claude, llm-ollama, etc.
+
+# Configure API keys and default model
+llm keys set openrouter
+llm models default openrouter/meta-llama/llama-3.1-405b
+```
+
+### Install llmess
+
+```bash
+pipx install llmess
+```
+
+Or with pip:
+
+```bash
+pip install llmess
+```
+
+> **Note**: llmess calls `llm` via subprocess, so it uses whatever `llm` is on your PATH. Your plugins and configuration are preserved.
+
+## Usage
+
+```bash
+llmess myfile.txt                    # View a file
+llmess -m gpt-4o myfile.txt          # Use a specific model
+llmess -B myfile.txt                 # Base mode: no system prompt
+cat file.txt | llmess                # Read from stdin
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-m`, `--model` | LLM model to use (default: your `llm` default) |
+| `-s`, `--system` | System prompt (default: instruct prompt) |
+| `-B`, `--base` | Base model mode: no system prompt |
+| `-S`, `--stealth` | Mimic `less` appearance exactly-ish probably |
+| `-T`, `--max-tokens N` | Max tokens to generate per LLM call |
+| `-C`, `--context CHARS` | Characters of context to send to LLM (default: 2000) |
+| `-o`, `--option KEY VALUE` | Model option to pass to llm (can be repeated) |
+| `-P`, `--prefetch [N]` | Prefetch N screens ahead in background (off by default; 2 if flag given without N) |
+| `--real-lines N` | Show first N real lines, then generate continuations |
+| `--real-screen` | Show first screenful of real content, then generate |
+| `--install-prank` | Output shell function to wrap `less` with llmess |
+| `-V`, `--version` | Show version |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LLMESS` | Default CLI flags (like `LESS` for less) |
+| `LLMESS_MODEL` | Default model |
+| `LLMESS_OPTIONS` | Default model options (comma-separated `key=value` pairs) |
+
+```bash
+# In ~/.bashrc or ~/.zshrc
+export LLMESS="-S -P"          # stealth + prefetch by default
+export LLMESS_MODEL="openrouter/meta-llama/llama-3.1-405b"
+```
+
+Priority: CLI flags > `LLMESS` > `LLMESS_MODEL`/`LLMESS_OPTIONS` > built-in defaults.
+
+## Controls
+
+| Key | Action |
+|-----|--------|
+| ↑ / k | Scroll up one line |
+| ↓ / j | Scroll down one line |
+| Page Up / b | Scroll up one page |
+| Page Down / f / Space | Scroll down one page |
+| g | Go to top |
+| G | Go to bottom |
+| / | Search forward |
+| n | Next match |
+| N | Previous match |
+| Esc | Clear search |
+| s | Save to file |
+| q | Quit |
+
+When you reach the bottom, scrolling down triggers LLM generation.
+
+## Search
+
+Press `/` to search. Matches are highlighted.
+
+If the term isn't found, llmess generates content containing it:
+
+```bash
+echo "Hello world" | llmess
+# Press /password<Enter>
+# → Generates content containing "password", jumps to match
+```
+
+This requires a system prompt (the default). With `-B` (base mode), search behaves normally.
+
+## Base Models vs. Instruct Models
+
+By default, llmess sends a system prompt instructing the model to continue text without commentary. This works well with instruct models and is ignored by base models.
+
+**Base models** continue text naturally. Use `-B` to skip the system prompt:
+
+```bash
+llmess -B -m openrouter/meta-llama/llama-3.1-405b myfile.txt
+```
+
+Search-triggered generation is not available with base models since they don't follow instructions.
+
+**Instruct models** work out of the box. Use `-s "custom prompt"` to override the default:
+
+```bash
+llmess -s "Continue this text exactly. No commentary." myfile.txt
+```
+
+Any model supported by `llm` works, including local models via Ollama.
+
+## Modes
+
+### Stealth Mode
+
+With `-S`, llmess mimics the appearance of `less`:
+- Status bar shows `filename lines 1-24 50%` format
+- No `[GENERATING...]` indicator
+- Shows `(END)` at bottom
+
+### Prefetch Mode
+
+With `-P`, llmess generates content ahead of where you're reading:
+
+```bash
+llmess -P file.txt       # Prefetch 2 screens ahead
+llmess -P 5 file.txt     # Prefetch 5 screens ahead
+```
+
+### Real-Then-Fake Mode
+
+Show real file content first, then generate continuations:
+
+```bash
+llmess --real-lines 50 ~/.bashrc    # First 50 lines are real
+llmess --real-screen config.yaml    # First screenful is real
+```
+
+## Prank Installation
+
+```bash
+llmess --install-prank
+```
+
+Outputs a shell function that wraps `less` with llmess. Add it to the target's shell config.
+
+The wrapper uses stealth mode, shows real content first, prefetches in background, and falls back to real `less` for piped output.
+
+## License
+
+MIT

llmess-0.1.0/README.md

@@ -0,0 +1,178 @@
+# llmess
+
+Some files end too early. Some files don't contain what you're looking for.
+
+`llmess` is a `less` pager that addresses both issues:
+
+- When you scroll past the end of a file, an LLM generates more content.
+- When you search for a term that doesn't exist, the LLM generates content containing it.
+
+Works with any model supported by the [`llm`](https://llm.datasette.io/) CLI.
+
+## Installation
+
+### Prerequisites
+
+You need the [`llm`](https://llm.datasette.io/) CLI tool installed and configured:
+
+```bash
+# Install llm
+pipx install llm
+
+# Install plugins for your preferred provider
+llm install llm-openrouter  # or llm-claude, llm-ollama, etc.
+
+# Configure API keys and default model
+llm keys set openrouter
+llm models default openrouter/meta-llama/llama-3.1-405b
+```
+
+### Install llmess
+
+```bash
+pipx install llmess
+```
+
+Or with pip:
+
+```bash
+pip install llmess
+```
+
+> **Note**: llmess calls `llm` via subprocess, so it uses whatever `llm` is on your PATH. Your plugins and configuration are preserved.
+
+## Usage
+
+```bash
+llmess myfile.txt                    # View a file
+llmess -m gpt-4o myfile.txt          # Use a specific model
+llmess -B myfile.txt                 # Base mode: no system prompt
+cat file.txt | llmess                # Read from stdin
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-m`, `--model` | LLM model to use (default: your `llm` default) |
+| `-s`, `--system` | System prompt (default: instruct prompt) |
+| `-B`, `--base` | Base model mode: no system prompt |
+| `-S`, `--stealth` | Mimic `less` appearance exactly-ish probably |
+| `-T`, `--max-tokens N` | Max tokens to generate per LLM call |
+| `-C`, `--context CHARS` | Characters of context to send to LLM (default: 2000) |
+| `-o`, `--option KEY VALUE` | Model option to pass to llm (can be repeated) |
+| `-P`, `--prefetch [N]` | Prefetch N screens ahead in background (off by default; 2 if flag given without N) |
+| `--real-lines N` | Show first N real lines, then generate continuations |
+| `--real-screen` | Show first screenful of real content, then generate |
+| `--install-prank` | Output shell function to wrap `less` with llmess |
+| `-V`, `--version` | Show version |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LLMESS` | Default CLI flags (like `LESS` for less) |
+| `LLMESS_MODEL` | Default model |
+| `LLMESS_OPTIONS` | Default model options (comma-separated `key=value` pairs) |
+
+```bash
+# In ~/.bashrc or ~/.zshrc
+export LLMESS="-S -P"          # stealth + prefetch by default
+export LLMESS_MODEL="openrouter/meta-llama/llama-3.1-405b"
+```
+
+Priority: CLI flags > `LLMESS` > `LLMESS_MODEL`/`LLMESS_OPTIONS` > built-in defaults.
+
+## Controls
+
+| Key | Action |
+|-----|--------|
+| ↑ / k | Scroll up one line |
+| ↓ / j | Scroll down one line |
+| Page Up / b | Scroll up one page |
+| Page Down / f / Space | Scroll down one page |
+| g | Go to top |
+| G | Go to bottom |
+| / | Search forward |
+| n | Next match |
+| N | Previous match |
+| Esc | Clear search |
+| s | Save to file |
+| q | Quit |
+
+When you reach the bottom, scrolling down triggers LLM generation.
+
+## Search
+
+Press `/` to search. Matches are highlighted.
+
+If the term isn't found, llmess generates content containing it:
+
+```bash
+echo "Hello world" | llmess
+# Press /password<Enter>
+# → Generates content containing "password", jumps to match
+```
+
+This requires a system prompt (the default). With `-B` (base mode), search behaves normally.
+
+## Base Models vs. Instruct Models
+
+By default, llmess sends a system prompt instructing the model to continue text without commentary. This works well with instruct models and is ignored by base models.
+
+**Base models** continue text naturally. Use `-B` to skip the system prompt:
+
+```bash
+llmess -B -m openrouter/meta-llama/llama-3.1-405b myfile.txt
+```
+
+Search-triggered generation is not available with base models since they don't follow instructions.
+
+**Instruct models** work out of the box. Use `-s "custom prompt"` to override the default:
+
+```bash
+llmess -s "Continue this text exactly. No commentary." myfile.txt
+```
+
+Any model supported by `llm` works, including local models via Ollama.
+
+## Modes
+
+### Stealth Mode
+
+With `-S`, llmess mimics the appearance of `less`:
+- Status bar shows `filename lines 1-24 50%` format
+- No `[GENERATING...]` indicator
+- Shows `(END)` at bottom
+
+### Prefetch Mode
+
+With `-P`, llmess generates content ahead of where you're reading:
+
+```bash
+llmess -P file.txt       # Prefetch 2 screens ahead
+llmess -P 5 file.txt     # Prefetch 5 screens ahead
+```
+
+### Real-Then-Fake Mode
+
+Show real file content first, then generate continuations:
+
+```bash
+llmess --real-lines 50 ~/.bashrc    # First 50 lines are real
+llmess --real-screen config.yaml    # First screenful is real
+```
+
+## Prank Installation
+
+```bash
+llmess --install-prank
+```
+
+Outputs a shell function that wraps `less` with llmess. Add it to the target's shell config.
+
+The wrapper uses stealth mode, shows real content first, prefetches in background, and falls back to real `less` for piped output.
+
+## License
+
+MIT

llmess-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "llmess"
+version = "0.1.0"
+description = "A less pager that uses LLMs to hallucinate infinite file continuations"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+    { name = "tgies" }
+]
+keywords = ["llm", "pager", "less", "cli", "humor"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Console :: Curses",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing",
+    "Topic :: Games/Entertainment",
+]
+dependencies = [
+    # Note: llm is NOT listed here intentionally.
+    # llmess calls llm via subprocess and expects users to have it
+    # installed at user level (pipx, etc.) with their plugins configured.
+    # Bundling llm would shadow the user's configured installation.
+]
+
+[project.scripts]
+llmess = "llmess.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/tgies/llmess"
+Repository = "https://github.com/tgies/llmess"
+
+[tool.ruff]
+target-version = "py38"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+]

llmess-0.1.0/src/llmess/__init__.py

@@ -0,0 +1,3 @@
+"""llmess - A less pager that uses LLMs to hallucinate infinite file continuations."""
+
+__version__ = "0.1.0"

llmess-0.1.0/src/llmess/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m llmess."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()