codexapi 0.1.2__tar.gz → 0.1.7__tar.gz

codexapi-0.1.7/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.1
+Name: codexapi
+Version: 0.1.7
+Summary: Minimal Python API for running the Codex CLI.
+License: MIT
+Keywords: codex,agent,cli,openai
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# CodexAPI
+
+Use OpenAI's codex from python as easily as calling a function with your codex credits instead of the API.
+
+*Note: this project is not affiliated with OpenAI in any way. Thanks for the awesome tools and models though!*
+
+## Requirements
+
+- Codex CLI installed and authenticated (`codex` must be on your PATH).
+- Python 3.8+.
+
+## Install
+
+```bash
+pip install codexapi
+```
+
+## Quickstart
+
+```python
+from codexapi import agent, Agent, Task
+
+# Run one-shot tasks as a function call
+print(agent("Say hello"))
+
+# Run a multi-turn conversation as a session
+session = Agent(cwd="/path/to/project")
+print(session("Summarize this repo."))
+print(session("Now list any risks."))
+
+# Save and resume a session later
+thread_id = session.thread_id
+session2 = Agent(cwd="/path/to/project", thread_id=thread_id)
+print(session2("Continue from where we left off."))
+
+# Define a task with a checker
+class RepoTask(Task):
+    def check(self):
+        # Return an error string if something is wrong, or None/"" if OK
+        return None
+
+task = RepoTask("Summarize this repo.", cwd="/path/to/project")
+result = task()
+print(result.success, result.summary)
+```
+
+## CLI
+
+After installing, use the `codexapi` command:
+
+```bash
+codexapi "Summarize this repo."
+codexapi --cwd /path/to/project "Fix the failing tests."
+echo "Say hello." | codexapi
+```
+
+Task mode exits with code 0 on success and 1 on failure, printing the summary.
+
+Show running sessions and their latest activity:
+
+```bash
+codexapi top
+```
+Press `h` for keys.
+
+Resume a session and print the thread id to stderr:
+
+```bash
+codexapi --thread-id THREAD_ID --print-thread-id "Continue where we left off."
+```
+
+## API
+
+### `agent(prompt, cwd=None, yolo=False, flags=None) -> str`
+
+Runs a single Codex turn and returns only the agent's message. Any reasoning
+items are filtered out.
+
+- `prompt` (str): prompt to send to Codex.
+- `cwd` (str | PathLike | None): working directory for the Codex session.
+- `yolo` (bool): pass `--yolo` to Codex when true.
+- `flags` (str | None): extra CLI flags to pass to Codex.
+
+### `Agent(cwd=None, yolo=False, thread_id=None, flags=None)`
+
+Creates a stateful session wrapper. Calling the instance sends the prompt into
+the same conversation and returns only the agent's message.
+
+- `__call__(prompt) -> str`: send a prompt to Codex and return the message.
+- `thread_id -> str | None`: expose the underlying session id once created.
+- `yolo` (bool): pass `--yolo` to Codex when true.
+- `flags` (str | None): extra CLI flags to pass to Codex.
+
+### `task(prompt, check=None, n=10, cwd=None, yolo=False, flags=None) -> str`
+
+Runs a task with checker-driven retries and returns the success summary.
+Raises `TaskFailed` when the maximum attempts are reached.
+
+- `check` (str | None | False): custom check prompt, default checker, or `False` to skip.
+- `n` (int): maximum number of retries after a failed check.
+
+### `task_result(prompt, check=None, n=10, cwd=None, yolo=False, flags=None) -> TaskResult`
+
+Runs a task with checker-driven retries and returns a `TaskResult` without
+raising `TaskFailed`.
+
+### `Task(prompt, max_attempts=10, cwd=None, yolo=False, thread_id=None, flags=None)`
+
+Runs a Codex task with checker-driven retries. Subclass it and implement
+`check()` to return an error string when the task is incomplete, or return
+`None`/`""` when the task passes.
+
+- `__call__() -> TaskResult`: run the task.
+- `set_up()`: optional setup hook.
+- `tear_down()`: optional cleanup hook.
+- `check() -> str | None`: return an error description or `None`/`""`.
+- `on_success(result)`: optional success hook.
+- `on_failure(result)`: optional failure hook.
+
+### `TaskResult(success, summary, attempts, errors, thread_id)`
+
+Simple result object returned by `Task.__call__`.
+
+- `success` (bool): whether the task completed successfully.
+- `summary` (str): agent summary of what happened.
+- `attempts` (int): how many attempts were used.
+- `errors` (str | None): last checker error, if any.
+- `thread_id` (str | None): Codex thread id for the session.
+
+### `TaskFailed`
+
+Exception raised by `task()` when retries are exhausted.
+
+- `summary` (str): failure summary text.
+- `attempts` (int | None): attempts made when the task failed.
+- `errors` (str | None): last checker error, if any.
+
+## Behavior notes
+
+- Uses `codex exec --json` and parses JSONL events for `agent_message` items.
+- Automatically passes `--skip-git-repo-check` so it can run outside a git repo.
+- Passes `--full-auto` unless `--yolo` is enabled.
+- Passes `--yolo` when enabled (use with care).
+- Raises `RuntimeError` if Codex exits non-zero or returns no agent message.
+
+## Configuration
+
+Set `CODEX_BIN` to point at a non-default Codex binary:
+
+```bash
+export CODEX_BIN=/path/to/codex
+```

