[Platform] Use JSON Path to convert responses

[chr-hertel]

Q	A
Bug fix?	no
New feature?	yes
Docs?	no
Issues
License	MIT

This approach combines two ideas:

1. having a central openai-based result converter which removes the need of duplication for some of our implementations
2. introducing a jsonpath based abstraction for configuring the mechanism of data extraction

And of course those two things don't have to be coupled, but one thing led to the other somehow ...

• This concept basically still needs proof for the second part by adopting it with Anthropic and Gemini.
• Tests for streaming examples and customized text and tool call extraction

[alexandre-daubois]

I really like the idea! Know that if you manage to get a resource for the response, JsonPath uses JsonStreamer to optimize the part to actually decode. Just in case 🙂

Given that JsonPath is experimental, I'd suggest changing the composer constraint to 7.3.*. That's what we do in core because experimental components may not be compatible between their minor versions. I have no plan to change classes or signatures in the JsonPath component until it's stable release as I managed to make it RFC compliant lately with the exact same API. But better be safe than sorry!

[valtzu]

Interesting approach!

Do we even need the platform-specific ResponseConverters if there's no platform-specific logic apart a custom json path? This path could be injected in PlatformFactory.

---

EDIT: ok hmm I guess the idea was to encapsulate the "protocol" in the converter to be reused in different platforms

[chr-hertel]

I'd suggest changing the composer constraint to 7.3.*

Thanks for that!

encapsulate the "protocol" in the converter to be reused in different platforms

exactly

[OskarStark]

We just created some CHANGELOG.md files.
Please rebase your branch and add info to the appropriate CHANGELOG.md file.

Thanks

[chr-hertel]

how do I deal with that kind of stuff?

[alexandre-daubois]

Running CS fixer locally doesn't help?

[Copilot]

Pull Request Overview

This PR introduces a JSON Path-based approach for converting AI platform responses, aiming to centralize response conversion logic and reduce duplication across different AI provider implementations. The implementation combines an OpenAI-based central converter with configurable JSON Path extraction mechanisms for different data types.

• Establishes a unified response conversion system using JSON Path for data extraction
• Adds comprehensive test fixtures for various AI platform response formats (Gemini, OpenAI, etc.)
• Introduces fixtures for different response types including completions, embeddings, tool calls, and streaming responses

Reviewed Changes

Copilot reviewed 64 out of 64 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/platform/tests/Contract/fixtures/embeddings-gemini.json	Test fixture for Gemini embedding response format
src/platform/tests/Contract/fixtures/embeddings-default.json	Test fixture for default (OpenAI) embedding response format
src/platform/tests/Contract/fixtures/completions-gemini-toolcall.json	Test fixture for Gemini tool call completion response
src/platform/tests/Contract/fixtures/completions-gemini-text.json	Test fixture for Gemini text completion response
src/platform/tests/Contract/fixtures/completions-gemini-stream	Test fixture for Gemini streaming completion responses
src/platform/tests/Contract/fixtures/completions-gemini-error.json	Test fixture for Gemini error response format
src/platform/tests/Contract/fixtures/completions-gemini-choices.json	Test fixture for Gemini completion with multiple choice responses
src/platform/tests/Contract/fixtures/completions-default-toolcall.json	Test fixture for default (OpenAI) tool call completion response
src/platform/tests/Contract/fixtures/completions-default-toolcall-multiple.json	Test fixture for default completion with multiple tool calls
src/platform/tests/Contract/fixtures/completions-default-toolcall-choices.json	Test fixture for default completion with tool call choices
src/platform/tests/Contract/fixtures/completions-default-text.json	Test fixture for default text completion response
src/platform/tests/Contract/fixtures/completions-default-stream-toolcall	Test fixture for default streaming tool call completion

[chr-hertel]

we need a centralized result conversion heavily-inspired by the OpenAI contract - but we don't have to use JSON Path here.

what do you think? clever thing to do or too artistic?

@OskarStark @DZunke @alexandre-daubois @lyrixx @derrabus @xabbuh @fabpot @valtzu

we end up having customized result conversion with extraction paths like this:

ai/src/platform/src/Bridge/Anthropic/PlatformFactory.php

Lines 39 to 52 in 0a97792

	[Contract\ResultConverter::create([
	new TextResultExtractor('$.content[[email protected] == "text"].text'),
	new ToolCallResultExtractor(
	'$.content[[email protected] == "tool_use"]',
	'$.content[[email protected] == "tool_use"].id',
	'$.content[[email protected] == "tool_use"].name',
	'$.content[[email protected] == "tool_use"].input',
	),
	new StreamResultExtractor(
	'$.delta.text',
	'$.delta[[email protected] == "tool_use"]',
	'$.delta.stop_reason',
	),
	])],

[alexandre-daubois]

heavily-inspired by the OpenAI contract

I'm not sure to get what it means?

Also about your last comment, I'm not sure to understand the problem, but I'd be happy to help if you can elaborate on it 🙂