Skip to content

Commit deedac7

Browse files
committed
MAP-6 step 1: CacheConfig intents (prefix, resource), CacheInfo, CachePage, CachedPrefix
Canonical values for the caching model from the 2026-09-01 design pass (lm15-contract/changes/2026-09-01-caching-design.md). Provider-neutral by construction: a stored cache belongs to one model on any provider with the tier; id formats, TTL spellings, and what the wire does with CacheConfig.resource are adapter concerns. - CacheConfig: prefix="stable"|"history" (named intents, exclusive with prefix_until_index), resource (a CacheInfo.id), mode="off" carries no other intent; vocabulary mirrors CACHE_MODES/RETENTIONS/PREFIXES. - CacheInfo(id, model, tokens, created_at, expires_at, label, provider_data), CachePage(items, next_cursor). - CachedPrefix(prefix: Request, resource: CacheInfo|None): request(messages) appends and sets the boundary at the seam; `cached + messages` is sugar. - serde pairs + vet kinds cache_info / cache_page / cached_prefix. No adapter change yet (step 2). 905 tests. Signed-off-by: Maxime Rivest <mrive052@gmail.com>
1 parent 89cfd85 commit deedac7

5 files changed

Lines changed: 376 additions & 13 deletions

File tree

‎lm15/__init__.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,9 @@
9898
FileUploadRequest,
9999
FileInfo,
100100
FilePage,
101+
CacheInfo,
102+
CachePage,
103+
CachedPrefix,
101104
BatchRequest,
102105
BatchEntry,
103106
BatchJobInfo,
@@ -219,6 +222,7 @@
219222
"ImageDelta", "ToolCallDelta", "CitationDelta", "ContinuationDelta",
220223
# auxiliary endpoints
221224
"FileUploadRequest", "FileInfo", "FilePage",
225+
"CacheInfo", "CachePage", "CachedPrefix",
222226
"BatchRequest", "BatchJobInfo", "BatchEntry",
223227
"VideoGenerationRequest", "VideoJobInfo", "VideoJob", "AsyncVideoJob",
224228
"BatchJob", "AsyncBatchJob",

‎lm15/serde.py‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@
2626
BinaryPart,
2727
BuiltinTool,
2828
CacheConfig,
29+
CachedPrefix,
30+
CacheInfo,
31+
CachePage,
2932
CitationDelta,
3033
CitationPart,
3134
Config,
@@ -389,6 +392,8 @@ def cache_config_to_dict(c: CacheConfig) -> dict[str, Any]:
389392
"retention": c.retention,
390393
"key": c.key,
391394
"prefix_until_index": c.prefix_until_index,
395+
"prefix": c.prefix,
396+
"resource": c.resource,
392397
})
393398

394399

@@ -404,6 +409,62 @@ def cache_config_from_dict(d: dict[str, Any]) -> CacheConfig:
404409
retention=retention,
405410
key=d.get("key"),
406411
prefix_until_index=d.get("prefix_until_index"),
412+
prefix=d.get("prefix"),
413+
resource=d.get("resource"),
414+
)
415+
416+
417+
# ─── Cache resources ─────────────────────────────────────────────────
418+
419+
def cache_info_to_dict(c: CacheInfo) -> dict[str, Any]:
420+
return _clean_mapping({
421+
"id": c.id,
422+
"model": c.model,
423+
"tokens": c.tokens,
424+
"created_at": c.created_at,
425+
"expires_at": c.expires_at,
426+
"label": c.label,
427+
"provider_data": c.provider_data,
428+
})
429+
430+
431+
def cache_info_from_dict(d: dict[str, Any]) -> CacheInfo:
432+
return CacheInfo(
433+
id=d["id"],
434+
model=d["model"],
435+
tokens=d.get("tokens"),
436+
created_at=d.get("created_at"),
437+
expires_at=d.get("expires_at"),
438+
label=d.get("label"),
439+
provider_data=d.get("provider_data"),
440+
)
441+
442+
443+
def cache_page_to_dict(p: CachePage) -> dict[str, Any]:
444+
return _clean_mapping({
445+
"items": [cache_info_to_dict(c) for c in p.items],
446+
"next_cursor": p.next_cursor,
447+
})
448+
449+
450+
def cache_page_from_dict(d: dict[str, Any]) -> CachePage:
451+
return CachePage(
452+
items=tuple(cache_info_from_dict(c) for c in d.get("items", [])),
453+
next_cursor=d.get("next_cursor"),
454+
)
455+
456+
457+
def cached_prefix_to_dict(c: CachedPrefix) -> dict[str, Any]:
458+
return _clean_mapping({
459+
"prefix": request_to_dict(c.prefix),
460+
"resource": cache_info_to_dict(c.resource) if c.resource is not None else None,
461+
})
462+
463+
464+
def cached_prefix_from_dict(d: dict[str, Any]) -> CachedPrefix:
465+
return CachedPrefix(
466+
prefix=request_from_dict(d["prefix"]),
467+
resource=cache_info_from_dict(d["resource"]) if isinstance(d.get("resource"), dict) else None,
407468
)
408469

