arg_coercion.py 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240
  1. """Tool-argument type coercion: repair string-typed values the model emitted against a tool's JSON Schema.
  2. Models emit "42" for integers, "true" for booleans, JSON-encoded strings for
  3. arrays/objects (also nested inside containers), and bare scalars where an array
  4. is expected (wrapped in a one-element list). Coercion is schema-guided and
  5. conservative: originals are kept whenever a repair is not unambiguous.
  6. """
  7. import json
  8. import logging
  9. from typing import Any, Dict
  10. from tools.registry import registry
  11. from tools.schema_sanitizer import resolve_local_schema_ref
  12. # Logger name kept as "model_tools": these messages were always emitted under
  13. # that name and log-based tooling filters on it.
  14. logger = logging.getLogger("model_tools")
  15. def coerce_tool_args(tool_name: str, args: dict[str, Any]) -> dict[str, Any]:
  16. """Coerce string-typed args to their JSON-Schema types; originals kept on failure."""
  17. if not args or not isinstance(args, dict):
  18. return args
  19. schema = registry.get_schema(tool_name)
  20. parameters = (schema or {}).get("parameters") or {}
  21. properties = parameters.get("properties")
  22. if not properties:
  23. return args
  24. # The model saw the SANITIZED schema (provider-illegal property keys were
  25. # renamed); map those keys back to the registry's wire names first.
  26. try:
  27. from tools.schema_sanitizer import unrename_tool_args
  28. args = unrename_tool_args(parameters, args)
  29. except Exception: # pragma: no cover — never break dispatch
  30. pass
  31. for key, value in list(args.items()):
  32. prop_schema = properties.get(key)
  33. if not prop_schema:
  34. continue
  35. prop_schema = resolve_local_schema_ref(prop_schema, parameters)
  36. expected = prop_schema.get("type")
  37. is_container = isinstance(value, (list, tuple))
  38. # Bare non-list value for an array schema. Strings go through
  39. # _coerce_value first so a JSON-encoded array is parsed and a nullable
  40. # "null" becomes None (not ["null"]). None itself is preserved: the tool's
  41. # own default handling decides between "omit" and "empty list".
  42. if expected == "array" and value is not None and not is_container:
  43. if isinstance(value, str):
  44. coerced = _coerce_value(value, expected, schema=prop_schema)
  45. if coerced is not value:
  46. args[key] = coerced
  47. continue
  48. if value.strip().startswith("["):
  49. logger.warning("coerce_tool_args: %s.%s looks like a JSON array string "
  50. "but could not be parsed — model may have emitted a "
  51. "JSON-encoded string instead of a native array. "
  52. "Falling back to single-element list.", tool_name, key)
  53. args[key] = [value]
  54. logger.info("coerce_tool_args: wrapped bare string in list for %s.%s", tool_name, key)
  55. continue
  56. args[key] = [value]
  57. logger.info("coerce_tool_args: wrapped bare %s in list for %s.%s", type(value).__name__, tool_name, key)
  58. continue
  59. if not isinstance(value, str):
  60. # Native container: still normalize JSON-encoded elements/sub-fields.
  61. if (expected == "array" and is_container) or (expected == "object" and isinstance(value, dict)):
  62. args[key] = _normalize_json_strings_for_schema(
  63. value, prop_schema, root_schema=parameters
  64. )
  65. continue
  66. if not expected and not _schema_allows_null(prop_schema):
  67. continue
  68. coerced = _coerce_value(value, expected, schema=prop_schema)
  69. if coerced is not value:
  70. args[key] = coerced
  71. if isinstance(coerced, (list, tuple, dict)):
  72. args[key] = _normalize_json_strings_for_schema(
  73. coerced, prop_schema, root_schema=parameters
  74. )
  75. return args
  76. def _schema_accepts_kind(
  77. schema: Any,
  78. kind: str,
  79. root_schema: Any = None,
  80. seen_schema_ids: frozenset[int] = frozenset(),
  81. ) -> bool:
  82. """True when *schema* permits JSON type *kind* via ``type`` or any anyOf/oneOf/allOf branch."""
  83. if not isinstance(schema, dict):
  84. return False
  85. if id(schema) in seen_schema_ids:
  86. return False
  87. # Track this branch only: a recursive union must not hide its other alternatives.
  88. seen_schema_ids = seen_schema_ids | {id(schema)}
  89. if root_schema is None:
  90. root_schema = schema
  91. schema = resolve_local_schema_ref(schema, root_schema)
  92. t = schema.get("type")
  93. if t == kind or (isinstance(t, list) and kind in t):
  94. return True
  95. return any(isinstance(branches := schema.get(union_key), list) and any(_schema_accepts_kind(b, kind, root_schema, seen_schema_ids) for b in branches)
  96. for union_key in ("anyOf", "oneOf", "allOf"))
  97. def _normalize_json_strings_for_schema(
  98. value: Any,
  99. schema: Any,
  100. root_schema: Any = None,
  101. ) -> Any:
  102. """Recursively parse JSON-encoded strings where the schema expects array/object.
  103. Schema-guided: a string is only parsed when its schema position expects a
  104. container, so legitimate JSON-looking ``type: string`` fields survive.
  105. Returns the same object when nothing changed (identity = cheap no-op check).
  106. Ported from cline/cline#11803, adapted to hermes-agent's coercion layer.
  107. """
  108. if not isinstance(schema, dict):
  109. return value
  110. if root_schema is None:
  111. root_schema = schema
  112. schema = resolve_local_schema_ref(schema, root_schema)
  113. if isinstance(value, str):
  114. trimmed = value.strip()
  115. expects_array = _schema_accepts_kind(schema, "array", root_schema)
  116. expects_object = _schema_accepts_kind(schema, "object", root_schema)
  117. if not ((expects_array and trimmed.startswith("[")) or (expects_object and trimmed.startswith("{"))):
  118. return value
  119. try:
  120. parsed = json.loads(trimmed)
  121. except (ValueError, TypeError):
  122. return value
  123. if not ((isinstance(parsed, list) and expects_array) or (isinstance(parsed, dict) and expects_object)):
  124. return value
  125. value = parsed
  126. if isinstance(value, list):
  127. items_schema = schema.get("items")
  128. if not isinstance(items_schema, dict):
  129. return value
  130. out = [
  131. _normalize_json_strings_for_schema(
  132. item, items_schema, root_schema=root_schema
  133. )
  134. for item in value
  135. ]
  136. return out if any(n is not o for n, o in zip(out, value)) else value
  137. if isinstance(value, dict):
  138. props = schema.get("properties")
  139. if not isinstance(props, dict):
  140. return value
  141. out = dict(value)
  142. for k, prop_schema in props.items():
  143. if k in value and isinstance(prop_schema, dict):
  144. out[k] = _normalize_json_strings_for_schema(
  145. value[k], prop_schema, root_schema=root_schema
  146. )
  147. return out if any(out[k] is not v for k, v in value.items()) else value
  148. return value
  149. def _coerce_value(value: str, expected_type, schema: dict | None = None):
  150. """Coerce string *value* to *expected_type* (str or union list); original on failure."""
  151. if _schema_allows_null(schema) and value.strip().lower() == "null":
  152. return None
  153. if isinstance(expected_type, list):
  154. return next((r for t in expected_type if (r := _coerce_value(value, t, schema=schema)) is not value), value)
  155. coercer = _SCALAR_COERCERS.get(expected_type)
  156. if coercer is not None:
  157. return coercer(value)
  158. return None if expected_type == "null" and value.strip().lower() == "null" else value
  159. def _schema_allows_null(schema: dict | None) -> bool:
  160. """True when a JSON Schema fragment explicitly permits null."""
  161. if not isinstance(schema, dict):
  162. return False
  163. schema_type = schema.get("type")
  164. if schema_type == "null" or (isinstance(schema_type, list) and "null" in schema_type):
  165. return True
  166. if schema.get("nullable") is True:
  167. return True
  168. return any(isinstance(variants := schema.get(union_key), list)
  169. and any(isinstance(v, dict) and v.get("type") == "null" for v in variants)
  170. for union_key in ("anyOf", "oneOf"))
  171. def _coerce_json(value: str, expected_python_type: type):
  172. """json.loads *value* when the schema expects array/object; original string on mismatch."""
  173. name = expected_python_type.__name__
  174. try:
  175. parsed = json.loads(value)
  176. except (ValueError, TypeError) as exc:
  177. logger.warning("coerce_tool_args: failed to parse string as JSON for expected type %s: %s", name, exc)
  178. return value
  179. if isinstance(parsed, expected_python_type):
  180. logger.debug("coerce_tool_args: coerced string to %s via json.loads", name)
  181. return parsed
  182. logger.warning("coerce_tool_args: JSON-parsed value is %s, expected %s — skipping coercion",
  183. type(parsed).__name__, name)
  184. return value
  185. def _coerce_number(value: str, integer_only: bool = False):
  186. """Parse *value* as a number; original string on failure, inf/nan, or decimals when integer_only."""
  187. try:
  188. f = float(value)
  189. except (ValueError, OverflowError):
  190. return value
  191. if f != f or f in (float("inf"), float("-inf")):
  192. return value # not JSON-serializable
  193. return int(f) if f == int(f) else value if integer_only else f
  194. def _coerce_boolean(value: str):
  195. """Parse "true"/"false" (case-insensitive); original string otherwise."""
  196. return {"true": True, "false": False}.get(value.strip().lower(), value)
  197. # JSON-Schema scalar/container type -> coercer; "null" and unions are handled in _coerce_value.
  198. _SCALAR_COERCERS = {
  199. "integer": lambda v: _coerce_number(v, integer_only=True),
  200. "number": _coerce_number,
  201. "boolean": _coerce_boolean,
  202. "array": lambda v: _coerce_json(v, list),
  203. "object": lambda v: _coerce_json(v, dict),
  204. }