/ 
Langertha-0.503
/ Langertha::Role::CachedContent

NAME

Langertha::Role::CachedContent - Role for the explicit cachedContent resource lifecycle (create/get/list/update/delete)

VERSION

version 0.503

SYNOPSIS

with 'Langertha::Role::CachedContent';

my $cc = $engine->create_cached_content_f(
    model              => 'models/gemini-2.5-pro',
    system_instruction => 'You are a careful reviewer.',
    ttl                => '300s',
    contents           => [ { role => 'user', parts => [ { text => 'long prompt...' } ] } ],
);
# Returns a Langertha::CachedContent with name set

my $same = await $engine->get_cached_content_f( $cc->name );
my @all  = await $engine->list_cached_contents_f;
await $engine->update_cached_content_f( $cc->name, ttl => '600s' );
await $engine->delete_cached_content_f( $cc->name );

DESCRIPTION

Lifecycle wrapper around the Gemini explicit cachedContent resource (https://ai.google.dev/api/caching). Composed by engines that want to expose resource management (currently Langertha::Engine::Gemini) — the methods are role methods, not engine methods, so any other engine with the same REST surface can compose the role rather than re-implement it.

Endpoints, {base} being the consumer's "gemini_endpoint" in Langertha::Engine::Gemini ({url}/v1beta on the Developer API):

  • POST {base}/cachedContents — create =item * GET {base}/cachedContents — list (paginated) =item * GET {base}/cachedContents/{name} — get =item * PATCH {base}/cachedContents/{name} — update (expiration only) =item * DELETE {base}/cachedContents/{name} — delete

The _f methods are async via Future::AsyncAwait and send through the engine's async transport (Langertha::Role::AsyncHTTP): Net::Async::HTTP when installed, an injected _async_http client, or the synchronous LWP fallback. On Net::Async::HTTP the engine's user_agent_timeout bounds each request. The sync methods ("create_cached_content", etc.) send over the engine's user_agent. Both give the same result, and an HTTP error croaks / fails with the same text (the engine's request failed message, see "parse_response" in Langertha::Role::HTTP).

The role owns the resource paths and the HTTP plumbing only. Base URL, API version and the credential are the consumer's — every request URL is built by the required gemini_endpoint / gemini_url seam (Langertha::Engine::Gemini, ADR 0016 decision 3), so a subclass that moves the endpoint or the auth scheme moves the whole cachedContents lifecycle with it. The role does not introspect model names or filter by generation. Engines narrow Langertha::Engine::Gemini's advertising of the capability per model family (see Langertha::Engine::Gemini's around engine_capabilities).

create_cached_content_f

my $cc = await $engine->create_cached_content_f(
    model              => 'models/gemini-2.5-pro',
    ttl                => '300s',
    system_instruction => 'be brief',
    contents           => [ ... ],
    tools              => [ ... ],          # optional
    display_name       => 'reviewer',       # optional
);
# $cc is a Langertha::CachedContent with name set

Posts to the cachedContents collection (POST /v1beta/cachedContents on the Developer API), parses the response into a Langertha::CachedContent. Accepts either a pre-built Langertha::CachedContent (the role will call to_create_body for you) or the individual named attributes.

Returns the persisted CachedContent.

create_cached_content

my $cc = $engine->create_cached_content(%same_args);

Sync wrapper around "create_cached_content_f".

get_cached_content_f

my $cc = await $engine->get_cached_content_f('cachedContents/abc123');
my $cc = await $engine->get_cached_content_f('abc123');          # bare id accepted

Fetch a single cache by name (or bare id).

list_cached_contents_f

my @caches = await $engine->list_cached_contents_f;
my @page   = await $engine->list_cached_contents_f(page_size => 50);

Returns a list of Langertha::CachedContent. Walks pagination automatically (https://ai.google.dev/api/caching#method:-cachedcontents.list). Accepts page_size and page_token for one-page control.

update_cached_content_f

await $engine->update_cached_content_f( 'cachedContents/abc123', ttl => '600s' );
await $engine->update_cached_content_f( 'cachedContents/abc123', expire_time => '2030-01-01T00:00:00Z' );

Updates a cache. Per the REST contract, only expiration is updatable (https://ai.google.dev/api/caching#method:-cachedcontents.patch). Pass exactly one of ttl or expire_time. The server requires the updateMask query parameter so we set it explicitly to whichever field the caller is updating.

delete_cached_content_f

await $engine->delete_cached_content_f('cachedContents/abc123');

Delete a cache. Returns 1 on success.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.