codexapi 0.1.1__tar.gz

codexapi-0.1.1/LICENSE

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

codexapi-0.1.1/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.1
+Name: codexapi
+Version: 0.1.1
+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 codex from python as easily as calling a function with your codex credits instead of the API.
+
+## 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
+
+# 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."))
+```
+
+## API
+
+### `agent(prompt, cwd=None, *, yolo=False, agent="codex") -> 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.
+- `agent` (str): agent backend to use (only `"codex"` is supported).
+
+### `Agent(cwd=None, *, yolo=False, agent="codex", trace_id=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.
+- `trace_id` (str | None): Codex thread id to resume from the first call.
+- `yolo` (bool): pass `--yolo` to Codex when true.
+- `agent` (str): agent backend to use (only `"codex"` is supported).
+
+## 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 `--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.1/README.md

@@ -0,0 +1,66 @@
+# CodexAPI
+
+Use codex from python as easily as calling a function with your codex credits instead of the API.
+
+## 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
+
+# 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."))
+```
+
+## API
+
+### `agent(prompt, cwd=None, *, yolo=False, agent="codex") -> 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.
+- `agent` (str): agent backend to use (only `"codex"` is supported).
+
+### `Agent(cwd=None, *, yolo=False, agent="codex", trace_id=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.
+- `trace_id` (str | None): Codex thread id to resume from the first call.
+- `yolo` (bool): pass `--yolo` to Codex when true.
+- `agent` (str): agent backend to use (only `"codex"` is supported).
+
+## 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 `--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.1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=65,<69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codexapi"
+version = "0.1.1"
+description = "Minimal Python API for running the Codex CLI."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["codex", "agent", "cli", "openai"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+dependencies = []
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

codexapi-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codexapi-0.1.1/src/codexapi/__init__.py

@@ -0,0 +1,6 @@
+"""Minimal Python API for running the Codex CLI."""
+
+from .client import Agent, agent
+
+__all__ = ["Agent", "agent"]
+__version__ = "0.1.1"

codexapi-0.1.1/src/codexapi/client.py

@@ -0,0 +1,172 @@
+"""Codex CLI wrapper used by the codexapi public interface."""
+
+from __future__ import annotations
+
+import json
+import os
+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",
+) -> str:
+    """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).
+
+    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,
+    )
+    return message
+
+
+class Agent:
+    """Stateful Codex session wrapper that resumes the same conversation.
+
+    Example:
+        session = Agent()
+        first = session("Say hi")
+        follow_up = session("What did you just say?")
+    """
+
+    def __init__(
+        self,
+        cwd: Optional[Pathish] = None,
+        *,
+        yolo: bool = False,
+        agent: str = "codex",
+        trace_id: Optional[str] = None,
+    ) -> None:
+        """Create a new session wrapper.
+
+        Args:
+            cwd: Optional working directory for the Codex session.
+            yolo: Whether to pass --yolo to Codex.
+            agent: Agent backend to use (only "codex" is supported).
+            trace_id: Optional Codex thread id to resume from the first call.
+        """
+        _require_codex_agent(agent)
+        self._cwd = cwd
+        self._yolo = yolo
+        self._thread_id: Optional[str] = trace_id
+
+    def __call__(self, prompt: str) -> str:
+        """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,
+        )
+        if 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,
+) -> Tuple[str, Optional[str]]:
+    """Invoke the Codex CLI and return the message plus thread id (if any)."""
+    cmd = [
+        _CODEX_BIN,
+        "exec",
+        "--json",
+        "--color",
+        "never",
+        "--skip-git-repo-check",
+    ]
+    if yolo:
+        cmd.append("--yolo")
+    if cwd is not None:
+        cmd.extend(["--cd", os.fspath(cwd)])
+    if thread_id:
+        cmd.extend(["resume", thread_id, "-"])
+    else:
+        cmd.append("-")
+
+    result = subprocess.run(
+        cmd,
+        input=prompt,
+        text=True,
+        capture_output=True,
+        cwd=os.fspath(cwd) if cwd is not None else None,
+    )
+    if result.returncode != 0:
+        stderr = result.stderr.strip()
+        msg = f"Codex failed with exit code {result.returncode}."
+        if stderr:
+            msg = f"{msg}\n{stderr}"
+        raise RuntimeError(msg)
+
+    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]]:
+    """Extract agent messages and the latest thread id from Codex JSONL output."""
+    thread_id: Optional[str] = None
+    messages: list[str] = []
+    raw_lines: list[str] = []
+
+    for line in output.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            raw_lines.append(line)
+            continue
+
+        if event.get("type") == "thread.started":
+            maybe_thread = event.get("thread_id")
+            if isinstance(maybe_thread, str):
+                thread_id = maybe_thread
+
+        if event.get("type") == "item.completed":
+            item = event.get("item") or {}
+            if item.get("type") == "agent_message":
+                text = item.get("text")
+                if isinstance(text, str):
+                    messages.append(text)
+
+    if not messages:
+        fallback = "\n".join(raw_lines) if raw_lines else output.strip()
+        raise RuntimeError(
+            "Codex returned no agent message. Raw output:\n" + fallback
+        )
+
+    return "\n\n".join(messages), thread_id

codexapi-0.1.1/src/codexapi.egg-info/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.1
+Name: codexapi
+Version: 0.1.1
+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 codex from python as easily as calling a function with your codex credits instead of the API.
+
+## 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
+
+# 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."))
+```
+
+## API
+
+### `agent(prompt, cwd=None, *, yolo=False, agent="codex") -> 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.
+- `agent` (str): agent backend to use (only `"codex"` is supported).
+
+### `Agent(cwd=None, *, yolo=False, agent="codex", trace_id=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.
+- `trace_id` (str | None): Codex thread id to resume from the first call.
+- `yolo` (bool): pass `--yolo` to Codex when true.
+- `agent` (str): agent backend to use (only `"codex"` is supported).
+
+## 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 `--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.1/src/codexapi.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+src/codexapi/__init__.py
+src/codexapi/client.py
+src/codexapi.egg-info/PKG-INFO
+src/codexapi.egg-info/SOURCES.txt
+src/codexapi.egg-info/dependency_links.txt
+src/codexapi.egg-info/top_level.txt

codexapi-0.1.1/src/codexapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

codexapi-0.1.1/src/codexapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+codexapi