409470

‎lm15/types.py‎

Lines changed: 188 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1659,32 +1659,64 @@ def is_off(self) -> bool:
16591659

16601660
CacheRetention = Literal["short", "long"]
16611661
CacheMode = Literal["auto", "off"]
1662+
CachePrefix = Literal["stable", "history"]
1663+
CACHE_MODES = frozenset(get_args(CacheMode))
1664+
CACHE_RETENTIONS = frozenset(get_args(CacheRetention))
1665+
CACHE_PREFIXES = frozenset(get_args(CachePrefix))
16621666

16631667

16641668
@dataclass(frozen=True, slots=True)
16651669
class CacheConfig:
16661670
"""
1667-
Universal prompt cache and session affinity configuration.
1668-
1669-
This is the primary, provider-neutral way to control prompt caching
1670-
and stable session routing.
1671-
1672-
- mode="auto": Let the provider adapter decide sensible defaults.
1673-
- mode="off": Explicitly disable sending cache hints.
1674-
- retention: Request short-lived or long-lived cache when supported.
1675-
- key: Stable identifier for cache/session affinity.
1676-
- prefix_until_index: Cache everything up to (and including) this
1677-
message index. Useful for stable system + tools + history prefixes.
1671+
Universal prompt cache configuration (MAP-6, docs/mapping-rules.md).
1672+
1673+
Every provider caches in up to three tiers: automatic (nothing to
1674+
send, best-effort), breakpoint (a mark on a block, guaranteed above a
1675+
per-model minimum), resource (a stored, named, billed object). The
1676+
fields name INTENTS; each adapter maps an intent to the best tier it
1677+
has, and the result is always visible in ``Usage.cache_read_tokens``.
1678+
1679+
- mode="auto": the cheapest safe instruction (a mark on the stable
1680+
beginning where marks exist; nothing elsewhere).
1681+
- mode="off": send nothing; where a provider has a real off switch
1682+
for cache WRITES, send it.
1683+
- prefix="stable": mark the end of system + tools.
1684+
prefix="history": mark the end of the last message (a growing
1685+
chat). Providers without marks fall back to the automatic tier:
1686+
that fallback spends nothing and its outcome is observable, the
1687+
two conditions that permit it.
1688+
- prefix_until_index: the same intent with a precise position (the
1689+
last block of that message). Mutually exclusive with ``prefix``.
1690+
- retention: "long" asks for the longer lifetime at extra cost;
1691+
providers without one RAISE.
1692+
- key: a best-effort routing/affinity hint; providers without one RAISE.
1693+
- resource: the id of a stored cache object (``CacheInfo.id``) to
1694+
reference; providers without the resource tier RAISE.
16781695
"""
16791696

16801697
mode: CacheMode = "auto"
16811698
retention: CacheRetention | None = None
16821699
key: str | None = None
16831700
prefix_until_index: int | None = None
1701+
prefix: CachePrefix | None = None
1702+
resource: str | None = None
16841703

