prpt 0.1.0__py3-none-any.whl

prpt/__init__.py

@@ -0,0 +1,33 @@
+"""PromptPilot — prompt-optimizing wrapper for AI coding CLIs."""
+from __future__ import annotations
+
+from prpt.core.types import (
+    Confidence,
+    NormalizedRequest,
+    RepoMetadata,
+    RewriteMode,
+    TaskType,
+    TokenStats,
+    ValidationResult,
+)
+from prpt.normalizers.base import Normalizer, SemanticValidator, create_normalizer
+from prpt.normalizers.heuristic import HeuristicNormalizer
+from prpt.repo.collector import RepoContextCollector
+from prpt.cli import main, main_cli
+
+__all__ = [
+    "Confidence",
+    "HeuristicNormalizer",
+    "NormalizedRequest",
+    "Normalizer",
+    "RepoContextCollector",
+    "RepoMetadata",
+    "RewriteMode",
+    "SemanticValidator",
+    "TaskType",
+    "TokenStats",
+    "ValidationResult",
+    "create_normalizer",
+    "main",
+    "main_cli",
+]

prpt/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m prpt`."""
+from prpt.cli import main_cli
+
+if __name__ == "__main__":
+    main_cli()

prpt/_subprocess.py

@@ -0,0 +1,168 @@
+"""Subprocess helpers — utf-8 enforcement + claude.exe orphan management.
+
+Two recurring bug patterns this module exists to prevent:
+
+1. **Windows GBK encoding crash** when subprocess.run is called with `text=True`
+   but no explicit `encoding=`. Python 3.11 on Windows defaults to the locale
+   encoding (often GBK), which fails on non-ASCII bytes from many tools.
+   `safe_run()` enforces utf-8/replace whenever text mode is implied.
+
+2. **claude.exe zombie accumulation.** When a chain run crashes or is Ctrl-C'd
+   with a claude.exe subprocess in flight, the orphan keeps retrying API calls,
+   competes for the API key's concurrent-request quota, and (~10+ orphans)
+   eventually exhausts Windows process handles and crashes the OS.
+   `claude_subprocess_session()` wraps a chain-run / launcher entry point
+   in a context manager that reaps orphans on entry AND exit.
+
+Use:
+    from prpt._subprocess import safe_run, claude_subprocess_session
+
+    # Encoding-safe subprocess
+    r = safe_run(["powershell", "-Command", "Get-Process"], capture_output=True, text=True)
+
+    # Wrap a launcher loop so any zombies it leaves are reaped automatically
+    with claude_subprocess_session("extra_gated_runs"):
+        for r in range(args.start, args.start + args.count):
+            run_chain_once(...)
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import time
+from contextlib import contextmanager
+from typing import Iterator
+
+
+def safe_run(*args, **kwargs) -> subprocess.CompletedProcess:
+    """subprocess.run with utf-8 enforced when text mode is implied.
+
+    "Text mode is implied" if any of these is set:
+      - text=True
+      - universal_newlines=True
+      - encoding= (any value)
+
+    In that case, encoding defaults to "utf-8" and errors defaults to "replace"
+    if not explicitly passed. Binary mode (text=False) is left alone — caller
+    must handle bytes themselves.
+
+    All other args/kwargs pass through to subprocess.run.
+    """
+    text_mode = (
+        kwargs.get("text") is True
+        or kwargs.get("universal_newlines") is True
+        or "encoding" in kwargs
+    )
+    if text_mode:
+        kwargs.setdefault("encoding", "utf-8")
+        kwargs.setdefault("errors", "replace")
+    return subprocess.run(*args, **kwargs)
+
+
+def reap_claude_orphans() -> int:
+    """Kill claude.exe processes whose parent process no longer exists.
+
+    Orphans accumulate when a harness run crashes or is Ctrl-C'd while a
+    claude.exe subprocess is in flight: the child continues running, retries
+    API calls indefinitely, and competes for the API key's concurrent-request
+    quota. ~10+ orphans can exhaust Windows process handles and crash the OS.
+
+    Windows-only; no-op on other platforms. Returns the number of processes
+    killed (best effort).
+    """
+    if os.name != "nt":
+        return 0
+    try:
+        # List all claude.exe PIDs with their parent PIDs
+        proc = safe_run(
+            ["wmic", "process", "where", "Name='claude.exe'",
+             "get", "ProcessId,ParentProcessId", "/format:csv"],
+            capture_output=True, text=True, timeout=30,
+        )
+        if proc.returncode != 0:
+            return 0
+        claude_pairs: list[tuple[int, int]] = []
+        for line in proc.stdout.splitlines():
+            parts = [p.strip() for p in line.split(",")]
+            if len(parts) < 3:
+                continue
+            try:
+                ppid = int(parts[1])
+                pid = int(parts[2])
+                claude_pairs.append((pid, ppid))
+            except (ValueError, IndexError):
+                continue
+
+        if not claude_pairs:
+            return 0
+
+        # List all live PIDs to detect orphans
+        live_proc = safe_run(
+            ["wmic", "process", "get", "ProcessId", "/format:csv"],
+            capture_output=True, text=True, timeout=30,
+        )
+        if live_proc.returncode != 0:
+            return 0
+        live_pids: set[int] = set()
+        for line in live_proc.stdout.splitlines():
+            parts = [p.strip() for p in line.split(",")]
+            if len(parts) < 2:
+                continue
+            try:
+                live_pids.add(int(parts[1]))
+            except (ValueError, IndexError):
+                continue
+
+        killed = 0
+        for pid, ppid in claude_pairs:
+            if ppid not in live_pids:
+                # Orphan — kill the process tree rooted at this claude.exe
+                try:
+                    safe_run(
+                        ["taskkill", "/F", "/T", "/PID", str(pid)],
+                        capture_output=True, timeout=10,
+                    )
+                    killed += 1
+                except Exception:
+                    pass
+        return killed
+    except Exception:
+        return 0
+
+
+@contextmanager
+def claude_subprocess_session(label: str = "") -> Iterator[None]:
+    """Wrap a sequence of claude.exe subprocess invocations with auto-reap.
+
+    Reaps claude.exe orphans on entry (cleans up from any prior crashed run)
+    AND on exit (catches anything we may have leaked, even if the body raised).
+    Use for launcher entry points (e.g. extra_*_runs.py main, run_chain_once)
+    so future launcher scripts get the protection automatically.
+
+    Args:
+        label: optional tag printed when zombies are reaped on exit. Helps
+            identify which run was leaking.
+
+    Example:
+        with claude_subprocess_session("extra_gated_runs"):
+            for r in range(args.start, args.start + args.count):
+                run_chain_once(chain, "claude-code", "gated_session", r, out_dir)
+    """
+    t0 = time.time()
+    pre_reaped = reap_claude_orphans()
+    if pre_reaped > 0:
+        sys.stderr.write(
+            "[claude_subprocess_session{0}] reaped {1} pre-existing orphans\n"
+            .format(":" + label if label else "", pre_reaped)
+        )
+    try:
+        yield
+    finally:
+        post_reaped = reap_claude_orphans()
+        if post_reaped > 0:
+            elapsed = time.time() - t0
+            sys.stderr.write(
+                "[claude_subprocess_session{0}] reaped {1} on exit ({2:.0f}s)\n"
+                .format(":" + label if label else "", post_reaped, elapsed)
+            )

prpt/adapters/__init__.py

@@ -0,0 +1,4 @@
+from prpt.adapters.echo import ToolAdapter, EchoAdapter
+from prpt.adapters.factory import AdapterFactory
+
+__all__ = ["ToolAdapter", "EchoAdapter", "AdapterFactory"]

prpt/adapters/anthropic_adapter.py

@@ -0,0 +1,246 @@
+"""Direct Anthropic API adapter — calls a model and captures actual token usage.
+
+Supports claude-opus-4-7, claude-sonnet-4-7, and any future Anthropic model
+via the `model` constructor parameter.
+
+Prompt-caching design
+---------------------
+The adapter accepts an optional `system` string (a stable instruction block)
+and an optional `context_block` string (stable repo context).  When either is
+large enough to cross Anthropic's minimum cacheable threshold, a
+`cache_control: ephemeral` marker is inserted so repeated calls within the
+5-minute TTL window are served from cache at 0.10× the normal input price.
+
+Cache breakpoint placement:
+    [ system (cacheable) ] [ context_block (cacheable) ] | [ task prompt ]
+    └────────── stable prefix, written once ────────────┘   └── dynamic ──┘
+
+When no system / context_block is provided the adapter falls back to the
+original single-string call — fully backward-compatible.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Optional
+
+from prpt.core.constants import (
+    DEFAULT_TARGET_MODEL, CACHE_WRITE_MULTIPLIER, CACHE_READ_MULTIPLIER,
+    MODEL_PRICING,
+)
+from prpt.core.utils import write_stderr
+from prpt.adapters.echo import ToolAdapter
+
+# Anthropic's minimum cacheable block: ~1 024 tokens for Sonnet/Opus.
+# Using chars as a cheap proxy: 1 024 tokens ≈ 4 096 chars.
+_CACHE_MIN_CHARS = 4_096
+_EPHEMERAL = {"type": "ephemeral"}
+
+
+def _extract_usage(response) -> dict:
+    """Pull all Anthropic usage fields into a flat dict (cache-aware)."""
+    u = response.usage
+    return {
+        "input_tokens":                 getattr(u, "input_tokens",                 0) or 0,
+        "output_tokens":                getattr(u, "output_tokens",                0) or 0,
+        "cache_creation_input_tokens":  getattr(u, "cache_creation_input_tokens",  0) or 0,
+        "cache_read_input_tokens":      getattr(u, "cache_read_input_tokens",       0) or 0,
+    }
+
+
+def _cost_usd(usage: dict, model: str) -> float:
+    """Compute total cost in USD using Anthropic cache-aware pricing."""
+    price = MODEL_PRICING.get(model, {"input": 15.00, "output": 75.00})
+    p_in  = price["input"]  / 1_000_000
+    p_out = price["output"] / 1_000_000
+    return (
+        usage["input_tokens"]               * p_in
+        + usage["output_tokens"]            * p_out
+        + usage["cache_creation_input_tokens"] * p_in * CACHE_WRITE_MULTIPLIER
+        + usage["cache_read_input_tokens"]     * p_in * CACHE_READ_MULTIPLIER
+    )
+
+
+class AnthropicDirectAdapter(ToolAdapter):
+    """
+    Calls an Anthropic model (default: claude-opus-4-7) via the SDK.
+
+    Parameters
+    ----------
+    model : str
+        Any Anthropic model ID, e.g. ``"claude-opus-4-7"`` or
+        ``"claude-sonnet-4-7"``.
+    system : str, optional
+        Stable instruction block sent as the ``system`` message.  When large
+        enough, marked with ``cache_control: ephemeral`` so it is cached
+        across repeated calls within 5 minutes.
+    context_block : str, optional
+        Stable repo-context blob.  Inserted as the first user content block,
+        also marked cacheable when large enough.  Placed *before* the task
+        prompt so the cache breakpoint sits between the stable prefix and the
+        per-request tail.
+    api_key : str, optional
+        Falls back to ``ANTHROPIC_API_KEY`` env var.
+    max_tokens : int
+        Maximum output tokens (default 4 096).
+    """
+
+    def __init__(
+        self,
+        model: str = DEFAULT_TARGET_MODEL,
+        api_key: Optional[str] = None,
+        max_tokens: int = 4096,
+        system: Optional[str] = None,
+        context_block: Optional[str] = None,
+    ):
+        try:
+            import anthropic as _anthropic
+            self._client = _anthropic.Anthropic(
+                api_key=api_key or os.environ.get("ANTHROPIC_API_KEY")
+            )
+        except ImportError:
+            raise ImportError(
+                "Claude tool support requires the anthropic SDK.\n"
+                "  Run: pip install prpt[claude]"
+            )
+        self._model         = model
+        self._max_tokens    = max_tokens
+        self._system        = system
+        self._context_block = context_block
+        self.last_usage: Optional[dict] = None
+
+    # ------------------------------------------------------------------
+    # Cache-aware request builders
+    # ------------------------------------------------------------------
+
+    def _build_system(self) -> list[dict] | str | None:
+        """Return system param: block-list with cache marker if large enough."""
+        if not self._system:
+            return None
+        block: dict = {"type": "text", "text": self._system}
+        if len(self._system) >= _CACHE_MIN_CHARS:
+            block["cache_control"] = _EPHEMERAL
+        return [block]
+
+    def _build_user_content(self, task_prompt: str) -> list[dict] | str:
+        """
+        Build user content.
+
+        If a context_block was provided: split into two blocks —
+          [0] cacheable context, [1] fresh task prompt.
+        Otherwise: single plain-string (backward-compat, no cache marker).
+        """
+        if not self._context_block:
+            return task_prompt
+
+        ctx_block: dict = {
+            "type": "text",
+            "text": (
+                "<repository_context>\n"
+                + self._context_block
+                + "\n</repository_context>"
+            ),
+        }
+        if len(self._context_block) >= _CACHE_MIN_CHARS:
+            ctx_block["cache_control"] = _EPHEMERAL
+
+        return [
+            ctx_block,
+            {"type": "text", "text": task_prompt},
+        ]
+
+    # ------------------------------------------------------------------
+    # ToolAdapter interface
+    # ------------------------------------------------------------------
+
+    def run(self, final_prompt: str, args: argparse.Namespace) -> int:
+        self.last_usage = None
+        if getattr(args, "verbose", False):
+            cache_state = "on" if self._system or self._context_block else "off"
+            write_stderr(
+                "[adapter] calling {model} via Anthropic SDK "
+                "(cache={cache})".format(model=self._model, cache=cache_state)
+            )
+        try:
+            create_kwargs: dict = {
+                "model":      self._model,
+                "max_tokens": self._max_tokens,
+                "messages":   [{
+                    "role":    "user",
+                    "content": self._build_user_content(final_prompt),
+                }],
+            }
+            system_arg = self._build_system()
+            if system_arg is not None:
+                create_kwargs["system"] = system_arg
+
+            response = self._client.messages.create(**create_kwargs)
+
+            usage = _extract_usage(response)
+            usage["total_cost_usd"] = _cost_usd(usage, self._model)
+            self.last_usage = usage
+
+            verbose = getattr(args, "verbose", False)
+            printed_text = False
+            tool_uses: list[str] = []
+
+            for block in response.content:
+                btype = getattr(block, "type", None)
+                if btype == "text" or (btype is None and hasattr(block, "text")):
+                    text = getattr(block, "text", "")
+                    if text:
+                        print(text)
+                        printed_text = True
+                elif btype == "thinking":
+                    if verbose:
+                        thinking_text = getattr(block, "thinking", "")
+                        write_stderr("[adapter] thinking: {0}".format(thinking_text))
+                elif btype == "redacted_thinking":
+                    if verbose:
+                        write_stderr("[adapter] thinking: <redacted>")
+                elif btype == "tool_use":
+                    name = getattr(block, "name", "<unknown>")
+                    tool_uses.append(name)
+
+            if verbose and tool_uses:
+                write_stderr(
+                    "[adapter] tool_use blocks: {0}".format(", ".join(tool_uses))
+                )
+
+            if not printed_text:
+                stop_reason = getattr(response, "stop_reason", "unknown")
+                detail = (
+                    " (tool_use: {0})".format(", ".join(tool_uses))
+                    if tool_uses else ""
+                )
+                write_stderr(
+                    "[adapter] warning: no text content in response "
+                    "(stop_reason={0}){1}".format(stop_reason, detail)
+                )
+            return 0
+
+        except Exception as exc:
+            write_stderr("[adapter] Anthropic API call failed: {0}".format(exc))
+            return 1
+
+    # ------------------------------------------------------------------
+    # Convenience: human-readable cache summary for --verbose / stats
+    # ------------------------------------------------------------------
+
+    def cache_summary(self) -> str:
+        """Return a one-line cache hit summary from the last run."""
+        if not self.last_usage:
+            return "no run yet"
+        r  = self.last_usage.get("cache_read_input_tokens",  0)
+        w  = self.last_usage.get("cache_creation_input_tokens", 0)
+        total_cached = r + w
+        if total_cached == 0:
+            return "cache: off (no cacheable blocks)"
+        hit_pct = r / total_cached * 100 if total_cached else 0
+        return (
+            "cache: {r:,} read / {w:,} written  ({pct:.0f}% hit)  "
+            "cost ${cost:.6f}".format(
+                r=r, w=w, pct=hit_pct,
+                cost=self.last_usage.get("total_cost_usd", 0.0),
+            )
+        )

prpt/adapters/echo.py

@@ -0,0 +1,16 @@
+"""Echo adapter — prints prompt to stdout (dry-run / default)."""
+from __future__ import annotations
+
+import argparse
+
+
+class ToolAdapter:
+    """Base class for all downstream tool adapters."""
+    def run(self, final_prompt: str, args: argparse.Namespace) -> int:
+        raise NotImplementedError
+
+
+class EchoAdapter(ToolAdapter):
+    def run(self, final_prompt: str, args: argparse.Namespace) -> int:
+        print(final_prompt)
+        return 0

prpt/adapters/factory.py

@@ -0,0 +1,40 @@
+"""Adapter factory — selects the right downstream adapter from --tool flag."""
+from __future__ import annotations
+
+import argparse
+from typing import Optional
+
+from prpt.core.constants import DEFAULT_TARGET_MODEL
+from prpt.adapters.echo import EchoAdapter, ToolAdapter
+from prpt.adapters.shell import CodexAdapter, ShellToolAdapter
+
+
+class AdapterFactory:
+    @staticmethod
+    def create(args: argparse.Namespace) -> ToolAdapter:
+        tool = (getattr(args, "tool", None) or "echo").lower()
+        extra_args = getattr(args, "tool_arg", None) or []
+        model = getattr(args, "model", None) or DEFAULT_TARGET_MODEL
+        max_tokens = getattr(args, "max_tokens", 4096) or 4096
+        api_key = getattr(args, "api_key", None)
+
+        if tool == "echo":
+            return EchoAdapter()
+
+        if tool == "codex":
+            return CodexAdapter(extra_args=extra_args)
+
+        if tool == "anthropic":
+            from prpt.adapters.anthropic_adapter import AnthropicDirectAdapter
+            system        = getattr(args, "system_prompt", None)
+            context_block = getattr(args, "context_block", None)
+            return AnthropicDirectAdapter(
+                model=model, api_key=api_key, max_tokens=max_tokens,
+                system=system, context_block=context_block,
+            )
+
+        if tool == "openai":
+            from prpt.adapters.openai_adapter import OpenAIDirectAdapter
+            return OpenAIDirectAdapter(model=model, api_key=api_key, max_tokens=max_tokens)
+
+        return ShellToolAdapter(tool_name=tool, extra_args=extra_args)

prpt/adapters/openai_adapter.py

@@ -0,0 +1,72 @@
+"""Direct OpenAI API adapter — calls a model and captures actual token usage."""
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Optional
+
+from prpt.core.utils import write_stderr
+from prpt.adapters.echo import ToolAdapter
+
+
+class OpenAIDirectAdapter(ToolAdapter):
+    """
+    Calls an OpenAI model via the SDK.
+    Captures actual input/output token usage for before/after comparison.
+    """
+
+    def __init__(
+        self, model: str = "gpt-4o", api_key: Optional[str] = None, max_tokens: int = 4096,
+    ):
+        try:
+            import openai as _openai
+            self._client = _openai.OpenAI(
+                api_key=api_key or os.environ.get("OPENAI_API_KEY")
+            )
+        except ImportError:
+            raise ImportError(
+                "Codex tool support requires the openai SDK.\n"
+                "  Run: pip install prpt[codex]"
+            )
+        self._model = model
+        self._max_tokens = max_tokens
+        self.last_usage: Optional[dict] = None
+
+    @staticmethod
+    def _is_reasoning_model(model: str) -> bool:
+        """Return True if the model is an o-series reasoning model (o1/o3/o4/o5+)."""
+        name = model.lower()
+        # Strip common provider prefixes (e.g. "openai/o3-mini", "azure/o1")
+        if "/" in name:
+            name = name.rsplit("/", 1)[1]
+        return name.startswith(("o1", "o3", "o4", "o5", "o6", "o7", "o8", "o9"))
+
+    def run(self, final_prompt: str, args: argparse.Namespace) -> int:
+        self.last_usage = None
+        if getattr(args, "verbose", False):
+            write_stderr("[adapter] calling {0} via OpenAI SDK".format(self._model))
+        try:
+            # o-series reasoning models (o1/o3/o4/...) reject `max_tokens` and
+            # require `max_completion_tokens` instead.
+            token_kwarg = (
+                "max_completion_tokens"
+                if self._is_reasoning_model(self._model)
+                else "max_tokens"
+            )
+            create_kwargs = {
+                "model": self._model,
+                "messages": [{"role": "user", "content": final_prompt}],
+                token_kwarg: self._max_tokens,
+            }
+            response = self._client.chat.completions.create(**create_kwargs)
+            self.last_usage = {
+                "input_tokens": response.usage.prompt_tokens,
+                "output_tokens": response.usage.completion_tokens,
+            }
+            content = response.choices[0].message.content
+            if content:
+                print(content)
+            return 0
+        except Exception as exc:
+            write_stderr("[adapter] OpenAI API call failed: {0}".format(exc))
+            return 1