promptpump 0.1.0__py3-none-any.whl

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/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()

promptpump/context.py

@@ -0,0 +1,322 @@
+"""Local workspace scanner: file tree, key files, and Python AST outlines.
+
+The scanner is deliberately conservative: it never follows symlinks, skips heavy
+directories and secret files, honours the root ``.gitignore``, and keeps the total
+output under a token budget so it fits a small local model's context window.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+import pathspec
+
+# Heavy / generated directories that are never worth scanning.
+DEFAULT_IGNORE_DIRS: frozenset[str] = frozenset(
+    {
+        ".git", ".hg", ".svn", "node_modules", "venv", ".venv", "env", "__pycache__",
+        ".mypy_cache", ".pytest_cache", ".ruff_cache", ".tox", ".idea", ".vscode",
+        "dist", "build", ".next", ".nuxt", "target", "coverage", ".eggs", ".cache",
+        "site-packages",
+    }
+)
+
+# Non-text files that would only waste tokens.
+BINARY_SUFFIXES: frozenset[str] = frozenset(
+    {
+        ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".svg", ".pdf", ".zip", ".tar",
+        ".gz", ".7z", ".rar", ".exe", ".dll", ".so", ".dylib", ".pyc", ".pyo", ".class",
+        ".jar", ".bin", ".woff", ".woff2", ".ttf", ".mp3", ".mp4", ".mov", ".sqlite",
+        ".db", ".lock", ".pt", ".pth", ".onnx", ".parquet", ".npy", ".npz",
+    }
+)
+
+SECRET_SUFFIXES: frozenset[str] = frozenset({".pem", ".key", ".p12", ".pfx"})
+ENV_TEMPLATE_NAMES: frozenset[str] = frozenset({".env.example", ".env.sample", ".env.template"})
+
+# Priority-ordered file names treated as "key files" (first match wins the budget).
+KEY_FILE_NAMES: tuple[str, ...] = (
+    "README.md", "README.rst", "README.txt", "README",
+    "pyproject.toml", "package.json", "requirements.txt", "setup.py", "setup.cfg", "Pipfile",
+    "tsconfig.json", "vite.config.ts", "vite.config.js", "next.config.js",
+    "Dockerfile", "docker-compose.yml", "Makefile", ".env.example",
+    "main.py", "app.py", "manage.py", "__main__.py", "cli.py",
+    "index.js", "index.ts", "server.js", "main.tsx", "App.tsx", "App.jsx",
+)
+
+MAX_FILE_BYTES = 1_000_000
+MAX_OUTLINE_FILES = 15
+MAX_OUTLINE_LINES_PER_FILE = 40
+
+
+def estimate_tokens(text: str) -> int:
+    """Cheap token estimate (~4 characters per token); good enough for budgeting."""
+    return max(1, len(text) // 4) if text else 0
+
+
+@dataclass(frozen=True)
+class KeyFile:
+    """A key project file and its (possibly truncated) content."""
+
+    path: str
+    content: str
+    truncated: bool = False
+
+
+@dataclass
+class WorkspaceContext:
+    """Snapshot of the local workspace handed to the compiler."""
+
+    root: Path
+    tree_lines: list[str] = field(default_factory=list)
+    key_files: list[KeyFile] = field(default_factory=list)
+    outlines: dict[str, list[str]] = field(default_factory=dict)
+
+    @property
+    def tree(self) -> str:
+        """The file tree as printable text, rooted at the project directory name."""
+        return "\n".join([f"{self.root.name}/", *self.tree_lines])
+
+    def render(self) -> str:
+        """Full context block sent to the model."""
+        parts = [f"<file_tree>\n{self.tree}\n</file_tree>"]
+        if self.key_files:
+            files = "\n".join(
+                f'<file path="{kf.path}"{" truncated" if kf.truncated else ""}>\n'
+                f"{kf.content}\n</file>"
+                for kf in self.key_files
+            )
+            parts.append(f"<key_files>\n{files}\n</key_files>")
+        if self.outlines:
+            mods = "\n".join(
+                f'<module path="{path}">\n' + "\n".join(lines) + "\n</module>"
+                for path, lines in self.outlines.items()
+            )
+            parts.append(f"<code_outline>\n{mods}\n</code_outline>")
+        return "\n\n".join(parts)
+
+    def render_summary(self, max_tree_lines: int = 60) -> str:
+        """Compact, deterministic summary used to ground ``<codebase_context>``."""
+        tree = self.tree.splitlines()
+        if len(tree) > max_tree_lines:
+            hidden = len(tree) - max_tree_lines
+            tree = [*tree[:max_tree_lines], f"... ({hidden} more entries)"]
+        lines = ["File tree:", "```text", *tree, "```"]
+        if self.key_files:
+            lines += ["", "Key files: " + ", ".join(kf.path for kf in self.key_files)]
+        if self.outlines:
+            lines += ["", "Python modules (public API):"]
+            for path, outline in self.outlines.items():
+                lines.append(f"- {path}")
+                lines.extend(f"  {entry}" for entry in outline[:12])
+        return "\n".join(lines)
+
+
+def load_gitignore(root: Path) -> pathspec.GitIgnoreSpec | None:
+    """Parse the root ``.gitignore`` if present (nested ignore files are not read)."""
+    gitignore = root / ".gitignore"
+    if not gitignore.is_file():
+        return None
+    try:
+        lines = gitignore.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return None
+    return pathspec.GitIgnoreSpec.from_lines(lines)
+
+
+def _is_secret(name: str) -> bool:
+    """Heuristic for files that may contain credentials; never read or list them."""
+    if name == ".env" or (name.startswith(".env.") and name not in ENV_TEMPLATE_NAMES):
+        return True
+    return (
+        Path(name).suffix.lower() in SECRET_SUFFIXES
+        or name.startswith("id_rsa")
+        or name == "credentials.json"
+    )
+
+
+def _read_text(path: Path, max_chars: int) -> tuple[str, bool] | None:
+    """Read up to ``max_chars`` of a text file; return ``None`` for binary/unreadable."""
+    try:
+        size = path.stat().st_size
+        if size > MAX_FILE_BYTES:
+            return None
+        with path.open("rb") as fh:
+            data = fh.read(max_chars * 4 + 1)
+    except OSError:
+        return None
+    if b"\x00" in data[:1024]:
+        return None
+    text = data.decode("utf-8", errors="replace")
+    truncated = len(text) > max_chars or size > len(data)
+    return text[:max_chars], truncated
+
+
+def outline_python(source: str, max_lines: int = MAX_OUTLINE_LINES_PER_FILE) -> list[str]:
+    """Extract classes, functions, and public methods from Python source via ``ast``."""
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError):
+        return []
+
+    def sig(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+        prefix = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
+        ret = f" -> {ast.unparse(node.returns)}" if node.returns else ""
+        return f"{prefix} {node.name}({ast.unparse(node.args)}){ret}"
+
+    def doc(node: ast.AST) -> str:
+        text = ast.get_docstring(node)  # type: ignore[arg-type]
+        return f"  # {text.splitlines()[0][:80]}" if text else ""
+
+    out: list[str] = []
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            bases = f"({', '.join(ast.unparse(b) for b in node.bases)})" if node.bases else ""
+            out.append(f"class {node.name}{bases}:{doc(node)}")
+            for sub in node.body:
+                if isinstance(sub, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    if not sub.name.startswith("_") or sub.name == "__init__":
+                        out.append(f"    {sig(sub)}")
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if not node.name.startswith("_"):
+                out.append(f"{sig(node)}{doc(node)}")
+    return out[:max_lines]
+
+
+def _fit_lines(lines: list[str], token_budget: int) -> list[str]:
+    """Trim ``lines`` so their estimated token total fits the budget."""
+    kept: list[str] = []
+    used = 0
+    for i, line in enumerate(lines):
+        cost = estimate_tokens(line) + 1
+        if used + cost > token_budget:
+            kept.append(f"... ({len(lines) - i} more entries truncated)")
+            break
+        kept.append(line)
+        used += cost
+    return kept
+
+
+class WorkspaceScanner:
+    """Crawls a directory and builds a :class:`WorkspaceContext`."""
+
+    def __init__(
+        self,
+        root: Path,
+        *,
+        max_tokens: int = 3000,
+        max_depth: int = 4,
+        max_entries: int = 400,
+        extra_ignore: Iterable[str] = (),
+    ) -> None:
+        self.root = root.resolve()
+        self.max_tokens = max_tokens
+        self.max_depth = max_depth
+        self.max_entries = max_entries
+        self.ignore_dirs = DEFAULT_IGNORE_DIRS | frozenset(extra_ignore)
+        self.gitignore = load_gitignore(self.root)
+        self._lines: list[str] = []
+        self._files: list[Path] = []
+        self._count = 0
+
+    # -- filtering ---------------------------------------------------------------------
+
+    def _skip(self, entry: Path, is_dir: bool) -> bool:
+        if entry.is_symlink():  # avoids loops and escaping the root
+            return True
+        name = entry.name
+        if is_dir:
+            if name in self.ignore_dirs or name.endswith(".egg-info"):
+                return True
+        elif _is_secret(name) or entry.suffix.lower() in BINARY_SUFFIXES:
+            return True
+        if self.gitignore is not None:
+            rel = entry.relative_to(self.root).as_posix()
+            return self.gitignore.match_file(rel + "/" if is_dir else rel)
+        return False
+
+    # -- tree --------------------------------------------------------------------------
+
+    def _walk(self, directory: Path, depth: int, prefix: str) -> None:
+        try:
+            entries = sorted(directory.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
+        except OSError:
+            return
+        visible = [(e, e.is_dir()) for e in entries]
+        visible = [(e, d) for e, d in visible if not self._skip(e, d)]
+        for i, (entry, is_dir) in enumerate(visible):
+            if self._count >= self.max_entries:
+                return
+            last = i == len(visible) - 1
+            self._lines.append(f"{prefix}{'└── ' if last else '├── '}{entry.name}{'/' if is_dir else ''}")
+            self._count += 1
+            if is_dir:
+                if depth < self.max_depth:
+                    self._walk(entry, depth + 1, prefix + ("    " if last else "│   "))
+            else:
+                self._files.append(entry.relative_to(self.root))
+
+    # -- key files & outlines ----------------------------------------------------------
+
+    def _select_key_files(self, token_budget: int) -> list[KeyFile]:
+        ranked: list[tuple[int, int, str, Path]] = []
+        for rel in self._files:
+            if len(rel.parts) <= 3 and rel.name in KEY_FILE_NAMES:
+                ranked.append((KEY_FILE_NAMES.index(rel.name), len(rel.parts), rel.as_posix(), rel))
+        ranked.sort()
+
+        selected: list[KeyFile] = []
+        remaining = token_budget
+        per_file_cap = max(200, token_budget // 2)
+        for *_, rel in ranked:
+            if remaining < 100:
+                break
+            budget = min(remaining, per_file_cap)
+            result = _read_text(self.root / rel, budget * 4)
+            if result is None:
+                continue
+            text, truncated = result
+            if not text.strip():
+                continue
+            selected.append(KeyFile(rel.as_posix(), text.rstrip(), truncated))
+            remaining -= estimate_tokens(text)
+        return selected
+
+    def _build_outlines(self, token_budget: int) -> dict[str, list[str]]:
+        candidates = sorted(
+            (p for p in self._files if p.suffix == ".py"), key=lambda p: (len(p.parts), p.as_posix())
+        )
+        outlines: dict[str, list[str]] = {}
+        remaining = token_budget
+        for rel in candidates:
+            if len(outlines) >= MAX_OUTLINE_FILES or remaining < 50:
+                break
+            result = _read_text(self.root / rel, 200_000)
+            if result is None:
+                continue
+            outline = outline_python(result[0])
+            if not outline:
+                continue
+            outlines[rel.as_posix()] = outline
+            remaining -= sum(estimate_tokens(line) + 1 for line in outline)
+        return outlines
+
+    # -- public ------------------------------------------------------------------------
+
+    def scan(self) -> WorkspaceContext:
+        """Run the scan and return a budgeted :class:`WorkspaceContext`."""
+        self._walk(self.root, 1, "")
+        tree_lines = _fit_lines(self._lines, int(self.max_tokens * 0.3))
+        key_files = self._select_key_files(int(self.max_tokens * 0.5))
+        used = sum(estimate_tokens(kf.content) for kf in key_files)
+        outline_budget = max(0, self.max_tokens - int(self.max_tokens * 0.3) - used)
+        outlines = self._build_outlines(outline_budget)
+        return WorkspaceContext(self.root, tree_lines, key_files, outlines)
+
+
+def scan_workspace(root: Path | str | None = None, **kwargs: object) -> WorkspaceContext:
+    """Convenience wrapper: scan ``root`` (default: current directory)."""
+    return WorkspaceScanner(Path(root or Path.cwd()), **kwargs).scan()  # type: ignore[arg-type]

promptpump/engine.py

@@ -0,0 +1,217 @@
+"""Core compiler: builds the payload, talks to Ollama, and post-processes the result."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Protocol, Sequence
+
+import requests
+
+from .context import WorkspaceContext
+from .templates import (
+    REQUIRED_TAGS,
+    build_system_prompt,
+    build_user_message,
+    get_stack,
+)
+
+DEFAULT_MODEL = "qwen2.5-coder:7b"
+DEFAULT_HOST = "http://localhost:11434"
+
+Message = dict[str, str]
+
+
+class PromptPumpError(Exception):
+    """Base class for all PromptPump errors."""
+
+
+class OllamaError(PromptPumpError):
+    """Raised when the local Ollama server cannot satisfy a request."""
+
+
+class ChatClient(Protocol):
+    """Anything that can turn chat messages into a text reply (easy to fake in tests)."""
+
+    def chat(self, messages: list[Message]) -> str: ...
+
+
+class OllamaClient:
+    """Minimal client for Ollama's ``/api/chat`` endpoint (non-streaming)."""
+
+    def __init__(
+        self,
+        host: str = DEFAULT_HOST,
+        model: str = DEFAULT_MODEL,
+        *,
+        timeout: float = 300.0,
+        temperature: float = 0.2,
+        seed: int = 42,
+        num_ctx: int = 8192,
+    ) -> None:
+        self.host = host.rstrip("/")
+        self.model = model
+        self.timeout = timeout
+        # Low temperature + fixed seed keeps runs as reproducible as a local LLM allows.
+        self.options = {"temperature": temperature, "seed": seed, "num_ctx": num_ctx}
+
+    def chat(self, messages: list[Message]) -> str:
+        """Send messages to the model and return the assistant text."""
+        payload = {
+            "model": self.model,
+            "messages": messages,
+            "stream": False,
+            "options": self.options,
+        }
+        try:
+            resp = requests.post(f"{self.host}/api/chat", json=payload, timeout=self.timeout)
+        except requests.ConnectionError as exc:
+            raise OllamaError(
+                f"Cannot reach Ollama at {self.host}. Is it running? Start it with `ollama serve`."
+            ) from exc
+        except requests.Timeout as exc:
+            raise OllamaError(f"Ollama timed out after {self.timeout:.0f}s.") from exc
+
+        if resp.status_code == 404:
+            raise OllamaError(f"Model '{self.model}' not found. Run `ollama pull {self.model}`.")
+        if not resp.ok:
+            raise OllamaError(f"Ollama returned HTTP {resp.status_code}: {resp.text[:200]}")
+        try:
+            return str(resp.json()["message"]["content"])
+        except (ValueError, KeyError, TypeError) as exc:
+            raise OllamaError("Unexpected response format from Ollama.") from exc
+
+    def list_models(self) -> list[str]:
+        """Return the names of locally installed models."""
+        try:
+            resp = requests.get(f"{self.host}/api/tags", timeout=10)
+            resp.raise_for_status()
+            return [m["name"] for m in resp.json().get("models", [])]
+        except (requests.RequestException, ValueError, KeyError) as exc:
+            raise OllamaError(f"Cannot reach Ollama at {self.host}.") from exc
+
+
+# ---------------------------------------------------------------------------------------
+# Post-processing
+# ---------------------------------------------------------------------------------------
+
+_THINK_RE = re.compile(r"<think>.*?</think>", re.DOTALL)
+_FENCE_RE = re.compile(r"^```[\w-]*\s*\n(.*?)\n?```\s*$", re.DOTALL)
+_CONTEXT_RE = re.compile(r"<codebase_context>.*?</codebase_context>", re.DOTALL)
+
+
+def clean_response(raw: str) -> str:
+    """Strip reasoning blocks, conversational filler, and wrapping code fences."""
+    text = _THINK_RE.sub("", raw).strip()
+
+    first = text.find(f"<{REQUIRED_TAGS[0]}>")
+    if first > 0:  # drop any preamble such as "Sure! Here's your prompt:"
+        text = text[first:]
+    closing = f"</{REQUIRED_TAGS[-1]}>"
+    last = text.rfind(closing)
+    if last != -1:  # drop trailing remarks such as "Let me know if..."
+        text = text[: last + len(closing)]
+
+    fenced = _FENCE_RE.match(text.strip())
+    if fenced:
+        text = fenced.group(1)
+    return text.strip()
+
+
+def find_missing_tags(text: str) -> list[str]:
+    """Return required tags whose opening or closing marker is absent."""
+    return [t for t in REQUIRED_TAGS if f"<{t}>" not in text or f"</{t}>" not in text]
+
+
+def ground_codebase_context(prompt: str, summary: str) -> str:
+    """Replace the model-written ``<codebase_context>`` with deterministic facts."""
+    block = f"<codebase_context>\n{summary}\n</codebase_context>"
+    return _CONTEXT_RE.sub(lambda _m: block, prompt, count=1)
+
+
+# ---------------------------------------------------------------------------------------
+# Compiler
+# ---------------------------------------------------------------------------------------
+
+
+@dataclass
+class CompileResult:
+    """Outcome of a compilation run."""
+
+    prompt: str
+    raw: str
+    model: str
+    attempts: int
+    grounded: bool
+    missing_tags: list[str] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        return not self.missing_tags
+
+
+class PromptCompiler:
+    """Combines shorthand + workspace + template rules and runs the local model."""
+
+    def __init__(
+        self, client: ChatClient, *, ground_context: bool = True, max_repairs: int = 1
+    ) -> None:
+        self.client = client
+        self.ground_context = ground_context
+        self.max_repairs = max_repairs
+
+    def build_messages(
+        self, shorthand: str, context: WorkspaceContext, stacks: Sequence[str] = ()
+    ) -> list[Message]:
+        """Assemble the system + user messages (also used by ``--dry-run``)."""
+        profiles = list(dict.fromkeys(get_stack(s) for s in stacks))
+        return [
+            {"role": "system", "content": build_system_prompt(profiles)},
+            {"role": "user", "content": build_user_message(shorthand, context.render())},
+        ]
+
+    def compile(
+        self, shorthand: str, context: WorkspaceContext, stacks: Sequence[str] = ()
+    ) -> CompileResult:
+        """Compile ``shorthand`` into a validated master prompt."""
+        if not shorthand.strip():
+            raise PromptPumpError("Shorthand prompt must not be empty.")
+
+        messages = self.build_messages(shorthand, context, stacks)
+        raw = self.client.chat(messages)
+        prompt = clean_response(raw)
+        missing = find_missing_tags(prompt)
+        attempts = 1
+
+        # One-shot repair loop: show the model what it missed and ask for a full redo.
+        while missing and attempts <= self.max_repairs:
+            messages = [
+                *messages,
+                {"role": "assistant", "content": raw},
+                {
+                    "role": "user",
+                    "content": (
+                        f"Your output is missing or has unclosed tags: {', '.join(missing)}. "
+                        "Re-output the COMPLETE master prompt with all seven tags in order. "
+                        "Output only the prompt."
+                    ),
+                },
+            ]
+            raw = self.client.chat(messages)
+            prompt = clean_response(raw)
+            missing = find_missing_tags(prompt)
+            attempts += 1
+
+        grounded = False
+        if self.ground_context and "<codebase_context>" in prompt:
+            prompt = ground_codebase_context(prompt, context.render_summary())
+            grounded = True
+
+        return CompileResult(
+            prompt=prompt,
+            raw=raw,
+            model=str(getattr(self.client, "model", "unknown")),
+            attempts=attempts,
+            grounded=grounded,
+            missing_tags=missing,
+        )