16851704
def __post_init__(self) -> None:
1686-
if self.mode == "off" and (self.retention is not None or self.key is not None):
1687-
raise ValueError("CacheConfig(mode='off') cannot specify retention or key")
1705+
if self.mode not in CACHE_MODES:
1706+
raise ValueError(f"unsupported cache mode: {self.mode}")
1707+
if self.retention is not None and self.retention not in CACHE_RETENTIONS:
1708+
raise ValueError(f"unsupported cache retention: {self.retention}")
1709+
if self.prefix is not None and self.prefix not in CACHE_PREFIXES:
1710+
raise ValueError(f"unsupported cache prefix: {self.prefix}")
1711+
_validate_optional_text(self.key, field_name="CacheConfig.key", allow_empty=False)
1712+
_validate_optional_text(self.resource, field_name="CacheConfig.resource", allow_empty=False)
1713+
if self.mode == "off" and (
1714+
self.retention is not None or self.key is not None
1715+
or self.prefix is not None or self.prefix_until_index is not None or self.resource is not None
1716+
):
1717+
raise ValueError("CacheConfig(mode='off') cannot specify retention, key, prefix, prefix_until_index, or resource")
1718+
if self.prefix is not None and self.prefix_until_index is not None:
1719+
raise ValueError("CacheConfig cannot specify both prefix and prefix_until_index")
16881720
if self.prefix_until_index is not None:
16891721
_coerce_int_field(self, "prefix_until_index")
16901722
_validate_non_negative(self.prefix_until_index, field_name="prefix_until_index")
@@ -2255,6 +2287,149 @@ def __post_init__(self) -> None:
22552287
_validate_optional_text(self.next_cursor, field_name="FilePage.next_cursor", allow_empty=False)
22562288

22572289

