oauth-codex 2.2.0__tar.gz → 2.3.1__tar.gz

{oauth_codex-2.2.0 → oauth_codex-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oauth-codex
-Version: 2.2.0
+Version: 2.3.1
 Summary: Codex OAuth-based Python SDK with a single Client and generate-first API
 Author: Codex
 Requires-Python: >=3.11
@@ -37,16 +37,30 @@ pip install oauth-codex
 from oauth_codex import Client
 
 client = Client()
-text = client.generate("hello")
+text = client.generate([{"role": "user", "content": "hello"}])
 print(text)
 ```
 
+Authenticate immediately during client construction:
+
+```python
+client = Client(authenticate_on_init=True)
+```
+
 ## Image Input
 
 ```python
 text = client.generate(
-    "Describe this image",
-    images=["https://example.com/cat.png", "./local-photo.jpg"],
+    [
+        {
+            "role": "user",
+            "content": [
+                {"type": "input_text", "text": "Describe this image"},
+                {"type": "input_image", "image_url": "https://example.com/cat.png"},
+                {"type": "input_image", "image_url": "data:image/jpeg;base64,..."},
+            ],
+        }
+    ],
 )
 print(text)
 ```
@@ -58,7 +72,7 @@ def add(a: int, b: int) -> dict:
     return {"sum": a + b}
 
 text = client.generate(
-    "Calculate 2+3",
+    [{"role": "user", "content": "Calculate 2+3"}],
     tools=[add],
 )
 print(text)
@@ -78,7 +92,7 @@ def tool(input: ToolInput) -> str:
     return f"Tool received query: {input.query}"
 
 
-text = client.generate("Use the tool", tools=[tool])
+text = client.generate([{"role": "user", "content": "Use the tool"}], tools=[tool])
 print(text)
 ```
 
@@ -100,7 +114,7 @@ class Summary(BaseModel):
 
 client = Client()
 out = client.generate(
-    "Return JSON with title and score",
+    [{"role": "user", "content": "Return JSON with title and score"}],
     output_schema=Summary,
 )
 print(out)  # {"title": "...", "score": 1}
@@ -110,7 +124,7 @@ You can also pass a raw JSON schema object.
 
 ```python
 out = client.generate(
-    "Return {\"ok\": true}",
+    [{"role": "user", "content": "Return {\"ok\": true}"}],
     output_schema={
         "type": "object",
         "properties": {"ok": {"type": "boolean"}},
@@ -131,7 +145,7 @@ from oauth_codex import Client
 
 async def main() -> None:
     client = Client()
-    text = await client.agenerate("hello async")
+    text = await client.agenerate([{"role": "user", "content": "hello async"}])
     print(text)
 
 

{oauth_codex-2.2.0 → oauth_codex-2.3.1}/README.md

@@ -23,16 +23,30 @@ pip install oauth-codex
 from oauth_codex import Client
 
 client = Client()
-text = client.generate("hello")
+text = client.generate([{"role": "user", "content": "hello"}])
 print(text)
 ```
 
+Authenticate immediately during client construction:
+
+```python
+client = Client(authenticate_on_init=True)
+```
+
 ## Image Input
 
 ```python
 text = client.generate(
-    "Describe this image",
-    images=["https://example.com/cat.png", "./local-photo.jpg"],
+    [
+        {
+            "role": "user",
+            "content": [
+                {"type": "input_text", "text": "Describe this image"},
+                {"type": "input_image", "image_url": "https://example.com/cat.png"},
+                {"type": "input_image", "image_url": "data:image/jpeg;base64,..."},
+            ],
+        }
+    ],
 )
 print(text)
 ```
@@ -44,7 +58,7 @@ def add(a: int, b: int) -> dict:
     return {"sum": a + b}
 
 text = client.generate(
-    "Calculate 2+3",
+    [{"role": "user", "content": "Calculate 2+3"}],
     tools=[add],
 )
 print(text)
@@ -64,7 +78,7 @@ def tool(input: ToolInput) -> str:
     return f"Tool received query: {input.query}"
 
 
-text = client.generate("Use the tool", tools=[tool])
+text = client.generate([{"role": "user", "content": "Use the tool"}], tools=[tool])
 print(text)
 ```
 
@@ -86,7 +100,7 @@ class Summary(BaseModel):
 
 client = Client()
 out = client.generate(
-    "Return JSON with title and score",
+    [{"role": "user", "content": "Return JSON with title and score"}],
     output_schema=Summary,
 )
 print(out)  # {"title": "...", "score": 1}
@@ -96,7 +110,7 @@ You can also pass a raw JSON schema object.
 
 ```python
 out = client.generate(
-    "Return {\"ok\": true}",
+    [{"role": "user", "content": "Return {\"ok\": true}"}],
     output_schema={
         "type": "object",
         "properties": {"ok": {"type": "boolean"}},
@@ -117,7 +131,7 @@ from oauth_codex import Client
 
 async def main() -> None:
     client = Client()
-    text = await client.agenerate("hello async")
+    text = await client.agenerate([{"role": "user", "content": "hello async"}])
     print(text)
 
 

{oauth_codex-2.2.0 → oauth_codex-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "oauth-codex"
-version = "2.2.0"
+version = "2.3.1"
 description = "Codex OAuth-based Python SDK with a single Client and generate-first API"
 readme = "README.md"
 requires-python = ">=3.11"

{oauth_codex-2.2.0 → oauth_codex-2.3.1}/src/oauth_codex/__init__.py

@@ -34,6 +34,7 @@ from ._exceptions import (
     UnprocessableEntityError,
 )
 from ._version import __title__, __version__
+from .core_types import listMessage
 
 __all__ = [
     "types",
@@ -41,6 +42,7 @@ __all__ = [
     "__version__",
     "Client",
     "OAuthCodexClient",
+    "listMessage",
     "OAuthCodexError",
     "OpenAIError",
     "APIError",

{oauth_codex-2.2.0 → oauth_codex-2.3.1}/src/oauth_codex/_client.py

@@ -1,11 +1,8 @@
 from __future__ import annotations
 
-import base64
 import asyncio
 import inspect
 import json
-import mimetypes
-from pathlib import Path
 from typing import Any, AsyncIterator, Callable, Iterator, get_type_hints
 
 from pydantic import BaseModel
@@ -15,11 +12,10 @@ from ._engine import OAuthCodexClient as _EngineClient
 from .auth.config import OAuthConfig
 from .core_types import (
     GenerateResult,
-    ImageInput,
-    Message,
     ReasoningEffort,
     ToolCall,
     ToolResult,
+    listMessage,
 )
 from .store import FallbackTokenStore
 from .tooling import build_strict_response_format, callable_to_tool_schema, normalize_tool_output
@@ -30,6 +26,29 @@ StructuredOutputSchema = type[BaseModel] | dict[str, Any]
 
 
 class OAuthCodexClient(SyncAPIClient):
+    """Public single-entry client for oauth-codex.
+
+    This client wraps the OAuth-backed responses engine and exposes a
+    generate-first workflow:
+
+    - `generate` and `agenerate` return final text, or a validated JSON object
+      when `output_schema` is provided.
+    - `stream` and `astream` yield text deltas while still supporting
+      automatic tool-call continuation rounds.
+
+    Public attributes:
+        default_model: Model used when `model` is omitted. Defaults to
+            `"gpt-5.3-codex"`.
+        max_tool_rounds: Maximum number of automatic tool continuation rounds
+            before raising `RuntimeError`.
+
+    Example:
+        from oauth_codex import Client
+
+        client = Client(authenticate_on_init=True)
+        text = client.generate([{"role": "user", "content": "hello"}])
+    """
+
     def __init__(
         self,
         *,
@@ -44,7 +63,28 @@ class OAuthCodexClient(SyncAPIClient):
         on_request_end: Any | None = None,
         on_auth_refresh: Any | None = None,
         on_error: Any | None = None,
+        authenticate_on_init: bool = False,
     ) -> None:
+        """Create a `Client` instance.
+
+        Args:
+            oauth_config: Optional OAuth endpoint/client configuration.
+            token_store: Token persistence backend. If omitted, a fallback
+                keyring/file store is used.
+            base_url: Base URL for Codex backend requests.
+            chatgpt_base_url: Legacy alias for `base_url`. `base_url` takes
+                precedence when both are provided.
+            timeout: Request timeout in seconds.
+            max_retries: Number of retry attempts for retryable failures.
+            compat_storage_dir: Optional local compatibility storage path.
+            on_request_start: Optional callback invoked when a request starts.
+            on_request_end: Optional callback invoked when a request ends.
+            on_auth_refresh: Optional callback invoked after token refresh.
+            on_error: Optional callback invoked when request/auth errors occur.
+            authenticate_on_init: When `True`, perform authentication during
+                client construction. If no stored token exists, interactive
+                login is started immediately.
+        """
         super().__init__()
 
         resolved_base_url = (
@@ -67,30 +107,82 @@ class OAuthCodexClient(SyncAPIClient):
         )
         self.default_model = DEFAULT_MODEL
         self.max_tool_rounds = DEFAULT_MAX_TOOL_ROUNDS
+        if authenticate_on_init:
+            self.authenticate()
 
     def is_authenticated(self) -> bool:
+        """Return whether usable OAuth tokens are currently available.
+
+        Returns:
+            `True` when a token is available, otherwise `False`.
+        """
         return self._engine.is_authenticated()
 
     def is_expired(self, *, leeway_seconds: int = 60) -> bool:
+        """Return whether the current token is expired or near expiry.
+
+        Args:
+            leeway_seconds: Safety margin in seconds added before expiry check.
+
+        Returns:
+            `True` if the token is expired within the given leeway.
+        """
         return self._engine.is_expired(leeway_seconds=leeway_seconds)
 
     def refresh_if_needed(self, *, force: bool = False) -> bool:
+        """Refresh tokens when needed.
+
+        Args:
+            force: Refresh even when token is not currently expired.
+
+        Returns:
+            `True` if refresh happened and succeeded, otherwise `False`.
+        """
         return self._engine.refresh_if_needed(force=force)
 
     async def arefresh_if_needed(self, *, force: bool = False) -> bool:
+        """Async version of `refresh_if_needed`.
+
+        Args:
+            force: Refresh even when token is not currently expired.
+
+        Returns:
+            `True` if refresh happened and succeeded, otherwise `False`.
+        """
         return await self._engine.arefresh_if_needed(force=force)
 
+    def authenticate(self) -> None:
+        """Ensure usable OAuth credentials are available now.
+
+        This loads stored credentials, starts interactive login when missing,
+        and refreshes tokens when expired.
+        """
+        self._engine._ensure_authenticated_sync()
+
     def login(self) -> None:
+        """Run interactive OAuth login flow in the current thread.
+
+        Raises:
+            OAuthCallbackParseError: If callback URL parsing fails.
+            OAuthStateMismatchError: If OAuth state verification fails.
+            TokenExchangeError: If code-to-token exchange fails.
+        """
         self._engine.login()
 
     async def alogin(self) -> None:
+        """Run interactive OAuth login flow without blocking the event loop.
+
+        Raises:
+            OAuthCallbackParseError: If callback URL parsing fails.
+            OAuthStateMismatchError: If OAuth state verification fails.
+            TokenExchangeError: If code-to-token exchange fails.
+        """
         await asyncio.to_thread(self._engine.login)
 
     def generate(
         self,
-        prompt: str | None = None,
+        messages: listMessage | None = None,
         *,
-        images: ImageInput | list[ImageInput] | None = None,
         tools: list[Callable[..., Any]] | None = None,
         model: str | None = None,
         reasoning_effort: ReasoningEffort = "medium",
@@ -100,7 +192,54 @@ class OAuthCodexClient(SyncAPIClient):
         output_schema: StructuredOutputSchema | None = None,
         strict_output: bool | None = None,
     ) -> str | dict[str, Any]:
-        messages = self._build_messages(prompt=prompt, images=images)
+        """Generate a final response with automatic tool execution.
+
+        Args:
+            messages: Non-empty list of response input messages.
+            tools: Optional list of Python callables used for automatic
+                function-calling rounds.
+            model: Optional model override. Uses `default_model` when omitted.
+            reasoning_effort: Reasoning intensity (`"low"`, `"medium"`,
+                `"high"`).
+            temperature: Sampling temperature.
+            top_p: Nucleus sampling probability.
+            max_output_tokens: Maximum generated output tokens.
+            output_schema: Optional structured-output schema. Accepts a
+                Pydantic model type or JSON schema dict.
+            strict_output: Strict schema mode. When `output_schema` is set and
+                `strict_output` is omitted, strict mode is enabled by default.
+
+        Returns:
+            Final text output, or a validated JSON object when `output_schema`
+            is provided.
+
+        Raises:
+            ValueError: If `messages` is missing/empty, or structured output is
+                not valid JSON.
+            TypeError: If `messages` is not a list, `tools` are invalid, or
+                structured output is not a JSON object.
+            RuntimeError: If automatic tool execution exceeds
+                `max_tool_rounds`.
+            pydantic.ValidationError: If a Pydantic `output_schema` fails
+                strict validation.
+
+        Examples:
+            Basic text generation:
+                text = client.generate([{"role": "user", "content": "hello"}])
+
+            Structured output:
+                from pydantic import BaseModel
+
+                class Summary(BaseModel):
+                    title: str
+                    score: int
+
+                data = client.generate(
+                    [{"role": "user", "content": "Return JSON"}],
+                    output_schema=Summary,
+                )
+        """
+        messages = self._normalize_initial_messages(messages)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
         response_format, effective_strict_output = self._resolve_structured_output_options(
             output_schema=output_schema,
@@ -149,9 +288,8 @@ class OAuthCodexClient(SyncAPIClient):
 
     async def agenerate(
         self,
-        prompt: str | None = None,
+        messages: listMessage | None = None,
         *,
-        images: ImageInput | list[ImageInput] | None = None,
         tools: list[Callable[..., Any]] | None = None,
         model: str | None = None,
         reasoning_effort: ReasoningEffort = "medium",
@@ -161,7 +299,41 @@ class OAuthCodexClient(SyncAPIClient):
         output_schema: StructuredOutputSchema | None = None,
         strict_output: bool | None = None,
     ) -> str | dict[str, Any]:
-        messages = self._build_messages(prompt=prompt, images=images)
+        """Async response generation with automatic tool execution.
+
+        Args:
+            messages: Non-empty list of response input messages.
+            tools: Optional list of Python callables used for automatic
+                function-calling rounds.
+            model: Optional model override. Uses `default_model` when omitted.
+            reasoning_effort: Reasoning intensity (`"low"`, `"medium"`,
+                `"high"`).
+            temperature: Sampling temperature.
+            top_p: Nucleus sampling probability.
+            max_output_tokens: Maximum generated output tokens.
+            output_schema: Optional structured-output schema. Accepts a
+                Pydantic model type or JSON schema dict.
+            strict_output: Strict schema mode. When `output_schema` is set and
+                `strict_output` is omitted, strict mode is enabled by default.
+
+        Returns:
+            Final text output, or a validated JSON object when `output_schema`
+            is provided.
+
+        Raises:
+            ValueError: If `messages` is missing/empty, or structured output is
+                not valid JSON.
+            TypeError: If `messages` is not a list, `tools` are invalid, or
+                structured output is not a JSON object.
+            RuntimeError: If automatic tool execution exceeds
+                `max_tool_rounds`.
+            pydantic.ValidationError: If a Pydantic `output_schema` fails
+                strict validation.
+
+        Examples:
+            text = await client.agenerate([{"role": "user", "content": "hello"}])
+        """
+        messages = self._normalize_initial_messages(messages)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
         response_format, effective_strict_output = self._resolve_structured_output_options(
             output_schema=output_schema,
@@ -210,9 +382,8 @@ class OAuthCodexClient(SyncAPIClient):
 
     def stream(
         self,
-        prompt: str | None = None,
+        messages: listMessage | None = None,
         *,
-        images: ImageInput | list[ImageInput] | None = None,
         tools: list[Callable[..., Any]] | None = None,
         model: str | None = None,
         reasoning_effort: ReasoningEffort = "medium",
@@ -222,7 +393,33 @@ class OAuthCodexClient(SyncAPIClient):
         output_schema: StructuredOutputSchema | None = None,
         strict_output: bool | None = None,
     ) -> Iterator[str]:
-        messages = self._build_messages(prompt=prompt, images=images)
+        """Stream text deltas with automatic tool execution rounds.
+
+        Args:
+            messages: Non-empty list of response input messages.
+            tools: Optional list of Python callables used for automatic
+                function-calling rounds.
+            model: Optional model override. Uses `default_model` when omitted.
+            reasoning_effort: Reasoning intensity (`"low"`, `"medium"`,
+                `"high"`).
+            temperature: Sampling temperature.
+            top_p: Nucleus sampling probability.
+            max_output_tokens: Maximum generated output tokens.
+            output_schema: Optional structured-output schema forwarded to the
+                backend. Stream output is still text deltas only.
+            strict_output: Strict schema mode. When `output_schema` is set and
+                `strict_output` is omitted, strict mode is enabled by default.
+
+        Yields:
+            Text delta chunks as they arrive.
+
+        Raises:
+            ValueError: If `messages` is missing/empty.
+            TypeError: If `messages` is not a list or `tools` are invalid.
+            RuntimeError: If automatic tool execution exceeds
+                `max_tool_rounds`.
+        """
+        messages = self._normalize_initial_messages(messages)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
         response_format, effective_strict_output = self._resolve_structured_output_options(
             output_schema=output_schema,
@@ -271,9 +468,8 @@ class OAuthCodexClient(SyncAPIClient):
 
     async def astream(
         self,
-        prompt: str | None = None,
+        messages: listMessage | None = None,
         *,
-        images: ImageInput | list[ImageInput] | None = None,
         tools: list[Callable[..., Any]] | None = None,
         model: str | None = None,
         reasoning_effort: ReasoningEffort = "medium",
@@ -283,7 +479,33 @@ class OAuthCodexClient(SyncAPIClient):
         output_schema: StructuredOutputSchema | None = None,
         strict_output: bool | None = None,
     ) -> AsyncIterator[str]:
-        messages = self._build_messages(prompt=prompt, images=images)
+        """Async stream of text deltas with automatic tool execution rounds.
+
+        Args:
+            messages: Non-empty list of response input messages.
+            tools: Optional list of Python callables used for automatic
+                function-calling rounds.
+            model: Optional model override. Uses `default_model` when omitted.
+            reasoning_effort: Reasoning intensity (`"low"`, `"medium"`,
+                `"high"`).
+            temperature: Sampling temperature.
+            top_p: Nucleus sampling probability.
+            max_output_tokens: Maximum generated output tokens.
+            output_schema: Optional structured-output schema forwarded to the
+                backend. Stream output is still text deltas only.
+            strict_output: Strict schema mode. When `output_schema` is set and
+                `strict_output` is omitted, strict mode is enabled by default.
+
+        Yields:
+            Text delta chunks as they arrive.
+
+        Raises:
+            ValueError: If `messages` is missing/empty.
+            TypeError: If `messages` is not a list or `tools` are invalid.
+            RuntimeError: If automatic tool execution exceeds
+                `max_tool_rounds`.
+        """
+        messages = self._normalize_initial_messages(messages)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
         response_format, effective_strict_output = self._resolve_structured_output_options(
             output_schema=output_schema,
@@ -375,10 +597,10 @@ class OAuthCodexClient(SyncAPIClient):
     def _messages_for_round(
         self,
         *,
-        messages: list[Message],
+        messages: listMessage,
         previous_response_id: str | None,
         tool_results: list[ToolResult] | None,
-    ) -> list[Message]:
+    ) -> listMessage:
         if self._is_tool_continuation_round(
             previous_response_id=previous_response_id,
             tool_results=tool_results,
@@ -386,64 +608,14 @@ class OAuthCodexClient(SyncAPIClient):
             return []
         return messages
 
-    def _build_messages(
-        self,
-        *,
-        prompt: str | None,
-        images: ImageInput | list[ImageInput] | None,
-    ) -> list[Message]:
-        image_urls = self._normalize_images(images)
-
-        if prompt is not None and not isinstance(prompt, str):
-            raise TypeError("prompt must be a string")
-        if prompt is None and not image_urls:
-            raise ValueError("Either prompt or images must be provided")
-
-        content: list[dict[str, Any]] = []
-        if prompt:
-            content.append({"type": "input_text", "text": prompt})
-        for image_url in image_urls:
-            content.append({"type": "input_image", "image_url": image_url})
-
-        if not content:
-            raise ValueError("Either prompt or images must be provided")
-        if len(content) == 1 and content[0]["type"] == "input_text":
-            return [{"role": "user", "content": content[0]["text"]}]
-        return [{"role": "user", "content": content}]
-
-    def _normalize_images(self, images: ImageInput | list[ImageInput] | None) -> list[str]:
-        if images is None:
-            return []
-
-        raw_items: list[ImageInput]
-        if isinstance(images, (str, Path)):
-            raw_items = [images]
-        elif isinstance(images, list):
-            raw_items = images
-        else:
-            raise TypeError("images must be a string/Path or list of string/Path")
-
-        normalized: list[str] = []
-        for item in raw_items:
-            normalized.append(self._coerce_image_to_url(item))
-        return normalized
-
-    def _coerce_image_to_url(self, image: ImageInput) -> str:
-        if isinstance(image, Path):
-            return self._path_to_data_url(image)
-
-        value = image.strip()
-        if value.startswith(("http://", "https://", "data:")):
-            return value
-        return self._path_to_data_url(Path(value).expanduser())
-
-    def _path_to_data_url(self, path: Path) -> str:
-        if not path.is_file():
-            raise FileNotFoundError(f"image file not found: {path}")
-
-        mime_type = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
-        encoded = base64.b64encode(path.read_bytes()).decode("ascii")
-        return f"data:{mime_type};base64,{encoded}"
+    def _normalize_initial_messages(self, messages: listMessage | None) -> listMessage:
+        if messages is None:
+            raise ValueError("`messages` must be a non-empty list")
+        if not isinstance(messages, list):
+            raise TypeError("`messages` must be a non-empty list")
+        if not messages:
+            raise ValueError("`messages` must be a non-empty list")
+        return messages
 
     def _normalize_tools(
         self,