feat: add ResponseContract handling [by Claude Code]

[chr-hertel]

Input:

When you look at the different implementations of ResponseConverterInterface in the various Platform\Bridge namespace, there is a lot of redundancies. I would think, that similar with
the Contract handling with the Normalizers, it is somehow possible to abstract away the response conversion into DTOs so we can share behavior of conversion between the
implementations. especially around tool call and stream handling.

[Copilot]

Pull Request Overview

This PR introduces a unified ResponseContract system to replace redundant per-platform response converters, streamlining response parsing and conversion across LLM platforms.

• Adds ResponseContract and ResponseContractFactory to centralize denormalization logic.
• Updates OpenAI and Mistral factories to use ResponseContract instead of separate converters.
• Provides extensive DTOs and denormalizers with full test coverage for parsing, streaming, and tool-call handling.

Reviewed Changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Platform/ResponseContract.php	Core coordinator and factory for denormalizers
src/Platform/ResponseContractFactory.php	Stateful adapter implementing ResponseConverterInterface
src/Platform/Bridge/OpenAI/PlatformFactory.php	Switched to ResponseContract-based converter for OpenAI
src/Platform/Bridge/Mistral/PlatformFactory.php	Switched to ResponseContract-based converter for Mistral
tests/Platform/ResponseContractTest.php	Coverage for simple text, tool calls, and non-streaming responses
tests/Platform/Bridge/**	New parser/stream tests for OpenAI and Mistral response formats

Comments suppressed due to low confidence (1)

tests/Platform/ResponseContractTest.php:60

• Consider adding a dedicated test for multi-choice responses (i.e., when choices contains more than one element) to cover the ChoiceResponse path in TextResponseDenormalizer.

    public function testConvertResponseSimpleText(): void

[chr-hertel]

public static methods go directly after the constructor

[chr-hertel]

this variable is not needed - just add the array directly to the supportsDenormalization method

[chr-hertel]

Okay, a few things here:

• let's not duplicate DTOs like ToolCall and ParsedToolCall but use the same - meaning the already existing PhpLlm\LlmChain\Platform\Response\ToolCall class - same for others.
• Let's get rid off the ResponseConverterInterface now and the corresponding code in the bridge classes

[chr-hertel]

Claude usage limit reached. Your limit will reset at 5pm (Europe/Berlin).

I guess my prompt in the beginning send Claude into introducing new DTOs and should have been more explicit about DTO usage, adding and running tests.

[chr-hertel]

alrighty, fun but trash.