2290+
# ─── Cache resources (the stored tier of MAP-6) ──────────────────────
2291+
#
2292+
# A stored cache object belongs to one model on every provider that has
2293+
# the tier (a KV state is model-specific by nature). ``CacheInfo`` is the
2294+
# snapshot; ``CachedPrefix`` is the ergonomic that pairs a prefix Request
2295+
# with its optional object and builds requests against it. Nothing here
2296+
# names a provider: id formats, TTL spellings, and what the wire does with
2297+
# ``CacheConfig.resource`` are the adapter's business.
2298+
2299+
2300+
@dataclass(frozen=True, slots=True)
2301+
class CacheInfo:
2302+
"""A snapshot of one provider-side stored cache object.
2303+
2304+
``id`` is the provider's reference verbatim; place it in
2305+
``CacheConfig.resource``. ``tokens`` is the stored token count when
2306+
reported (storage cost = tokens x hours x the provider's rate).
2307+
``expires_at`` is ISO-8601 UTC, normalized from the provider's form.
2308+
"""
2309+
2310+
id: str
2311+
model: str
2312+
tokens: int | None = None
2313+
created_at: str | None = None
2314+
expires_at: str | None = None
2315+
label: str | None = None
2316+
provider_data: ProviderData | None = None
2317+
2318+
def __post_init__(self) -> None:
2319+
_validate_text(self.id, field_name="CacheInfo.id", allow_empty=False)
2320+
_validate_text(self.model, field_name="CacheInfo.model", allow_empty=False)
2321+
_coerce_int_field(self, "tokens")
2322+
_validate_non_negative(self.tokens, field_name="CacheInfo.tokens")
2323+
_validate_optional_text(self.created_at, field_name="CacheInfo.created_at", allow_empty=False)
2324+
_validate_optional_text(self.expires_at, field_name="CacheInfo.expires_at", allow_empty=False)
2325+
_validate_optional_text(self.label, field_name="CacheInfo.label", allow_empty=False)
2326+
_validate_json_field(self, "provider_data")
2327+
2328+
2329+
@dataclass(frozen=True, slots=True)
2330+
class CachePage:
2331+
"""One page of stored cache objects plus an opaque continuation cursor."""
2332+
2333+
items: tuple[CacheInfo, ...] = ()
2334+
next_cursor: str | None = None
2335+
2336+
def __post_init__(self) -> None:
2337+
object.__setattr__(self, "items", tuple(self.items))
2338+
if not all(isinstance(item, CacheInfo) for item in self.items):
2339+
raise TypeError("CachePage.items must contain CacheInfo objects")
2340+
_validate_optional_text(self.next_cursor, field_name="CachePage.next_cursor", allow_empty=False)
2341+
2342+
2343+
@dataclass(frozen=True, slots=True)
2344+
class CachedPrefix:
2345+
"""A reusable prompt beginning: ``cached = lm.cache(prefix)``.
2346+
2347+
``prefix`` is a Request whose model, system, tools, and messages form
2348+
the reusable part (its config must be default: a cached object has no
2349+
temperature). ``resource`` is the stored object on providers with
2350+
that tier, ``None`` on providers that mark blocks or cache
2351+
automatically. ``request(messages)`` builds a Request that appends
2352+
``messages`` and sets the cache boundary at the seam; ``cached +
2353+
messages`` is Python sugar for it. The built Request and its wire
2354+
bytes are what the contract pins; the sugar is per-language.
2355+
"""
2356+
2357+
prefix: Request
2358+
resource: CacheInfo | None = None
2359+
2360+
def __post_init__(self) -> None:
2361+
if not isinstance(self.prefix, Request):
2362+
raise TypeError("CachedPrefix.prefix must be a Request")
2363+
if self.prefix.config != Config():
2364+
raise ValueError("CachedPrefix.prefix must carry a default Config: a cached object has no generation settings")
2365+
if self.resource is not None:
2366+
if not isinstance(self.resource, CacheInfo):
2367+
raise TypeError("CachedPrefix.resource must be a CacheInfo")
2368+
if self.resource.model != self.prefix.model:
2369+
raise ValueError("CachedPrefix.resource.model must equal the prefix model (a stored cache belongs to one model)")
2370+
2371+
@property
2372+
def id(self) -> str | None:
2373+
return self.resource.id if self.resource is not None else None
2374+
2375+
@property
2376+
def expires_at(self) -> str | None:
2377+
return self.resource.expires_at if self.resource is not None else None
2378+
2379+
def cache_config(self) -> CacheConfig:
2380+
"""The CacheConfig that marks the seam between prefix and suffix."""
2381+
return CacheConfig(
2382+
prefix_until_index=len(self.prefix.messages) - 1,
2383+
resource=self.id,
2384+
)
2385+
2386+
def request(
2387+
self,
2388+
messages: "str | Message | Sequence[Message] | Request",
2389+
*,
2390+
config: Config | None = None,
2391+
) -> Request:
2392+
"""Append ``messages`` to the prefix and set the cache boundary.
2393+
2394+
``messages`` may be a string (one user message), a Message, a
2395+
sequence of Messages, or a Request (same model, no system, no
2396+
tools: the prefix owns those). ``config`` supplies generation
2397+
settings; its ``cache`` must be unset (the prefix decides).
2398+
"""
2399+
suffix: tuple[Message, ...]
2400+
if isinstance(messages, Request):
2401+
if messages.model != self.prefix.model:
2402+
raise ValueError("suffix Request model must equal the prefix model")
2403+
if messages.system is not None or messages.tools:
2404+
raise ValueError("suffix Request cannot redefine system or tools: the prefix owns them")
2405+
if config is None and messages.config != Config():
2406+
config = messages.config
2407+
suffix = messages.messages
2408+
elif isinstance(messages, str):
2409+
suffix = (Message.user(messages),)
2410+
elif isinstance(messages, Message):
2411+
suffix = (messages,)
2412+
else:
2413+
suffix = tuple(messages)
2414+
if not suffix or not all(isinstance(m, Message) for m in suffix):
2415+
raise TypeError("messages must be a Message or a non-empty sequence of Messages")
2416+
base = config if config is not None else Config()
2417+
if base.cache is not None:
2418+
raise ValueError("config.cache is decided by the CachedPrefix; leave it unset")
2419+
from dataclasses import replace as _replace
2420+
2421+
return Request(
2422+
model=self.prefix.model,
2423+
system=self.prefix.system,
2424+
tools=self.prefix.tools,
2425+
messages=self.prefix.messages + suffix,
2426+
config=_replace(base, cache=self.cache_config()),
2427+
)
2428+
2429+
def __add__(self, messages: "str | Message | Sequence[Message] | Request") -> Request:
2430+
return self.request(messages)
2431+
2432+
22582433
# ─── Batch ───────────────────────────────────────────────────────────
22592434

22602435

‎lm15/vet.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,9 @@ def adapter_for_provider(provider: str, api_key: str, base_url: str | None = Non
8989
"reasoning": (serde.reasoning_from_dict, serde.reasoning_to_dict),
9090
"config": (serde.config_from_dict, serde.config_to_dict),
9191
"cache_config": (serde.cache_config_from_dict, serde.cache_config_to_dict),
92+
"cache_info": (serde.cache_info_from_dict, serde.cache_info_to_dict),
93+
"cache_page": (serde.cache_page_from_dict, serde.cache_page_to_dict),
94+
"cached_prefix": (serde.cached_prefix_from_dict, serde.cached_prefix_to_dict),
9295
"continuation_state": (serde.continuation_from_dict, serde.continuation_to_dict),
9396
"error_detail": (serde.error_detail_from_dict, serde.error_detail_to_dict),
9497
"delta": (serde.delta_from_dict, serde.delta_to_dict),

0 commit comments

Comments
 (0)