codexapi 0.1.3__tar.gz → 0.1.7__tar.gz

{codexapi-0.1.3/src/codexapi.egg-info → codexapi-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.1.3
+Version: 0.1.7
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -56,9 +56,34 @@ 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, full_auto=False) -> str`
+### `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.
@@ -67,9 +92,8 @@ items are filtered out.
 - `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.
-- `full_auto` (bool): enable `--full-auto` for workspace-write and on-request approvals.
 
-### `Agent(cwd=None, yolo=False, thread_id=None, flags=None, full_auto=False)`
+### `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.
@@ -78,9 +102,21 @@ the same conversation and returns only the agent's 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.
-- `full_auto` (bool): enable `--full-auto` for workspace-write and on-request approvals.
 
-### `Task(prompt, max_attempts=10, cwd=None, yolo=False, thread_id=None, flags=None, full_auto=True)`
+### `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
@@ -92,7 +128,6 @@ Runs a Codex task with checker-driven retries. Subclass it and implement
 - `check() -> str | None`: return an error description or `None`/`""`.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
-- `full_auto` (bool): enable `--full-auto` for workspace-write and on-request approvals.
 
 ### `TaskResult(success, summary, attempts, errors, thread_id)`
 
@@ -104,10 +139,19 @@ Simple result object returned by `Task.__call__`.
 - `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.
 

{codexapi-0.1.3 → codexapi-0.1.7}/README.md

@@ -44,9 +44,34 @@ 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, full_auto=False) -> str`
+### `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.
@@ -55,9 +80,8 @@ items are filtered out.
 - `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.
-- `full_auto` (bool): enable `--full-auto` for workspace-write and on-request approvals.
 
-### `Agent(cwd=None, yolo=False, thread_id=None, flags=None, full_auto=False)`
+### `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.
@@ -66,9 +90,21 @@ the same conversation and returns only the agent's 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.
-- `full_auto` (bool): enable `--full-auto` for workspace-write and on-request approvals.
 
-### `Task(prompt, max_attempts=10, cwd=None, yolo=False, thread_id=None, flags=None, full_auto=True)`
+### `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
@@ -80,7 +116,6 @@ Runs a Codex task with checker-driven retries. Subclass it and implement
 - `check() -> str | None`: return an error description or `None`/`""`.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
-- `full_auto` (bool): enable `--full-auto` for workspace-write and on-request approvals.
 
 ### `TaskResult(success, summary, attempts, errors, thread_id)`
 
@@ -92,10 +127,19 @@ Simple result object returned by `Task.__call__`.
 - `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.
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.1.3"
+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.3 → codexapi-0.1.7}/src/codexapi/agent.py

@@ -8,7 +8,7 @@ import subprocess
 _CODEX_BIN = os.environ.get("CODEX_BIN", "codex")
 
 
-def agent(prompt, cwd=None, yolo=False, flags=None, full_auto=False):
+def agent(prompt, cwd=None, yolo=False, flags=None):
     """Run a single Codex turn and return only the agent's message.
 
     Args:
@@ -20,14 +20,7 @@ def agent(prompt, cwd=None, yolo=False, flags=None, full_auto=False):
     Returns:
         The agent's visible response text with reasoning traces removed.
     """
-    message, _thread_id = _run_codex(
-        prompt,
-        cwd,
-        thread_id=None,
-        yolo=yolo,
-        flags=flags,
-        full_auto=full_auto,
-    )
+    message, _thread_id = _run_codex(prompt, cwd, None, yolo, flags)
     return message
 
 
@@ -46,7 +39,6 @@ class Agent:
         yolo=False,
         thread_id=None,
         flags=None,
-        full_auto=False,
     ):
         """Create a new session wrapper.
 
@@ -60,7 +52,6 @@ class Agent:
         self.cwd = cwd
         self._yolo = yolo
         self._flags = flags
-        self._full_auto = full_auto
         self.thread_id = thread_id
 
     def __call__(self, prompt):
@@ -71,14 +62,13 @@ class Agent:
             self.thread_id,
             self._yolo,
             self._flags,
-            self._full_auto,
         )
         if thread_id:
             self.thread_id = thread_id
         return message
 
 
-def _run_codex(prompt, cwd, thread_id, yolo, flags, full_auto):
+def _run_codex(prompt, cwd, thread_id, yolo, flags):
     """Invoke the Codex CLI and return the message plus thread id (if any)."""
     command = [
         _CODEX_BIN,
@@ -90,7 +80,7 @@ def _run_codex(prompt, cwd, thread_id, yolo, flags, full_auto):
     ]
     if yolo:
         command.append("--yolo")
-    if full_auto:
+    else:
         command.append("--full-auto")
     if flags:
         command.extend(shlex.split(flags))