{
  "id": "llm/tool-argument-type-coercion-failure",
  "signature": "ValidationError: 1 validation error for ToolCall\nvalue\n  Input should be a valid integer [type=int_parsing, input_value='42.5', input_type=str]",
  "signature_zh": "ValidationError: ToolCall 的 1 个验证错误\nvalue\n  输入应为有效整数 [type=int_parsing, input_value='42.5', input_type=str]",
  "regex": "Input should be a valid integer.*input_value=.*input_type=str",
  "domain": "llm",
  "category": "type_error",
  "subcategory": null,
  "root_cause": "When using tool calling with structured outputs, the LLM may generate arguments as strings (e.g., '42.5') instead of the expected type (e.g., integer), causing Pydantic or JSON schema validation to fail during type coercion.",
  "root_cause_type": "generic",
  "root_cause_zh": "使用带有结构化输出的工具调用时，LLM 可能生成字符串形式的参数（例如 '42.5'）而不是预期的类型（例如整数），导致 Pydantic 或 JSON schema 验证在类型强制转换期间失败。",
  "versions": [
    {
      "version": "pydantic==2.5.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "pydantic==2.7.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "openai==1.16.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "gpt-4-turbo-2024-04-09",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "This may still fail if the string cannot be parsed as the target type (e.g., 'abc' for int) or produces unexpected values.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "This can mask genuine errors like out-of-range values or non-numeric strings.",
      "fail_rate": 0.55,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Use Pydantic's `BeforeValidator` to coerce types: `from pydantic import BeforeValidator; def coerce_int(v): return int(float(v)) if isinstance(v, str) else v; class ToolCall(BaseModel): value: Annotated[int, BeforeValidator(coerce_int)]`",
      "success_rate": 0.9,
      "how": "Use Pydantic's `BeforeValidator` to coerce types: `from pydantic import BeforeValidator; def coerce_int(v): return int(float(v)) if isinstance(v, str) else v; class ToolCall(BaseModel): value: Annotated[int, BeforeValidator(coerce_int)]`",
      "condition": "",
      "sources": []
    },
    {
      "action": "In the tool schema, specify `type: 'number'` instead of `type: 'integer'` to accept both integers and floats as strings.",
      "success_rate": 0.8,
      "how": "In the tool schema, specify `type: 'number'` instead of `type: 'integer'` to accept both integers and floats as strings.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Add a retry loop with a system prompt instructing the LLM to produce valid JSON with correct types: 'Ensure all numeric fields are numbers, not strings.'",
      "success_rate": 0.75,
      "how": "Add a retry loop with a system prompt instructing the LLM to produce valid JSON with correct types: 'Ensure all numeric fields are numbers, not strings.'",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "使用 Pydantic 的 `BeforeValidator` 强制类型转换：`from pydantic import BeforeValidator; def coerce_int(v): return int(float(v)) if isinstance(v, str) else v; class ToolCall(BaseModel): value: Annotated[int, BeforeValidator(coerce_int)]`",
    "在工具模式中，指定 `type: 'number'` 而不是 `type: 'integer'`，以接受字符串形式的整数和浮点数。",
    "添加一个重试循环，并附带系统提示，指示 LLM 生成具有正确类型的有效 JSON：'确保所有数字字段是数字，而不是字符串。'"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.pydantic.dev/latest/errors/validation_errors/",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.86,
  "fix_success_rate": 0.8,
  "resolvable": "true",
  "first_seen": "2024-03-12",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}