promptpump/templates.py

@@ -0,0 +1,232 @@
+"""Structural schema, system prompt, and stack-specific rules.
+
+Everything in this module is static data plus pure functions, so the same inputs
+always produce the same system prompt (the deterministic half of PromptPump).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+# The seven tags every compiled master prompt must contain, in this exact order.
+REQUIRED_TAGS: tuple[str, ...] = (
+    "role_definition",
+    "task_objective",
+    "codebase_context",
+    "architectural_specifications",
+    "implementation_steps",
+    "constraints_and_guardrails",
+    "expected_output_format",
+)
+
+
+class UnknownStackError(ValueError):
+    """Raised when a --stack value does not match a known profile."""
+
+
+@dataclass(frozen=True)
+class StackProfile:
+    """Domain-specific rules injected into the system prompt."""
+
+    name: str
+    label: str
+    rules: tuple[str, ...]
+
+
+STACKS: dict[str, StackProfile] = {
+    p.name: p
+    for p in (
+        StackProfile(
+            "python",
+            "Python",
+            (
+                "Target Python 3.10+; use type hints on every public function and `pathlib` for paths.",
+                "Prefer the standard library; justify any new third-party dependency.",
+                "Follow PEP 8, use dataclasses or typed models for structured data, and raise specific exceptions.",
+                "Require pytest tests for new behaviour, including at least one failure-path test.",
+            ),
+        ),
+        StackProfile(
+            "fastapi",
+            "FastAPI",
+            (
+                "Define request/response bodies as Pydantic models; never return raw dicts from routes.",
+                "Split code into routers, schemas, services, and dependencies; keep route handlers thin.",
+                "Use dependency injection (`Depends`) for DB sessions, auth, and settings.",
+                "Use async handlers only when the underlying I/O is async; declare explicit status codes and error responses.",
+                "Add tests with `TestClient` or `httpx.AsyncClient` covering success and validation errors.",
+            ),
+        ),
+        StackProfile(
+            "django",
+            "Django",
+            (
+                "Keep business logic in models/services, not views; use class-based or function views consistently with the project.",
+                "Every model change requires a migration; never edit applied migrations.",
+                "Use the ORM with `select_related`/`prefetch_related` to avoid N+1 queries.",
+                "Read configuration from settings/environment; never hard-code secrets.",
+            ),
+        ),
+        StackProfile(
+            "react",
+            "React",
+            (
+                "Use function components and hooks only; keep components small and single-purpose.",
+                "Colocate state with the lowest common parent; lift or use context only when needed.",
+                "Type props explicitly (TypeScript if the project uses it) and handle loading, error, and empty states.",
+                "Avoid unnecessary re-renders: stable keys, `useMemo`/`useCallback` only where measured or obviously needed.",
+                "Cover behaviour with React Testing Library tests that query by role/label, not implementation details.",
+            ),
+        ),
+        StackProfile(
+            "nextjs",
+            "Next.js",
+            (
+                "Respect the project's router (App Router vs Pages Router) and do not mix them.",
+                "Default to Server Components; add `use client` only where interactivity requires it.",
+                "Fetch data on the server where possible; validate all inputs in route handlers.",
+            ),
+        ),
+        StackProfile(
+            "node",
+            "Node.js",
+            (
+                "Match the project's module system (ESM or CommonJS) and package manager.",
+                "Use async/await with centralized error handling; never swallow rejected promises.",
+                "Validate external input at the boundary and read config from environment variables.",
+            ),
+        ),
+        StackProfile(
+            "pygame",
+            "Pygame",
+            (
+                "Structure the game around a single main loop: handle events, update state, then render, in that order.",
+                "Use delta time (`clock.tick(fps) / 1000`) for movement; never tie speed to frame rate.",
+                "Separate game state/logic from rendering; model entities as classes (or `pygame.sprite.Sprite` subclasses).",
+                "Load assets once at startup, never inside the loop; call `pygame.quit()` on exit.",
+                "Keep constants (screen size, FPS, colours) in one config location.",
+            ),
+        ),
+        StackProfile(
+            "pytorch",
+            "PyTorch",
+            (
+                "Separate dataset, model, training loop, and evaluation into distinct modules.",
+                "Seed all RNGs, set `model.train()`/`model.eval()` explicitly, and wrap inference in `torch.no_grad()`.",
+                "Make device placement explicit and configurable; log metrics per epoch and checkpoint the best model.",
+            ),
+        ),
+    )
+}
+
+# Friendly aliases accepted on the command line.
+STACK_ALIASES: dict[str, str] = {
+    "py": "python",
+    "fast-api": "fastapi",
+    "reactjs": "react",
+    "next": "nextjs",
+    "next.js": "nextjs",
+    "nodejs": "node",
+    "torch": "pytorch",
+}
+
+
+def get_stack(name: str) -> StackProfile:
+    """Resolve a stack name or alias (case-insensitive) to its profile."""
+    key = name.strip().lower()
+    key = STACK_ALIASES.get(key, key)
+    try:
+        return STACKS[key]
+    except KeyError:
+        available = ", ".join(sorted(STACKS))
+        raise UnknownStackError(f"Unknown stack '{name}'. Available stacks: {available}") from None
+
+
+def list_stacks() -> list[StackProfile]:
+    """Return all known stack profiles sorted by name."""
+    return [STACKS[k] for k in sorted(STACKS)]
+
+
+SYSTEM_PROMPT_TEMPLATE = """\
+You are PromptPump, a deterministic prompt compiler for software engineers.
+
+Your job: convert a short shorthand request plus workspace context into ONE high-density \
+"master prompt" that another coding LLM will execute. You do NOT write the implementation \
+and you do NOT answer the request yourself.
+
+OUTPUT CONTRACT (strict):
+1. Output ONLY the master prompt. No greeting, no explanation, no code fences around the \
+whole output, no closing remarks.
+2. The output MUST contain exactly these seven XML tags, once each, in this order:
+{{TAG_LIST}}
+3. Inside each tag use terse, imperative Markdown (bullets or numbered lists). No filler.
+4. Ground everything in the <workspace> block. Reference only files, modules, and \
+dependencies that appear there. If something is unknown, record it as an explicit \
+assumption inside <constraints_and_guardrails>. Never invent file paths or APIs.
+5. Do not copy the shorthand verbatim. Expand it into concrete, testable requirements.
+6. REUSE BEFORE CREATE: if the workspace outline already contains a function or class that \
+does part of the job, name it and extend or call it. Never propose a duplicate module or helper.
+7. NO IMPLEMENTATION CODE: name files, functions, and signatures, but do not write function \
+bodies or test bodies inside the prompt.
+8. TARGET THE MECHANISM: state HOW the behaviour is achieved (for example: change the \
+generation prompt vs post-process the answer), not just what the end result should look like.
+9. UNKNOWNS: the workspace snapshot may be truncated. Any file, test, model, or API you cannot \
+see must be listed under "Assumptions (verify before coding)" in <constraints_and_guardrails>.
+10. STAY IN SCOPE: add no features, flags, files, or dependencies beyond the request. If the \
+request contains contradictory or ambiguous parts, resolve them explicitly in the assumptions \
+instead of copying the contradiction.
+
+SECTION RULES:
+<role_definition>: One short paragraph assigning the executing LLM a precise senior-engineer \
+persona matched to the languages and frameworks visible in the workspace.
+<task_objective>: One unambiguous, measurable objective, followed by success criteria and \
+explicit out-of-scope items.
+<codebase_context>: The facts from the workspace that matter: language, frameworks, entry \
+points, and the files most likely to change.
+<architectural_specifications>: Design decisions: files/modules to create or modify, data \
+flow, key interfaces and signatures, naming and style conventions that match existing code.
+<implementation_steps>: Ordered, numbered, small, verifiable steps; each names its target file.
+<constraints_and_guardrails>: Hard rules: dependencies, compatibility, error handling, \
+security, performance, testing, files not to touch, then an "Assumptions (verify before \
+coding)" list.
+<expected_output_format>: Exactly how the executing LLM must reply (for example: full file \
+contents per path in fenced blocks, then a brief test plan). Nothing else.
+
+{{STACK_SECTION}}"""
+
+
+def render_tag_list() -> str:
+    """Render the required tags as a numbered list for the system prompt."""
+    return "\n".join(f"   {i}. <{tag}>...</{tag}>" for i, tag in enumerate(REQUIRED_TAGS, 1))
+
+
+def render_stack_section(stacks: Sequence[StackProfile]) -> str:
+    """Render stack-specific rules, or an explicit 'none' marker."""
+    if not stacks:
+        return "STACK RULES: none specified. Infer conventions from the workspace only."
+    lines = [
+        "STACK RULES (defaults: apply them in <architectural_specifications> and "
+        "<constraints_and_guardrails>, but skip any that conflict with conventions "
+        "visible in the workspace):"
+    ]
+    for profile in stacks:
+        lines.append(f"[{profile.label}]")
+        lines.extend(f"- {rule}" for rule in profile.rules)
+    return "\n".join(lines)
+
+
+def build_system_prompt(stacks: Sequence[StackProfile] = ()) -> str:
+    """Assemble the full system prompt for the local model."""
+    return SYSTEM_PROMPT_TEMPLATE.replace("{{TAG_LIST}}", render_tag_list()).replace(
+        "{{STACK_SECTION}}", render_stack_section(stacks)
+    )
+
+
+def build_user_message(shorthand: str, workspace_text: str) -> str:
+    """Wrap the shorthand request and workspace snapshot into the user turn."""
+    return (
+        f"<shorthand_request>\n{shorthand.strip()}\n</shorthand_request>\n\n"
+        f"<workspace>\n{workspace_text.strip()}\n</workspace>\n\n"
+        "Compile the master prompt now. Output only the seven XML-tagged sections."
+    )

promptpump-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+promptpump/__init__.py,sha256=TCWmbRwkpwV4-qOKh0dEp93PZAFcRbcP2ZPgUn2EQnQ,408
+promptpump/cli.py,sha256=3XSJoc1e4owDyC6tP2jmFmSMIyLvtVI9LjTKJeEmYTE,6526
+promptpump/context.py,sha256=aXDYNTgxOyhAagSzLWqWFSGLpTn3gS6agUE97AbBwNk,12924
+promptpump/engine.py,sha256=d8YoaX7jVTv5WdhWBbCqfDT2DHQ0Bq4a9FzR1G6oGJM,7671
+promptpump/templates.py,sha256=GGRcNQvqo6M39NUuG09zxbQNMCFkKiQVkA0JIJ4tzXY,10609
+promptpump-0.1.0.dist-info/licenses/LICENSE,sha256=RTV018ZVG9hNOJQD_Hk-r3GrMgpuJcZ7Ka451K00SgA,1070
+promptpump-0.1.0.dist-info/METADATA,sha256=I7QYtInQ-sLM_8nbVS0UVu9PK6FNd73D91kA8Q15Nhc,4106
+promptpump-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+promptpump-0.1.0.dist-info/entry_points.txt,sha256=AVHnv6655-sjTVBdtpdGd2fOKcyOiHrWx3X4BgXjpmE,50
+promptpump-0.1.0.dist-info/top_level.txt,sha256=WvQM6aRNXWYOyOlfJ1ApgLQ3Xy0nphpyFPFgC3euEAM,11
+promptpump-0.1.0.dist-info/RECORD,,

promptpump-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

promptpump-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+promptpump = promptpump.cli:app

promptpump-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+promptpump