ralph-any 0.1.0__py3-none-any.whl

ralph/__init__.py

@@ -0,0 +1,14 @@
+"""Ralph Any — iterative AI dev loop via ACP."""
+
+__version__ = "0.1.0"
+
+from ralph.detect import detect_promise
+from ralph.engine import LoopConfig, LoopResult, RalphEngine
+
+__all__ = [
+    "__version__",
+    "detect_promise",
+    "LoopConfig",
+    "LoopResult",
+    "RalphEngine",
+]

ralph/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m ralph``."""
+
+from ralph.cli import main
+
+main()

ralph/cli.py

@@ -0,0 +1,122 @@
+"""CLI interface for Ralph Any."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+from ralph.engine import LoopConfig, RalphEngine
+
+EXIT_SUCCESS = 0
+EXIT_FAILED = 1
+EXIT_CANCELLED = 2
+EXIT_TIMEOUT = 3
+EXIT_MAX_ITERATIONS = 4
+
+_STATE_TO_EXIT = {
+    "complete": EXIT_SUCCESS,
+    "failed": EXIT_FAILED,
+    "cancelled": EXIT_CANCELLED,
+    "timeout": EXIT_TIMEOUT,
+    "max_iterations": EXIT_MAX_ITERATIONS,
+}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ralph",
+        description="Ralph Wiggum Loop — iterative AI dev loop via ACP",
+    )
+    p.add_argument(
+        "prompt",
+        help="Task description, or path to a .md/.txt file",
+    )
+    p.add_argument(
+        "-m", "--max-iterations",
+        type=int,
+        default=10,
+        help="Maximum loop iterations (default: 10)",
+    )
+    p.add_argument(
+        "-t", "--timeout",
+        type=int,
+        default=1800,
+        help="Maximum runtime in seconds (default: 1800 = 30m)",
+    )
+    p.add_argument(
+        "--promise",
+        default="任務完成！🥇",
+        help="Completion promise phrase (default: 任務完成！🥇)",
+    )
+    p.add_argument(
+        "-c", "--command",
+        default="claude-code-acp",
+        help="ACP CLI command (default: claude-code-acp)",
+    )
+    p.add_argument(
+        "--command-args",
+        nargs="*",
+        default=[],
+        help="Extra arguments for the ACP CLI",
+    )
+    p.add_argument(
+        "-d", "--working-dir",
+        default=".",
+        help="Working directory (default: .)",
+    )
+    p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show config without running",
+    )
+    return p
+
+
+def _resolve_prompt(raw: str) -> str:
+    """If ``raw`` is a path to an existing .md or .txt file, read it."""
+    p = Path(raw)
+    if p.is_file() and p.suffix in (".md", ".txt"):
+        return p.read_text(encoding="utf-8")
+    return raw
+
+
+def _run(config: LoopConfig) -> int:
+    engine = RalphEngine(config)
+    try:
+        result = asyncio.run(engine.run())
+    except KeyboardInterrupt:
+        print("\n⚠ Loop cancelled", flush=True)
+        return EXIT_CANCELLED
+
+    duration = f"{result.duration_seconds:.1f}s"
+    print(f"\n▶ Result: {result.state} ({result.iterations} iterations, {duration})")
+
+    return _STATE_TO_EXIT.get(result.state, EXIT_FAILED)
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    prompt_text = _resolve_prompt(args.prompt)
+
+    config = LoopConfig(
+        prompt=prompt_text,
+        promise_phrase=args.promise,
+        command=args.command,
+        command_args=args.command_args,
+        working_dir=args.working_dir,
+        max_iterations=args.max_iterations,
+        timeout_seconds=args.timeout,
+        dry_run=args.dry_run,
+    )
+
+    if config.dry_run:
+        print("Dry-run config:")
+        for k, v in vars(config).items():
+            print(f"  {k}: {v}")
+        sys.exit(EXIT_SUCCESS)
+
+    sys.exit(_run(config))

ralph/detect.py

@@ -0,0 +1,7 @@
+"""Promise completion detection."""
+
+
+def detect_promise(text: str, phrase: str) -> bool:
+    if not phrase:
+        return False
+    return f"<promise>{phrase}</promise>" in text

