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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oauth-codex
-Version: 2.1.0
+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.1.0 → 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.1.0 → oauth_codex-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "oauth-codex"
-version = "2.1.0"
+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.1.0 → 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 = 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
@@ -114,6 +121,8 @@ class OAuthCodexClient(SyncAPIClient):
                 ),
                 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,
@@ -128,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
@@ -146,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
@@ -164,6 +182,8 @@ class OAuthCodexClient(SyncAPIClient):
                 ),
                 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,
@@ -178,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
@@ -196,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
@@ -215,6 +244,8 @@ class OAuthCodexClient(SyncAPIClient):
                 ),
                 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,
@@ -249,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
@@ -268,6 +305,8 @@ class OAuthCodexClient(SyncAPIClient):
                 ),
                 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,
@@ -294,6 +333,37 @@ 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,
         *,

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

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

{oauth_codex-2.1.0 → 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

{oauth_codex-2.1.0 → oauth_codex-2.2.0}/src/oauth_codex.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oauth-codex
-Version: 2.1.0
+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.1.0 → oauth_codex-2.2.0}/src/oauth_codex.egg-info/SOURCES.txt

@@ -58,4 +58,5 @@ src/oauth_codex/types/vector_stores/vector_store_search_response.py
 tests/test_engine_stream_and_continuity.py
 tests/test_generate_async.py
 tests/test_generate_sync.py
-tests/test_public_surface.py
+tests/test_public_surface.py
+tests/test_tooling_strict_schema.py

{oauth_codex-2.1.0 → oauth_codex-2.2.0}/tests/test_generate_async.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import pytest
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError
 
 from conftest import InMemoryTokenStore
 from oauth_codex import Client
@@ -12,6 +12,11 @@ class ToolInput(BaseModel):
     query: str
 
 