codexapi-0.1.7/README.md

@@ -0,0 +1,152 @@
+# CodexAPI
+
+Use OpenAI's codex from python as easily as calling a function with your codex credits instead of the API.
+
+*Note: this project is not affiliated with OpenAI in any way. Thanks for the awesome tools and models though!*
+
+## Requirements
+
+- Codex CLI installed and authenticated (`codex` must be on your PATH).
+- Python 3.8+.
+
+## Install
+
+```bash
+pip install codexapi
+```
+
+## Quickstart
+
+```python
+from codexapi import agent, Agent, Task
+
+# Run one-shot tasks as a function call
+print(agent("Say hello"))
+
+# Run a multi-turn conversation as a session
+session = Agent(cwd="/path/to/project")
+print(session("Summarize this repo."))
+print(session("Now list any risks."))
+
+# Save and resume a session later
+thread_id = session.thread_id
+session2 = Agent(cwd="/path/to/project", thread_id=thread_id)
+print(session2("Continue from where we left off."))
+
+# Define a task with a checker
+class RepoTask(Task):
+    def check(self):
+        # Return an error string if something is wrong, or None/"" if OK
+        return None
+
+task = RepoTask("Summarize this repo.", cwd="/path/to/project")
+result = task()
+print(result.success, result.summary)
+```
+
+## CLI
+
+After installing, use the `codexapi` command:
+
+```bash
+codexapi "Summarize this repo."
+codexapi --cwd /path/to/project "Fix the failing tests."
+echo "Say hello." | codexapi
+```
+
+Task mode exits with code 0 on success and 1 on failure, printing the summary.
+
+Show running sessions and their latest activity:
+
+```bash
+codexapi top
+```
+Press `h` for keys.
+
+Resume a session and print the thread id to stderr:
+
+```bash
+codexapi --thread-id THREAD_ID --print-thread-id "Continue where we left off."
+```
+
+## API
+
+### `agent(prompt, cwd=None, yolo=False, flags=None) -> str`
+
+Runs a single Codex turn and returns only the agent's message. Any reasoning
+items are filtered out.
+
+- `prompt` (str): prompt to send to Codex.
+- `cwd` (str | PathLike | None): working directory for the Codex session.
+- `yolo` (bool): pass `--yolo` to Codex when true.
+- `flags` (str | None): extra CLI flags to pass to Codex.
+
+### `Agent(cwd=None, yolo=False, thread_id=None, flags=None)`
+
+Creates a stateful session wrapper. Calling the instance sends the prompt into
+the same conversation and returns only the agent's message.
+
+- `__call__(prompt) -> str`: send a prompt to Codex and return the message.
+- `thread_id -> str | None`: expose the underlying session id once created.
+- `yolo` (bool): pass `--yolo` to Codex when true.
+- `flags` (str | None): extra CLI flags to pass to Codex.
+
+### `task(prompt, check=None, n=10, cwd=None, yolo=False, flags=None) -> str`
+
+Runs a task with checker-driven retries and returns the success summary.
+Raises `TaskFailed` when the maximum attempts are reached.
+
+- `check` (str | None | False): custom check prompt, default checker, or `False` to skip.
+- `n` (int): maximum number of retries after a failed check.
+
+### `task_result(prompt, check=None, n=10, cwd=None, yolo=False, flags=None) -> TaskResult`
+
+Runs a task with checker-driven retries and returns a `TaskResult` without
+raising `TaskFailed`.
+
+### `Task(prompt, max_attempts=10, cwd=None, yolo=False, thread_id=None, flags=None)`
+
+Runs a Codex task with checker-driven retries. Subclass it and implement
+`check()` to return an error string when the task is incomplete, or return
+`None`/`""` when the task passes.
+
+- `__call__() -> TaskResult`: run the task.
+- `set_up()`: optional setup hook.
+- `tear_down()`: optional cleanup hook.
+- `check() -> str | None`: return an error description or `None`/`""`.
+- `on_success(result)`: optional success hook.
+- `on_failure(result)`: optional failure hook.
+
+### `TaskResult(success, summary, attempts, errors, thread_id)`
+
+Simple result object returned by `Task.__call__`.
+
+- `success` (bool): whether the task completed successfully.
+- `summary` (str): agent summary of what happened.
+- `attempts` (int): how many attempts were used.
+- `errors` (str | None): last checker error, if any.
+- `thread_id` (str | None): Codex thread id for the session.
+
+### `TaskFailed`
+
+Exception raised by `task()` when retries are exhausted.
+
+- `summary` (str): failure summary text.
+- `attempts` (int | None): attempts made when the task failed.
+- `errors` (str | None): last checker error, if any.
+
+## Behavior notes
+
+- Uses `codex exec --json` and parses JSONL events for `agent_message` items.
+- Automatically passes `--skip-git-repo-check` so it can run outside a git repo.
+- Passes `--full-auto` unless `--yolo` is enabled.
+- Passes `--yolo` when enabled (use with care).
+- Raises `RuntimeError` if Codex exits non-zero or returns no agent message.
+
+## Configuration
+
+Set `CODEX_BIN` to point at a non-default Codex binary:
+
+```bash
+export CODEX_BIN=/path/to/codex
+```

