Road to Symfony AI v1.0

[chr-hertel]

Of course, we want Symfony AI to become a stable and reliable set of packages, complying to known Symfony standards, like the BC promise. This will only be achieved with the release of v1.0.

Reaching that level of reliability is important for adoption and using Symfony AI in production without patching your code all the time.

When going with symfony/ai instead of integration into symfony/symfony we decoupled releases deliberately since we're still figuring out what we need to build. And as long, as we are aware of flaws, that make BC breaks necessary, it would create extra effort to provide a BC layer - slowing is down.

However, we want to create transparency, where we are on this road, for users to follow along.
This issue tracks high-level items, that need to be resolved until we can tag a v1.0 of Symfony AI.
When all items are tackled, a feature freeze around 4 weeks will kick in, to stabilize the codebase.

• This uses the MoSCoW method for priotization. Items are up for discussion.
• Items are labeled as MUST if impact to component API is expected.

Open to resolve

• Platform Component
  • MUST Solve dynamic model catalogs decoupling package lifecycle of model lifecycle
  • MUST Better stream handling for exposing thinking/reasoning as well
    • [Platform] Replace untyped stream chunks with semantic DeltaInterface deltas #1759
    • [Platform][OpenAI] Missing reasoning content when streaming with Responses API #1830
    • [Platform][Gemini] Support thought (reasoning) in tool calls to prevent 400 INVALID_ARGUMENT #1539
  • MUST Better handling of multi-modal responses (generated speech, images or video)
  • MUST Solve model catalog handling and model lifecycle
    • [Platform] Accept Model instance in Platform::invoke() #2139
    • [Platform] Streamline the models.dev bridge to a data-only layer #2147
    • Static model catalogs?
    • Docs
  • SHOULD Meaningful adoption of capabilities/tasks, validation and routing in ModelCatalog/Platform
  • SHOULD Rework ModelClient to EndpointClient
  • COULD Normalized options
  • COULD Exception structure
  • COULD Remote tool support
  • COULD Twig message template support
  • COULD Toon support for embedded objects
  • COULD Streamlined Error Handling
  • COULD Streamlined JSON to data conversion
• Agent Component
  • MUST Redesigned API to tailored Agent API instead of being a slim Platform decorator (name + instruction + tools + input + options)
    • [Agent] Revisit Agent Component Interface #1406
  • MUST Introduce traces to come out-of-the-box instead of custom
    • [Agent] Agent Execution Trace #17
  • MUST Fold state handling into Agent and deprecate Chat component (incl. sleep/branch/rewind?)
  • SHOULD Built-in support for integration with messenger & workflow component
  • SHOULD Integrate hand-off into one universal Agent
  • SHOULD Default approach to human-in-the-loop (cookbook)
  • SHOULD Sources/traces support across built-in tools
  • SHOULD Message template support for SimilaritySearch (and others?)
  • SHOULD Parallelization
  • COULD MCP support, agent acting as MCP Client
  • COULD Prevent tool calling loops
  • COULD Validation on top of structured output
  • COULD Tool classifier (read vs write) => replaced by metadata in [AI Bundle][Agent][Platform] Allow attaching metadata to tools #2316
• Store Component
  • MUST Introduce retrieval extension points for features like multi-vector query or reranking
  • MUST Work out-of-the-box with entities/repositories - unified store vs. additional store (demo)
  • MUST StoreFactory + ScopedClients
  • MUST Scope of StoreInterface methods, .e.g count() or clear()
  • SHOULD More loaders & transformer implementations (web, folder, pdf, word, json, ...)
  • COULD Generalize common options when querying
• Chat Component
  • MUST Handle multi-user conversations
  • SHOULD Streaming integration
• Mate
  • MUST Composer Plugin Integration
    • [Mate] Composer Plugin Integration #1832
• AI Bundle
  • SHOULD Panel split into components (platform, store, tools, and agents), but unified trace for Agent
• Demo
  • SHOULD Switch to Hugging Face as default (document OpenAI, Gemini, etc.)
  • COULD Use Mercure
• General
  • MUST Get rid off public properties for easing BC promise
  • SHOULD Get rid of variadics for easing BC promise

Known, but not needed for

• Agent/Model evaluation framework
• A2A or A2UI/AG-UI support
• OTEL integration
• More bridges
• MCP Apps
• ORT
• Platform Routing / Connector

[julesdig]

Hi @chr-hertel ,

I’ve been following the Symfony AI roadmap and saw the open items toward v1.0 (especially the Platform / Agent parts).

I’d really like to contribute to Symfony AI as an open-source contributor.
I’m motivated to code, but I’m not entirely sure where the best entry point is right now.

Would you recommend starting with a specific SHOULD / COULD item, or a particular component that would benefit most from contributions at the moment?

Happy to work on a concrete, well-scoped task.

Thanks!

[OskarStark]

Welcome and thanks for joining us on this journey :airplane

I think

SHOULD More loaders & transformer implementations (web, folder, pdf, word, json, ...)

is a good starting point with a smaller scope. Maybe start with the folder or json one