ralph/engine.py

@@ -0,0 +1,134 @@
+"""Ralph Loop engine — the core iteration loop over any ACP-compatible agent."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import time
+from dataclasses import dataclass, field
+from typing import Literal
+
+from claude_code_acp import AcpClient
+
+from ralph.detect import detect_promise
+from ralph.prompt import build_system_prompt
+
+LoopState = Literal["complete", "failed", "cancelled", "timeout", "max_iterations"]
+
+
+@dataclass
+class LoopConfig:
+    prompt: str
+    promise_phrase: str = "任務完成！🥇"
+    command: str = "claude-code-acp"
+    command_args: list[str] = field(default_factory=list)
+    working_dir: str = "."
+    max_iterations: int = 10
+    timeout_seconds: int = 1800  # 30 minutes
+    dry_run: bool = False
+
+
+@dataclass
+class LoopResult:
+    state: LoopState
+    iterations: int
+    duration_seconds: float
+    error: str | None = None
+
+
+class RalphEngine:
+    def __init__(self, config: LoopConfig) -> None:
+        self.config = config
+        self.client = AcpClient(
+            command=config.command,
+            args=config.command_args or None,
+            cwd=config.working_dir,
+        )
+        self._register_events()
+
+    def _register_events(self) -> None:
+        client = self.client
+
+        @client.on_text
+        async def on_text(text: str) -> None:
+            sys.stdout.write(text)
+            sys.stdout.flush()
+
+        @client.on_tool_start
+        async def on_tool_start(tool_id: str, name: str, input: dict) -> None:
+            print(f"\n🛠️  {name}", flush=True)
+
+        @client.on_tool_end
+        async def on_tool_end(tool_id: str, status: str, output: object) -> None:
+            icon = "✔️" if status == "completed" else "❌"
+            print(f" {icon} {status}", flush=True)
+
+        @client.on_permission
+        async def on_permission(name: str, input: dict, options: list) -> str:
+            # Auto-allow all tool executions in the loop.
+            # Pick the first "allow" style option from what the agent offers.
+            for opt in options:
+                opt_id = opt if isinstance(opt, str) else opt.get("id", "")
+                if opt_id in ("allow", "allow_always", "proceed_once"):
+                    return opt_id
+            # Fallback: return the first option's id
+            if options:
+                return options[0] if isinstance(options[0], str) else options[0].get("id", "allow")
+            return "allow"
+
+        @client.on_error
+        async def on_error(exception: Exception) -> None:
+            print(f"\n⚠️  Error: {exception}", file=sys.stderr, flush=True)
+
+    async def run(self) -> LoopResult:
+        config = self.config
+        system_prompt = build_system_prompt(config.promise_phrase)
+        start = time.monotonic()
+
+        async with self.client:
+            for i in range(1, config.max_iterations + 1):
+                elapsed = time.monotonic() - start
+                if elapsed >= config.timeout_seconds:
+                    return LoopResult(
+                        state="timeout",
+                        iterations=i - 1,
+                        duration_seconds=elapsed,
+                    )
+
+                print(f"\n━━━ Iteration {i}/{config.max_iterations} ━━━", flush=True)
+
+                prompt = (
+                    f"{system_prompt}\n\n---\n\n"
+                    f"[Iteration {i}/{config.max_iterations}]\n\n{config.prompt}"
+                )
+
+                try:
+                    response = await asyncio.wait_for(
+                        self.client.prompt(prompt),
+                        timeout=max(0, config.timeout_seconds - elapsed),
+                    )
+                except asyncio.TimeoutError:
+                    return LoopResult(
+                        state="timeout",
+                        iterations=i,
+                        duration_seconds=time.monotonic() - start,
+                    )
+
+                if detect_promise(response, config.promise_phrase):
+                    print(
+                        f"\n🎉 Promise detected: \"{config.promise_phrase}\"",
+                        flush=True,
+                    )
+                    return LoopResult(
+                        state="complete",
+                        iterations=i,
+                        duration_seconds=time.monotonic() - start,
+                    )
+
+                print(f"\n✓ Iteration {i} complete", flush=True)
+
+        return LoopResult(
+            state="max_iterations",
+            iterations=config.max_iterations,
+            duration_seconds=time.monotonic() - start,
+        )

ralph/prompt.py

@@ -0,0 +1,46 @@
+"""System prompt template for the Ralph Wiggum Loop."""
+
+_TEMPLATE = """\
+# Ralph Loop System Instructions
+
+You are operating inside the **Ralph Wiggum Loop**:
+- The user prompt will be fed back to you *unchanged* after each response.
+- You will see the repo state and any files you modified from previous iterations.
+- Your job is to keep iterating until the task is fully complete, then exit with the \
+completion phrase (see below).
+
+## Working Rules
+
+1. **Continue from the current repo state** each iteration. Do not repeat the same \
+actions if they already happened.
+2. **Always make progress**: change files, run checks, or ask for specific missing \
+info. If blocked, say exactly what is missing and what you need.
+3. **Be concrete**: report what you changed, what you verified, and what remains.
+4. **No hallucinations**: never claim edits or test results that did not happen.
+5. **Infinite Sessions + plan.md**: if you create `plan.md`, immediately begin \
+implementation in the same response or the next iteration. Do **not** ask the \
+user a follow-up question after writing `plan.md` unless a critical blocker \
+makes implementation impossible.
+
+## Completion Signal
+
+Only when the task is completely finished:
+1. Write a **short summary of all changes** (include files touched).
+2. As the **very last text** in your response, output this *exact* phrase:
+   "<promise>{{PROMISE}}</promise>"
+
+Requirements for the completion phrase:
+- It must be the final characters of the response (no trailing whitespace or text).
+- Do not wrap it in a code block or quotes.
+- Do not output it unless the task is **fully and verifiably** done.
+
+## Critical Rule
+
+Never output the completion phrase to escape the loop. If you are stuck, blocked, \
+or waiting on the user, explain the blocker and keep the loop going.\
+"""
+
+
+def build_system_prompt(promise_phrase: str, template: str | None = None) -> str:
+    source = template if template is not None else _TEMPLATE
+    return source.replace("{{PROMISE}}", promise_phrase)

ralph_any-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: ralph-any
+Version: 0.1.0
+Summary: Ralph Wiggum Loop — iterative AI dev loop via ACP (supports Claude, Gemini, and more)
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: claude-code-acp

ralph_any-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ralph/__init__.py,sha256=EzqzYypFDRxCeFKPx7ms7ocgrwDJ4jJ7Hf3VYXiww4A,287
+ralph/__main__.py,sha256=FdEO4lE2dw6-b4Kk97vznatvCAEuO-6qFwOkWP6en-c,69
+ralph/cli.py,sha256=Gd5GNdS3ErRQvspHrEFJ-Z6Hv8xGHtAKCCJC8vqVe10,3115
+ralph/detect.py,sha256=e99V2o9KECN2fR6sZ7qLghVpdomShCW1Jf_rHjo0og0,180
+ralph/engine.py,sha256=CZFU7GtmKnPIXuN9mx-5iSxcUCyCgUNZkilj1POuTyM,4600
+ralph/prompt.py,sha256=9B5z6zeEyX0Jr6tJ6P7_ahMUVckQySWST51DypGdIDQ,2022
+ralph_any-0.1.0.dist-info/METADATA,sha256=Wsf3QptDpsOKf81ZdYhuuOPT-3pzm0NSR8NfGD1kjZc,350
+ralph_any-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ralph_any-0.1.0.dist-info/entry_points.txt,sha256=39mDVcb7RNWfrI1JwWs7ae3TrLLzwzy6R6EurlGgTfI,41
+ralph_any-0.1.0.dist-info/licenses/LICENSE,sha256=Losvcv3YtvA9lWEq2Ngj6bbejg6sBzR5vxZKb-Db5i0,1079
+ralph_any-0.1.0.dist-info/RECORD,,

ralph_any-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ralph_any-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ralph = ralph.cli:main

ralph_any-0.1.0.dist-info/licenses/LICENSE

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