{codexapi-0.1.2 → codexapi-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.1.2"
+version = "0.1.7"
 description = "Minimal Python API for running the Codex CLI."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -17,6 +17,9 @@ classifiers = [
 
 dependencies = []
 
+[project.scripts]
+codexapi = "codexapi.cli:main"
+
 [tool.setuptools]
 package-dir = {"" = "src"}
 

codexapi-0.1.7/src/codexapi/__init__.py

@@ -0,0 +1,15 @@
+"""Minimal Python API for running the Codex CLI."""
+
+from .agent import Agent, agent
+from .task import Task, TaskFailed, TaskResult, task, task_result
+
+__all__ = [
+    "Agent",
+    "Task",
+    "TaskFailed",
+    "TaskResult",
+    "agent",
+    "task",
+    "task_result",
+]
+__version__ = "0.1.7"

codexapi-0.1.7/src/codexapi/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

codexapi-0.1.2/src/codexapi/client.py → codexapi-0.1.7/src/codexapi/agent.py

@@ -1,46 +1,26 @@
 """Codex CLI wrapper used by the codexapi public interface."""
 
-from __future__ import annotations
-
 import json
 import os
 import shlex
 import subprocess
-from typing import Optional, Tuple, Union
-
-Pathish = Union[str, os.PathLike]
 
 _CODEX_BIN = os.environ.get("CODEX_BIN", "codex")
 
 
-def agent(
-    prompt: str,
-    cwd: Optional[Pathish] = None,
-    *,
-    yolo: bool = False,
-    agent: str = "codex",
-    flags: Optional[str] = None,
-) -> str:
+def agent(prompt, cwd=None, yolo=False, flags=None):
     """Run a single Codex turn and return only the agent's message.
 
     Args:
         prompt: The user prompt to send to Codex.
         cwd: Optional working directory for the Codex session.
         yolo: Whether to pass --yolo to Codex.
-        agent: Agent backend to use (only "codex" is supported).
         flags: Additional raw CLI flags to pass to Codex.
 
     Returns:
         The agent's visible response text with reasoning traces removed.
     """
-    _require_codex_agent(agent)
-    message, _thread_id = _run_codex(
-        prompt=prompt,
-        cwd=cwd,
-        thread_id=None,
-        yolo=yolo,
-        flags=flags,
-    )
+    message, _thread_id = _run_codex(prompt, cwd, None, yolo, flags)
     return message
 
 
@@ -55,13 +35,11 @@ class Agent:
 
     def __init__(
         self,
-        cwd: Optional[Pathish] = None,
-        *,
-        yolo: bool = False,
-        agent: str = "codex",
-        trace_id: Optional[str] = None,
-        flags: Optional[str] = None,
-    ) -> None:
+        cwd=None,
+        yolo=False,
+        thread_id=None,
+        flags=None,
+    ):
         """Create a new session wrapper.
 
         Args:
@@ -71,41 +49,28 @@ class Agent:
             trace_id: Optional Codex thread id to resume from the first call.
             flags: Additional raw CLI flags to pass to Codex.
         """
-        _require_codex_agent(agent)
-        self._cwd = cwd
+        self.cwd = cwd
         self._yolo = yolo
         self._flags = flags
-        self._thread_id: Optional[str] = trace_id
+        self.thread_id = thread_id
 
-    def __call__(self, prompt: str) -> str:
+    def __call__(self, prompt):
         """Send a prompt to Codex and return only the agent's message."""
         message, thread_id = _run_codex(
-            prompt=prompt,
-            cwd=self._cwd,
-            thread_id=self._thread_id,
-            yolo=self._yolo,
-            flags=self._flags,
+            prompt,
+            self.cwd,
+            self.thread_id,
+            self._yolo,
+            self._flags,
         )
         if thread_id:
-            self._thread_id = thread_id
+            self.thread_id = thread_id
         return message
 
-    @property
-    def thread_id(self) -> Optional[str]:
-        """Return the current Codex session id, if any."""
-        return self._thread_id
 
-
-def _run_codex(
-    *,
-    prompt: str,
-    cwd: Optional[Pathish],
-    thread_id: Optional[str],
-    yolo: bool,
-    flags: Optional[str],
-) -> Tuple[str, Optional[str]]:
+def _run_codex(prompt, cwd, thread_id, yolo, flags):
     """Invoke the Codex CLI and return the message plus thread id (if any)."""
-    cmd = [
+    command = [
         _CODEX_BIN,
         "exec",
         "--json",
@@ -114,22 +79,24 @@ def _run_codex(
         "--skip-git-repo-check",
     ]
     if yolo:
-        cmd.append("--yolo")
+        command.append("--yolo")
+    else:
+        command.append("--full-auto")
     if flags:
-        cmd.extend(shlex.split(flags))
-    if cwd is not None:
-        cmd.extend(["--cd", os.fspath(cwd)])
+        command.extend(shlex.split(flags))
+    if cwd:
+        command.extend(["--cd", os.fspath(cwd)])
     if thread_id:
-        cmd.extend(["resume", thread_id, "-"])
+        command.extend(["resume", thread_id, "-"])
     else:
-        cmd.append("-")
+        command.append("-")
 
     result = subprocess.run(
-        cmd,
+        command,
         input=prompt,
         text=True,
         capture_output=True,
-        cwd=os.fspath(cwd) if cwd is not None else None,
+        cwd=os.fspath(cwd) if cwd else None,
     )
     if result.returncode != 0:
         stderr = result.stderr.strip()
@@ -141,16 +108,11 @@ def _run_codex(
     return _parse_jsonl(result.stdout)
 
 
-def _require_codex_agent(agent_name: str) -> None:
-    if agent_name != "codex":
-        raise ValueError('Only agent="codex" is supported right now.')
-
-
-def _parse_jsonl(output: str) -> Tuple[str, Optional[str]]:
+def _parse_jsonl(output):
     """Extract agent messages and the latest thread id from Codex JSONL output."""
-    thread_id: Optional[str] = None
-    messages: list[str] = []
-    raw_lines: list[str] = []
+    thread_id = None
+    messages = []
+    raw_lines = []
 
     for line in output.splitlines():
         line = line.strip()