[julesdig]

@OskarStark Thanks for the suggestion!

To make sure I’m aligned: I started working on a JsonLoader following the same approach as the existing TextFileLoader.

The idea for now is:

• JsonLoader reads a JSON file from disk (same checks as TextFileLoader)
• validates that the file contains valid JSON
• and creates one TextDocument from it, using the JSON content as the document content

So conceptually, it’s the same as TextFileLoader, except the source is JSON instead of plain text.

What I’m not fully sure about yet is the next step:

• whether the loader should already extract a specific text field (e.g. "content")
• or if it’s expected that the JSON stays as-is and the transformation / chunking into text is handled later by a Transformer

For a first contribution, would you consider a simple JsonLoader (JSON file → TextDocument with raw JSON content) acceptable, similar in spirit to TextFileLoader?

Happy to iterate based on your feedback.

[chr-hertel]

@julesdig only doing the same like the TextFileLoader would be too little, but let's move the discussion to #1404

[chr-hertel]

In order to get things ready for v1.0 we should start to focus more on the fundamental extension point of the components over adding more features - also making sure we don't have too much of stabilization phase and maintenance over features, that could easily also live in user land or libs on top of symfony/ai.

For me, this means to focus on primary extension points and drop larger features sitting on top. As mitigation for lib users I would propose to add docs/cookbook articles to outline how to use extension points for higher level features, i started with an example to reduce the scope for a lower library footprint => #1548 becomes #1768

Also applies to #1549, #1707, Chat Component, MultiAgent, #1718, and a few more things I guess.
I know this is quite disruptive for some work, and might be controversial, but I don't think in the end we would break a single use-case but only redefine what symfony/ai covers for now, and shift more to users projects or additional libs.

Let's discuss @OskarStark @welcoMattic @Guikingone @fabpot @javiereguiluz

[fabpot]

It makes a lot of sense to me.

[wachterjohannes]

@chr-hertel Couldn’t agree more. Doubling down on the core extension points is the right call—keeps things manageable and avoids turning symfony/ai into a kitchen sink. I’m already offloading some of the extra extensions to MatesOfMate to keep the main repo focused. Cookbook examples will make it easy for others to plug in what they need.

[javiereguiluz]

I agree with the previous comments: I think this is the right call.

In current AI landscape, I think that shipping fast (and adapting to changes fast) is more important that trying to ship a lof of features.

Thanks.

[Guikingone]

Don't have a strong opinion on this to be honest, IMHO, the end conversation shouldn't be about stabilization / adding features but about what Symfony AI aims to be.

• If Symfony AI is a foundational layer to integrate AI into applications without having a strong opinion about how it must be integrated, well, yes, reducing the end scope might be defended (even if at the end of the day, if Sf AI is only a foundational layer, what's the benefit of using it instead of NeuronAI or others? I know, I might sound trivial but the question must be asked, on the other hand, Symfony UX is an initiative that ease the integration of external librairies / practices into Symfony, it delivers a strong view while being a "foundational layer" and based around the Sf ecosystem, not to mention that Sf UX includes "biased tools / approaches" about how to solve certain use cases).

• If Symfony AI is an opinionated set of components that aims to integrate AI into PHP application, well, the answer, IMHO, cannot be "let's reduce the scope and only maintain the foundations" as other "frameworks" are already more advanced than Sf AI (NeuronAI, LaravelAI in a sense, Mastra, Letta, Langchain and so on), if Sf AI aims to be "the de facto AI framework" for PHP / Sf ecosystem, in this case, it "should" deliver a strong view on how to do it while allowing to be extended freely (as Mate already does).

• If Symfony AI aims to be the "SymfonyClaw" equivalent in Symfony ecosystem, well, sorry to say that it's already too late to reduce the scope as other solutions are already more advanced and integrate more features, delivering a 1.0 that doesn't integrate feature like compressions and more might set Sf AI as "simple concurrent already too late".

Sorry for this "kind in a middle answer", don't have a strong opinion to be honest (well, I have one but as a daily user of Sf AI and contributor, I can't express it freely without being biased), if the target is "let's stabilize the current state / integrations and discuss about future features after the release of 1.0", I think it might be too soon, the 0.6 is out since a few days and the 0.5 cannot be considered as a "real release" in my opinion as it was mostly a "bug fix" one, on the other hand, stabilization is crucial if the library aim to become "the standard" in the Sf ecosystem while building on top of a solid foundation.

Regarding features, it all comes down to what Sf AI aim to be, if it's a foundational layer, well, reducing scope might be a solution while documenting how to integrate advanced features (like workflows and others) and easing developer experience with helpers and other.

The only situation I'm fearing is one like the FosUser / FosRest bundles, as Symfony grows, using those bundle become a bad idea as the framework already integrate tools to solve the issues tackled by the bundles, my fear is that if Sf AI aims to "reduce its scope and let user solve their problems at the application-lever", one day, developers will try to contribue to Sf AI to solve the issues at the "library" lever and we'll end up in the same situation (while being late regarding other librairies) 😅

PS: Sorry for the long answer 😄