[Platform][Cache] Cache content-object inputs via CacheKeyGenerator strategy

[tacman]

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

CachePlatform (the ai.platform.cache.* decorator) could only build a cache
key for string, array and MessageBag inputs — it threw
Unsupported input type on anything else. That means it could not decorate any
platform task whose top-level input is a content object, which is the normal
shape for the slow/expensive calls most worth caching:

• audio transcription — $platform->invoke('whisper-1', Audio::fromFile(...))
• OCR — $platform->invoke('mistral-ocr-latest', new DocumentUrl(...))
• single-image vision — $platform->invoke($model, new ImageUrl(...))

Approach

Per @chr-hertel's review (keying inputs is the bridge's job — it shouldn't leak
into the Platform component or its content classes), this keeps the knowledge of
how to key an input inside the Cache bridge via a small strategy
interface:

namespace Symfony\AI\Platform\Bridge\Cache;

interface CacheKeyGenerator
{
    public function supports(object $input): bool;
    public function generate(object $input): string;
}

CachePlatform holds an ordered list of generators and the first one that
supports() an input keys it:

$normalizedInput = match (true) {
    \is_string($input) => md5($input),
    \is_array($input) => json_encode($input),
    default => $this->generateInputCacheKey($input), // tries each CacheKeyGenerator
};

The default set covers MessageBag, DocumentUrl, ImageUrl and
File (and its Audio/Image/Video/Document subclasses). DocumentUrl
and ImageUrl key on the URL; File on a hash of its bytes. getCacheKey()
values are used verbatim in a cache key, so the URL/byte arms hash their value
(xxh128) the same way the existing string arm uses md5().

MessageBag now routes through the same mechanism
(MessageBagCacheKeyGenerator), so all object inputs go through one
consistent path instead of a special-cased inline arm.

$cached = new CachePlatform($platform, cache: $pool);
$cached->invoke('mistral-ocr-latest', new DocumentUrl('https://…/doc.pdf'), [
    'prompt_cache_key' => 'ocr',
]); // now cached instead of throwing

A userland content type opts in by registering its own generator — no change to
CachePlatform or to core content classes:

new CachePlatform($platform, cache: $pool, cacheKeyGenerators: [
    new MyContentCacheKeyGenerator(),
    new MessageBagCacheKeyGenerator(),
    // …
]);

Scope

Fully isolated in the bridge: no changes to the Platform component or its
content classes, so the dependency points bridge → component only. This is
also additive — behavior for string/array/MessageBag inputs is unchanged.

Tests added to CachePlatformTest (content-object cached once; different inputs
not shared; unsupported object still throws; custom generator honored). Surfaced
while adding a Mistral OCR bridge (#2072), but independent of it — the gap
already affects Whisper today.

Supersedes the earlier CacheableInputInterface-in-Platform approach from
this PR's first revision, which leaked the bridge's caching concern into the
core content classes.

[chr-hertel]

From architecture point of view I'm not a real fan here since requirements of that cache bridge are leaking into the main Platform component - you avoided that it gets obvious with moving the CacheableInputInterface into the Platform namespace, but semantically it's still leaky. can we isolate this in the bridge itself?

[tacman]

Yeah, you're right — keying inputs is the bridge's job, not something core content classes should advertise. The fix I have in mind keeps an interface (so it stays extensible) but moves it into the bridge as a strategy:

namespace Symfony\AI\Platform\Bridge\Cache;

interface CacheKeyGenerator
{
    public function supports(object $input): bool;
    public function generate(object $input): string;
}

CachePlatform holds an ordered list of these (default set covers DocumentUrl/ImageUrl/File), so the dependency points bridge → component, content classes go back to pure, and a userland content type can register its own generator instead of implementing a core interface. CacheableInputInterface and the getCacheKey() methods get dropped.

One thing I want your call on before I push, since it shapes the implementation: should MessageBag route through the same generator mechanism, or stay inline? Today it's keyed inline ($input->getId()). I'd lean toward folding it into a MessageBagCacheKeyGenerator so all object inputs go through one consistent path — otherwise we've got two parallel mechanisms for objects, which is a bit of the same smell. But if you'd rather keep MessageBag special-cased inline and only route the content objects through generators, that's an easy variant. Which do you prefer?

[tacman]

@chr-hertel thoughts on this? I'd love to get it in before 0.11 -- the mistral calls are relatively expensive, so I'd love to cache them.

[chr-hertel]

that pattern looks like a good fit to me 👍

[tacman]

CacheKeyGenerator, with MessageBag going through it as well? I'll submit a PR shortly.

[tacman]

Pushed the CacheKeyGenerator strategy as discussed — it lives entirely in the Cache bridge now, so there are no changes to the Platform component or its content classes (CacheableInputInterface and the getCacheKey() methods are gone). MessageBag routes through the same mechanism (MessageBagCacheKeyGenerator), so all object inputs share one consistent path, and custom input types opt in by registering their own generator. Default set: MessageBag, DocumentUrl, ImageUrl, File/Audio. CHANGELOG is under 0.11.

[tacman]

Green now — the last red was a Fabbot nit (exception value needed double-quoting in CachePlatform), fixed. Recap of where this landed vs your review: the caching concern is fully isolated in the bridge via the CacheKeyGenerator strategy you sketched — nothing leaks into the Platform component or its content classes, and MessageBag routes through the same path. I credited you as co-author on the CacheKeyGenerator interface since the shape was your call. Mind giving it another look when you have a sec? 🙏