schema_sanitizer.py 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439
  1. """Sanitize tool JSON schemas for strict LLM backends. llama.cpp's grammar converter fails on
  2. ``{"type": "object"}`` without ``properties``, bare-string schemas and ``type`` arrays; Anthropic
  3. rejects nullable ``anyOf`` at the top of ``input_schema``; Fireworks rejects ``default`` beside
  4. ``$ref``; Codex rejects top-level combinators. Walks a deep copy and fixes only those shapes.
  5. Legacy boolean ``required`` flags are removed from schema positions, lifting property-level
  6. ``true`` flags into the parent's required-name list; literal defaults/consts are not schemas."""
  7. from __future__ import annotations
  8. import copy
  9. import logging
  10. import re
  11. from typing import Any, Callable
  12. from urllib.parse import unquote
  13. logger = logging.getLogger(__name__)
  14. # Anthropic (and Bedrock/Vertex/Azure fronting it) reject property keys not matching this; one bad
  15. # key anywhere in the tools array 400s the request (Cloudflare's MCP ships 61).
  16. _PROP_KEY_RE = re.compile(r"^[a-zA-Z0-9_.-]{1,64}$")
  17. _PROP_KEY_BAD_CHARS = re.compile(r"[^a-zA-Z0-9_.-]")
  18. _UNION_KEYS = ("anyOf", "oneOf")
  19. _UNION_META_KEYS = ("title", "description", "default", "examples") # copied onto replacements
  20. def _empty_object() -> dict:
  21. return {"type": "object", "properties": {}, "required": []}
  22. def _rewrite(schema: Any, fn: Callable[[dict], Any]) -> Any:
  23. """Bottom-up map over a schema tree: lists/dicts recurse, then *fn* sees each dict."""
  24. if isinstance(schema, list):
  25. return [_rewrite(item, fn) for item in schema]
  26. if not isinstance(schema, dict):
  27. return schema
  28. return fn({k: _rewrite(v, fn) for k, v in schema.items()})
  29. def sanitize_property_key(key: str) -> str:
  30. """Deterministically map an arbitrary property key to a conforming one."""
  31. return _PROP_KEY_BAD_CHARS.sub("_", key)[:64] or "param"
  32. def _rename_property_keys(props: dict, path: str) -> dict[str, str]:
  33. """{original_key: conforming_key} for one properties dict (identity entries omitted).
  34. Deterministic (insertion order, numeric suffixes on collision) so the model-visible schema
  35. and the dispatch-time reverse map from the registry's original schema agree."""
  36. renames: dict[str, str] = {}
  37. taken = {k for k in props if _PROP_KEY_RE.match(k)}
  38. for key in (k for k in props if not _PROP_KEY_RE.match(k)):
  39. base = sanitize_property_key(key)
  40. candidate, i = base, 2
  41. while candidate in taken:
  42. candidate, i = base[: 64 - len(f"_{i}")] + f"_{i}", i + 1
  43. taken.add(candidate)
  44. renames[key] = candidate
  45. logger.debug("schema_sanitizer[%s]: renamed property key %r -> %r "
  46. "(provider key-pattern compat)", path, key, candidate)
  47. return renames
  48. # RFC 6901: an array index is "0" or a number without leading zeros; "~" escapes only "~0" and "~1".
  49. _POINTER_INDEX = re.compile(r"0|[1-9][0-9]*")
  50. _BAD_POINTER_ESCAPE = re.compile(r"~(?![01])")
  51. def resolve_local_schema_ref(schema: Any, root_schema: Any, seen_refs: set[str] | None = None) -> Any:
  52. """Follow a document-local ``$ref`` in *schema* against *root_schema*, for dispatch-time
  53. decisions (argument coercion, key unrenaming). Remote, malformed or dangling refs come back
  54. unchanged; sibling keywords are kept, and the referenced schema wins where they conflict."""
  55. if not isinstance(schema, dict) or not isinstance(root_schema, dict):
  56. return schema
  57. ref = schema.get("$ref")
  58. if not isinstance(ref, str) or not ref.startswith("#"):
  59. return schema
  60. # A $ref is a URI reference: percent-decode the fragment, then read it as a JSON Pointer.
  61. pointer = unquote(ref[1:])
  62. if pointer and not pointer.startswith("/"):
  63. return schema # a plain-name anchor such as "#Address", not a pointer
  64. seen = seen_refs or set()
  65. if ref in seen:
  66. return schema
  67. target: Any = root_schema
  68. for raw_token in pointer.split("/")[1:]:
  69. if _BAD_POINTER_ESCAPE.search(raw_token):
  70. return schema
  71. token = raw_token.replace("~1", "/").replace("~0", "~")
  72. if isinstance(target, dict) and token in target:
  73. target = target[token]
  74. elif isinstance(target, list) and _POINTER_INDEX.fullmatch(token) and int(token) < len(target):
  75. # Path refs can pass through arrays, e.g. zod-to-json-schema's "#/properties/a/anyOf/0".
  76. target = target[int(token)]
  77. else:
  78. return schema
  79. if not isinstance(target, dict):
  80. return schema
  81. resolved = resolve_local_schema_ref(target, root_schema, seen | {ref})
  82. siblings = {key: value for key, value in schema.items() if key != "$ref"}
  83. if not siblings or not isinstance(resolved, dict):
  84. return resolved
  85. combined = dict(resolved)
  86. for key, value in siblings.items():
  87. combined.setdefault(key, value)
  88. return combined
  89. def unrename_tool_args(params_schema: Any, args: Any, root_schema: Any = None) -> Any:
  90. """Map sanitized keys in model-emitted args back to wire names. ``params_schema`` is the
  91. ORIGINAL registry schema; recurses into objects/array items, following local ``$ref``s
  92. (the sanitizer renames keys inside ``$defs`` too); unknown keys pass through."""
  93. root = params_schema if root_schema is None else root_schema
  94. params_schema = resolve_local_schema_ref(params_schema, root)
  95. props = params_schema.get("properties") if isinstance(params_schema, dict) else None
  96. if not isinstance(props, dict) or not isinstance(args, dict):
  97. return args
  98. reverse = {v: k for k, v in _rename_property_keys(props, "<unrename>").items()}
  99. out = {}
  100. for key, value in args.items():
  101. orig = reverse.get(key, key)
  102. sub = resolve_local_schema_ref(props[orig], root) if isinstance(props.get(orig), dict) else {}
  103. if isinstance(value, dict) and sub:
  104. value = unrename_tool_args(sub, value, root)
  105. elif isinstance(value, list) and isinstance(sub.get("items"), dict):
  106. value = [unrename_tool_args(sub["items"], item, root) if isinstance(item, dict) else item
  107. for item in value]
  108. out[orig] = value
  109. return out
  110. def sanitize_tool_schemas(tools: list[dict]) -> list[dict]:
  111. """Deep-copied ``tools`` (OpenAI format) with sanitized parameter schemas; safe to mutate."""
  112. return [_sanitize_single_tool(tool) for tool in tools] if tools else tools
  113. def _sanitize_single_tool(tool: dict) -> dict:
  114. out = copy.deepcopy(tool)
  115. fn = out.get("function") if isinstance(out, dict) else None
  116. if not isinstance(fn, dict):
  117. return out
  118. params = fn.get("parameters")
  119. if not isinstance(params, dict): # missing / non-dict → minimal valid shape
  120. fn["parameters"] = _empty_object()
  121. return out
  122. name = fn.get("name", "<tool>")
  123. top = _sanitize_node(params, path=name)
  124. top = top if isinstance(top, dict) else {} # guarantee an object with properties on top
  125. top["type"] = "object"
  126. if not isinstance(top.get("properties"), dict):
  127. top["properties"] = {}
  128. if not isinstance(top.get("required"), list):
  129. top["required"] = []
  130. # The recursive pass only handles array-form ``type: [X, "null"]``; collapse anyOf unions
  131. # here, keeping ``nullable: true`` so ``tools.arg_coercion._schema_allows_null`` still coerces.
  132. top = strip_nullable_unions(top, keep_nullable_hint=True)
  133. top = _strip_top_level_combinators(top, path=name)
  134. fn["parameters"] = _strip_ref_siblings(top)
  135. return out
  136. _REF_FORBIDDEN_SIBLINGS = frozenset({"default"}) # strict validators reject these beside ``$ref``
  137. def _strip_ref_siblings(node: Any) -> Any:
  138. """Recursively drop forbidden siblings of ``$ref`` (Fireworks rejects ``default`` there)."""
  139. def strip(out: dict) -> dict:
  140. for key in _REF_FORBIDDEN_SIBLINGS if "$ref" in out else ():
  141. out.pop(key, None)
  142. return out
  143. return _rewrite(node, strip)
  144. _TOP_LEVEL_FORBIDDEN_KEYS = ("allOf", "anyOf", "oneOf", "enum", "not")
  145. def _strip_top_level_combinators(params: dict, *, path: str = "<tool>") -> dict:
  146. """Drop combinators from the TOP level only (Codex rejects them there). They are usually
  147. conditional-required hints, so validity is unchanged (handlers re-validate); nested ones
  148. stay."""
  149. if not isinstance(params, dict):
  150. return params
  151. out = dict(params)
  152. for key in [k for k in _TOP_LEVEL_FORBIDDEN_KEYS if k in out]:
  153. logger.debug("schema_sanitizer[%s]: stripped top-level %r combinator "
  154. "from tool parameters (strict-backend compat)", path, key)
  155. del out[key]
  156. return out
  157. def _is_null_branch(item: Any) -> bool:
  158. return isinstance(item, dict) and item.get("type") == "null"
  159. def _carry_union_meta(outer: dict, replacement: dict, *, skip_default_on_ref: bool) -> None:
  160. """Copy outer-union metadata onto *replacement* where absent (``default`` is illegal beside
  161. ``$ref`` on strict backends, hence ``skip_default_on_ref``)."""
  162. for meta_key in _UNION_META_KEYS:
  163. if meta_key in outer and meta_key not in replacement and not (
  164. skip_default_on_ref and meta_key == "default" and "$ref" in replacement):
  165. replacement[meta_key] = outer[meta_key]
  166. def strip_nullable_unions(schema: Any, *, keep_nullable_hint: bool = True) -> Any:
  167. """Collapse ``anyOf``/``oneOf`` nullable unions (MCP/Pydantic optional fields) to the single
  168. non-null branch: Anthropic rejects the null branch and optionality already lives in the parent's
  169. ``required``. Only when a null branch was dropped AND exactly one non-null branch survives.
  170. ``keep_nullable_hint`` sets ``nullable: true`` for runtime ``"null"`` → ``None`` coercion."""
  171. def collapse(stripped: dict) -> Any:
  172. for key in _UNION_KEYS:
  173. variants = stripped.get(key)
  174. if not isinstance(variants, list):
  175. continue
  176. non_null = [item for item in variants if not _is_null_branch(item)]
  177. if len(non_null) == 1 and len(non_null) != len(variants):
  178. replacement = dict(non_null[0]) if isinstance(non_null[0], dict) else {}
  179. if keep_nullable_hint:
  180. replacement.setdefault("nullable", True)
  181. _carry_union_meta(stripped, replacement, skip_default_on_ref=True)
  182. return _rewrite(replacement, collapse) # the survivor may itself be a union
  183. return stripped
  184. return _rewrite(schema, collapse)
  185. _CONST_PRIMITIVE_TYPES: dict[type, str] = {
  186. bool: "boolean", int: "integer", float: "number", str: "string"}
  187. def _const_branch_type(branch: Any) -> str | None:
  188. """Primitive JSON-Schema type of a pure ``const`` branch (declared ``type``, if any, must match;
  189. only ``title``/``description`` may accompany it), else None."""
  190. if not isinstance(branch, dict) or "const" not in branch \
  191. or set(branch) - {"const", "type", "title", "description"}:
  192. return None
  193. # ``type(value)`` lookup (not isinstance): bool is a subclass of int.
  194. json_type = _CONST_PRIMITIVE_TYPES.get(type(branch["const"]))
  195. return json_type if branch.get("type") in (None, json_type) else None
  196. def collapse_const_unions(schema: Any) -> Any:
  197. """Collapse ``anyOf``/``oneOf`` unions of same-typed consts (Rust/TS MCP servers emit
  198. ``{"anyOf": [{"const": "red"}, {"const": "green"}]}``) to ``enum``; ported from block/goose
  199. ``tool_schema_normalize.rs`` (Apache-2.0). Only when EVERY non-null branch is a pure ``const``
  200. of one primitive type (``bool`` never merges with ``integer``); one ``{"type": "null"}`` branch
  201. is tolerated as ``nullable: true``. Branch order kept; outer metadata carried; input never
  202. mutated."""
  203. def collapse(out: dict) -> Any:
  204. for key in _UNION_KEYS:
  205. variants = out.get(key)
  206. if not isinstance(variants, list) or not variants:
  207. continue
  208. null_branches = [i for i in variants if _is_null_branch(i) and "const" not in i]
  209. const_branches = [item for item in variants if item not in null_branches]
  210. if len(null_branches) > 1 or not const_branches:
  211. continue
  212. branch_types = {_const_branch_type(item) for item in const_branches}
  213. if len(branch_types) != 1 or None in branch_types:
  214. continue
  215. replacement: dict = {
  216. "type": branch_types.pop(), "enum": [item["const"] for item in const_branches]}
  217. if null_branches:
  218. replacement["nullable"] = True
  219. _carry_union_meta(out, replacement, skip_default_on_ref=False)
  220. return replacement
  221. return out
  222. return _rewrite(schema, collapse)
  223. _BARE_TYPE_NAMES = frozenset({"object", "string", "number", "integer", "boolean", "array", "null"})
  224. # Values that are NOT schemas (recursing would treat a required name like "path" as a bare schema).
  225. _NON_SCHEMA_LIST_KEYS = frozenset({"required", "enum", "examples", "dependentRequired"})
  226. _SCHEMA_MAP_KEYS = frozenset({"properties", "$defs", "definitions", "patternProperties", "dependentSchemas"})
  227. _SCHEMA_CHILD_KEYS = frozenset({
  228. "items", "additionalItems", "additionalProperties", "unevaluatedItems", "unevaluatedProperties",
  229. "contains", "propertyNames", "not", "if", "then", "else", "anyOf", "oneOf", "allOf", "prefixItems",
  230. })
  231. def _normalize_type_array(value: list, out: dict) -> None:
  232. """Normalize a ``type: [...]`` array into *out* (llama.cpp and Gemini-via-OpenAI reject arrays).
  233. Per AI-SDK: one non-null type → ``type: X`` (+ ``nullable`` if ``null`` present); several →
  234. ``anyOf`` of single-type schemas so EVERY branch survives; none → ``null``/object fallback."""
  235. has_null = "null" in value
  236. non_null = [t for t in value if isinstance(t, str) and t != "null"]
  237. if not non_null:
  238. out["type"] = "null" if has_null else "object"
  239. return
  240. if len(non_null) == 1:
  241. out["type"] = non_null[0]
  242. else:
  243. out["anyOf"] = [{"type": t} for t in non_null]
  244. if has_null:
  245. out.setdefault("nullable", True)
  246. def _sanitize_node(node: Any, path: str) -> Any:
  247. """Recursively sanitize a JSON-Schema fragment: bare-string schemas → ``{"type": <value>}``
  248. (unknown strings → permissive object); object nodes gain ``properties: {}``; ``type`` arrays
  249. are normalized; property keys are renamed to the provider-safe pattern and ``required``
  250. follows, with entries missing from ``properties`` pruned.
  251. - Normalizes ``type: [X, "null"]`` arrays to single ``type: X`` (keeping ``nullable: true`` as a hint),
  252. and multi-type arrays like ``["number", "string"]`` to an ``anyOf`` of single-type schemas so no branch
  253. is dropped (ported from anomalyco/opencode#31877). - Recurses into ``properties``, ``items``,
  254. ``additionalProperties``, ``anyOf``, ``oneOf``, ``allOf``, and ``$defs`` / ``definitions``.
  255. """
  256. if isinstance(node, str):
  257. if node in _BARE_TYPE_NAMES:
  258. logger.debug("schema_sanitizer[%s]: replacing bare-string schema %r with {'type': %r}",
  259. path, node, node)
  260. return _empty_object() if node == "object" else {"type": node}
  261. logger.debug("schema_sanitizer[%s]: replacing non-schema string %r "
  262. "with empty object schema", path, node)
  263. return _empty_object()
  264. if isinstance(node, list):
  265. return [_sanitize_node(item, f"{path}[{i}]") for i, item in enumerate(node)]
  266. if not isinstance(node, dict):
  267. return node
  268. # Renames computed up front so ``required`` remaps even when it precedes ``properties``.
  269. props_in = node.get("properties")
  270. prop_renames = (_rename_property_keys(props_in, f"{path}.properties")
  271. if isinstance(props_in, dict) else {})
  272. out: dict = {}
  273. for key, value in node.items():
  274. # JSON Schema ``type`` arrays (e.g. ``["number", "string"]``, common in MCP tool schemas) are
  275. # rejected by several tool-call backends: * llama.cpp's grammar generator only accepts a singular
  276. # string type. * Gemini (including OpenAI-compatible gateways proxying to
  277. # Gemini) rejects the array form outright — plain @ai-sdk/google rewrites it, but the
  278. # OpenAI-compatible path forwards it verbatim and the backend 400s. Normalize per the SDK's
  279. # behavior: * single non-null type → ``type: X`` (+ ``nullable: true`` if the array also contained
  280. # "null"). No data lost. * multiple non-null types → ``anyOf`` of single-type schemas, so EVERY
  281. # branch survives instead of silently dropping all but the first. ``null`` is lifted into
  282. # ``nullable: true``. * all-null / empty → ``type: "null"`` (or object fallback). Ported from
  283. # anomalyco/opencode#31877.
  284. if key == "type" and isinstance(value, list):
  285. _normalize_type_array(value, out)
  286. elif key in _SCHEMA_MAP_KEYS and isinstance(value, dict):
  287. renames = prop_renames if key == "properties" else {}
  288. out[key] = {
  289. renames.get(k, k): _sanitize_node(v, f"{path}.{key}.{renames.get(k, k)}")
  290. for k, v in value.items()}
  291. elif key == "dependencies" and isinstance(value, dict):
  292. out[key] = {k: _sanitize_node(v, f"{path}.{key}.{k}") if isinstance(v, dict)
  293. else copy.deepcopy(v) for k, v in value.items()}
  294. elif key in {"items", "additionalProperties"}:
  295. # Bool ``additionalProperties`` is valid; bool ``items`` is non-standard but preserved.
  296. out[key] = value if isinstance(value, bool) else _sanitize_node(value, f"{path}.{key}")
  297. elif key in _NON_SCHEMA_LIST_KEYS:
  298. if key == "required" and isinstance(value, bool):
  299. continue # Legacy property flags are lifted by the parent below.
  300. if key == "required" and prop_renames and isinstance(value, list):
  301. out[key] = [prop_renames.get(r, r) if isinstance(r, str) else r for r in value]
  302. else:
  303. out[key] = copy.deepcopy(value) if isinstance(value, (list, dict)) else value
  304. elif key in _SCHEMA_CHILD_KEYS:
  305. out[key] = _sanitize_node(value, f"{path}.{key}")
  306. else:
  307. # Defaults, consts and extension metadata are literal data, not schemas.
  308. out[key] = copy.deepcopy(value)
  309. if isinstance(props_in, dict):
  310. lifted = [prop_renames.get(k, k) for k, v in props_in.items()
  311. if isinstance(v, dict) and v.get("required") is True]
  312. if lifted:
  313. required = out.get("required", [])
  314. required = required if isinstance(required, list) else []
  315. out["required"] = required + [key for key in lifted if key not in required]
  316. if out.get("type") == "object":
  317. if not isinstance(out.get("properties"), dict):
  318. out["properties"] = {}
  319. # Always emit a list: ``required: []`` is valid everywhere, while a missing or
  320. # non-list key reads as ``null`` on strict OpenAI-compatible proxies (#56123).
  321. required = out.get("required")
  322. out["required"] = ([r for r in required if isinstance(r, str) and r in out["properties"]]
  323. if isinstance(required, list) else [])
  324. return out
  325. # ---- Reactive strips — only invoked after a backend rejects a schema ----
  326. _STRIP_ON_RECOVERY_KEYS = frozenset({"pattern", "format"})
  327. _SCHEMA_MARKERS = frozenset({"type", "anyOf", "oneOf", "allOf"}) # a node with one IS a schema
  328. def _dict_nodes(node: Any):
  329. """Pre-order walk over every dict node (yielded before its values, so it may be mutated)."""
  330. if isinstance(node, dict):
  331. yield node
  332. children = node.values() if isinstance(node, dict) else node if isinstance(node, list) else ()
  333. for child in children:
  334. yield from _dict_nodes(child)
  335. def _reactive_strip(
  336. tools: list[dict], strip_node: Callable[[dict], int], log_msg: str) -> tuple[list[dict], int]:
  337. """Apply *strip_node* (-> keywords removed) to every dict node of each tool's parameters, in
  338. place; OpenAI (``{"function": {"parameters"}}``) and Responses (``{"parameters"}``) formats."""
  339. stripped = 0
  340. for tool in tools or ():
  341. if not isinstance(tool, dict):
  342. continue
  343. fn = tool.get("function")
  344. params = fn.get("parameters") if isinstance(fn, dict) else None
  345. params = params if isinstance(params, dict) else tool.get("parameters")
  346. if isinstance(params, dict):
  347. stripped += sum(strip_node(node) for node in _dict_nodes(params))
  348. if stripped:
  349. logger.info(log_msg, stripped)
  350. return tools, stripped
  351. def strip_pattern_and_format(tools: list[dict]) -> tuple[list[dict], int]:
  352. """Strip ``pattern``/``format`` in place — reactive, only after llama.cpp's grammar converter
  353. rejected a schema (its regex engine is a small ECMAScript subset); cloud providers use these as
  354. prompting hints. Only beside ``type``/combinators, so a property *named* ``pattern`` stays."""
  355. def _strip(node: dict) -> int:
  356. is_schema = bool(node.keys() & _SCHEMA_MARKERS)
  357. hits = [k for k in node if k in _STRIP_ON_RECOVERY_KEYS] if is_schema else []
  358. for k in hits:
  359. del node[k]
  360. return len(hits)
  361. return _reactive_strip(
  362. tools, _strip,
  363. "schema_sanitizer: stripped %d pattern/format keyword(s) from "
  364. "tool schemas (llama.cpp grammar-parse recovery)")
  365. def strip_slash_enum(tools: list[dict]) -> tuple[list[dict], int]:
  366. """Strip ``enum`` keywords whose string values contain ``/``, in place: xAI's grammar compiler
  367. rejects them (HTTP 400 before any token) — typically MCP enums of HuggingFace model IDs."""
  368. def _strip(node: dict) -> int:
  369. enum_val = node.get("enum")
  370. if isinstance(enum_val, list) and any(isinstance(v, str) and "/" in v for v in enum_val):
  371. del node["enum"]
  372. return 1
  373. return 0
  374. return _reactive_strip(
  375. tools, _strip,
  376. "schema_sanitizer: stripped %d enum keyword(s) containing '/' "
  377. "from tool schemas (xAI Responses grammar-compile recovery)")