ractogateway.adapters._openai_schema

OpenAI Structured Outputs schema sanitisation utilities.

OpenAI’s Structured Outputs API (response_format with type='json_schema') rejects schemas that contain keywords unsupported by its implementation. This module sanitises Pydantic v2 JSON schemas to conform to OpenAI’s supported subset and provides early sanity-checks that surface problems before an API call is made — giving actionable errors instead of opaque API rejections.

Unsupported keywords stripped automatically

  • default — any type

  • title — any level

  • $schema — top-level only

Number constraints (OpenAI ignores / rejects):

minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf

String constraints:

minLength, maxLength, pattern, format

Array constraints:

minItems, maxItems, uniqueItems

Content encoding:

contentEncoding, contentMediaType

Strict-mode invariants enforced

  • Every object schema’s properties keys all appear in required.

  • Every object schema has "additionalProperties": false.

These two rules are required by OpenAI when "strict": true is set.

ractogateway.adapters._openai_schema.sanitize_for_openai(schema)[source]

Return a sanitised copy of schema for OpenAI Structured Outputs.

Strips every keyword OpenAI does not support and enforces strict-mode invariants (all properties required, additionalProperties: false).

Parameters:

schema (dict[str, Any]) – A JSON Schema dict as produced by pydantic.BaseModel.model_json_schema().

Return type:

dict[str, Any]

Returns:

dict – A new dict with all incompatible keywords removed and strict-mode invariants applied. The original schema dict is not mutated.

ractogateway.adapters._openai_schema.validate_schema_for_openai(schema, *, model_name='model')[source]

Raise ValueError if schema contains constructs that cannot be safely sanitised for OpenAI Structured Outputs.

Call this before sanitisation to get a clear, early error instead of an opaque API rejection from OpenAI.

Parameters:

  • schema (dict[str, Any]) – Raw schema from pydantic.BaseModel.model_json_schema().

  • model_name (str) – Human-readable name included in error messages (use the class name).

Raises:

ValueError – Describing the incompatibility and a suggested fix.

Return type:

None

ractogateway.adapters._openai_schema.build_response_format(model)[source]

Build an OpenAI response_format parameter dict for model.

Generates the Pydantic model’s JSON Schema, validates it for OpenAI compatibility, sanitises it, and returns a response_format value ready to pass directly to an OpenAI Chat Completions call.

Parameters:

model (type[BaseModel]) – A Pydantic BaseModel subclass whose schema will be used for OpenAI Structured Outputs.

Return type:

dict[str, Any]

Returns:

dict – {"type": "json_schema", "json_schema": {"name": ..., "schema": ..., "strict": True}}

Raises:

ValueError – If the model’s schema contains constructs that OpenAI Structured Outputs does not support (raised before any API call is made).