/ 
Langertha-0.503
/ Langertha::PromptCache

NAME

Langertha::PromptCache - Immutable prompt-caching request control with cross-provider conversion

VERSION

version 0.503

SYNOPSIS

my $c = Langertha::PromptCache->new(
    enable => 1,
    ttl    => '1h',
);
my %kwargs = $c->to('anthropic');
# ( cache_control => { type => 'ephemeral', ttl => '1h' } )

my $c2 = Langertha::PromptCache->new( key => 'my-route' );
my %kw2 = $c2->to('openai');
# ( prompt_cache_key => 'my-route' )

DESCRIPTION

Canonical value object for the request-side prompt-caching knob, dispatched by an engine's cache_wire_format. Mirrors Langertha::Reasoning: the per-provider placement of the field lives in this one reviewable place rather than scattered across engines (ADR 0001).

Prompt caching is asymmetric across providers. Only two providers expose a per-request knob worth modeling:

  • Anthropic — an explicit cache_control breakpoint enables caching (top-level auto-place form). Carries an optional ttl (5m default, 1h).

  • OpenAI — caching is automatic; the only request-side lever is prompt_cache_key, a routing hint that steers which cache shard is used.

Every other provider (Gemini, DeepSeek, ...) caches implicitly with no request-side parameter, so this value object models exactly these two shapes.

enable

Whether to emit an Anthropic cache_control breakpoint. Ignored by the OpenAI serializer (OpenAI caching is automatic).

ttl

Optional Anthropic cache time-to-live: 5m (the current default when omitted) or 1h. Only emitted when set; the 1h window needs this set explicitly.

key

Optional OpenAI prompt_cache_key routing hint. Ignored by the Anthropic serializer.

to_anthropic

Serializes to the top-level cache_control => { type => 'ephemeral' } auto-place form (plus ttl when set). Empty list when caching is not enabled.

to_openai

Serializes to a flat prompt_cache_key. Empty list when no key is set.

to

my %kwargs = $c->to($cache_wire_format);

Dispatch to the per-format serializer. Returns the body kwargs to merge into the request (an empty list when nothing applies to that wire).

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.