refactor(tool-call): normalize wire shapes at LiteLLM boundary

[isaacbmiller]

Why

Tool-call wire-shape coercion was scattered across tool.py, base.py, two_step_adapter.py, and inspect_history.py. Every layer sniffed shapes (v['function']['name'] vs v['name'] vs output_item.model_dump() vs pydantic attribute access), which led to cascading fallbacks that drifted apart, parts of the pipeline that crashed when one provider's shape leaked into another's branch, and a recurring crash from the pydantic v2 MockValSer / SchemaSerializer bug (pydantic/pydantic#7713, BerriAI/litellm#9345) that needs to be worked around in exactly one spot, not five.

What

• New to_tool_call(item) in dspy/adapters/types/tool.py is the only function that touches wire shapes. It accepts:
  • OpenAI Chat Completions pydantic / dict ({type:'function', function:{name, arguments}, id})
  • OpenAI Responses API pydantic / dict ({type:'function_call', name, arguments, call_id})
  • falls back to attribute access if model_dump() raises TypeError from the MockValSer bug
• ToolCalls.ToolCall gains an optional id: str | None field so we can round-trip provider call IDs.
• BaseLM normalizes once at the two LiteLLM exit points (_process_lm_response_choices line 270 and _process_response line 322). After this, output['tool_calls'] is always list[ToolCall].
• Consumers collapse to one-liners:
  • Adapter._call_postprocess and TwoStepAdapter postprocess: 8-line dict comprehensions → ToolCalls(tool_calls=list(tool_calls))
  • inspect_history: tc['function']['name'] → tc.name
  • ToolCalls.validate_input: 27 lines → 14 lines, now only handles serialization round-trips (its actual job), not provider wire shapes
• json_repair no longer imported in base.py or two_step_adapter.py; it lives where shape coercion lives (tool.py).

Why now

The recurring MockValSer crash isn't fixable upstream: pydantic#7713 has been open since October 2023 (missed the v2.12 milestone, October 2025) and litellm#9345 was closed as not_planned. The getattr fallback is the standard workaround, but it had to live in tool.py AND in adapter postprocess AND in inspect_history. Putting it in one place lets us delete the others.

Verification

• tests/adapters/test_tool_call_normalization.py (new): 12 boundary tests pinning each wire shape, MockValSer fallback, error reporting, and ToolCall.id round-trip.
• tests/adapters/: 265 passed, 9 skipped.
• tests/clients/ + tests/predict/ + tests/signatures/ + tests/callback/ + tests/reliability/test_pydantic_models.py: 604 passed, 96 skipped, 2 xfailed.
• 3 pre-existing assertions in test_chat_adapter.py / test_json_adapter.py updated to expect ToolCall.id (now captured from the mocked LiteLLM response).
• test_tool_call_with_null_content_does_not_raise updated to feed the canonical shape; raw OpenAI dicts are no longer a valid input to _call_postprocess because BaseLM normalizes upstream.

Supersedes #43.

[greptile-apps]

Greptile Summary

This PR consolidates all LiteLLM tool-call wire-shape coercion into a single inbound boundary (to_tool_call in tool.py) and two symmetric outbound methods (format_as_litellm_tool_definition / format_as_litellm_tool_call), eliminating the scattered sniffing logic that caused cascading failures and the recurring MockValSer pydantic bug to surface in multiple places.

• Boundary normalization: BaseLM now calls to_tool_call at both exit points before any downstream code sees tool calls, so output['tool_calls'] is always list[ToolCall] after the LiteLLM boundary; _process_response also now always emits a text key (possibly None), removing the KeyError that previously fired for tool-call-only Responses API responses.
• Outbound serialization: ToolCall.format_as_litellm_tool_call correctly emits arguments as a JSON-encoded string (not a dict) and conditionally includes id/call_id, fixing the silent data-loss in the old format() method.
• Test coverage: 12 new boundary tests pin each wire shape, MockValSer fallback, wrong-dialect rejection, and id round-trip fidelity; existing adapter tests updated to reflect the canonical ToolCall objects instead of raw OpenAI dicts.

Confidence Score: 5/5

The change is safe to merge: the single inbound normalizer and its outbound counterparts are well-tested, the MockValSer fallback is isolated, and the previously crashing KeyError in inspect_history is now structurally prevented.

The refactor eliminates a documented class of recurring crashes and replaces fragmented wire-shape sniffing with a single, tested boundary. The one minor inconsistency — format_as_litellm_tool_definition raising for non-standard model_type while the response-processing path tolerates them — only affects custom BaseLM subclasses that explicitly set a non-standard model_type AND override supports_function_calling to True, an extremely narrow combination.

No files require special attention. The normalizer logic in dspy/adapters/types/tool.py is the most complex addition but is thoroughly covered by the new boundary tests.

Important Files Changed

Filename	Overview
dspy/adapters/types/tool.py	Major refactor: adds to_tool_call inbound normalizer, format_as_litellm_tool_definition/format_as_litellm_tool_call outbound serializers with two-dialect contract, ToolCall.id field, and removes from_dict_list. Core logic is solid; minor inconsistency where format_as_litellm_tool_definition raises for non-standard model_type but the response-processing path tolerates it silently.
dspy/clients/base_lm.py	Normalizes tool calls at both LiteLLM exit points via to_tool_call; _process_response now always emits text (even as None), fixing the downstream KeyError for tool-call-only Responses API outputs.
dspy/utils/inspect_history.py	Updated to access tool_call.name/tool_call.args directly on ToolCall objects; text-is-always-present contract from base_lm.py removes the KeyError risk on line 81.
dspy/adapters/base.py	Removes 8-line dict comprehension that sniffed wire shapes in favour of ToolCalls(tool_calls=list(tool_calls)); forwards model_type to format_as_litellm_tool_definition.
dspy/adapters/two_step_adapter.py	Identical simplification to base.py: removes 8-line dict comprehension and json_repair import.
tests/adapters/test_tool.py	Adds 12 new boundary tests covering both wire shapes, MockValSer fallback, wrong-dialect rejection, id round-trips, and argument-as-JSON-string enforcement.
dspy/adapters/types/base_type.py	Moves BaseLM import under TYPE_CHECKING to break a circular import; no logic changes.

Sequence Diagram

sequenceDiagram
    participant Adapter as Adapter._call_preprocess
    participant BaseLM as BaseLM
    participant LiteLLM as LiteLLM
    participant Normalizer as to_tool_call (tool.py)
    participant Post as Adapter._call_postprocess

    Adapter->>BaseLM: "lm(messages, tools=[format_as_litellm_tool_definition(model_type)])"
    BaseLM->>LiteLLM: litellm.completion / litellm.responses
    LiteLLM-->>BaseLM: raw wire shape (Chat or Responses API)
    BaseLM->>Normalizer: to_tool_call(tc, model_type)
    Note over Normalizer: handles dict, pydantic, MockValSer fallback
    Normalizer-->>BaseLM: ToolCalls.ToolCall(name, args, id)
    BaseLM-->>Adapter: "output[tool_calls] = list[ToolCall]"
    Adapter->>Post: "ToolCalls(tool_calls=list(tool_calls))"
    Post-->>Adapter: "value[field] = ToolCalls instance"

Loading

_{Reviews (13): Last reviewed commit: "docs(tool-call): document the wire-shape..." | Re-trigger Greptile}