promptpump 0.1.0__tar.gz

promptpump-0.1.0/LICENSE

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

promptpump-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: promptpump
+Version: 0.1.0
+Summary: Deterministic context-engineering engine and prompt compiler powered by a local Ollama model.
+Author: Ritesh Nipane
+License: MIT
+Project-URL: Homepage, https://github.com/RiteshNipane/PromptPump
+Project-URL: Issues, https://github.com/RiteshNipane/PromptPump/issues
+Keywords: prompt-engineering,ollama,llm,cli,context-engineering
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: requests>=2.31
+Requires-Dist: pyperclip>=1.8
+Requires-Dist: pathspec>=0.11
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# PromptPump
+
+A local CLI tool and Python library that turns a short shorthand prompt into a
+high-density, production-ready **master prompt**. It scans your project (file tree,
+README/config snippets, Python AST outlines), merges that with a strict structural
+schema, and compiles it with a local model (Ollama + Qwen2.5-Coder). Nothing leaves
+your machine.
+
+## Install
+
+Requires Python 3.10+ and [Ollama](https://ollama.com) (Windows, macOS, Linux).
+
+```bash
+ollama pull qwen2.5-coder:7b          # or qwen2.5-coder:14b for better quality
+pip install pipx && pipx ensurepath   # once; then reopen your terminal
+pipx install promptpump               # works in PowerShell, cmd, bash, zsh
+promptpump doctor                     # verify Ollama + model
+```
+
+Plain `pip install promptpump` also works. On Linux, clipboard support needs `xclip` or `xsel`.
+
+Develop from source: `pip install -e ".[dev]"`.
+
+## Usage
+
+```bash
+promptpump doctor                                   # verify Ollama + model
+promptpump stacks                                   # list stack profiles
+promptpump run "add jwt auth to the api" --stack fastapi --copy
+promptpump run "add a pause menu" --stack pygame --stack python --path ../mygame
+promptpump run "refactor db layer" --dry-run        # inspect the payload, no model call
+promptpump run "add caching" --no-copy > prompt.md  # progress goes to stderr, prompt to stdout
+```
+
+| Option | Description |
+| --- | --- |
+| `--stack/-s` | Inject stack rules (repeatable): python, fastapi, django, react, nextjs, node, pygame, pytorch |
+| `--copy/--no-copy` | Copy to clipboard (default: on) |
+| `--path/-p` | Project directory to scan (default: `.`) |
+| `--model/-m` | Ollama model (env `PROMPTPUMP_MODEL`) |
+| `--host` | Ollama URL (env `PROMPTPUMP_HOST`) |
+| `--max-context-tokens` | Workspace context budget (default 3000) |
+| `--ground/--no-ground` | Replace the model's `<codebase_context>` with deterministic scan facts (default: on) |
+| `--dry-run` | Print the system/user payload and exit |
+
+## Library use
+
+```python
+from promptpump import OllamaClient, PromptCompiler, scan_workspace
+
+ctx = scan_workspace(".")
+result = PromptCompiler(OllamaClient()).compile("add rate limiting", ctx, ["fastapi"])
+print(result.prompt)
+```
+
+## How it stays deterministic
+
+- Fixed system prompt and stack rules (`templates.py`); temperature 0.2 and fixed seed.
+- Output validated against the seven required tags, with one automatic repair retry.
+- Conversational filler and code fences stripped; `<codebase_context>` overwritten with real scan data so the model cannot hallucinate files.
+- Secrets (`.env`, keys), binaries, and `.gitignore`d paths are never read.
+
+## Tests
+
+```bash
+pytest
+```
+
+## Limitations
+
+Only the root `.gitignore` is parsed; nested ignore files are not.

promptpump-0.1.0/README.md

@@ -0,0 +1,71 @@
+# PromptPump
+
+A local CLI tool and Python library that turns a short shorthand prompt into a
+high-density, production-ready **master prompt**. It scans your project (file tree,
+README/config snippets, Python AST outlines), merges that with a strict structural
+schema, and compiles it with a local model (Ollama + Qwen2.5-Coder). Nothing leaves
+your machine.
+
+## Install
+
+Requires Python 3.10+ and [Ollama](https://ollama.com) (Windows, macOS, Linux).
+
+```bash
+ollama pull qwen2.5-coder:7b          # or qwen2.5-coder:14b for better quality
+pip install pipx && pipx ensurepath   # once; then reopen your terminal
+pipx install promptpump               # works in PowerShell, cmd, bash, zsh
+promptpump doctor                     # verify Ollama + model
+```
+
+Plain `pip install promptpump` also works. On Linux, clipboard support needs `xclip` or `xsel`.
+
+Develop from source: `pip install -e ".[dev]"`.
+
+## Usage
+
+```bash
+promptpump doctor                                   # verify Ollama + model
+promptpump stacks                                   # list stack profiles
+promptpump run "add jwt auth to the api" --stack fastapi --copy
+promptpump run "add a pause menu" --stack pygame --stack python --path ../mygame
+promptpump run "refactor db layer" --dry-run        # inspect the payload, no model call
+promptpump run "add caching" --no-copy > prompt.md  # progress goes to stderr, prompt to stdout
+```
+
+| Option | Description |
+| --- | --- |
+| `--stack/-s` | Inject stack rules (repeatable): python, fastapi, django, react, nextjs, node, pygame, pytorch |
+| `--copy/--no-copy` | Copy to clipboard (default: on) |
+| `--path/-p` | Project directory to scan (default: `.`) |
+| `--model/-m` | Ollama model (env `PROMPTPUMP_MODEL`) |
+| `--host` | Ollama URL (env `PROMPTPUMP_HOST`) |
+| `--max-context-tokens` | Workspace context budget (default 3000) |
+| `--ground/--no-ground` | Replace the model's `<codebase_context>` with deterministic scan facts (default: on) |
+| `--dry-run` | Print the system/user payload and exit |
+
+## Library use
+
+```python
+from promptpump import OllamaClient, PromptCompiler, scan_workspace
+
+ctx = scan_workspace(".")
+result = PromptCompiler(OllamaClient()).compile("add rate limiting", ctx, ["fastapi"])
+print(result.prompt)
+```
+
+## How it stays deterministic
+
+- Fixed system prompt and stack rules (`templates.py`); temperature 0.2 and fixed seed.
+- Output validated against the seven required tags, with one automatic repair retry.
+- Conversational filler and code fences stripped; `<codebase_context>` overwritten with real scan data so the model cannot hallucinate files.
+- Secrets (`.env`, keys), binaries, and `.gitignore`d paths are never read.
+
+## Tests
+
+```bash
+pytest
+```
+
+## Limitations
+
+Only the root `.gitignore` is parsed; nested ignore files are not.

promptpump-0.1.0/promptpump/__init__.py

@@ -0,0 +1,16 @@
+"""PromptPump: compile shorthand prompts into dense, structured master prompts."""
+
+from .context import WorkspaceContext, scan_workspace
+from .engine import CompileResult, OllamaClient, PromptCompiler, PromptPumpError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CompileResult",
+    "OllamaClient",
+    "PromptCompiler",
+    "PromptPumpError",
+    "WorkspaceContext",
+    "scan_workspace",
+    "__version__",
+]

promptpump-0.1.0/promptpump/cli.py

@@ -0,0 +1,188 @@
+"""Typer CLI entry point: ``promptpump run "shorthand" --stack python --copy``."""
+
+import sys
+import time
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from . import __version__
+from .context import scan_workspace
+from .engine import (
+    DEFAULT_HOST,
+    DEFAULT_MODEL,
+    OllamaClient,
+    PromptCompiler,
+    PromptPumpError,
+)
+from .templates import UnknownStackError, get_stack, list_stacks
+
+app = typer.Typer(
+    name="promptpump",
+    help="Compile a short shorthand prompt into a dense, production-ready master prompt "
+    "using local codebase context and a local Ollama model.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+# Progress and diagnostics go to stderr so stdout stays clean for piping the prompt.
+err = Console(stderr=True)
+
+
+def copy_to_clipboard(text: str) -> bool:
+    """Copy ``text`` to the system clipboard; return False if unavailable."""
+    try:
+        import pyperclip
+
+        pyperclip.copy(text)
+        return True
+    except Exception:  # pyperclip raises PyperclipException when no backend exists
+        return False
+
+
+def _force_utf8() -> None:
+    """Avoid UnicodeEncodeError on Windows when output is redirected (cp1252 default)."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8", errors="replace")
+            except (OSError, ValueError):
+                pass
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"promptpump {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        Optional[bool],
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version."),
+    ] = None,
+) -> None:
+    """PromptPump: deterministic context engineering for coding prompts."""
+    _force_utf8()
+
+
+@app.command()
+def run(
+    prompt: Annotated[str, typer.Argument(help="Shorthand prompt, e.g. 'add jwt auth'.")],
+    stack: Annotated[
+        Optional[list[str]],
+        typer.Option("--stack", "-s", help="Stack rules to inject (repeatable). See `stacks`."),
+    ] = None,
+    copy: Annotated[
+        bool, typer.Option("--copy/--no-copy", help="Copy the result to the clipboard.")
+    ] = True,
+    path: Annotated[
+        Path,
+        typer.Option("--path", "-p", exists=True, file_okay=False, resolve_path=True,
+                     help="Project directory to scan."),
+    ] = Path("."),
+    model: Annotated[
+        str, typer.Option("--model", "-m", envvar="PROMPTPUMP_MODEL", help="Ollama model name.")
+    ] = DEFAULT_MODEL,
+    host: Annotated[
+        str, typer.Option("--host", envvar="PROMPTPUMP_HOST", help="Ollama base URL.")
+    ] = DEFAULT_HOST,
+    max_context_tokens: Annotated[
+        int, typer.Option("--max-context-tokens", min=500, help="Workspace context budget.")
+    ] = 3000,
+    ground: Annotated[
+        bool,
+        typer.Option("--ground/--no-ground",
+                     help="Overwrite <codebase_context> with deterministic scan facts."),
+    ] = True,
+    timeout: Annotated[float, typer.Option(help="Seconds to wait for the model.")] = 300.0,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Print the payload; do not call the model.")
+    ] = False,
+) -> None:
+    """Compile PROMPT into a structured master prompt."""
+    try:
+        profiles = [get_stack(s) for s in stack or []]
+    except UnknownStackError as exc:
+        err.print(f"[red]error:[/red] {escape(str(exc))}")
+        raise typer.Exit(2) from exc
+
+    with err.status("Scanning workspace..."):
+        context = scan_workspace(path, max_tokens=max_context_tokens)
+    err.print(
+        f"[dim]Scanned {context.root.name}/: {len(context.tree_lines)} tree entries, "
+        f"{len(context.key_files)} key files, {len(context.outlines)} outlined modules[/dim]"
+    )
+
+    compiler = PromptCompiler(
+        OllamaClient(host=host, model=model, timeout=timeout), ground_context=ground
+    )
+    stack_names = [p.name for p in profiles]
+
+    if dry_run:
+        for message in compiler.build_messages(prompt, context, stack_names):
+            typer.echo(f"===== {message['role'].upper()} =====\n{message['content']}\n")
+        raise typer.Exit()
+
+    start = time.perf_counter()
+    try:
+        with err.status(f"Compiling with {escape(model)} (local)..."):
+            result = compiler.compile(prompt, context, stack_names)
+    except PromptPumpError as exc:
+        err.print(f"[red]error:[/red] {escape(str(exc))}")
+        raise typer.Exit(1) from exc
+    elapsed = time.perf_counter() - start
+
+    if result.missing_tags:
+        err.print(
+            f"[yellow]warning:[/yellow] model output is missing tags: "
+            f"{', '.join(result.missing_tags)}. Try a larger model or rephrase."
+        )
+    err.print(f"[green]Compiled[/green] in {elapsed:.1f}s ({result.attempts} attempt(s))")
+
+    typer.echo(result.prompt)
+
+    if copy:
+        if copy_to_clipboard(result.prompt):
+            err.print("[green]Copied to clipboard.[/green]")
+        else:
+            err.print("[yellow]Clipboard unavailable (install xclip/xsel on Linux).[/yellow]")
+
+
+@app.command()
+def stacks() -> None:
+    """List available --stack profiles."""
+    table = Table("Name", "Label", "Rules")
+    for profile in list_stacks():
+        table.add_row(profile.name, profile.label, str(len(profile.rules)))
+    Console().print(table)
+
+
+@app.command()
+def doctor(
+    model: Annotated[str, typer.Option("--model", "-m", envvar="PROMPTPUMP_MODEL")] = DEFAULT_MODEL,
+    host: Annotated[str, typer.Option("--host", envvar="PROMPTPUMP_HOST")] = DEFAULT_HOST,
+) -> None:
+    """Check that Ollama is reachable and the model is installed."""
+    client = OllamaClient(host=host, model=model)
+    try:
+        installed = client.list_models()
+    except PromptPumpError as exc:
+        err.print(f"[red]x[/red] {escape(str(exc))} Start it with `ollama serve`.")
+        raise typer.Exit(1) from exc
+    err.print(f"[green]ok[/green] Ollama reachable at {host}")
+    if any(name == model or name.split(":")[0] == model for name in installed):
+        err.print(f"[green]ok[/green] Model '{model}' is installed")
+    else:
+        err.print(f"[red]x[/red] Model '{model}' missing. Run: ollama pull {model}")
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()