codexapi 0.5.17__tar.gz → 0.6.0__tar.gz

{codexapi-0.5.17/src/codexapi.egg-info → codexapi-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.5.17
+Version: 0.6.0
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -140,12 +140,20 @@ codexapi ralph --cancel --cwd /path/to/project
 
 Science mode wraps a short task in a science prompt and runs it through the
 Ralph loop. It defaults to `--yolo` and expects progress notes in `SCIENCE.md`.
+Each iteration appends the agent output to `LOGBOOK.md` and the runner extracts
+any improved figures of merit for optional notifications.
 
 ```bash
 codexapi science "hyper-optimize the kernel cycles"
 codexapi science --no-yolo "hyper-optimize the kernel cycles" --max-iterations 3
 ```
 
+Optional Pushover notifications: create `~/.pushover` with two non-empty lines.
+Line 1 is your user or group key, line 2 is the app API token. When this file
+exists, Science will send a notification whenever it detects a new best result,
+including the metric values and percent improvement. Task runs will also send a
+✅/❌ notification with the task summary.
+
 Run a task file across a list file:
 
 ```bash

{codexapi-0.5.17 → codexapi-0.6.0}/README.md

@@ -125,12 +125,20 @@ codexapi ralph --cancel --cwd /path/to/project
 
 Science mode wraps a short task in a science prompt and runs it through the
 Ralph loop. It defaults to `--yolo` and expects progress notes in `SCIENCE.md`.
+Each iteration appends the agent output to `LOGBOOK.md` and the runner extracts
+any improved figures of merit for optional notifications.
 
 ```bash
 codexapi science "hyper-optimize the kernel cycles"
 codexapi science --no-yolo "hyper-optimize the kernel cycles" --max-iterations 3
 ```
 
+Optional Pushover notifications: create `~/.pushover` with two non-empty lines.
+Line 1 is your user or group key, line 2 is the app API token. When this file
+exists, Science will send a notification whenever it detects a new best result,
+including the metric values and percent improvement. Task runs will also send a
+✅/❌ notification with the task summary.
+
 Run a task file across a list file:
 
 ```bash

{codexapi-0.5.17 → codexapi-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.5.17"
+version = "0.6.0"
 description = "Minimal Python API for running the Codex CLI."
 readme = "README.md"
 requires-python = ">=3.8"

{codexapi-0.5.17 → codexapi-0.6.0}/src/codexapi/__init__.py

@@ -2,11 +2,17 @@
 
 from .agent import Agent, agent
 from .foreach import ForeachResult, foreach
+from .pushover import Pushover
+from .ralph import Ralph
+from .science import Science
 from .task import Task, TaskFailed, TaskResult, task, task_result
 
 __all__ = [
     "Agent",
     "ForeachResult",
+    "Pushover",
+    "Ralph",
+    "Science",
     "Task",
     "TaskFailed",
     "TaskResult",
@@ -15,4 +21,4 @@ __all__ = [
     "task",
     "task_result",
 ]
-__version__ = "0.5.17"
+__version__ = "0.6.0"

{codexapi-0.5.17 → codexapi-0.6.0}/src/codexapi/cli.py

@@ -14,7 +14,8 @@ from pathlib import Path
 
 from .agent import Agent, agent
 from .foreach import foreach
-from .ralph import cancel_ralph_loop, run_ralph_loop
+from .ralph import Ralph, cancel_ralph_loop
+from .science import Science
 from .task import DEFAULT_MAX_ITERATIONS, TaskFailed, task
 from .taskfile import TaskFile, load_task_file, task_def_uses_item
 
@@ -26,22 +27,6 @@ _TAIL_MAX_BYTES = 4 * 1024 * 1024
 _TAIL_MIN_LINES = 200
 _PROJECT_LOOP_SLEEP = 30
 _ROLL_OUT_PREFIX = "rollout-"
-_SCIENCE_TEMPLATE = (
-    "Good afternoon! We have a fun task today - take a good look around this repo "
-    "and review all relevant knowledge you have. Our task is to {task}. We're "
-    "working step by step in a scientific manner so if there's a SCIENCE.md read "
-    "that first to understand the progress of the rest of the team so far. Then "
-    "try as hard as you can to find a good path forwards - run as many experiments "
-    "as you want and take your time, we have all night. Note down everything you "
-    "learn that wasn't obvious in a knowledge section in SCIENCE.md and any "
-    "experiments in a similar section. The aim is to move the ball forwards, "
-    "either by getting closer to the goal ruling out a hypothesis that doesn't "
-    "whilst understanding why. Try your best and have fun with this one! If you "
-    "think of several options, pick one and run with it - I will not be available "
-    "to make decisions for you, I give you my full permission to explore and make "
-    "your own best judgement towards our goal! Remember to update SCIENCE.md. "
-    "Good hunting!"
-)
 _TASK_TEMPLATE = (
     "prompt: |\n"
     "  Main task prompt. Required. Use {{item}} for per-item values.\n"
@@ -111,11 +96,6 @@ def _single_line(text):
     return " ".join(text.replace("\r", " ").split())
 
 
-def _science_prompt(task):
-    if not isinstance(task, str) or not task.strip():
-        raise SystemExit("Science task must be a non-empty string.")
-    return _SCIENCE_TEMPLATE.replace("{task}", task.strip())
-
 
 def _create_task_template(path):
     if not isinstance(path, str) or not path.strip():
@@ -1496,7 +1476,7 @@ def main(argv=None):
     if args.command == "ralph":
         if args.max_iterations < 0:
             raise SystemExit("--max-iterations must be >= 0.")
-        run_ralph_loop(
+        Ralph(
             prompt,
             args.cwd,
             args.yolo,
@@ -1504,21 +1484,20 @@ def main(argv=None):
             args.max_iterations,
             args.completion_promise,
             args.ralph_fresh,
-        )
+        )()
         return
     if args.command == "science":
         if args.max_iterations < 0:
             raise SystemExit("--max-iterations must be >= 0.")
-        science_prompt = _science_prompt(prompt)
-        run_ralph_loop(
-            science_prompt,
+        Science(
+            prompt,
             args.cwd,
             args.yolo,
             args.flags,
             args.max_iterations,
             args.completion_promise,
             args.ralph_fresh,
-        )
+        )()
         return
     if args.command == "task":
         if args.project:

codexapi-0.6.0/src/codexapi/pushover.py

@@ -0,0 +1,179 @@
+"""Pushover notification helper."""
+
+import json
+import os
+import sys
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+
+_PUSHOVER_PATH = "~/.pushover"
+_PUSHOVER_URL = "https://api.pushover.net/1/messages.json"
+_MAX_MESSAGE = 1024
+
+_STARTUP_MESSAGE = (
+    "Pushover user and app keys read, notifications for task and science enabled."
+)
+
+
+class Pushover:
+    """Send Pushover notifications when configured."""
+
+    _lock = threading.Lock()
+    _state = {}
+
+    def __init__(self, path=_PUSHOVER_PATH):
+        self.path = os.path.expanduser(path)
+        self._state_ref = self._state_for_path(self.path)
+
+    def ensure_ready(self, announce=True):
+        state = self._state_ref
+        with self._lock:
+            if not state["checked"]:
+                state["checked"] = True
+                if not os.path.exists(self.path):
+                    state["enabled"] = False
+                    return False
+                try:
+                    tokens = _load_pushover_tokens(self.path)
+                except ValueError as exc:
+                    state["error"] = f"Pushover config error: {exc}"
+                    raise SystemExit(state["error"]) from None
+                state["tokens"] = tokens
+                state["enabled"] = True
+            if state["error"]:
+                raise SystemExit(state["error"]) from None
+            if announce and state["enabled"] and not state["announced"]:
+                print(_STARTUP_MESSAGE)
+                state["announced"] = True
+            return state["enabled"]
+
+    def send(self, title, message):
+        tokens = self._get_tokens()
+        if not tokens:
+            return False
+        user_key, app_token = tokens
+        title_text = _single_line(title).strip() or "Codex update"
+        message_text = (message or "").strip()
+        if not message_text:
+            return False
+        message_text = _truncate(message_text, _MAX_MESSAGE)
+        payload = urllib.parse.urlencode(
+            {
+                "token": app_token,
+                "user": user_key,
+                "title": title_text,
+                "message": message_text,
+            }
+        ).encode("utf-8")
+        request = urllib.request.Request(_PUSHOVER_URL, data=payload)
+        try:
+            with urllib.request.urlopen(request, timeout=10) as response:
+                body = response.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            _report_pushover_error(body, exc.code)
+            return False
+        except Exception as exc:
+            _warn(f"Pushover notification failed: {exc}")
+            return False
+        try:
+            data = json.loads(body)
+        except json.JSONDecodeError:
+            _warn("Pushover returned invalid JSON.")
+            return False
+        if data.get("status") != 1:
+            _report_pushover_error(body, None)
+            return False
+        return True
+
+    def _get_tokens(self):
+        if not self.ensure_ready(announce=False):
+            return None
+        return self._state_ref["tokens"]
+
+    @classmethod
+    def _state_for_path(cls, path):
+        state = cls._state.get(path)
+        if state is None:
+            state = {
+                "checked": False,
+                "enabled": False,
+                "tokens": None,
+                "error": None,
+                "announced": False,
+            }
+            cls._state[path] = state
+        return state
+
+
+def _load_pushover_tokens(path):
+    with open(path, "r", encoding="utf-8") as handle:
+        lines = [line.strip() for line in handle if line.strip()]
+    if len(lines) != 2:
+        raise ValueError(
+            f"{path} must contain two non-empty lines: user key then app token"
+        )
+    return lines[0], lines[1]
+
+
+def _report_pushover_error(body, status_code):
+    errors = None
+    try:
+        data = json.loads(body)
+        if isinstance(data, dict):
+            errors = data.get("errors")
+    except json.JSONDecodeError:
+        errors = None
+    message = "Pushover notification failed."
+    if status_code:
+        message = f"{message} HTTP {status_code}."
+    detail = _format_pushover_errors(errors)
+    if detail:
+        message = f"{message} {detail}"
+    _warn(message)
+
+
+def _format_pushover_errors(errors):
+    if not errors:
+        return ""
+    if isinstance(errors, str):
+        errors = [errors]
+    if not isinstance(errors, list):
+        return ""
+    cleaned = [str(error).strip() for error in errors if str(error).strip()]
+    if not cleaned:
+        return ""
+    hint = []
+    lower = " ".join(cleaned).lower()
+    if "user" in lower:
+        hint.append("Check the user key on line 1 of ~/.pushover.")
+    if "token" in lower or "application" in lower:
+        hint.append("Check the app token on line 2 of ~/.pushover.")
+    if "message" in lower:
+        hint.append("Check that the message is not empty or too long.")
+    suffix = " ".join(hint)
+    if suffix:
+        return f"{'; '.join(cleaned)} {suffix}"
+    return "; ".join(cleaned)
+
+
+def _single_line(text):
+    if not text:
+        return ""
+    return " ".join(str(text).replace("\r", " ").split())
+
+
+def _truncate(text, limit):
+    if not text:
+        return ""
+    if len(text) <= limit:
+        return text
+    if limit <= 3:
+        return text[:limit]
+    return text[: limit - 3] + "..."
+
+
+def _warn(message):
+    print(message, file=sys.stderr)