arize-phoenix 9.5.0__py3-none-any.whl → 9.6.1__py3-none-any.whl

{arize_phoenix-9.5.0.dist-info → arize_phoenix-9.6.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arize-phoenix
-Version: 9.5.0
+Version: 9.6.1
 Summary: AI Observability and Evaluation
 Project-URL: Documentation, https://docs.arize.com/phoenix/
 Project-URL: Issues, https://github.com/Arize-ai/phoenix/issues

{arize_phoenix-9.5.0.dist-info → arize_phoenix-9.6.1.dist-info}/RECORD

@@ -6,7 +6,7 @@ phoenix/exceptions.py,sha256=n2L2KKuecrdflB9MsCdAYCiSEvGJptIsfRkXMoJle7A,169
 phoenix/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 phoenix/services.py,sha256=ngkyKGVatX3cO2WJdo2hKdaVKP-xJCMvqthvga6kJss,5196
 phoenix/settings.py,sha256=x87BX7hWGQQZbrW_vrYqFR_izCGfO9gFc--JXUG4Tdk,754
-phoenix/version.py,sha256=T_7n4J2JLWQ42N9H4Lbyh67nFa5HaqLPNGqgJpswgHk,22
+phoenix/version.py,sha256=gkjhVoAFhlcpBLzRIiqhKP7hOWAIqvxp25eVs0y914g,22
 phoenix/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 phoenix/core/embedding_dimension.py,sha256=zKGbcvwOXgLf-yrJBpQyKtd-LEOPRKHnUToyAU8Owis,87
 phoenix/core/model.py,sha256=qBFraOtmwCCnWJltKNP18DDG0mULXigytlFsa6YOz6k,4837
@@ -157,7 +157,7 @@ phoenix/server/api/helpers/__init__.py,sha256=m2-xaSPqUiSs91k62JaRDjFNfl-1byxBfY
 phoenix/server/api/helpers/annotations.py,sha256=9gMXKpMTfWEChoSCnvdWYuyB0hlSnNOp-qUdar9Vono,262
 phoenix/server/api/helpers/dataset_helpers.py,sha256=DoMBTg-qXTnC_K4Evx1WKpCCYgRbITpVqyY-8efJRf0,8984
 phoenix/server/api/helpers/experiment_run_filters.py,sha256=DOnVwrmn39eAkk2mwuZP8kIcAnR5jrOgllEwWSjsw94,29893
-phoenix/server/api/helpers/playground_clients.py,sha256=mDYuATl7LxwdQAp2WJlUCERTDqkn3wbTtDK_kj04n_A,41881
+phoenix/server/api/helpers/playground_clients.py,sha256=C-GPq4wklcnGXiW5-7-ipx5wjowDuwSKzqbGHta2QEc,41888
 phoenix/server/api/helpers/playground_registry.py,sha256=CPLMziFB2wmr-dfbx7VbzO2f8YIG_k5RftzvGXYGQ1w,2570
 phoenix/server/api/helpers/playground_spans.py,sha256=ObAhvV_yNwEQDkjzgU5G73wfIisc8q4cpB0OFH5cd24,16974
 phoenix/server/api/helpers/prompts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -231,7 +231,7 @@ phoenix/server/api/routers/utils.py,sha256=M41BoH-fl37izhRuN2aX7lWm7jOC20A_3uClv
 phoenix/server/api/routers/v1/__init__.py,sha256=0oOcsKJkQtBXAjZAo3AMtfjyW3OGCU4MI4TGW5nV6lo,2614
 phoenix/server/api/routers/v1/annotation_configs.py,sha256=rZ3yJm7m75BVegSjSHqsdqf7n26roGg7vYYiiKfWA3A,15898
 phoenix/server/api/routers/v1/annotations.py,sha256=oeafR2tCLu-uIwM9J72gN3MX5WDhrOMU3Jqd1uIiFqg,5921
-phoenix/server/api/routers/v1/datasets.py,sha256=gHlF4x0EmWiJ-8vwJygoh0bO3gvDBmi6vYnLAbSkQw4,37057
+phoenix/server/api/routers/v1/datasets.py,sha256=Wqiy6ZKqn4BZSFyn93gzuhWx3mGn7kOkNncHzCWuBq8,37325
 phoenix/server/api/routers/v1/evaluations.py,sha256=GFTo42aIEX0Htn0EjjoE1JZDYlvryeZ_CK9kowhwzGw,12830
 phoenix/server/api/routers/v1/experiment_evaluations.py,sha256=xSs004jNYsOl3eg-6Zjo2tt9TefTd7WR3twWYrsNQNk,4828
 phoenix/server/api/routers/v1/experiment_runs.py,sha256=jqpquCygtUYNNN7lgSvGvOlXCE7KTleDRFjxJ7bbDfM,6400
@@ -305,11 +305,12 @@ phoenix/server/api/types/Retrieval.py,sha256=OhMK2ncjoyp5h1yjKhjlKpoTbQrMHuxmgSF
 phoenix/server/api/types/ScalarDriftMetricEnum.py,sha256=IUAcRPpgL41WdoIgK6cNk2Te38SspXGyEs-S1fY23_A,232
 phoenix/server/api/types/Segments.py,sha256=vT2v0efoa5cuBKxLtxTnsUP5YJJCZfTloM71Spu0tMI,2915
 phoenix/server/api/types/SortDir.py,sha256=OUpXhlCzCxPoXSDkJJygEs9Rw9pMymfaZUG5zPTrw4Y,152
-phoenix/server/api/types/Span.py,sha256=N61m2HKaF-F7t7myCfg5k2cbzM_4R86wZS4r881e-SY,28787
+phoenix/server/api/types/Span.py,sha256=ZaDUBOPk4YE9nV0379Yc1NEZKnItWmIdCbJVgXaBgAU,30482
 phoenix/server/api/types/SpanAnnotation.py,sha256=uPWu7Z8rmpfKhaaxbged4_o00pPCR3nkn7Gji9vB8jY,1959
 phoenix/server/api/types/SpanIOValue.py,sha256=c5TWdZZN3v0gHI5xWeY7gjD-sE9ugWlGGAio-gDS-Uo,1653
 phoenix/server/api/types/SystemApiKey.py,sha256=2ym8EgsTBIvxx1l9xZ-2YMovz58ZwYb_MaHBTJ9NH2E,166
 phoenix/server/api/types/TimeSeries.py,sha256=nuuZtfHmOhTjeB8_SvZ5PUQexAkTcPScwYeFC5RUlRU,5491
+phoenix/server/api/types/TokenCountPromptDetails.py,sha256=CWDWLrYoufrR1ePWfbq0-AgAkdjmGnJQt4_wNIt6bOQ,183
 phoenix/server/api/types/TokenUsage.py,sha256=g-PjAGVigpchQgkXAuC5sc53fn2YwAgfeXkGmFPi_TE,201
 phoenix/server/api/types/ToolDefinition.py,sha256=T6UH2vcbuPBDy7jKYOqMth2NdqxMPgDBf11Tpbt5Yb8,187
 phoenix/server/api/types/Trace.py,sha256=fx1ozxiFMu-9AUyJ9LyMr6QtMqxzGEkucu7eE_dDZBM,8195
@@ -323,6 +324,9 @@ phoenix/server/api/types/VectorDriftMetricEnum.py,sha256=etiJM5ZjQuD-oE7sY-FbdIK
 phoenix/server/api/types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 phoenix/server/api/types/node.py,sha256=BLl_IOFr0zrqUxaAtGLGui5aeM5VNVXFTzGeAKrztr0,822
 phoenix/server/api/types/pagination.py,sha256=BXm46gXZfrBS4hpiLvVSEdsbb29ctUMVJYjKXlOLxUA,9064
+phoenix/server/cost_tracking/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+phoenix/server/cost_tracking/cost_lookup.py,sha256=c9COURDSW-LFAeuX1k2PX-kKpy8WZeIiwwjJr_YZOqY,9416
+phoenix/server/cost_tracking/model_cost_manifest.json,sha256=tlOYj69-K0ru53ql3UtX-ynRU_J3C_g5BUGZR6aSirM,19270
 phoenix/server/email/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 phoenix/server/email/sender.py,sha256=eC6RcLANVJH0mh20mGZ2qr-bU-OWo9po2e5og2tMzJw,4127
 phoenix/server/email/types.py,sha256=IO2bTtCh-1cve-xiM4MWnunCCVNOQ3Z2cqTqF7vH-do,466
@@ -342,10 +346,10 @@ phoenix/server/static/apple-touch-icon-76x76.png,sha256=CT_xT12I0u2i0WU8JzBZBuOQ
 phoenix/server/static/apple-touch-icon.png,sha256=fOfpjqGpWYbJ0eAurKsyoZP1EAs6ZVooBJ_SGk2ZkDs,3801
 phoenix/server/static/favicon.ico,sha256=bY0vvCKRftemZfPShwZtE93DiiQdaYaozkPGwNFr6H8,34494
 phoenix/server/static/modernizr.js,sha256=mvK-XtkNqjOral-QvzoqsyOMECXIMu5BQwSVN_wcU9c,2564
-phoenix/server/static/.vite/manifest.json,sha256=G8gBwLzRf4U016UfDRFEhhJl5YH5dGNHsDnzSEedR4Q,2165
-phoenix/server/static/assets/components-DpK7N6zE.js,sha256=IVHCYHDk1KKozLI2rurH65X7PVrkik2G4XIvyIKtduQ,535614
-phoenix/server/static/assets/index-BXA0RjaV.js,sha256=Vv39xY1j-wkgUXMGjC1Eff_RB8g4PafLOboJuDbIbSs,60240
-phoenix/server/static/assets/pages-jHwPRLA2.js,sha256=6z8FwfIi37BVvsgfRhd33sqRor__LbTmRQE5cqpmQZ8,1036277
+phoenix/server/static/.vite/manifest.json,sha256=hW3yshzfVwBhZmcRVFOv6lgVC5qy7v5U59K207nsiVI,2165
+phoenix/server/static/assets/components-CDvTuTqd.js,sha256=lJUX_imM4QeN2DzlgfWXoC-tJ3eci8aeS-YaU6Bgy1Y,535701
+phoenix/server/static/assets/index-DpcxdHu4.js,sha256=qvTZErnPG4_mjpaNZbTi53rL_9s9k25udpb0AElehBM,60240
+phoenix/server/static/assets/pages-Bcs41-Zv.js,sha256=o5FR83BYGFyox-6dXabSgsHCGxVGblMzqnlKVpCsRjY,1038496
 phoenix/server/static/assets/vendor-CToBXdDM.js,sha256=q_UwZrhCRrNhrvFyv3OO6bW52jM1TDiYk3aTj-NgdLU,2744392
 phoenix/server/static/assets/vendor-WIZid84E.css,sha256=spZD2r7XL5GfLO13ln-IuXfnjAref8l6g_n_AvxxOlI,5517
 phoenix/server/static/assets/vendor-arizeai-BhbMHqQs.js,sha256=l3G1o-P_IYcqQWOHBcSpT5RextOH2myGl58ZSN7NvcQ,193248
@@ -392,9 +396,9 @@ phoenix/utilities/project.py,sha256=auVpARXkDb-JgeX5f2aStyFIkeKvGwN9l7qrFeJMVxI,
 phoenix/utilities/re.py,sha256=6YyUWIkv0zc2SigsxfOWIHzdpjKA_TZo2iqKq7zJKvw,2081
 phoenix/utilities/span_store.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 phoenix/utilities/template_formatters.py,sha256=gh9PJD6WEGw7TEYXfSst1UR4pWWwmjxMLrDVQ_CkpkQ,2779
-arize_phoenix-9.5.0.dist-info/METADATA,sha256=yEwAElNirOhrgg9eu_9QRI9_aeRC1_QUACrcjhOyfOA,25590
-arize_phoenix-9.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-arize_phoenix-9.5.0.dist-info/entry_points.txt,sha256=Pgpn8Upxx9P8z8joPXZWl2LlnAlGc3gcQoVchb06X1Q,94
-arize_phoenix-9.5.0.dist-info/licenses/IP_NOTICE,sha256=JBqyyCYYxGDfzQ0TtsQgjts41IJoa-hiwDrBjCb9gHM,469
-arize_phoenix-9.5.0.dist-info/licenses/LICENSE,sha256=HFkW9REuMOkvKRACuwLPT0hRydHb3zNg-fdFt94td18,3794
-arize_phoenix-9.5.0.dist-info/RECORD,,
+arize_phoenix-9.6.1.dist-info/METADATA,sha256=WERys-C4em-Qhasa3VK1FGQoe33vfqXhySCYQ3mvX5A,25590
+arize_phoenix-9.6.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arize_phoenix-9.6.1.dist-info/entry_points.txt,sha256=Pgpn8Upxx9P8z8joPXZWl2LlnAlGc3gcQoVchb06X1Q,94
+arize_phoenix-9.6.1.dist-info/licenses/IP_NOTICE,sha256=JBqyyCYYxGDfzQ0TtsQgjts41IJoa-hiwDrBjCb9gHM,469
+arize_phoenix-9.6.1.dist-info/licenses/LICENSE,sha256=HFkW9REuMOkvKRACuwLPT0hRydHb3zNg-fdFt94td18,3794
+arize_phoenix-9.6.1.dist-info/RECORD,,

phoenix/server/api/helpers/playground_clients.py

@@ -701,7 +701,7 @@ class AzureOpenAIStreamingClient(OpenAIBaseStreamingClient):
     provider_key=GenerativeProviderKey.ANTHROPIC,
     model_names=[
         PROVIDER_DEFAULT,
-        "claude-3-7-latest",
+        "claude-3-7-sonnet-latest",
         "claude-3-7-sonnet-20250219",
         "claude-3-5-sonnet-latest",
         "claude-3-5-haiku-latest",

phoenix/server/api/routers/v1/datasets.py

@@ -3,6 +3,7 @@ import gzip
 import io
 import json
 import logging
+import urllib
 import zlib
 from asyncio import QueueFull
 from collections import Counter
@@ -817,10 +818,11 @@ async def get_dataset_csv(
     except ValueError as e:
         raise HTTPException(detail=str(e), status_code=HTTP_422_UNPROCESSABLE_ENTITY)
     content = await run_in_threadpool(_get_content_csv, examples)
+    encoded_dataset_name = urllib.parse.quote(dataset_name)
     return Response(
         content=content,
         headers={
-            "content-disposition": f'attachment; filename="{dataset_name}.csv"',
+            "content-disposition": f"attachment; filename*=UTF-8''{encoded_dataset_name}.csv",
             "content-type": "text/csv",
         },
     )
@@ -859,7 +861,10 @@ async def get_dataset_jsonl_openai_ft(
     except ValueError as e:
         raise HTTPException(detail=str(e), status_code=HTTP_422_UNPROCESSABLE_ENTITY)
     content = await run_in_threadpool(_get_content_jsonl_openai_ft, examples)
-    response.headers["content-disposition"] = f'attachment; filename="{dataset_name}.jsonl"'
+    encoded_dataset_name = urllib.parse.quote(dataset_name)
+    response.headers["content-disposition"] = (
+        f"attachment; filename*=UTF-8''{encoded_dataset_name}.jsonl"
+    )
     return content
 
 
@@ -896,7 +901,10 @@ async def get_dataset_jsonl_openai_evals(
     except ValueError as e:
         raise HTTPException(detail=str(e), status_code=HTTP_422_UNPROCESSABLE_ENTITY)
     content = await run_in_threadpool(_get_content_jsonl_openai_evals, examples)
-    response.headers["content-disposition"] = f'attachment; filename="{dataset_name}.jsonl"'
+    encoded_dataset_name = urllib.parse.quote(dataset_name)
+    response.headers["content-disposition"] = (
+        f"attachment; filename*=UTF-8''{encoded_dataset_name}.jsonl"
+    )
     return content
 
 

phoenix/server/api/types/Span.py

@@ -44,6 +44,8 @@ from phoenix.server.api.types.SpanAnnotation import SpanAnnotation, to_gql_span_
 from phoenix.server.api.types.SpanIOValue import SpanIOValue, truncate_value
 from phoenix.trace.attributes import get_attribute_value
 
+from .TokenCountPromptDetails import TokenCountPromptDetails
+
 if TYPE_CHECKING:
     from phoenix.server.api.types.Project import Project
     from phoenix.server.api.types.Trace import Trace
@@ -351,6 +353,48 @@ class Span(Node):
         )
         return cast(Optional[int], value)
 
+    @strawberry.field
+    async def token_prompt_details(
+        self,
+        info: Info[Context, None],
+    ) -> TokenCountPromptDetails:
+        if self.db_span:
+            attributes = self.db_span.attributes
+        else:
+            attributes = await info.context.data_loaders.span_fields.load(
+                (self.span_rowid, models.Span.attributes),
+            )
+
+        cache_read: Optional[int] = None
+        raw_cache_read = get_attribute_value(
+            attributes=attributes,
+            key=LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ,
+        )
+        if isinstance(raw_cache_read, int):
+            cache_read = raw_cache_read
+
+        cache_write: Optional[int] = None
+        raw_cache_write = get_attribute_value(
+            attributes=attributes,
+            key=LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE,
+        )
+        if isinstance(raw_cache_write, int):
+            cache_write = raw_cache_write
+
+        audio: Optional[int] = None
+        raw_audio = get_attribute_value(
+            attributes=attributes,
+            key=LLM_TOKEN_COUNT_PROMPT_DETAILS_AUDIO,
+        )
+        if isinstance(raw_audio, int):
+            audio = raw_audio
+
+        return TokenCountPromptDetails(
+            cache_read=cache_read,
+            cache_write=cache_write,
+            audio=audio,
+        )
+
     @strawberry.field
     async def input(
         self,
@@ -800,6 +844,11 @@ def _convert_metadata_to_string(metadata: Any) -> Optional[str]:
 
 INPUT_MIME_TYPE = SpanAttributes.INPUT_MIME_TYPE
 INPUT_VALUE = SpanAttributes.INPUT_VALUE
+LLM_TOKEN_COUNT_PROMPT_DETAILS_AUDIO = SpanAttributes.LLM_TOKEN_COUNT_PROMPT_DETAILS_AUDIO
+LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ = SpanAttributes.LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ
+LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE = (
+    SpanAttributes.LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE
+)
 METADATA = SpanAttributes.METADATA
 OUTPUT_MIME_TYPE = SpanAttributes.OUTPUT_MIME_TYPE
 OUTPUT_VALUE = SpanAttributes.OUTPUT_VALUE

phoenix/server/api/types/TokenCountPromptDetails.py

@@ -0,0 +1,10 @@
+from typing import Optional
+
+import strawberry
+
+
+@strawberry.type
+class TokenCountPromptDetails:
+    cache_read: Optional[int]
+    cache_write: Optional[int]
+    audio: Optional[int]

phoenix/server/cost_tracking/cost_lookup.py

@@ -0,0 +1,255 @@
+import json
+import os
+import re
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterator, Optional, Union
+
+
+@dataclass
+class ModelTokenCost:
+    # Cost in USD
+    input: Optional[float] = None
+    output: Optional[float] = None
+    cache_write: Optional[float] = None
+    cache_read: Optional[float] = None
+    audio: Optional[float] = None
+
+
+class RegexDict:
+    __slots__ = ("_entries",)
+
+    def __init__(self) -> None:
+        self._entries: list[tuple[re.Pattern[str], Any]] = []
+
+    def __setitem__(self, pattern: Union[str, re.Pattern[str]], value: Any) -> None:
+        if isinstance(pattern, str):
+            compiled = re.compile(pattern)
+        elif isinstance(pattern, re.Pattern):
+            compiled = pattern
+        else:
+            raise TypeError("RegexDict key must be a str or re.Pattern")
+
+        for idx, (existing_pat, _) in enumerate(self._entries):
+            if existing_pat.pattern == compiled.pattern and existing_pat.flags == compiled.flags:
+                self._entries[idx] = (compiled, value)
+                return
+        self._entries.append((compiled, value))
+
+    def __delitem__(self, pattern: Union[str, re.Pattern[str]]) -> None:
+        if isinstance(pattern, str):
+            target = pattern
+        elif isinstance(pattern, re.Pattern):
+            target = pattern.pattern
+        else:
+            raise TypeError("RegexDict key must be a str or re.Pattern")
+
+        for idx, (existing_pat, _) in enumerate(self._entries):
+            if existing_pat.pattern == target:
+                del self._entries[idx]
+                return
+        raise KeyError(pattern)
+
+    def __getitem__(self, key: str) -> Any:
+        for pattern, value in self._entries:
+            if pattern.fullmatch(key):
+                return value
+        raise KeyError(key)
+
+    def __contains__(self, key: str) -> bool:
+        try:
+            _ = self[key]
+            return True
+        except KeyError:
+            return False
+
+    def __iter__(self) -> Iterator[tuple[str, Any]]:
+        for pattern, value in self._entries:
+            yield pattern.pattern, value
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+
+class ModelCostLookup:
+    __slots__ = ("_provider_model_map", "_model_map", "_overrides", "_cache", "_max_cache_size")
+
+    def __init__(self) -> None:
+        # Each provider maps to a *RegexDict* of (pattern -> cost).
+        self._provider_model_map: defaultdict[Optional[str], RegexDict] = defaultdict(RegexDict)
+        # Map from *pattern string* to a set of providers that have that pattern.
+        self._model_map: defaultdict[re.Pattern[str], set[Optional[str]]] = defaultdict(set)
+        # A prioritized list of cost overrides (later overrides have higher priority).
+        self._overrides: list[tuple[Optional[str], re.Pattern[str], ModelTokenCost]] = []
+        # Cache for computed costs keyed by (provider, model_name).
+        self._cache: dict[tuple[Optional[str], str], list[tuple[str, ModelTokenCost]]] = {}
+        self._max_cache_size = 100
+
+    def add_pattern(
+        self, provider: Optional[str], pattern: re.Pattern[str], cost: ModelTokenCost
+    ) -> None:
+        """Register a model pattern with its cost."""
+
+        assert isinstance(pattern, re.Pattern), "pattern must be a compiled regex"
+        self._provider_model_map[provider][pattern] = cost
+        self._model_map[pattern].add(provider)
+        self._cache.clear()
+
+    def remove_pattern(self, provider: Optional[str], pattern: re.Pattern[str]) -> None:
+        """Remove a previously-registered model pattern."""
+
+        assert isinstance(pattern, re.Pattern), "pattern must be a compiled regex"
+        if provider not in self._provider_model_map:
+            return
+        del self._provider_model_map[provider][pattern]
+        self._model_map[pattern].discard(provider)
+        if not self._provider_model_map[provider]:
+            del self._provider_model_map[provider]
+        if not self._model_map[pattern]:
+            del self._model_map[pattern]
+        self._cache.clear()
+
+    def get_cost(
+        self, provider: Optional[str], model_name: str
+    ) -> list[tuple[str, ModelTokenCost]]:
+        key = (provider, model_name)
+        if key in self._cache:
+            value = self._cache.pop(key)
+            self._cache[key] = value
+            return value
+
+        result = self._lookup_cost(provider, model_name)
+
+        if len(self._cache) >= self._max_cache_size:
+            self._cache.pop(next(iter(self._cache)))
+
+        self._cache[key] = result
+        return result
+
+    def has_model(self, provider: Optional[str], model_name: str) -> bool:
+        """Return ``True`` if a cost (either base or overridden) exists for the model."""
+
+        return self._contains(provider, model_name)
+
+    def pattern_count(self) -> int:
+        """Return the number of registered *base* patterns (overrides not counted)."""
+
+        return sum(len(regex_dict) for regex_dict in self._provider_model_map.values())
+
+    def _lookup_cost(
+        self, provider: Optional[str], model_name: str
+    ) -> list[tuple[str, ModelTokenCost]]:
+        assert isinstance(model_name, str), "Lookup key must be a str"
+        # 1) Provider-specific lookup
+        if provider is not None:
+            override_cost = self._lookup_override(provider, model_name)
+            if override_cost is not None:
+                return [(provider, override_cost)]
+
+            regex_dict = self._provider_model_map.get(provider)
+            if regex_dict is None:
+                raise KeyError(provider)
+            return [(provider, regex_dict[model_name])]
+
+        # 2) provider-agnostic lookup
+        provider_cost_map: dict[str, ModelTokenCost] = {}
+        for p, regex_dict in self._provider_model_map.items():
+            try:
+                provider_cost_map[p] = regex_dict[model_name]  # type: ignore
+            except KeyError:
+                continue
+
+        for override_provider, override_pattern, override_cost in self._overrides:
+            if override_pattern.fullmatch(model_name):
+                if override_provider is None:
+                    for p in list(provider_cost_map):
+                        provider_cost_map[p] = override_cost
+                else:
+                    provider_cost_map[override_provider] = override_cost
+
+        if not provider_cost_map:
+            raise KeyError(model_name)
+        return list(provider_cost_map.items())
+
+    def _contains(self, provider: Optional[str], model_name: str) -> bool:
+        if provider is None:
+            if any(pat.fullmatch(model_name) for _, pat, _ in self._overrides):
+                return True
+            return any(model_name in regex_dict for regex_dict in self._provider_model_map.values())
+
+        if self._lookup_override(provider, model_name) is not None:
+            return True
+
+        regex_dict = self._provider_model_map.get(provider)
+        if not regex_dict:
+            return False
+        return model_name in regex_dict
+
+    def add_override(
+        self, provider: Optional[str], pattern: re.Pattern[str], cost: ModelTokenCost
+    ) -> None:
+        """Register a *prioritized* cost override.
+
+        Overrides are evaluated in the order in which they are added (LIFO).
+        """
+
+        if not isinstance(pattern, re.Pattern):
+            raise TypeError("pattern must be a compiled regex")
+        self._overrides.append((provider, pattern, cost))
+        self._cache.clear()
+
+    def _lookup_override(
+        self, provider: Optional[str], model_name: str
+    ) -> Optional[ModelTokenCost]:
+        """Return the cost from the highest-priority override that matches, or *None*."""
+
+        for override_provider, override_pattern, override_cost in reversed(self._overrides):
+            provider_matches = override_provider is None or override_provider == provider
+            if provider_matches and override_pattern.fullmatch(model_name):
+                return override_cost
+        return None
+
+
+def create_cost_table(
+    manifest_path: Optional[Union[str, "os.PathLike[str]"]] = None,
+) -> "ModelCostLookup":
+    if manifest_path is None:
+        manifest_path = Path(__file__).with_name("model_cost_manifest.json")
+
+    manifest_path = Path(manifest_path)
+
+    if not manifest_path.exists():
+        raise FileNotFoundError(f"Model cost manifest not found: {manifest_path}")
+
+    with manifest_path.open("r", encoding="utf-8") as fp:
+        try:
+            manifest_entries: list[dict[str, Any]] = json.load(fp)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Failed to parse manifest JSON: {manifest_path}") from exc
+
+    lookup = ModelCostLookup()
+
+    for entry in manifest_entries:
+        provider: Optional[str] = entry.get("provider")
+
+        try:
+            pattern = re.compile(entry["regex"])
+        except re.error as exc:
+            raise ValueError(
+                f"Invalid regex in manifest for model {entry.get('model')}: {entry['regex']}"
+            ) from exc
+
+        cost = ModelTokenCost(
+            input=entry.get("input"),
+            output=entry.get("output"),
+            cache_write=entry.get("cache_write"),
+            cache_read=entry.get("cache_read"),
+        )
+
+        lookup.add_pattern(provider, pattern, cost)
+
+    return lookup
+
+
+COST_TABLE = create_cost_table()