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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oauth-codex
-Version: 2.0.3
+Version: 2.2.0
 Summary: Codex OAuth-based Python SDK with a single Client and generate-first API
 Author: Codex
 Requires-Python: >=3.11
@@ -84,6 +84,44 @@ print(text)
 
 If a tool raises an exception, the SDK forwards it to the model as `{\"error\": ...}` and continues the loop.
 
+## Structured Output (Strict JSON Schema / Pydantic)
+
+`generate` / `agenerate` can produce validated JSON object output via `output_schema`.
+
+```python
+from pydantic import BaseModel
+from oauth_codex import Client
+
+
+class Summary(BaseModel):
+    title: str
+    score: int
+
+
+client = Client()
+out = client.generate(
+    "Return JSON with title and score",
+    output_schema=Summary,
+)
+print(out)  # {"title": "...", "score": 1}
+```
+
+You can also pass a raw JSON schema object.
+
+```python
+out = client.generate(
+    "Return {\"ok\": true}",
+    output_schema={
+        "type": "object",
+        "properties": {"ok": {"type": "boolean"}},
+    },
+)
+print(out)  # {"ok": True}
+```
+
+When `output_schema` is set, strict mode is enabled by default unless `strict_output` is explicitly provided.
+`stream` / `astream` still yield text deltas only; they do not parse final JSON objects.
+
 ## Async
 
 ```python

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

@@ -70,6 +70,44 @@ print(text)
 
 If a tool raises an exception, the SDK forwards it to the model as `{\"error\": ...}` and continues the loop.
 
+## Structured Output (Strict JSON Schema / Pydantic)
+
+`generate` / `agenerate` can produce validated JSON object output via `output_schema`.
+
+```python
+from pydantic import BaseModel
+from oauth_codex import Client
+
+
+class Summary(BaseModel):
+    title: str
+    score: int
+
+
+client = Client()
+out = client.generate(
+    "Return JSON with title and score",
+    output_schema=Summary,
+)
+print(out)  # {"title": "...", "score": 1}
+```
+
+You can also pass a raw JSON schema object.
+
+```python
+out = client.generate(
+    "Return {\"ok\": true}",
+    output_schema={
+        "type": "object",
+        "properties": {"ok": {"type": "boolean"}},
+    },
+)
+print(out)  # {"ok": True}
+```
+
+When `output_schema` is set, strict mode is enabled by default unless `strict_output` is explicitly provided.
+`stream` / `astream` still yield text deltas only; they do not parse final JSON objects.
+
 ## Async
 
 ```python

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

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

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

@@ -22,10 +22,11 @@ from .core_types import (
     ToolResult,
 )
 from .store import FallbackTokenStore
-from .tooling import callable_to_tool_schema, normalize_tool_output
+from .tooling import build_strict_response_format, callable_to_tool_schema, normalize_tool_output
 
 DEFAULT_MODEL = "gpt-5.3-codex"
-DEFAULT_MAX_TOOL_ROUNDS = 8
+DEFAULT_MAX_TOOL_ROUNDS = 16
+StructuredOutputSchema = type[BaseModel] | dict[str, Any]
 
 
 class OAuthCodexClient(SyncAPIClient):
@@ -96,9 +97,15 @@ class OAuthCodexClient(SyncAPIClient):
         temperature: float | None = None,
         top_p: float | None = None,
         max_output_tokens: int | None = None,
-    ) -> str:
+        output_schema: StructuredOutputSchema | None = None,
+        strict_output: bool | None = None,
+    ) -> str | dict[str, Any]:
         messages = self._build_messages(prompt=prompt, images=images)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
+        response_format, effective_strict_output = self._resolve_structured_output_options(
+            output_schema=output_schema,
+            strict_output=strict_output,
+        )
 
         previous_response_id: str | None = None
         tool_results: list[ToolResult] | None = None
@@ -107,9 +114,15 @@ class OAuthCodexClient(SyncAPIClient):
         for _ in range(self.max_tool_rounds):
             result = self._engine.generate(
                 model=self._resolve_model(model),
-                messages=messages,
+                messages=self._messages_for_round(
+                    messages=messages,
+                    previous_response_id=previous_response_id,
+                    tool_results=tool_results,
+                ),
                 tools=normalized_tools,
                 tool_results=tool_results,
+                response_format=response_format,
+                strict_output=effective_strict_output,
                 reasoning={"effort": reasoning_effort},
                 previous_response_id=previous_response_id,
                 temperature=temperature,
@@ -124,7 +137,10 @@ class OAuthCodexClient(SyncAPIClient):
                 output_parts.append(result.text)
 
             if not result.tool_calls:
-                return "".join(output_parts)
+                text = "".join(output_parts)
+                if output_schema is None:
+                    return text
+                return self._parse_structured_output_text(text=text, output_schema=output_schema)
 
             tool_results = self._execute_tool_calls_sync(result.tool_calls, tools_by_name)
             previous_response_id = result.response_id
@@ -142,9 +158,15 @@ class OAuthCodexClient(SyncAPIClient):
         temperature: float | None = None,
         top_p: float | None = None,
         max_output_tokens: int | None = None,
-    ) -> str:
+        output_schema: StructuredOutputSchema | None = None,
+        strict_output: bool | None = None,
+    ) -> str | dict[str, Any]:
         messages = self._build_messages(prompt=prompt, images=images)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
+        response_format, effective_strict_output = self._resolve_structured_output_options(
+            output_schema=output_schema,
+            strict_output=strict_output,
+        )
 
         previous_response_id: str | None = None
         tool_results: list[ToolResult] | None = None
@@ -153,9 +175,15 @@ class OAuthCodexClient(SyncAPIClient):
         for _ in range(self.max_tool_rounds):
             result = await self._engine.agenerate(
                 model=self._resolve_model(model),
-                messages=messages,
+                messages=self._messages_for_round(
+                    messages=messages,
+                    previous_response_id=previous_response_id,
+                    tool_results=tool_results,
+                ),
                 tools=normalized_tools,
                 tool_results=tool_results,
+                response_format=response_format,
+                strict_output=effective_strict_output,
                 reasoning={"effort": reasoning_effort},
                 previous_response_id=previous_response_id,
                 temperature=temperature,
@@ -170,7 +198,10 @@ class OAuthCodexClient(SyncAPIClient):
                 output_parts.append(result.text)
 
             if not result.tool_calls:
-                return "".join(output_parts)
+                text = "".join(output_parts)
+                if output_schema is None:
+                    return text
+                return self._parse_structured_output_text(text=text, output_schema=output_schema)
 
             tool_results = await self._execute_tool_calls_async(result.tool_calls, tools_by_name)
             previous_response_id = result.response_id
@@ -188,9 +219,15 @@ class OAuthCodexClient(SyncAPIClient):
         temperature: float | None = None,
         top_p: float | None = None,
         max_output_tokens: int | None = None,
+        output_schema: StructuredOutputSchema | None = None,
+        strict_output: bool | None = None,
     ) -> Iterator[str]:
         messages = self._build_messages(prompt=prompt, images=images)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
+        response_format, effective_strict_output = self._resolve_structured_output_options(
+            output_schema=output_schema,
+            strict_output=strict_output,
+        )
 
         previous_response_id: str | None = None
         tool_results: list[ToolResult] | None = None
@@ -200,9 +237,15 @@ class OAuthCodexClient(SyncAPIClient):
             round_response_id: str | None = previous_response_id
             events = self._engine.generate_stream(
                 model=self._resolve_model(model),
-                messages=messages,
+                messages=self._messages_for_round(
+                    messages=messages,
+                    previous_response_id=previous_response_id,
+                    tool_results=tool_results,
+                ),
                 tools=normalized_tools,
                 tool_results=tool_results,
+                response_format=response_format,
+                strict_output=effective_strict_output,
                 reasoning={"effort": reasoning_effort},
                 previous_response_id=previous_response_id,
                 temperature=temperature,
@@ -237,9 +280,15 @@ class OAuthCodexClient(SyncAPIClient):
         temperature: float | None = None,
         top_p: float | None = None,
         max_output_tokens: int | None = None,
+        output_schema: StructuredOutputSchema | None = None,
+        strict_output: bool | None = None,
     ) -> AsyncIterator[str]:
         messages = self._build_messages(prompt=prompt, images=images)
         normalized_tools, tools_by_name = self._normalize_tools(tools)
+        response_format, effective_strict_output = self._resolve_structured_output_options(
+            output_schema=output_schema,
+            strict_output=strict_output,
+        )
 
         previous_response_id: str | None = None
         tool_results: list[ToolResult] | None = None
@@ -249,9 +298,15 @@ class OAuthCodexClient(SyncAPIClient):
             round_response_id: str | None = previous_response_id
             events = await self._engine.agenerate_stream(
                 model=self._resolve_model(model),
-                messages=messages,
+                messages=self._messages_for_round(
+                    messages=messages,
+                    previous_response_id=previous_response_id,
+                    tool_results=tool_results,
+                ),
                 tools=normalized_tools,
                 tool_results=tool_results,
+                response_format=response_format,
+                strict_output=effective_strict_output,
                 reasoning={"effort": reasoning_effort},
                 previous_response_id=previous_response_id,
                 temperature=temperature,
@@ -278,6 +333,59 @@ class OAuthCodexClient(SyncAPIClient):
     def _resolve_model(self, model: str | None) -> str:
         return model or self.default_model
 
+    def _resolve_structured_output_options(
+        self,
+        *,
+        output_schema: StructuredOutputSchema | None,
+        strict_output: bool | None,
+    ) -> tuple[dict[str, Any] | None, bool]:
+        effective_strict_output = strict_output if strict_output is not None else bool(output_schema)
+        if output_schema is None:
+            return None, effective_strict_output
+        return build_strict_response_format(output_schema), effective_strict_output
+
+    def _parse_structured_output_text(
+        self,
+        *,
+        text: str,
+        output_schema: StructuredOutputSchema,
+    ) -> dict[str, Any]:
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise ValueError("structured output is not valid JSON") from exc
+
+        if not isinstance(parsed, dict):
+            raise TypeError("structured output must be a JSON object")
+
+        model_type = self._resolve_pydantic_model_type(output_schema)
+        if model_type is None:
+            return parsed
+        validated = model_type.model_validate(parsed, strict=True)
+        return validated.model_dump(mode="json")
+
+    def _is_tool_continuation_round(
+        self,
+        *,
+        previous_response_id: str | None,
+        tool_results: list[ToolResult] | None,
+    ) -> bool:
+        return bool(previous_response_id) and bool(tool_results)
+
+    def _messages_for_round(
+        self,
+        *,
+        messages: list[Message],
+        previous_response_id: str | None,
+        tool_results: list[ToolResult] | None,
+    ) -> list[Message]:
+        if self._is_tool_continuation_round(
+            previous_response_id=previous_response_id,
+            tool_results=tool_results,
+        ):
+            return []
+        return messages
+
     def _build_messages(
         self,
         *,

{oauth_codex-2.0.3 → oauth_codex-2.2.0}/src/oauth_codex/_engine.py

@@ -199,7 +199,15 @@ class OAuthCodexClient:
     ) -> str | GenerateResult:
         self._require_responses_mode(api_mode)
 
-        normalized_messages = self._normalize_messages(prompt=prompt, messages=messages)
+        allows_empty_messages = self._is_tool_continuation_request(
+            previous_response_id=previous_response_id,
+            tool_results=tool_results,
+        )
+        normalized_messages = self._normalize_messages(
+            prompt=prompt,
+            messages=messages,
+            allow_empty_messages=allows_empty_messages,
+        )
         normalized_tools = normalize_tool_inputs(tools)
         normalized_tool_results = self._normalize_tool_results(tool_results)
 
@@ -276,7 +284,15 @@ class OAuthCodexClient:
     ) -> str | GenerateResult:
         self._require_responses_mode(api_mode)
 
-        normalized_messages = self._normalize_messages(prompt=prompt, messages=messages)
+        allows_empty_messages = self._is_tool_continuation_request(
+            previous_response_id=previous_response_id,
+            tool_results=tool_results,
+        )
+        normalized_messages = self._normalize_messages(
+            prompt=prompt,
+            messages=messages,
+            allow_empty_messages=allows_empty_messages,
+        )
         normalized_tools = normalize_tool_inputs(tools)
         normalized_tool_results = self._normalize_tool_results(tool_results)
 
@@ -353,7 +369,15 @@ class OAuthCodexClient:
     ) -> Iterator[str] | Iterator[StreamEvent]:
         self._require_responses_mode(api_mode)
 
-        normalized_messages = self._normalize_messages(prompt=prompt, messages=messages)
+        allows_empty_messages = self._is_tool_continuation_request(
+            previous_response_id=previous_response_id,
+            tool_results=tool_results,
+        )
+        normalized_messages = self._normalize_messages(
+            prompt=prompt,
+            messages=messages,
+            allow_empty_messages=allows_empty_messages,
+        )
         normalized_tools = normalize_tool_inputs(tools)
         normalized_tool_results = self._normalize_tool_results(tool_results)
 
@@ -426,7 +450,15 @@ class OAuthCodexClient:
     ) -> AsyncIterator[str] | AsyncIterator[StreamEvent]:
         self._require_responses_mode(api_mode)
 
-        normalized_messages = self._normalize_messages(prompt=prompt, messages=messages)
+        allows_empty_messages = self._is_tool_continuation_request(
+            previous_response_id=previous_response_id,
+            tool_results=tool_results,
+        )
+        normalized_messages = self._normalize_messages(
+            prompt=prompt,
+            messages=messages,
+            allow_empty_messages=allows_empty_messages,
+        )
         normalized_tools = normalize_tool_inputs(tools)
         normalized_tool_results = self._normalize_tool_results(tool_results)
 
@@ -1392,6 +1424,7 @@ class OAuthCodexClient:
         *,
         prompt: str | None,
         messages: list[Message] | None,
+        allow_empty_messages: bool = False,
     ) -> list[Message]:
         if (prompt is None and messages is None) or (prompt is not None and messages is not None):
             raise ValueError("Provide exactly one of `prompt` or `messages`")
@@ -1399,10 +1432,20 @@ class OAuthCodexClient:
         if prompt is not None:
             return [{"role": "user", "content": prompt}]
 
-        if not isinstance(messages, list) or not messages:
+        if not isinstance(messages, list):
+            raise ValueError("`messages` must be a non-empty list")
+        if not messages and not allow_empty_messages:
             raise ValueError("`messages` must be a non-empty list")
         return [dict(item) for item in messages]
 
+    def _is_tool_continuation_request(
+        self,
+        *,
+        previous_response_id: str | None,
+        tool_results: list[ToolResult] | None,
+    ) -> bool:
+        return bool(previous_response_id) and bool(tool_results)
+
     def _normalize_tool_results(
         self,
         tool_results: list[ToolResult] | None,

{oauth_codex-2.0.3 → oauth_codex-2.2.0}/src/oauth_codex/_version.py

@@ -1,2 +1,2 @@
 __title__ = "oauth-codex"
-__version__ = "2.0.3"
+__version__ = "2.2.0"

{oauth_codex-2.0.3 → oauth_codex-2.2.0}/src/oauth_codex/tooling.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import copy
 import inspect
 import json
 from types import UnionType
@@ -30,6 +31,200 @@ def _pydantic_model_to_schema(model_type: type[Any]) -> dict[str, Any]:
     return {"type": "object"}
 
 
+def _resolve_json_pointer_ref(*, root: dict[str, Any], ref: str) -> dict[str, Any]:
+    if not ref.startswith("#/"):
+        raise ValueError(f"Only local JSON pointer refs are supported, got: {ref}")
+
+    target: Any = root
+    for raw_part in ref[2:].split("/"):
+        part = raw_part.replace("~1", "/").replace("~0", "~")
+        if not isinstance(target, dict) or part not in target:
+            raise ValueError(f"Unresolvable JSON pointer ref: {ref}")
+        target = target[part]
+
+    if not isinstance(target, dict):
+        raise ValueError(f"JSON pointer ref must resolve to an object schema: {ref}")
+    return copy.deepcopy(target)
+
+
+def _ensure_strict_json_schema(
+    json_schema: dict[str, Any],
+    *,
+    path: tuple[str, ...] = (),
+    root: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    if not isinstance(json_schema, dict):
+        raise TypeError(f"Expected dict at path={path!r}, got {type(json_schema).__name__}")
+
+    if root is None:
+        root = json_schema
+
+    defs = json_schema.get("$defs")
+    if defs is not None:
+        if not isinstance(defs, dict):
+            raise TypeError(f"Expected $defs to be a dict at path={path!r}")
+        for def_name, def_schema in defs.items():
+            if not isinstance(def_schema, dict):
+                raise TypeError(f"Expected object schema in $defs[{def_name!r}]")
+            _ensure_strict_json_schema(
+                def_schema,
+                path=(*path, "$defs", str(def_name)),
+                root=root,
+            )
+
+    definitions = json_schema.get("definitions")
+    if definitions is not None:
+        if not isinstance(definitions, dict):
+            raise TypeError(f"Expected definitions to be a dict at path={path!r}")
+        for definition_name, definition_schema in definitions.items():
+            if not isinstance(definition_schema, dict):
+                raise TypeError(f"Expected object schema in definitions[{definition_name!r}]")
+            _ensure_strict_json_schema(
+                definition_schema,
+                path=(*path, "definitions", str(definition_name)),
+                root=root,
+            )
+
+    if json_schema.get("type") == "object" and "additionalProperties" not in json_schema:
+        json_schema["additionalProperties"] = False
+
+    properties = json_schema.get("properties")
+    if properties is not None:
+        if not isinstance(properties, dict):
+            raise TypeError(f"Expected properties to be a dict at path={path!r}")
+        json_schema["required"] = list(properties.keys())
+        json_schema["properties"] = {
+            key: _ensure_strict_json_schema(
+                prop_schema,
+                path=(*path, "properties", str(key)),
+                root=root,
+            )
+            for key, prop_schema in properties.items()
+        }
+
+    items = json_schema.get("items")
+    if items is not None:
+        if isinstance(items, dict):
+            json_schema["items"] = _ensure_strict_json_schema(
+                items,
+                path=(*path, "items"),
+                root=root,
+            )
+        elif isinstance(items, list):
+            json_schema["items"] = [
+                _ensure_strict_json_schema(
+                    entry,
+                    path=(*path, "items", str(i)),
+                    root=root,
+                )
+                for i, entry in enumerate(items)
+            ]
+        else:
+            raise TypeError(f"Expected items to be a dict or list at path={path!r}")
+
+    any_of = json_schema.get("anyOf")
+    if any_of is not None:
+        if not isinstance(any_of, list):
+            raise TypeError(f"Expected anyOf to be a list at path={path!r}")
+        json_schema["anyOf"] = [
+            _ensure_strict_json_schema(
+                variant,
+                path=(*path, "anyOf", str(i)),
+                root=root,
+            )
+            for i, variant in enumerate(any_of)
+        ]
+
+    all_of = json_schema.get("allOf")
+    if all_of is not None:
+        if not isinstance(all_of, list):
+            raise TypeError(f"Expected allOf to be a list at path={path!r}")
+        if len(all_of) == 1:
+            entry = _ensure_strict_json_schema(
+                all_of[0],
+                path=(*path, "allOf", "0"),
+                root=root,
+            )
+            json_schema.update(entry)
+            json_schema.pop("allOf", None)
+        else:
+            json_schema["allOf"] = [
+                _ensure_strict_json_schema(
+                    entry,
+                    path=(*path, "allOf", str(i)),
+                    root=root,
+                )
+                for i, entry in enumerate(all_of)
+            ]
+
+    if json_schema.get("default", object()) is None:
+        json_schema.pop("default", None)
+
+    ref = json_schema.get("$ref")
+    if ref is not None and len(json_schema) > 1:
+        if not isinstance(ref, str):
+            raise TypeError(f"Expected $ref to be a string at path={path!r}")
+        resolved = _resolve_json_pointer_ref(root=root, ref=ref)
+        json_schema.update({**resolved, **json_schema})
+        json_schema.pop("$ref", None)
+        return _ensure_strict_json_schema(json_schema, path=path, root=root)
+
+    return json_schema
+
+
+def build_strict_response_format(output_schema: type[Any] | dict[str, Any]) -> dict[str, Any]:
+    name = "output"
+    description: str | None = None
+
+    if _is_pydantic_model_type(output_schema):
+        model_type = output_schema
+        schema = _pydantic_model_to_schema(model_type)
+        name = getattr(model_type, "__name__", "output") or "output"
+    elif isinstance(output_schema, dict):
+        schema: dict[str, Any]
+        if output_schema.get("type") == "json_schema":
+            nested = output_schema.get("json_schema")
+            if nested is not None:
+                if not isinstance(nested, dict):
+                    raise TypeError("response format json_schema payload must be a dictionary")
+                schema = nested.get("schema")
+                if not isinstance(schema, dict):
+                    raise TypeError("response format json_schema.schema must be a dictionary")
+                name = str(nested.get("name") or output_schema.get("name") or "output")
+                nested_description = nested.get("description")
+                root_description = output_schema.get("description")
+                if isinstance(nested_description, str):
+                    description = nested_description
+                elif isinstance(root_description, str):
+                    description = root_description
+            else:
+                schema = output_schema.get("schema")
+                if not isinstance(schema, dict):
+                    raise TypeError("response format schema must be a dictionary")
+                name = str(output_schema.get("name") or "output")
+                root_description = output_schema.get("description")
+                if isinstance(root_description, str):
+                    description = root_description
+        else:
+            schema = output_schema
+    else:
+        raise TypeError("output_schema must be a pydantic model type or a dictionary")
+
+    strict_schema = _ensure_strict_json_schema(copy.deepcopy(schema))
+    if strict_schema.get("type") != "object":
+        raise ValueError("structured output schema root must be a JSON object")
+
+    response_format: dict[str, Any] = {
+        "type": "json_schema",
+        "name": name,
+        "schema": strict_schema,
+        "strict": True,
+    }
+    if description:
+        response_format["description"] = description
+    return response_format
+
+
 def _python_type_to_schema(annotation: Any) -> dict[str, Any]:
     if annotation is inspect._empty:
         return {"type": "string"}
@@ -199,6 +394,7 @@ def to_responses_tools(
             "parameters": dict(tool.get("parameters", {"type": "object", "properties": {}})),
         }
         if strict_output:
+            item["parameters"] = _ensure_strict_json_schema(copy.deepcopy(item["parameters"]))
             item["strict"] = True
         normalized.append(item)
     return normalized