| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439 |
- """Sanitize tool JSON schemas for strict LLM backends. llama.cpp's grammar converter fails on
- ``{"type": "object"}`` without ``properties``, bare-string schemas and ``type`` arrays; Anthropic
- rejects nullable ``anyOf`` at the top of ``input_schema``; Fireworks rejects ``default`` beside
- ``$ref``; Codex rejects top-level combinators. Walks a deep copy and fixes only those shapes.
- Legacy boolean ``required`` flags are removed from schema positions, lifting property-level
- ``true`` flags into the parent's required-name list; literal defaults/consts are not schemas."""
- from __future__ import annotations
- import copy
- import logging
- import re
- from typing import Any, Callable
- from urllib.parse import unquote
- logger = logging.getLogger(__name__)
- # Anthropic (and Bedrock/Vertex/Azure fronting it) reject property keys not matching this; one bad
- # key anywhere in the tools array 400s the request (Cloudflare's MCP ships 61).
- _PROP_KEY_RE = re.compile(r"^[a-zA-Z0-9_.-]{1,64}$")
- _PROP_KEY_BAD_CHARS = re.compile(r"[^a-zA-Z0-9_.-]")
- _UNION_KEYS = ("anyOf", "oneOf")
- _UNION_META_KEYS = ("title", "description", "default", "examples") # copied onto replacements
- def _empty_object() -> dict:
- return {"type": "object", "properties": {}, "required": []}
- def _rewrite(schema: Any, fn: Callable[[dict], Any]) -> Any:
- """Bottom-up map over a schema tree: lists/dicts recurse, then *fn* sees each dict."""
- if isinstance(schema, list):
- return [_rewrite(item, fn) for item in schema]
- if not isinstance(schema, dict):
- return schema
- return fn({k: _rewrite(v, fn) for k, v in schema.items()})
- def sanitize_property_key(key: str) -> str:
- """Deterministically map an arbitrary property key to a conforming one."""
- return _PROP_KEY_BAD_CHARS.sub("_", key)[:64] or "param"
- def _rename_property_keys(props: dict, path: str) -> dict[str, str]:
- """{original_key: conforming_key} for one properties dict (identity entries omitted).
- Deterministic (insertion order, numeric suffixes on collision) so the model-visible schema
- and the dispatch-time reverse map from the registry's original schema agree."""
- renames: dict[str, str] = {}
- taken = {k for k in props if _PROP_KEY_RE.match(k)}
- for key in (k for k in props if not _PROP_KEY_RE.match(k)):
- base = sanitize_property_key(key)
- candidate, i = base, 2
- while candidate in taken:
- candidate, i = base[: 64 - len(f"_{i}")] + f"_{i}", i + 1
- taken.add(candidate)
- renames[key] = candidate
- logger.debug("schema_sanitizer[%s]: renamed property key %r -> %r "
- "(provider key-pattern compat)", path, key, candidate)
- return renames
- # RFC 6901: an array index is "0" or a number without leading zeros; "~" escapes only "~0" and "~1".
- _POINTER_INDEX = re.compile(r"0|[1-9][0-9]*")
- _BAD_POINTER_ESCAPE = re.compile(r"~(?![01])")
- def resolve_local_schema_ref(schema: Any, root_schema: Any, seen_refs: set[str] | None = None) -> Any:
- """Follow a document-local ``$ref`` in *schema* against *root_schema*, for dispatch-time
- decisions (argument coercion, key unrenaming). Remote, malformed or dangling refs come back
- unchanged; sibling keywords are kept, and the referenced schema wins where they conflict."""
- if not isinstance(schema, dict) or not isinstance(root_schema, dict):
- return schema
- ref = schema.get("$ref")
- if not isinstance(ref, str) or not ref.startswith("#"):
- return schema
- # A $ref is a URI reference: percent-decode the fragment, then read it as a JSON Pointer.
- pointer = unquote(ref[1:])
- if pointer and not pointer.startswith("/"):
- return schema # a plain-name anchor such as "#Address", not a pointer
- seen = seen_refs or set()
- if ref in seen:
- return schema
- target: Any = root_schema
- for raw_token in pointer.split("/")[1:]:
- if _BAD_POINTER_ESCAPE.search(raw_token):
- return schema
- token = raw_token.replace("~1", "/").replace("~0", "~")
- if isinstance(target, dict) and token in target:
- target = target[token]
- elif isinstance(target, list) and _POINTER_INDEX.fullmatch(token) and int(token) < len(target):
- # Path refs can pass through arrays, e.g. zod-to-json-schema's "#/properties/a/anyOf/0".
- target = target[int(token)]
- else:
- return schema
- if not isinstance(target, dict):
- return schema
- resolved = resolve_local_schema_ref(target, root_schema, seen | {ref})
- siblings = {key: value for key, value in schema.items() if key != "$ref"}
- if not siblings or not isinstance(resolved, dict):
- return resolved
- combined = dict(resolved)
- for key, value in siblings.items():
- combined.setdefault(key, value)
- return combined
- def unrename_tool_args(params_schema: Any, args: Any, root_schema: Any = None) -> Any:
- """Map sanitized keys in model-emitted args back to wire names. ``params_schema`` is the
- ORIGINAL registry schema; recurses into objects/array items, following local ``$ref``s
- (the sanitizer renames keys inside ``$defs`` too); unknown keys pass through."""
- root = params_schema if root_schema is None else root_schema
- params_schema = resolve_local_schema_ref(params_schema, root)
- props = params_schema.get("properties") if isinstance(params_schema, dict) else None
- if not isinstance(props, dict) or not isinstance(args, dict):
- return args
- reverse = {v: k for k, v in _rename_property_keys(props, "<unrename>").items()}
- out = {}
- for key, value in args.items():
- orig = reverse.get(key, key)
- sub = resolve_local_schema_ref(props[orig], root) if isinstance(props.get(orig), dict) else {}
- if isinstance(value, dict) and sub:
- value = unrename_tool_args(sub, value, root)
- elif isinstance(value, list) and isinstance(sub.get("items"), dict):
- value = [unrename_tool_args(sub["items"], item, root) if isinstance(item, dict) else item
- for item in value]
- out[orig] = value
- return out
- def sanitize_tool_schemas(tools: list[dict]) -> list[dict]:
- """Deep-copied ``tools`` (OpenAI format) with sanitized parameter schemas; safe to mutate."""
- return [_sanitize_single_tool(tool) for tool in tools] if tools else tools
- def _sanitize_single_tool(tool: dict) -> dict:
- out = copy.deepcopy(tool)
- fn = out.get("function") if isinstance(out, dict) else None
- if not isinstance(fn, dict):
- return out
- params = fn.get("parameters")
- if not isinstance(params, dict): # missing / non-dict → minimal valid shape
- fn["parameters"] = _empty_object()
- return out
- name = fn.get("name", "<tool>")
- top = _sanitize_node(params, path=name)
- top = top if isinstance(top, dict) else {} # guarantee an object with properties on top
- top["type"] = "object"
- if not isinstance(top.get("properties"), dict):
- top["properties"] = {}
- if not isinstance(top.get("required"), list):
- top["required"] = []
- # The recursive pass only handles array-form ``type: [X, "null"]``; collapse anyOf unions
- # here, keeping ``nullable: true`` so ``tools.arg_coercion._schema_allows_null`` still coerces.
- top = strip_nullable_unions(top, keep_nullable_hint=True)
- top = _strip_top_level_combinators(top, path=name)
- fn["parameters"] = _strip_ref_siblings(top)
- return out
- _REF_FORBIDDEN_SIBLINGS = frozenset({"default"}) # strict validators reject these beside ``$ref``
- def _strip_ref_siblings(node: Any) -> Any:
- """Recursively drop forbidden siblings of ``$ref`` (Fireworks rejects ``default`` there)."""
- def strip(out: dict) -> dict:
- for key in _REF_FORBIDDEN_SIBLINGS if "$ref" in out else ():
- out.pop(key, None)
- return out
- return _rewrite(node, strip)
- _TOP_LEVEL_FORBIDDEN_KEYS = ("allOf", "anyOf", "oneOf", "enum", "not")
- def _strip_top_level_combinators(params: dict, *, path: str = "<tool>") -> dict:
- """Drop combinators from the TOP level only (Codex rejects them there). They are usually
- conditional-required hints, so validity is unchanged (handlers re-validate); nested ones
- stay."""
- if not isinstance(params, dict):
- return params
- out = dict(params)
- for key in [k for k in _TOP_LEVEL_FORBIDDEN_KEYS if k in out]:
- logger.debug("schema_sanitizer[%s]: stripped top-level %r combinator "
- "from tool parameters (strict-backend compat)", path, key)
- del out[key]
- return out
- def _is_null_branch(item: Any) -> bool:
- return isinstance(item, dict) and item.get("type") == "null"
- def _carry_union_meta(outer: dict, replacement: dict, *, skip_default_on_ref: bool) -> None:
- """Copy outer-union metadata onto *replacement* where absent (``default`` is illegal beside
- ``$ref`` on strict backends, hence ``skip_default_on_ref``)."""
- for meta_key in _UNION_META_KEYS:
- if meta_key in outer and meta_key not in replacement and not (
- skip_default_on_ref and meta_key == "default" and "$ref" in replacement):
- replacement[meta_key] = outer[meta_key]
- def strip_nullable_unions(schema: Any, *, keep_nullable_hint: bool = True) -> Any:
- """Collapse ``anyOf``/``oneOf`` nullable unions (MCP/Pydantic optional fields) to the single
- non-null branch: Anthropic rejects the null branch and optionality already lives in the parent's
- ``required``. Only when a null branch was dropped AND exactly one non-null branch survives.
- ``keep_nullable_hint`` sets ``nullable: true`` for runtime ``"null"`` → ``None`` coercion."""
- def collapse(stripped: dict) -> Any:
- for key in _UNION_KEYS:
- variants = stripped.get(key)
- if not isinstance(variants, list):
- continue
- non_null = [item for item in variants if not _is_null_branch(item)]
- if len(non_null) == 1 and len(non_null) != len(variants):
- replacement = dict(non_null[0]) if isinstance(non_null[0], dict) else {}
- if keep_nullable_hint:
- replacement.setdefault("nullable", True)
- _carry_union_meta(stripped, replacement, skip_default_on_ref=True)
- return _rewrite(replacement, collapse) # the survivor may itself be a union
- return stripped
- return _rewrite(schema, collapse)
- _CONST_PRIMITIVE_TYPES: dict[type, str] = {
- bool: "boolean", int: "integer", float: "number", str: "string"}
- def _const_branch_type(branch: Any) -> str | None:
- """Primitive JSON-Schema type of a pure ``const`` branch (declared ``type``, if any, must match;
- only ``title``/``description`` may accompany it), else None."""
- if not isinstance(branch, dict) or "const" not in branch \
- or set(branch) - {"const", "type", "title", "description"}:
- return None
- # ``type(value)`` lookup (not isinstance): bool is a subclass of int.
- json_type = _CONST_PRIMITIVE_TYPES.get(type(branch["const"]))
- return json_type if branch.get("type") in (None, json_type) else None
- def collapse_const_unions(schema: Any) -> Any:
- """Collapse ``anyOf``/``oneOf`` unions of same-typed consts (Rust/TS MCP servers emit
- ``{"anyOf": [{"const": "red"}, {"const": "green"}]}``) to ``enum``; ported from block/goose
- ``tool_schema_normalize.rs`` (Apache-2.0). Only when EVERY non-null branch is a pure ``const``
- of one primitive type (``bool`` never merges with ``integer``); one ``{"type": "null"}`` branch
- is tolerated as ``nullable: true``. Branch order kept; outer metadata carried; input never
- mutated."""
- def collapse(out: dict) -> Any:
- for key in _UNION_KEYS:
- variants = out.get(key)
- if not isinstance(variants, list) or not variants:
- continue
- null_branches = [i for i in variants if _is_null_branch(i) and "const" not in i]
- const_branches = [item for item in variants if item not in null_branches]
- if len(null_branches) > 1 or not const_branches:
- continue
- branch_types = {_const_branch_type(item) for item in const_branches}
- if len(branch_types) != 1 or None in branch_types:
- continue
- replacement: dict = {
- "type": branch_types.pop(), "enum": [item["const"] for item in const_branches]}
- if null_branches:
- replacement["nullable"] = True
- _carry_union_meta(out, replacement, skip_default_on_ref=False)
- return replacement
- return out
- return _rewrite(schema, collapse)
- _BARE_TYPE_NAMES = frozenset({"object", "string", "number", "integer", "boolean", "array", "null"})
- # Values that are NOT schemas (recursing would treat a required name like "path" as a bare schema).
- _NON_SCHEMA_LIST_KEYS = frozenset({"required", "enum", "examples", "dependentRequired"})
- _SCHEMA_MAP_KEYS = frozenset({"properties", "$defs", "definitions", "patternProperties", "dependentSchemas"})
- _SCHEMA_CHILD_KEYS = frozenset({
- "items", "additionalItems", "additionalProperties", "unevaluatedItems", "unevaluatedProperties",
- "contains", "propertyNames", "not", "if", "then", "else", "anyOf", "oneOf", "allOf", "prefixItems",
- })
- def _normalize_type_array(value: list, out: dict) -> None:
- """Normalize a ``type: [...]`` array into *out* (llama.cpp and Gemini-via-OpenAI reject arrays).
- Per AI-SDK: one non-null type → ``type: X`` (+ ``nullable`` if ``null`` present); several →
- ``anyOf`` of single-type schemas so EVERY branch survives; none → ``null``/object fallback."""
- has_null = "null" in value
- non_null = [t for t in value if isinstance(t, str) and t != "null"]
- if not non_null:
- out["type"] = "null" if has_null else "object"
- return
- if len(non_null) == 1:
- out["type"] = non_null[0]
- else:
- out["anyOf"] = [{"type": t} for t in non_null]
- if has_null:
- out.setdefault("nullable", True)
- def _sanitize_node(node: Any, path: str) -> Any:
- """Recursively sanitize a JSON-Schema fragment: bare-string schemas → ``{"type": <value>}``
- (unknown strings → permissive object); object nodes gain ``properties: {}``; ``type`` arrays
- are normalized; property keys are renamed to the provider-safe pattern and ``required``
- follows, with entries missing from ``properties`` pruned.
- - Normalizes ``type: [X, "null"]`` arrays to single ``type: X`` (keeping ``nullable: true`` as a hint),
- and multi-type arrays like ``["number", "string"]`` to an ``anyOf`` of single-type schemas so no branch
- is dropped (ported from anomalyco/opencode#31877). - Recurses into ``properties``, ``items``,
- ``additionalProperties``, ``anyOf``, ``oneOf``, ``allOf``, and ``$defs`` / ``definitions``.
- """
- if isinstance(node, str):
- if node in _BARE_TYPE_NAMES:
- logger.debug("schema_sanitizer[%s]: replacing bare-string schema %r with {'type': %r}",
- path, node, node)
- return _empty_object() if node == "object" else {"type": node}
- logger.debug("schema_sanitizer[%s]: replacing non-schema string %r "
- "with empty object schema", path, node)
- return _empty_object()
- if isinstance(node, list):
- return [_sanitize_node(item, f"{path}[{i}]") for i, item in enumerate(node)]
- if not isinstance(node, dict):
- return node
- # Renames computed up front so ``required`` remaps even when it precedes ``properties``.
- props_in = node.get("properties")
- prop_renames = (_rename_property_keys(props_in, f"{path}.properties")
- if isinstance(props_in, dict) else {})
- out: dict = {}
- for key, value in node.items():
- # JSON Schema ``type`` arrays (e.g. ``["number", "string"]``, common in MCP tool schemas) are
- # rejected by several tool-call backends: * llama.cpp's grammar generator only accepts a singular
- # string type. * Gemini (including OpenAI-compatible gateways proxying to
- # Gemini) rejects the array form outright — plain @ai-sdk/google rewrites it, but the
- # OpenAI-compatible path forwards it verbatim and the backend 400s. Normalize per the SDK's
- # behavior: * single non-null type → ``type: X`` (+ ``nullable: true`` if the array also contained
- # "null"). No data lost. * multiple non-null types → ``anyOf`` of single-type schemas, so EVERY
- # branch survives instead of silently dropping all but the first. ``null`` is lifted into
- # ``nullable: true``. * all-null / empty → ``type: "null"`` (or object fallback). Ported from
- # anomalyco/opencode#31877.
- if key == "type" and isinstance(value, list):
- _normalize_type_array(value, out)
- elif key in _SCHEMA_MAP_KEYS and isinstance(value, dict):
- renames = prop_renames if key == "properties" else {}
- out[key] = {
- renames.get(k, k): _sanitize_node(v, f"{path}.{key}.{renames.get(k, k)}")
- for k, v in value.items()}
- elif key == "dependencies" and isinstance(value, dict):
- out[key] = {k: _sanitize_node(v, f"{path}.{key}.{k}") if isinstance(v, dict)
- else copy.deepcopy(v) for k, v in value.items()}
- elif key in {"items", "additionalProperties"}:
- # Bool ``additionalProperties`` is valid; bool ``items`` is non-standard but preserved.
- out[key] = value if isinstance(value, bool) else _sanitize_node(value, f"{path}.{key}")
- elif key in _NON_SCHEMA_LIST_KEYS:
- if key == "required" and isinstance(value, bool):
- continue # Legacy property flags are lifted by the parent below.
- if key == "required" and prop_renames and isinstance(value, list):
- out[key] = [prop_renames.get(r, r) if isinstance(r, str) else r for r in value]
- else:
- out[key] = copy.deepcopy(value) if isinstance(value, (list, dict)) else value
- elif key in _SCHEMA_CHILD_KEYS:
- out[key] = _sanitize_node(value, f"{path}.{key}")
- else:
- # Defaults, consts and extension metadata are literal data, not schemas.
- out[key] = copy.deepcopy(value)
- if isinstance(props_in, dict):
- lifted = [prop_renames.get(k, k) for k, v in props_in.items()
- if isinstance(v, dict) and v.get("required") is True]
- if lifted:
- required = out.get("required", [])
- required = required if isinstance(required, list) else []
- out["required"] = required + [key for key in lifted if key not in required]
- if out.get("type") == "object":
- if not isinstance(out.get("properties"), dict):
- out["properties"] = {}
- # Always emit a list: ``required: []`` is valid everywhere, while a missing or
- # non-list key reads as ``null`` on strict OpenAI-compatible proxies (#56123).
- required = out.get("required")
- out["required"] = ([r for r in required if isinstance(r, str) and r in out["properties"]]
- if isinstance(required, list) else [])
- return out
- # ---- Reactive strips — only invoked after a backend rejects a schema ----
- _STRIP_ON_RECOVERY_KEYS = frozenset({"pattern", "format"})
- _SCHEMA_MARKERS = frozenset({"type", "anyOf", "oneOf", "allOf"}) # a node with one IS a schema
- def _dict_nodes(node: Any):
- """Pre-order walk over every dict node (yielded before its values, so it may be mutated)."""
- if isinstance(node, dict):
- yield node
- children = node.values() if isinstance(node, dict) else node if isinstance(node, list) else ()
- for child in children:
- yield from _dict_nodes(child)
- def _reactive_strip(
- tools: list[dict], strip_node: Callable[[dict], int], log_msg: str) -> tuple[list[dict], int]:
- """Apply *strip_node* (-> keywords removed) to every dict node of each tool's parameters, in
- place; OpenAI (``{"function": {"parameters"}}``) and Responses (``{"parameters"}``) formats."""
- stripped = 0
- for tool in tools or ():
- if not isinstance(tool, dict):
- continue
- fn = tool.get("function")
- params = fn.get("parameters") if isinstance(fn, dict) else None
- params = params if isinstance(params, dict) else tool.get("parameters")
- if isinstance(params, dict):
- stripped += sum(strip_node(node) for node in _dict_nodes(params))
- if stripped:
- logger.info(log_msg, stripped)
- return tools, stripped
- def strip_pattern_and_format(tools: list[dict]) -> tuple[list[dict], int]:
- """Strip ``pattern``/``format`` in place — reactive, only after llama.cpp's grammar converter
- rejected a schema (its regex engine is a small ECMAScript subset); cloud providers use these as
- prompting hints. Only beside ``type``/combinators, so a property *named* ``pattern`` stays."""
- def _strip(node: dict) -> int:
- is_schema = bool(node.keys() & _SCHEMA_MARKERS)
- hits = [k for k in node if k in _STRIP_ON_RECOVERY_KEYS] if is_schema else []
- for k in hits:
- del node[k]
- return len(hits)
- return _reactive_strip(
- tools, _strip,
- "schema_sanitizer: stripped %d pattern/format keyword(s) from "
- "tool schemas (llama.cpp grammar-parse recovery)")
- def strip_slash_enum(tools: list[dict]) -> tuple[list[dict], int]:
- """Strip ``enum`` keywords whose string values contain ``/``, in place: xAI's grammar compiler
- rejects them (HTTP 400 before any token) — typically MCP enums of HuggingFace model IDs."""
- def _strip(node: dict) -> int:
- enum_val = node.get("enum")
- if isinstance(enum_val, list) and any(isinstance(v, str) and "/" in v for v in enum_val):
- del node["enum"]
- return 1
- return 0
- return _reactive_strip(
- tools, _strip,
- "schema_sanitizer: stripped %d enum keyword(s) containing '/' "
- "from tool schemas (xAI Responses grammar-compile recovery)")
|