+class StructuredOutput(BaseModel):
+    answer: str
+    count: int
+
+
 def _client() -> Client:
     return Client(
         token_store=InMemoryTokenStore(
@@ -117,3 +122,108 @@ async def test_agenerate_supports_single_pydantic_tool_input(monkeypatch: pytest
     assert out == "done"
     tool_results = calls[1]["tool_results"]
     assert tool_results[0].output == {"output": "Tool received query: hello"}
+
+
+@pytest.mark.asyncio
+async def test_agenerate_supports_structured_output_with_pydantic_schema(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = _client()
+    captured: dict[str, object] = {}
+
+    async def fake_agenerate(**kwargs):
+        captured.update(kwargs)
+        return GenerateResult(
+            text='{"answer":"ok","count":1}',
+            tool_calls=[],
+            finish_reason="stop",
+            response_id="resp_1",
+        )
+
+    monkeypatch.setattr(client._engine, "agenerate", fake_agenerate)
+
+    out = await client.agenerate("return json", output_schema=StructuredOutput)
+
+    assert out == {"answer": "ok", "count": 1}
+    response_format = captured["response_format"]
+    assert response_format["type"] == "json_schema"
+    assert response_format["name"] == "StructuredOutput"
+    assert response_format["strict"] is True
+    assert response_format["schema"]["required"] == ["answer", "count"]
+    assert captured["strict_output"] is True
+
+
+@pytest.mark.asyncio
+async def test_agenerate_structured_output_rejects_invalid_json(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = _client()
+
+    async def fake_agenerate(**kwargs):
+        _ = kwargs
+        return GenerateResult(
+            text="not-json",
+            tool_calls=[],
+            finish_reason="stop",
+        )
+
+    monkeypatch.setattr(client._engine, "agenerate", fake_agenerate)
+
+    with pytest.raises(ValueError, match="valid JSON"):
+        await client.agenerate(
+            "return json",
+            output_schema={"type": "object", "properties": {"ok": {"type": "boolean"}}},
+        )
+
+
+@pytest.mark.asyncio
+async def test_agenerate_structured_output_enforces_pydantic_strict_validation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = _client()
+
+    async def fake_agenerate(**kwargs):
+        _ = kwargs
+        return GenerateResult(
+            text='{"answer":"ok","count":"1"}',
+            tool_calls=[],
+            finish_reason="stop",
+        )
+
+    monkeypatch.setattr(client._engine, "agenerate", fake_agenerate)
+
+    with pytest.raises(ValidationError):
+        await client.agenerate("return json", output_schema=StructuredOutput)
+
+
+@pytest.mark.asyncio
+async def test_astream_accepts_output_schema_and_keeps_text_stream(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = _client()
+    calls: list[dict[str, object]] = []
+
+    async def fake_astream(**kwargs):
+        calls.append(kwargs)
+
+        async def events():
+            yield StreamEvent(type="text_delta", delta="{", response_id="resp_1")
+            yield StreamEvent(type="text_delta", delta='"ok":true}', response_id="resp_1")
+            yield StreamEvent(type="done", response_id="resp_1")
+
+        return events()
+
+    monkeypatch.setattr(client._engine, "agenerate_stream", fake_astream)
+
+    out: list[str] = []
+    async for delta in client.astream(
+        "return json",
+        output_schema={"type": "object", "properties": {"ok": {"type": "boolean"}}},
+    ):
+        out.append(delta)
+
+    assert out == ["{", '"ok":true}']
+    assert calls[0]["strict_output"] is True
+    response_format = calls[0]["response_format"]
+    assert response_format["type"] == "json_schema"
+    assert response_format["strict"] is True

{oauth_codex-2.1.0 → oauth_codex-2.2.0}/tests/test_generate_sync.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import pytest
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, ValidationError
 
 from conftest import InMemoryTokenStore
 from oauth_codex import Client
@@ -16,6 +16,11 @@ class ToolInput(BaseModel):
     query: str
 
 
+class StructuredOutput(BaseModel):
+    answer: str
+    count: int
+
+
 def _client() -> Client:
     return Client(
         token_store=InMemoryTokenStore(
@@ -277,6 +282,108 @@ def test_generate_raises_when_tool_round_limit_exceeded(monkeypatch: pytest.Monk
         client.generate("loop", tools=[loop])
 
 
+def test_generate_supports_structured_output_with_pydantic_schema(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = _client()
+    captured: dict[str, object] = {}
+
+    def fake_generate(**kwargs):
+        captured.update(kwargs)
+        return GenerateResult(
+            text='{"answer":"ok","count":1}',
+            tool_calls=[],
+            finish_reason="stop",
+            response_id="resp_1",
+        )
+
+    monkeypatch.setattr(client._engine, "generate", fake_generate)
+
+    out = client.generate("return json", output_schema=StructuredOutput)
+
+    assert out == {"answer": "ok", "count": 1}
+    response_format = captured["response_format"]
+    assert response_format["type"] == "json_schema"
+    assert response_format["name"] == "StructuredOutput"
+    assert response_format["strict"] is True
+    assert response_format["schema"]["type"] == "object"
+    assert response_format["schema"]["additionalProperties"] is False
+    assert response_format["schema"]["required"] == ["answer", "count"]
+    assert captured["strict_output"] is True
+
+
+def test_generate_supports_structured_output_with_raw_schema_dict(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = _client()
+    captured: dict[str, object] = {}
+
+    def fake_generate(**kwargs):
+        captured.update(kwargs)
+        return GenerateResult(
+            text='{"ok":true}',
+            tool_calls=[],
+            finish_reason="stop",
+        )
+
+    monkeypatch.setattr(client._engine, "generate", fake_generate)
+
+    out = client.generate(
+        "return json",
+        output_schema={
+            "type": "object",
+            "properties": {"ok": {"type": "boolean"}},
+        },
+    )
+
+    assert out == {"ok": True}
+    response_format = captured["response_format"]
+    assert response_format["type"] == "json_schema"
+    assert response_format["name"] == "output"
+    assert response_format["strict"] is True
+    assert response_format["schema"]["required"] == ["ok"]
+    assert response_format["schema"]["additionalProperties"] is False
+
+
+def test_generate_structured_output_rejects_invalid_json(monkeypatch: pytest.MonkeyPatch) -> None:
+    client = _client()
+
+    def fake_generate(**kwargs):
+        _ = kwargs
+        return GenerateResult(
+            text="not-json",
+            tool_calls=[],
+            finish_reason="stop",
+        )
+
+    monkeypatch.setattr(client._engine, "generate", fake_generate)
+
+    with pytest.raises(ValueError, match="valid JSON"):
+        client.generate(
+            "return json",
+            output_schema={"type": "object", "properties": {"ok": {"type": "boolean"}}},
+        )
+
+
+def test_generate_structured_output_enforces_pydantic_strict_validation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = _client()
+
+    def fake_generate(**kwargs):
+        _ = kwargs
+        return GenerateResult(
+            text='{"answer":"ok","count":"1"}',
+            tool_calls=[],
+            finish_reason="stop",
+        )
+
+    monkeypatch.setattr(client._engine, "generate", fake_generate)
+
+    with pytest.raises(ValidationError):
+        client.generate("return json", output_schema=StructuredOutput)
+
+
 def test_stream_supports_tool_calls(monkeypatch: pytest.MonkeyPatch) -> None:
     client = _client()
     calls: list[dict[str, object]] = []
@@ -308,3 +415,31 @@ def test_stream_supports_tool_calls(monkeypatch: pytest.MonkeyPatch) -> None:
     assert calls[1]["messages"] == []
     tool_results = calls[1]["tool_results"]
     assert tool_results[0].output == {"sum": 3}
+
+
+def test_stream_accepts_output_schema_and_keeps_text_stream(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = _client()
+    calls: list[dict[str, object]] = []
+
+    def fake_stream(**kwargs):
+        calls.append(kwargs)
+        yield StreamEvent(type="text_delta", delta="{", response_id="resp_1")
+        yield StreamEvent(type="text_delta", delta='"ok":true}', response_id="resp_1")
+        yield StreamEvent(type="done", response_id="resp_1")
+
+    monkeypatch.setattr(client._engine, "generate_stream", fake_stream)
+
+    out = list(
+        client.stream(
+            "return json",
+            output_schema={"type": "object", "properties": {"ok": {"type": "boolean"}}},
+        )
+    )
+
+    assert out == ["{", '"ok":true}']
+    assert calls[0]["strict_output"] is True
+    response_format = calls[0]["response_format"]
+    assert response_format["type"] == "json_schema"
+    assert response_format["strict"] is True

oauth_codex-2.2.0/tests/test_tooling_strict_schema.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import pytest
+
+from oauth_codex.tooling import _ensure_strict_json_schema, build_strict_response_format, to_responses_tools
+
+
+def test_build_strict_response_format_normalizes_recursive_object_schema() -> None:
+    response_format = build_strict_response_format(
+        {
+            "type": "object",
+            "properties": {
+                "nested": {
+                    "type": "object",
+                    "properties": {
+                        "value": {"type": "string"},
+                    },
+                },
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "name": {"type": "string"},
+                        },
+                    },
+                },
+                "choice": {
+                    "anyOf": [
+                        {
+                            "type": "object",
+                            "properties": {
+                                "a": {"type": "string"},
+                            },
+                        },
+                        {
+                            "type": "object",
+                            "properties": {
+                                "b": {"type": "string"},
+                            },
+                        },
+                    ],
+                },
+            },
+        }
+    )
+
+    schema = response_format["schema"]
+    assert schema["type"] == "object"
+    assert schema["additionalProperties"] is False
+    assert schema["required"] == ["nested", "items", "choice"]
+    assert schema["properties"]["nested"]["additionalProperties"] is False
+    assert schema["properties"]["items"]["items"]["additionalProperties"] is False
+    assert schema["properties"]["choice"]["anyOf"][0]["additionalProperties"] is False
+    assert schema["properties"]["choice"]["anyOf"][1]["additionalProperties"] is False
+
+
+def test_build_strict_response_format_inlines_ref_with_sibling_keys() -> None:
+    response_format = build_strict_response_format(
+        {
+            "type": "object",
+            "properties": {
+                "item": {
+                    "$ref": "#/$defs/Item",
+                    "description": "Inline ref",
+                }
+            },
+            "$defs": {
+                "Item": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string", "default": None},
+                    },
+                }
+            },
+        }
+    )
+
+    item_schema = response_format["schema"]["properties"]["item"]
+    assert "$ref" not in item_schema
+    assert item_schema["description"] == "Inline ref"
+    assert item_schema["additionalProperties"] is False
+    assert "default" not in item_schema["properties"]["name"]
+
+
+def test_build_strict_response_format_rejects_invalid_schema_input() -> None:
+    with pytest.raises(TypeError):
+        build_strict_response_format({"type": "json_schema", "schema": "bad"})
+
+    with pytest.raises(ValueError, match="root must be a JSON object"):
+        build_strict_response_format({"type": "array", "items": {"type": "string"}})
+
+
+def test_ensure_strict_json_schema_fails_fast_on_unresolvable_ref() -> None:
+    with pytest.raises(ValueError, match="Unresolvable JSON pointer ref"):
+        _ensure_strict_json_schema(
+            {
+                "type": "object",
+                "properties": {
+                    "item": {
+                        "$ref": "#/$defs/Missing",
+                        "description": "broken",
+                    }
+                },
+            }
+        )
+
+
+def test_to_responses_tools_applies_strict_schema_to_parameters() -> None:
+    tools = [
+        {
+            "type": "function",
+            "name": "demo",
+            "description": "Demo tool",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "payload": {
+                        "type": "object",
+                        "properties": {"value": {"type": "string"}},
+                    }
+                },
+            },
+        }
+    ]
+
+    normalized = to_responses_tools(tools, strict_output=True)
+    assert normalized[0]["strict"] is True
+    assert normalized[0]["parameters"]["additionalProperties"] is False
+    assert normalized[0]["parameters"]["properties"]["payload"]["additionalProperties"] is False