Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(python): emit strict and keep base provider config in OpenAIResponsesProvider

jkomyno15e2b72f3df8
diff --git a/python/composio/core/provider/_openai_responses.py b/python/composio/core/provider/_openai_responses.py
index 887a77181..9aaae9bf2 100644
--- a/python/composio/core/provider/_openai_responses.py
+++ b/python/composio/core/provider/_openai_responses.py
@@ -10,52 +10,97 @@ from openai.types.responses.response import Response
from openai.types.responses.response_output_item import ResponseFunctionToolCall
from composio.core.provider import NonAgenticProvider, ToolCallSession
+from composio.core.provider.base import BaseProviderConfig
from composio.types import Modifiers, Tool, ToolExecutionResponse
-from composio.utils.json_schema import dereference_json_schema
+from composio.utils.logging import get as get_logger
from composio.utils.shared import normalize_tool_arguments
-from composio.utils.strict_schema import to_strict_json_schema
+from composio.utils.strict_schema import omit_null_tool_arguments, to_strict_json_schema
+
+logger = get_logger(__name__)
# Responses API uses a flattened tool structure
ResponsesTool = dict[str, t.Any]
ResponsesToolCollection = list[ResponsesTool]
+# Parameters emitted for a tool without input parameters under strict mode.
+_EMPTY_OBJECT_SCHEMA: dict[str, t.Any] = {
+ "type": "object",
+ "properties": {},
+ "required": [],
+ "additionalProperties": False,
+}
+
class OpenAIResponsesProvider(
NonAgenticProvider[ResponsesTool, ResponsesToolCollection], name="openai_responses"
):
"""OpenAI Responses API Provider class definition."""
- def __init__(self, strict: bool = False) -> None:
+ def __init__(
+ self, strict: bool = False, **kwargs: t.Unpack[BaseProviderConfig]
+ ) -> None:
"""
- :param strict: Normalize wrapped tool parameter schemas for OpenAI
- structured outputs (every object fully required and closed,
- nullable types via ``anyOf``, ``$ref``/``$defs`` inlined).
- Mirrors the TypeScript ``OpenAIResponsesProvider({ strict })``
- option. Defaults to ``False``.
+ :param strict: Emit wrapped tools with ``strict: true`` and normalize
+ their parameter schemas for OpenAI structured outputs (every object
+ fully required and closed, optional properties widened to accept
+ ``null``, ``$ref``/``$defs`` inlined). Mirrors the TypeScript
+ ``OpenAIResponsesProvider({ strict })`` option. Defaults to
+ ``False``.
"""
+ super().__init__(**kwargs)
self.strict = strict
+ # Dereferenced parameter schemas of the tools wrapped under strict
+ # mode, keyed by slug, so tool-call arguments can be reconciled
+ # against the schema the model actually saw.
+ self._strict_input_schemas: dict[str, dict[str, t.Any]] = {}
def wrap_tool(self, tool: Tool) -> ResponsesTool:
"""Wrap a tool for the Responses API format."""
parameters: t.Any = tool.input_parameters or {}
- if (
- self.strict
- and isinstance(parameters, dict)
- and parameters.get("type") == "object"
- ):
- # Structured outputs reject schemas whose nested objects keep
- # optional properties or their own additionalProperties, so the
- # strict contract must be applied at every depth. Inline $refs
- # first; lenient mode keeps upstream schemas with dangling refs
- # usable.
- dereferenced = dereference_json_schema(parameters, on_unresolved="sentinel")
- parameters = to_strict_json_schema(dereferenced).schema
- return {
+ wrapped: ResponsesTool = {
"type": "function",
"name": tool.slug,
"description": tool.description,
"parameters": parameters,
+ "strict": self.strict,
}
+ if not self.strict:
+ return wrapped
+
+ # Structured outputs enforce their contract at every depth: all
+ # properties required, closed objects, no annotation keywords. The
+ # strict rewrite keeps every parameter (optional ones become nullable)
+ # and reports constructs it cannot express; such a tool is sent
+ # without strict mode rather than with a narrower schema.
+ source = parameters if tool.input_parameters else dict(_EMPTY_OBJECT_SCHEMA)
+ strict = to_strict_json_schema(source)
+ if strict.unsupported:
+ reasons = "; ".join(
+ f"{entry.path or '<root>'}: {entry.keyword} ({entry.detail})"
+ for entry in strict.unsupported
+ )
+ logger.warning(
+ 'OpenAIResponsesProvider: tool "%s" is sent without strict mode '
+ "because its schema cannot be expressed as strict structured "
+ "outputs: %s",
+ tool.slug,
+ reasons,
+ )
+ self._strict_input_schemas.pop(tool.slug, None)
+ wrapped["parameters"] = source
+ wrapped["strict"] = False
+ return wrapped
+ if strict.total_changes:
+ logger.debug(
+ 'OpenAIResponsesProvider: strict mode rewrote %d node(s) of tool "%s": %s',
+ strict.total_changes,
+ tool.slug,
+ "; ".join(f"{c.path}: {c.reason}" for c in strict.changes),
+ )
+ self._strict_input_schemas[tool.slug] = strict.source
+ wrapped["parameters"] = strict.schema
+ wrapped["strict"] = True
+ return wrapped
def wrap_tools(self, tools: t.Sequence[Tool]) -> ResponsesToolCollection:
"""Wrap multiple tools for the Responses API format."""
@@ -103,6 +148,12 @@ class OpenAIResponsesProvider(
# tolerates empty / object-shaped payloads too (issue #2406).
slug = tool_call.name
arguments = normalize_tool_arguments(tool_call.arguments)
+ strict_schema = self._strict_input_schemas.get(slug)
+ if strict_schema is not None:
+ # Under strict mode optional parameters are emitted as
+ # required-nullable, so a ``null`` the tool's own schema does not
+ # accept means "omitted".
+ arguments = omit_null_tool_arguments(arguments, strict_schema)
return self.execute_tool_for_target(
target=target,
diff --git a/python/composio/utils/strict_schema.py b/python/composio/utils/strict_schema.py
index 5728ba3eb..c8ade6ea5 100644
--- a/python/composio/utils/strict_schema.py
+++ b/python/composio/utils/strict_schema.py
@@ -3,21 +3,32 @@
Python counterpart of the TypeScript SDK's ``toStrictJsonSchema``
(``ts/packages/core/src/utils/jsonSchema.ts``). OpenAI's structured-output
contract requires *every* object node — not just the root — to list all of its
-properties in ``required``, set ``additionalProperties: False``, avoid
-annotation-only keywords, and express nullable / multi-typed fields via
-``anyOf``. Tool parameter schemas that nest objects or use ``type`` arrays are
-otherwise rejected by the API with a 400.
-
-Every structural change is recorded so callers can surface diagnostics instead
-of failing silently. The input is never mutated. Dereference ``$ref`` pointers
-first (see :func:`composio.utils.json_schema.dereference_json_schema`) so
-definitions under ``$defs`` are normalized too.
+properties in ``required``, set ``additionalProperties: False`` and avoid
+annotation-only keywords. Optional fields are emulated the way OpenAI
+documents: the property stays, becomes required, and is widened to accept
+``null`` (``"type": ["string", "null"]`` or an extra ``anyOf`` branch). Nothing
+is dropped, so the model keeps every parameter it could pass before; the strict
+provider drops a ``null`` the tool's own schema does not accept before
+executing the tool (see :func:`omit_null_tool_arguments`).
+
+Constructs strict mode cannot express — objects that accept arbitrary keys
+(schema-valued or ``True`` ``additionalProperties``, ``patternProperties``,
+property-less free-form objects), ``allOf``, ``prefixItems``, dangling or
+cyclic ``$ref`` pointers and a non-object root — are reported in
+``unsupported`` instead of being rewritten into something narrower; the
+provider sends such a tool without strict mode.
+
+The pipeline is ``dereference_json_schema`` (lenient) → strict rewrite →
+``required`` de-duplication. The input is never mutated and every rewrite is
+recorded (capped at 50 entries; ``total_changes`` carries the real count).
"""
from __future__ import annotations
import typing as t
+from composio.utils.json_schema import dereference_json_schema
+
MAX_NODE_DEPTH = 512
MAX_CHANGES = 50
@@ -25,9 +36,9 @@ MAX_CHANGES = 50
STRICT_STRIP_KEYWORDS = frozenset({"examples", "default"})
# Keywords whose values are literal data, not schemas - never recursed as schemas.
-STRICT_INSTANCE_VALUE_KEYWORDS = frozenset({"const", "enum"})
+INSTANCE_VALUE_KEYWORDS = frozenset({"const", "default", "enum", "examples"})
-STRICT_SCHEMA_SINGLE_KEYS = frozenset(
+SCHEMA_KEYWORDS = frozenset(
{
"additionalItems",
"additionalProperties",
@@ -42,190 +53,298 @@ STRICT_SCHEMA_SINGLE_KEYS = frozenset(
"unevaluatedProperties",
}
)
-STRICT_SCHEMA_ARRAY_KEYS = frozenset({"allOf", "anyOf", "oneOf", "prefixItems"})
-STRICT_SCHEMA_MAP_KEYS = frozenset(
+SCHEMA_ARRAY_KEYWORDS = frozenset({"allOf", "anyOf", "oneOf", "prefixItems"})
+SCHEMA_MAP_KEYWORDS = frozenset(
{"$defs", "definitions", "dependentSchemas", "patternProperties", "properties"}
)
+# Keywords OpenAI structured outputs reject and that have no lossless rewrite.
+STRICT_UNSUPPORTED_KEYWORDS = ("allOf", "prefixItems")
+
+StrictSchemaChangeReason = t.Literal[
+ "optional-property-nullable",
+ "unsupported-keyword-stripped",
+ "one-of-converted",
+]
+
class StrictSchemaChange(t.NamedTuple):
- """A single structural change applied by :func:`to_strict_json_schema`."""
+ """A single lossless rewrite applied by :func:`to_strict_json_schema`."""
path: str
- reason: str
+ reason: StrictSchemaChangeReason
detail: str = ""
+class StrictSchemaIncompatibility(t.NamedTuple):
+ """A construct strict structured outputs cannot express."""
+
+ path: str
+ keyword: str
+ detail: str
+
+
class StrictJsonSchemaResult(t.NamedTuple):
- """Normalized schema plus a change log."""
+ """Result of :func:`to_strict_json_schema`."""
- schema: t.Any
+ schema: dict[str, t.Any]
+ """The strict schema; only usable when ``unsupported`` is empty."""
+ source: dict[str, t.Any]
+ """The dereferenced input optionality was decided against."""
changes: list[StrictSchemaChange]
+ total_changes: int
+ unsupported: list[StrictSchemaIncompatibility]
def _join_path(parent: str, key: str) -> str:
return f"{parent}.{key}" if parent else key
-def _split_type_array(
- node: dict[str, t.Any], path: str, changes: list[StrictSchemaChange]
-) -> dict[str, t.Any]:
- type_values = node["type"]
- branches = [
- {"type": "null"} if value == "null" else {**node, "type": value}
- for value in type_values
- ]
- rest = {key: value for key, value in node.items() if key != "type"}
- reason = (
- "nullable-type-converted" if "null" in type_values else "multi-type-converted"
- )
- if len(changes) < MAX_CHANGES:
- changes.append(
- StrictSchemaChange(
- path=path,
- reason=reason,
- detail=f"type [{', '.join(str(value) for value in type_values)}] converted to anyOf",
- )
- )
- return {**rest, "anyOf": branches}
-
-
-def _walk(
- value: t.Any,
- mode: str,
- depth: int,
- path: str,
- changes: list[StrictSchemaChange],
-) -> t.Any:
+def _widen_to_nullable(node: dict[str, t.Any]) -> dict[str, t.Any]:
+ """Accept ``null`` without placing ``type`` beside ``anyOf``."""
+ any_of = node.get("anyOf")
+ if isinstance(any_of, list):
+ if any(isinstance(b, dict) and b.get("type") == "null" for b in any_of):
+ return node
+ return {**node, "anyOf": [*any_of, {"type": "null"}]}
+ node_type = node.get("type")
+ if isinstance(node_type, str):
+ return node if node_type == "null" else {**node, "type": [node_type, "null"]}
+ if isinstance(node_type, list):
+ return node if "null" in node_type else {**node, "type": [*node_type, "null"]}
+ annotations: dict[str, t.Any] = {
+ k: node[k] for k in ("description", "title") if k in node
+ }
+ rest = {k: v for k, v in node.items() if k not in annotations}
+ if not rest:
+ return node
+ return {**annotations, "anyOf": [rest, {"type": "null"}]}
+
+
+def _schema_accepts_null(node: t.Any) -> bool:
+ """Whether a (dereferenced) schema node accepts ``null`` as an instance."""
+ if not isinstance(node, dict):
+ return True
+ node_type = node.get("type")
+ if isinstance(node_type, str):
+ return node_type == "null"
+ if isinstance(node_type, list):
+ return "null" in node_type
+ if isinstance(node.get("enum"), list):
+ return None in node["enum"]
+ if "const" in node:
+ return node["const"] is None
+ for keyword in ("anyOf", "oneOf"):
+ branches = node.get(keyword)
+ if isinstance(branches, list):
+ return any(_schema_accepts_null(b) for b in branches)
+ return True
+
+
+def _dedupe_required(value: t.Any, is_schema: bool = True, depth: int = 0) -> t.Any:
if depth > MAX_NODE_DEPTH:
raise ValueError(
f"JSON Schema exceeds maximum nesting depth of {MAX_NODE_DEPTH}"
)
-
if isinstance(value, list):
- item_mode = "schema" if mode == "schema-array" else "value"
- return [
- _walk(item, item_mode, depth + 1, f"{path}[{index}]", changes)
- for index, item in enumerate(value)
- ]
-
- if not isinstance(value, dict) or mode == "value":
+ return [_dedupe_required(item, is_schema, depth + 1) for item in value]
+ if not isinstance(value, dict):
return value
+ clone: dict[str, t.Any] = {}
+ for key, child in value.items():
+ if is_schema and key == "required" and isinstance(child, list):
+ clone[key] = list(dict.fromkeys(child))
+ else:
+ clone[key] = _dedupe_required(
+ child, is_schema and key not in INSTANCE_VALUE_KEYWORDS, depth + 1
+ )
+ return clone
- node: dict[str, t.Any] = value
-
- # Nullable / multi-type arrays must become anyOf before anything else so
- # the generated branches flow through the normal recursion below.
- if isinstance(node.get("type"), list):
- node = _split_type_array(node, path, changes)
-
- stripped: dict[str, t.Any] = {}
- for key, child in node.items():
- if key in STRICT_STRIP_KEYWORDS:
- if len(changes) < MAX_CHANGES:
- changes.append(
- StrictSchemaChange(
- path=path,
- reason="annotation-keyword-stripped",
- detail=f'keyword "{key}" removed',
+
+class _Walker:
+ def __init__(self) -> None:
+ self.changes: list[StrictSchemaChange] = []
+ self.total_changes = 0
+ self.unsupported: list[StrictSchemaIncompatibility] = []
+
+ def record(self, path: str, reason: StrictSchemaChangeReason, detail: str) -> None:
+ self.total_changes += 1
+ if len(self.changes) < MAX_CHANGES:
+ self.changes.append(StrictSchemaChange(path, reason, detail))
+
+ def reject(self, path: str, keyword: str, detail: str) -> None:
+ self.unsupported.append(StrictSchemaIncompatibility(path, keyword, detail))
+
+ def walk_children(
+ self, node: dict[str, t.Any], mode: str, depth: int, path: str
+ ) -> dict[str, t.Any]:
+ clone: dict[str, t.Any] = {}
+ for key, child in node.items():
+ child_mode = "value"
+ if mode == "schema-map":
+ child_mode = "schema"
+ elif mode == "schema" and key not in INSTANCE_VALUE_KEYWORDS:
+ if key in SCHEMA_MAP_KEYWORDS:
+ child_mode = "schema-map"
+ elif key in SCHEMA_ARRAY_KEYWORDS or (
+ key == "items" and isinstance(child, list)
+ ):
+ child_mode = "schema-array"
+ elif key in SCHEMA_KEYWORDS or key == "items":
+ child_mode = "schema"
+
+ if child_mode == "schema-map" and isinstance(child, dict):
+ clone[key] = {
+ name: self.walk(
+ sub_schema,
+ "schema",
+ depth + 1,
+ _join_path(_join_path(path, key), name),
)
- )
- continue
- stripped[key] = child
- node = stripped
-
- has_properties_keyword = isinstance(node.get("properties"), dict)
- if not (has_properties_keyword or node.get("type") == "object"):
- return _walk_children(node, mode, depth, path, changes)
-
- properties = node["properties"] if has_properties_keyword else {}
- declared_required = [
- entry for entry in node.get("required", []) if isinstance(entry, str)
- ]
- keep_only_required = len(declared_required) > 0
- kept = set(declared_required if keep_only_required else properties.keys())
-
- next_properties: dict[str, t.Any] = {}
- for name, property_schema in properties.items():
- child_path = _join_path(path, f"properties.{name}")
- if name in kept:
- next_properties[name] = _walk(
- property_schema, "schema", depth + 1, child_path, changes
+ for name, sub_schema in child.items()
+ }
+ continue
+ clone[key] = self.walk(child, child_mode, depth + 1, _join_path(path, key))
+ return clone
+
+ def walk(self, value: t.Any, mode: str, depth: int, path: str) -> t.Any:
+ if depth > MAX_NODE_DEPTH:
+ raise ValueError(
+ f"JSON Schema exceeds maximum nesting depth of {MAX_NODE_DEPTH}"
)
- elif len(changes) < MAX_CHANGES:
- changes.append(
- StrictSchemaChange(
- path=child_path,
- reason="non-required-property-dropped",
- detail=f'property "{name}" is not listed in "required"',
+ if isinstance(value, list):
+ item_mode = "schema" if mode == "schema-array" else "value"
+ return [
+ self.walk(item, item_mode, depth + 1, f"{path}[{index}]")
+ for index, item in enumerate(value)
+ ]
+ if not isinstance(value, dict) or mode == "value":
+ return value
+
+ node: dict[str, t.Any] = {}
+ for key, child in value.items():
+ if key in STRICT_STRIP_KEYWORDS:
+ self.record(
+ path, "unsupported-keyword-stripped", f'keyword "{key}" removed'
)
+ continue
+ node[key] = child
+ if isinstance(node.get("oneOf"), list) and "anyOf" not in node:
+ node["anyOf"] = node.pop("oneOf")
+ self.record(path, "one-of-converted", "oneOf became anyOf")
+ for keyword in STRICT_UNSUPPORTED_KEYWORDS:
+ if keyword in node:
+ self.reject(path, keyword, f'"{keyword}" has no strict-mode equivalent')
+
+ out = self.walk_children(node, mode, depth, path)
+
+ node_type = out.get("type")
+ declares_object = node_type == "object" or (
+ isinstance(node_type, list) and "object" in node_type
+ )
+ if not declares_object and not isinstance(out.get("properties"), dict):
+ return out
+
+ properties: dict[str, t.Any] = dict(out.get("properties") or {})
+ declared_required = {
+ entry for entry in out.get("required") or [] if isinstance(entry, str)
+ }
+ for name, property_schema in properties.items():
+ if name in declared_required or not isinstance(property_schema, dict):
+ continue
+ properties[name] = _widen_to_nullable(property_schema)
+ self.record(
+ _join_path(path, f"properties.{name}"),
+ "optional-property-nullable",
+ f'property "{name}" is now required and accepts null',
)
- managed = ("type", "properties", "required", "additionalProperties")
- rest = {key: child for key, child in node.items() if key not in managed}
+ additional = out.get("additionalProperties")
+ accepts_dynamic_keys = additional is True or isinstance(additional, dict)
+ if accepts_dynamic_keys:
+ self.reject(path, "additionalProperties", "object accepts arbitrary keys")
+ elif "patternProperties" in out:
+ self.reject(
+ path, "patternProperties", "object accepts pattern-matched keys"
+ )
+ elif not properties and "additionalProperties" not in out:
+ self.reject(path, "properties", "free-form object accepts arbitrary keys")
- return {
- **_walk_children(rest, "schema", depth, path, changes),
- "type": "object",
- "properties": next_properties,
- "required": list(next_properties.keys()),
- "additionalProperties": False,
- }
+ result = {**out}
+ if "type" not in result:
+ result["type"] = "object"
+ result["properties"] = properties
+ result["required"] = list(properties.keys())
+ if not accepts_dynamic_keys:
+ result["additionalProperties"] = False
+ return result
-def _walk_children(
- node: dict[str, t.Any],
- mode: str,
- depth: int,
- path: str,
- changes: list[StrictSchemaChange],
-) -> dict[str, t.Any]:
- clone: dict[str, t.Any] = {}
- for key, child in node.items():
- child_mode = "value"
- if mode == "schema-map":
- child_mode = "schema"
- elif mode == "schema" and key not in STRICT_INSTANCE_VALUE_KEYWORDS:
- if key in STRICT_SCHEMA_MAP_KEYS:
- child_mode = "schema-map"
- elif key in STRICT_SCHEMA_ARRAY_KEYS or (
- key == "items" and isinstance(child, list)
- ):
- child_mode = "schema-array"
- elif key in STRICT_SCHEMA_SINGLE_KEYS or key == "items":
- child_mode = "schema"
+def to_strict_json_schema(schema: t.Any) -> StrictJsonSchemaResult:
+ """Normalize a tool parameter schema for OpenAI structured outputs.
- if child_mode == "schema-map" and isinstance(child, dict):
- map_clone: dict[str, t.Any] = {}
- for name, sub_schema in child.items():
- map_clone[name] = _walk(
- sub_schema,
- "schema",
- depth + 1,
- _join_path(_join_path(path, key), name),
- changes,
- )
- clone[key] = map_clone
- continue
- clone[key] = _walk(child, child_mode, depth + 1, _join_path(path, key), changes)
- return clone
+ Applies the strict contract at every depth: every object lists all of its
+ properties in ``required`` and is closed; optional properties are widened
+ to accept ``null`` instead of being dropped; ``oneOf`` becomes ``anyOf``;
+ ``default`` and ``examples`` are stripped; internal ``$ref`` pointers are
+ inlined first and ``required`` arrays are de-duplicated last. Constructs
+ strict mode cannot express are listed in ``unsupported``; when that list
+ is non-empty the returned ``schema`` must not be sent as strict.
+ :param schema: The JSON schema to normalize; never mutated.
+ :return: A :class:`StrictJsonSchemaResult`.
+ """
+ walker = _Walker()
+ dereferenced = dereference_json_schema(
+ schema,
+ on_unresolved="sentinel",
+ on_replace=lambda ref, _reason: walker.reject(
+ "", "$ref", f'unresolved $ref "{ref}"'
+ ),
+ )
+ normalized = _dedupe_required(walker.walk(dereferenced, "schema", 0, ""))
+ if not isinstance(normalized, dict) or normalized.get("type") != "object":
+ walker.reject("", "type", "root must be a non-nullable object")
+ return StrictJsonSchemaResult(
+ schema=normalized,
+ source=dereferenced,
+ changes=walker.changes,
+ total_changes=walker.total_changes,
+ unsupported=walker.unsupported,
+ )
-def to_strict_json_schema(schema: t.Any) -> StrictJsonSchemaResult:
- """Normalize a JSON Schema for OpenAI structured outputs.
- Applies the strict contract at every depth:
+def omit_null_tool_arguments(
+ arguments: dict[str, t.Any], schema: t.Any
+) -> dict[str, t.Any]:
+ """Drop ``None``-valued arguments the tool's own schema does not accept.
+
+ Strict structured outputs cannot express optional parameters, so
+ :func:`to_strict_json_schema` makes every parameter required and nullable.
+ The model then sends ``null`` for a parameter it would otherwise have
+ omitted; forwarding it to the tool would fail validation against the
+ tool's real schema, so it is treated as "omitted". A ``null`` the original
+ schema accepts is kept. ``schema`` is the dereferenced tool schema
+ (``StrictJsonSchemaResult.source``). The input is not mutated.
+ """
+ return t.cast(dict[str, t.Any], _omit_nulls(arguments, schema))
- - Objects with a non-empty ``required`` keep only those properties;
- objects without one keep every property but require them all.
- - ``type`` arrays become ``anyOf`` branches with an explicit null variant.
- - Annotation keywords (``examples``, ``default``) are stripped.
- - Composition keywords, array items and property maps normalize recursively.
- :param schema: The JSON schema to normalize; never mutated.
- :return: A :class:`StrictJsonSchemaResult` with the normalized schema and
- a change log capped at 50 entries.
- """
- changes: list[StrictSchemaChange] = []
- normalized = _walk(schema, "schema", 0, "", changes)
- return StrictJsonSchemaResult(schema=normalized, changes=changes)
+def _omit_nulls(value: t.Any, schema: t.Any) -> t.Any:
+ node = schema if isinstance(schema, dict) else {}
+ if isinstance(value, list):
+ items = node.get("items") if isinstance(node.get("items"), dict) else None
+ return [_omit_nulls(item, items) for item in value]
+ if not isinstance(value, dict):
+ return value
+ declared = node.get("properties")
+ properties: dict[str, t.Any] = declared if isinstance(declared, dict) else {}
+ clone: dict[str, t.Any] = {}
+ for key, child in value.items():
+ property_schema = properties.get(key)
+ if child is None:
+ if property_schema is None or _schema_accepts_null(property_schema):
+ clone[key] = child
+ continue
+ clone[key] = _omit_nulls(child, property_schema)
+ return clone
diff --git a/python/tests/test_strict_schema.py b/python/tests/test_strict_schema.py
index df82910b6..a1158f9fd 100644
--- a/python/tests/test_strict_schema.py
+++ b/python/tests/test_strict_schema.py
@@ -1,8 +1,39 @@
"""Tests for composio.utils.strict_schema and its use by OpenAIResponsesProvider."""
+import copy
+import json
+
import pytest
-from composio.utils.strict_schema import to_strict_json_schema
+from composio.utils.strict_schema import omit_null_tool_arguments, to_strict_json_schema
+
+
+def assert_strict_shape(node, path=""):
+ """Structural invariants OpenAI enforces on every node of a strict schema."""
+ if isinstance(node, list):
+ for index, item in enumerate(node):
+ assert_strict_shape(item, f"{path}[{index}]")
+ return
+ if not isinstance(node, dict):
+ return
+ if "anyOf" in node:
+ assert "type" not in node, f"{path}: type beside anyOf"
+ for keyword in ("default", "examples", "oneOf", "patternProperties"):
+ assert keyword not in node, f"{path}: {keyword}"
+ node_type = node.get("type")
+ is_object = node_type == "object" or (
+ isinstance(node_type, list) and "object" in node_type
+ )
+ if is_object or "properties" in node:
+ properties = node.get("properties") or {}
+ assert node.get("required") == list(properties.keys()), f"{path}: required"
+ assert node.get("additionalProperties") is False, (
+ f"{path}: additionalProperties"
+ )
+ for key, child in node.items():
+ if key in ("enum", "const"):
+ continue
+ assert_strict_shape(child, f"{path}.{key}" if path else key)
class TestToStrictJsonSchema:
@@ -19,7 +50,7 @@ class TestToStrictJsonSchema:
assert result.schema == schema
assert result.changes == []
- def test_drops_nested_non_required_properties_and_closes_every_object(self):
+ def test_keeps_optional_properties_required_and_nullable(self):
result = to_strict_json_schema(
{
"type": "object",
@@ -28,7 +59,7 @@ class TestToStrictJsonSchema:
"type": "object",
"properties": {
"url": {"type": "string"},
- "note": {"type": "string"},
+ "note": {"type": "string", "description": "optional note"},
},
"required": ["url"],
}
@@ -42,23 +73,25 @@ class TestToStrictJsonSchema:
"properties": {
"cfg": {
"type": "object",
- "properties": {"url": {"type": "string"}},
- "required": ["url"],
+ "properties": {
+ "url": {"type": "string"},
+ "note": {
+ "type": ["string", "null"],
+ "description": "optional note",
+ },
+ },
+ "required": ["url", "note"],
"additionalProperties": False,
}
},
"required": ["cfg"],
"additionalProperties": False,
}
- dropped = [
- change
- for change in result.changes
- if change.reason == "non-required-property-dropped"
+ assert [(c.path, c.reason) for c in result.changes] == [
+ ("properties.cfg.properties.note", "optional-property-nullable")
]
- assert len(dropped) == 1
- assert "note" in dropped[0].detail
- def test_requires_every_property_when_required_is_missing(self):
+ def test_requires_and_widens_every_property_when_required_is_missing(self):
result = to_strict_json_schema(
{
"type": "object",
@@ -66,31 +99,74 @@ class TestToStrictJsonSchema:
}
)
- assert result.schema["required"] == ["a", "b"]
- assert result.schema["additionalProperties"] is False
+ assert result.schema == {
+ "type": "object",
+ "properties": {
+ "a": {"type": ["string", "null"]},
+ "b": {"type": ["number", "null"]},
+ },
+ "required": ["a", "b"],
+ "additionalProperties": False,
+ }
- def test_converts_nullable_type_arrays_into_any_of(self):
+ def test_keeps_nullable_type_arrays_and_closes_nullable_objects(self):
result = to_strict_json_schema(
{
"type": "object",
"properties": {
- "id": {"type": ["string", "null"], "description": "identifier"}
+ "id": {"type": ["string", "null"], "description": "identifier"},
+ "cfg": {
+ "type": ["object", "null"],
+ "properties": {"a": {"type": "string"}},
+ "required": ["a"],
+ },
+ "xs": {"type": ["array", "null"], "items": {"type": "string"}},
},
- "required": ["id"],
+ "required": ["id", "cfg", "xs"],
}
)
+ assert result.schema["properties"]["cfg"] == {
+ "type": ["object", "null"],
+ "properties": {"a": {"type": "string"}},
+ "required": ["a"],
+ "additionalProperties": False,
+ }
assert result.schema["properties"]["id"] == {
- "anyOf": [
- {"type": "string", "description": "identifier"},
- {"type": "null"},
- ],
+ "type": ["string", "null"],
"description": "identifier",
}
- reasons = {change.reason for change in result.changes}
- assert "nullable-type-converted" in reasons
+ assert result.changes == []
+ assert_strict_shape(result.schema)
+
+ def test_widens_composition_and_enum_properties_without_type_beside_any_of(self):
+ result = to_strict_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "value": {"anyOf": [{"type": "string"}, {"type": "number"}]},
+ "already": {"anyOf": [{"type": "string"}, {"type": "null"}]},
+ "choice": {"enum": ["a", "b"], "description": "pick one"},
+ "multi": {"type": ["string", "number"]},
+ },
+ }
+ )
+
+ properties = result.schema["properties"]
+ assert properties["value"] == {
+ "anyOf": [{"type": "string"}, {"type": "number"}, {"type": "null"}]
+ }
+ assert properties["already"] == {
+ "anyOf": [{"type": "string"}, {"type": "null"}]
+ }
+ assert properties["choice"] == {
+ "description": "pick one",
+ "anyOf": [{"enum": ["a", "b"]}, {"type": "null"}],
+ }
+ assert properties["multi"] == {"type": ["string", "number", "null"]}
+ assert_strict_shape(result.schema)
- def test_normalizes_composition_branches_recursively(self):
+ def test_normalizes_composition_branches_and_array_items_recursively(self):
result = to_strict_json_schema(
{
"type": "object",
@@ -107,25 +183,7 @@ class TestToStrictJsonSchema:
},
{"type": "null"},
]
- }
- },
- "required": ["payload"],
- }
- )
-
- branch = result.schema["properties"]["payload"]["anyOf"][0]
- assert branch == {
- "type": "object",
- "properties": {"inner": {"type": "string"}},
- "required": ["inner"],
- "additionalProperties": False,
- }
-
- def test_normalizes_array_items(self):
- result = to_strict_json_schema(
- {
- "type": "object",
- "properties": {
+ },
"rows": {
"type": "array",
"items": {
@@ -136,54 +194,206 @@ class TestToStrictJsonSchema:
},
"required": ["id"],
},
- }
+ },
+ "either": {"oneOf": [{"type": "string"}, {"type": "number"}]},
},
- "required": ["rows"],
+ "required": ["payload", "rows", "either"],
}
)
- assert result.schema["properties"]["rows"]["items"] == {
+ assert result.schema["properties"]["payload"]["anyOf"][0] == {
"type": "object",
- "properties": {"id": {"type": "string"}},
- "required": ["id"],
+ "properties": {
+ "inner": {"type": "string"},
+ "extra": {"type": ["string", "null"]},
+ },
+ "required": ["inner", "extra"],
"additionalProperties": False,
}
+ assert result.schema["properties"]["rows"]["items"]["required"] == ["id", "tag"]
+ assert result.schema["properties"]["either"] == {
+ "anyOf": [{"type": "string"}, {"type": "number"}]
+ }
+ assert "one-of-converted" in {c.reason for c in result.changes}
+ assert_strict_shape(result.schema)
- def test_strips_annotation_keywords_and_reports_them(self):
+ def test_reports_dynamic_key_and_free_form_objects_as_unsupported(self):
result = to_strict_json_schema(
{
"type": "object",
"properties": {
- "name": {"type": "string", "examples": ["a"], "default": "x"}
+ "headers": {
+ "type": "object",
+ "additionalProperties": {"type": "string"},
+ },
+ "meta": {"type": "object", "description": "any json"},
+ "tagged": {
+ "type": "object",
+ "patternProperties": {"^x-": {"type": "string"}},
+ },
+ "open": {"type": "object", "additionalProperties": True},
+ },
+ "required": ["headers", "meta", "tagged", "open"],
+ }
+ )
+
+ assert [(e.path, e.keyword) for e in result.unsupported] == [
+ ("properties.headers", "additionalProperties"),
+ ("properties.meta", "properties"),
+ ("properties.tagged", "patternProperties"),
+ ("properties.open", "additionalProperties"),
+ ]
+ # The schema-valued additionalProperties is preserved, not overwritten.
+ assert result.schema["properties"]["headers"]["additionalProperties"] == {
+ "type": "string"
+ }
+ assert "patternProperties" in result.schema["properties"]["tagged"]
+
+ def test_strips_annotation_keywords_and_reports_keywords_it_cannot_rewrite(self):
+ result = to_strict_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "name": {"type": "string", "examples": ["a"], "default": "x"},
+ "pair": {"type": "array", "prefixItems": [{"type": "number"}]},
+ "all": {"allOf": [{"type": "string"}]},
},
- "required": ["name"],
+ "required": ["name", "pair", "all"],
}
)
assert result.schema["properties"]["name"] == {"type": "string"}
- stripped = [
- change
- for change in result.changes
- if change.reason == "annotation-keyword-stripped"
+ reasons = [c.reason for c in result.changes]
+ assert reasons.count("unsupported-keyword-stripped") == 2
+ assert [(e.path, e.keyword) for e in result.unsupported] == [
+ ("properties.pair", "prefixItems"),
+ ("properties.all", "allOf"),
]
- assert len(stripped) == 2
+
+ def test_inlines_refs_dedupes_required_and_reports_dangling_refs(self):
+ result = to_strict_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "cfg": {"$ref": "#/$defs/Config"},
+ "missing": {"$ref": "#/$defs/Nope"},
+ },
+ "required": ["cfg", "cfg", "missing"],
+ "$defs": {
+ "Config": {
+ "type": "object",
+ "properties": {
+ "url": {"type": "string"},
+ "note": {"type": "string"},
+ },
+ "required": ["url"],
+ }
+ },
+ }
+ )
+
+ assert "$ref" not in json.dumps(result.schema)
+ assert "$defs" not in result.schema
+ assert result.schema["properties"]["cfg"] == {
+ "type": "object",
+ "properties": {
+ "url": {"type": "string"},
+ "note": {"type": ["string", "null"]},
+ },
+ "required": ["url", "note"],
+ "additionalProperties": False,
+ }
+ assert result.schema["required"] == ["cfg", "missing"]
+ assert [(e.path, e.keyword) for e in result.unsupported] == [
+ ("", "$ref"),
+ ("properties.missing", "additionalProperties"),
+ ]
+ assert ("properties.cfg.properties.note", "optional-property-nullable") in [
+ (c.path, c.reason) for c in result.changes
+ ]
+
+ def test_caps_the_change_log_without_losing_properties(self):
+ properties = {f"p{i}": {"type": "string"} for i in range(60)}
+
+ result = to_strict_json_schema(
+ {"type": "object", "properties": properties, "required": ["p0"]}
+ )
+
+ assert len(result.schema["properties"]) == 60
+ assert len(result.changes) == 50
+ assert result.total_changes == 59
def test_does_not_mutate_input(self):
schema = {
"type": "object",
"properties": {
- "cfg": {"type": "object", "properties": {"opt": {"type": "string"}}}
+ "cfg": {
+ "type": "object",
+ "properties": {"opt": {"type": "string", "default": 1}},
+ }
},
"required": ["cfg"],
}
- import copy
-
snapshot = copy.deepcopy(schema)
to_strict_json_schema(schema)
assert schema == snapshot
+ def test_is_idempotent(self):
+ once = to_strict_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "cfg": {"$ref": "#/$defs/Config"},
+ "id": {"type": ["string", "null"]},
+ },
+ "$defs": {
+ "Config": {
+ "type": "object",
+ "properties": {
+ "url": {"type": "string"},
+ "note": {"type": "string"},
+ },
+ "required": ["url"],
+ }
+ },
+ }
+ ).schema
+
+ twice = to_strict_json_schema(once)
+
+ assert twice.schema == once
+ assert twice.changes == []
+ assert twice.unsupported == []
+
+ def test_reports_non_object_and_cyclic_roots_as_unsupported(self):
+ assert [
+ (e.path, e.keyword)
+ for e in to_strict_json_schema({"type": "string"}).unsupported
+ ] == [("", "type")]
+ nullable_root = to_strict_json_schema(
+ {"type": ["object", "null"], "properties": {"a": {"type": "string"}}}
+ )
+ assert ("", "type") in [(e.path, e.keyword) for e in nullable_root.unsupported]
+
+ cyclic = to_strict_json_schema(
+ {
+ "type": "object",
+ "properties": {"node": {"$ref": "#/$defs/Node"}},
+ "required": ["node"],
+ "$defs": {
+ "Node": {
+ "type": "object",
+ "properties": {"child": {"$ref": "#/$defs/Node"}},
+ "required": ["child"],
+ }
+ },
+ }
+ )
+ # The cycle-break sentinel is a free-form object strict mode cannot express.
+ assert "additionalProperties" in {e.keyword for e in cyclic.unsupported}
+
def test_raises_past_maximum_depth(self):
deep = {"type": "string"}
for _ in range(600):
@@ -193,10 +403,54 @@ class TestToStrictJsonSchema:
"required": ["nest"],
}
- with pytest.raises(ValueError, match="maximum nesting depth"):
+ with pytest.raises(Exception, match="depth"):
to_strict_json_schema(deep)
+_OMIT_SCHEMA = {
+ "type": "object",
+ "properties": {
+ "cfg": {
+ "type": "object",
+ "properties": {"url": {"type": "string"}, "note": {"type": "string"}},
+ "required": ["url"],
+ },
+ "label": {"type": "string"},
+ "clearable": {"type": ["string", "null"]},
+ "choice": {"anyOf": [{"enum": ["a"]}, {"type": "null"}]},
+ "rows": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {"id": {"type": "string"}, "tag": {"type": "string"}},
+ },
+ },
+ },
+}
+
+
+class TestOmitNullToolArguments:
+ def test_drops_nulls_the_schema_rejects_and_keeps_the_ones_it_accepts(self):
+ arguments = {
+ "cfg": {"url": "https://example.com", "note": None},
+ "label": None,
+ "clearable": None,
+ "choice": None,
+ "unknown": None,
+ "rows": [{"id": "1", "tag": None}, None],
+ }
+ snapshot = copy.deepcopy(arguments)
+
+ assert omit_null_tool_arguments(arguments, _OMIT_SCHEMA) == {
+ "cfg": {"url": "https://example.com"},
+ "clearable": None,
+ "choice": None,
+ "unknown": None,
+ "rows": [{"id": "1"}, None],
+ }
+ assert arguments == snapshot
+
+
class TestOpenAIResponsesProviderStrict:
def _tool(self, input_parameters):
from tests.test_provider import create_mock_tool
@@ -212,8 +466,19 @@ class TestOpenAIResponsesProviderStrict:
wrapped = provider.wrap_tool(self._tool({"type": "object", "properties": {}}))
assert wrapped["parameters"] == {"type": "object", "properties": {}}
+ assert wrapped["strict"] is False
+
+ def test_constructor_keeps_base_provider_config(self):
+ from composio.core.provider._openai_responses import OpenAIResponsesProvider
+
+ provider = OpenAIResponsesProvider(
+ strict=True, schema_config={"skip_defaults": True}
+ )
- def test_wrap_tool_normalizes_complex_schemas_in_strict_mode(self):
+ assert provider.strict is True
+ assert provider.skip_default is True
+
+ def test_wrap_tool_emits_strict_and_normalizes_complex_schemas(self):
from composio.core.provider._openai_responses import OpenAIResponsesProvider
provider = OpenAIResponsesProvider(strict=True)
@@ -223,62 +488,130 @@ class TestOpenAIResponsesProviderStrict:
"type": "object",
"properties": {
"cfg": {
+ "$ref": "#/$defs/Config",
+ },
+ "id": {"type": ["string", "null"]},
+ "label": {"type": "string"},
+ },
+ "required": ["cfg", "id"],
+ "$defs": {
+ "Config": {
"type": "object",
"properties": {
"url": {"type": "string"},
"note": {"type": "string"},
},
"required": ["url"],
- },
- "id": {"type": ["string", "null"]},
+ }
},
- "required": ["cfg", "id"],
}
)
)
- import json
-
+ assert wrapped["strict"] is True
assert "$ref" not in json.dumps(wrapped)
assert wrapped["parameters"] == {
"type": "object",
"properties": {
"cfg": {
"type": "object",
- "properties": {"url": {"type": "string"}},
- "required": ["url"],
+ "properties": {
+ "url": {"type": "string"},
+ "note": {"type": ["string", "null"]},
+ },
+ "required": ["url", "note"],
"additionalProperties": False,
},
- "id": {"anyOf": [{"type": "string"}, {"type": "null"}]},
+ "id": {"type": ["string", "null"]},
+ "label": {"type": ["string", "null"]},
},
- "required": ["cfg", "id"],
+ "required": ["cfg", "id", "label"],
"additionalProperties": False,
}
- def test_wrap_tool_inlines_defs_in_strict_mode(self):
+ def test_wrap_tool_sends_unsupported_schemas_without_strict(self):
from composio.core.provider._openai_responses import OpenAIResponsesProvider
provider = OpenAIResponsesProvider(strict=True)
- wrapped = provider.wrap_tool(
+ input_parameters = {
+ "type": "object",
+ "properties": {
+ "headers": {
+ "type": "object",
+ "additionalProperties": {"type": "string"},
+ },
+ "name": {"type": "string"},
+ },
+ "required": ["headers"],
+ }
+ wrapped = provider.wrap_tool(self._tool(input_parameters))
+
+ assert wrapped["strict"] is False
+ assert wrapped["parameters"] == input_parameters
+
+ def test_wrap_tool_emits_empty_closed_object_without_parameters(self):
+ from composio.core.provider._openai_responses import OpenAIResponsesProvider
+
+ provider = OpenAIResponsesProvider(strict=True)
+ wrapped = provider.wrap_tool(self._tool(None))
+
+ assert wrapped["strict"] is True
+ assert wrapped["parameters"] == {
+ "type": "object",
+ "properties": {},
+ "required": [],
+ "additionalProperties": False,
+ }
+
+ def test_execute_tool_call_omits_null_arguments_in_strict_mode(self):
+ from openai.types.responses.response_output_item import ResponseFunctionToolCall
+
+ from composio.core.provider._openai_responses import OpenAIResponsesProvider
+
+ received = {}
+
+ def execute_tool(slug, arguments, modifiers=None, **kwargs):
+ received["slug"] = slug
+ received["arguments"] = arguments
+ return {"data": {}, "error": None, "successful": True}
+
+ provider = OpenAIResponsesProvider(strict=True)
+ provider.set_execute_tool_fn(execute_tool)
+ provider.wrap_tool(
self._tool(
{
"type": "object",
- "properties": {"cfg": {"$ref": "#/$defs/Config"}},
- "required": ["cfg"],
- "$defs": {
- "Config": {
+ "properties": {
+ "cfg": {
"type": "object",
- "properties": {"url": {"type": "string"}},
+ "properties": {
+ "url": {"type": "string"},
+ "note": {"type": "string"},
+ },
"required": ["url"],
- }
+ },
+ "label": {"type": "string"},
+ "clearable": {"type": ["string", "null"]},
},
+ "required": ["cfg"],
}
)
)
+ provider.execute_tool_call(
+ user_id="user",
+ tool_call=ResponseFunctionToolCall(
+ type="function_call",
+ call_id="call_1",
+ name="TEST_TOOL",
+ arguments=json.dumps(
+ {
+ "cfg": {"url": "u", "note": None},
+ "label": None,
+ "clearable": None,
+ }
+ ),
+ ),
+ )
- assert wrapped["parameters"]["properties"]["cfg"] == {
- "type": "object",
- "properties": {"url": {"type": "string"}},
- "required": ["url"],
- "additionalProperties": False,
- }
+ assert received["slug"] == "TEST_TOOL"
+ assert received["arguments"] == {"cfg": {"url": "u"}, "clearable": None}