@@ -1659,32 +1659,64 @@ def is_off(self) -> bool:
16591659
16601660CacheRetention = Literal ["short" , "long" ]
16611661CacheMode = 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 )
16651669class 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
0 commit comments