arize-phoenix 9.4.0__tar.gz → 9.6.0__tar.gz

{arize_phoenix-9.4.0 → arize_phoenix-9.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arize-phoenix
-Version: 9.4.0
+Version: 9.6.0
 Summary: AI Observability and Evaluation
 Project-URL: Documentation, https://docs.arize.com/phoenix/
 Project-URL: Issues, https://github.com/Arize-ai/phoenix/issues
@@ -49,7 +49,7 @@ Requires-Dist: scipy
 Requires-Dist: sqlalchemy[asyncio]<3,>=2.0.4
 Requires-Dist: sqlean-py>=3.45.1
 Requires-Dist: starlette
-Requires-Dist: strawberry-graphql==0.267.0
+Requires-Dist: strawberry-graphql==0.269.0
 Requires-Dist: tqdm
 Requires-Dist: typing-extensions>=4.6
 Requires-Dist: uvicorn
@@ -71,7 +71,7 @@ Requires-Dist: opentelemetry-sdk; extra == 'container'
 Requires-Dist: opentelemetry-semantic-conventions; extra == 'container'
 Requires-Dist: prometheus-client; extra == 'container'
 Requires-Dist: py-grpc-prometheus; extra == 'container'
-Requires-Dist: strawberry-graphql[opentelemetry]==0.267.0; extra == 'container'
+Requires-Dist: strawberry-graphql[opentelemetry]==0.269.0; extra == 'container'
 Requires-Dist: umap-learn; extra == 'container'
 Requires-Dist: uvloop; (platform_system != 'Windows') and extra == 'container'
 Provides-Extra: dev
@@ -102,7 +102,7 @@ Requires-Dist: pytest-postgresql; extra == 'dev'
 Requires-Dist: pytest-xdist; extra == 'dev'
 Requires-Dist: pytest==8.3.3; extra == 'dev'
 Requires-Dist: ruff==0.6.9; extra == 'dev'
-Requires-Dist: strawberry-graphql[debug-server,opentelemetry]==0.267.0; extra == 'dev'
+Requires-Dist: strawberry-graphql[debug-server,opentelemetry]==0.269.0; extra == 'dev'
 Requires-Dist: tabulate; extra == 'dev'
 Requires-Dist: tox-uv==1.11.3; extra == 'dev'
 Requires-Dist: tox==4.18.1; extra == 'dev'

{arize_phoenix-9.4.0 → arize_phoenix-9.6.0}/pyproject.toml

@@ -29,7 +29,7 @@ dependencies = [
   "starlette",
   "uvicorn",
   "psutil",
-  "strawberry-graphql==0.267.0",  # avoid this issue: https://github.com/strawberry-graphql/strawberry/issues/3854
+  "strawberry-graphql==0.269.0",  # fix relay ids
   "pyarrow",
   "typing-extensions>=4.6",
   "scipy",
@@ -88,7 +88,7 @@ dev = [
   "pytest-postgresql",
   "asyncpg",
   "psycopg[binary,pool]",
-  "strawberry-graphql[debug-server,opentelemetry]==0.267.0",  # avoid this issue: https://github.com/strawberry-graphql/strawberry/issues/3854
+  "strawberry-graphql[debug-server,opentelemetry]==0.269.0",  # fix relay ids
   "pre-commit",
   "arize[AutoEmbeddings, LLM_Evaluation]",
   "llama-index>=0.10.3",
@@ -137,7 +137,7 @@ container = [
   "opentelemetry-instrumentation-sqlalchemy",
   "opentelemetry-instrumentation-grpc",
   "py-grpc-prometheus",
-  "strawberry-graphql[opentelemetry]==0.267.0",  # avoid this issue: https://github.com/strawberry-graphql/strawberry/issues/3854
+  "strawberry-graphql[opentelemetry]==0.269.0",  # fix relay ids
   "uvloop; platform_system != 'Windows'",
   "fast-hdbscan>=0.2.0",
   "numba>=0.60.0",  # https://github.com/astral-sh/uv/issues/6281
@@ -168,6 +168,7 @@ exclude = [
 artifacts = [
   "src/phoenix/server/static",
   "src/phoenix/db/migrations",
+  "src/phoenix/server/cost_tracking/model_cost_manifest.json",
 ]
 
 [tool.hatch.build]
@@ -187,6 +188,7 @@ exclude = [
 artifacts = [
   "src/phoenix/server/static",
   "src/phoenix/db/migrations",
+  "src/phoenix/server/cost_tracking/model_cost_manifest.json",
 ]
 
 [tool.pytest.ini_options]

{arize_phoenix-9.4.0 → arize_phoenix-9.6.0}/src/phoenix/db/README.md

@@ -37,7 +37,7 @@ alembic upgrade head
 
 If the above command fails, it may be necessary to undo partially applied changes from a failed migration by first running down-migrations. This can be accomplished by identifying the ID of the migration revision you wish to return to. Revisions are defined [here](./migrations/versions/).
 
-⚠️ Running down-migrations can result in lost data. Only run down-migrations if you know what you are doing and consider backing up your database first. If you have any questions or doubts, contact the Phoenix team in the `#phoenix-support` channel of the [Arize AI Slack community](https://join.slack.com/t/arize-ai/shared_invite/zt-1px8dcmlf-fmThhDFD_V_48oU7ALan4Q) or via GitHub.
+⚠️ Running down-migrations can result in lost data. Only run down-migrations if you know what you are doing and consider backing up your database first. If you have any questions or doubts, contact the Phoenix team in the `#phoenix-support` channel of the [Arize AI Slack community](https://arize-ai.slack.com/join/shared_invite/zt-2w57bhem8-hq24MB6u7yE_ZF_ilOYSBw#/shared-invite/email) or via GitHub.
 
 ```bash
 alembic downgrade <revision-id>

{arize_phoenix-9.4.0 → arize_phoenix-9.6.0}/src/phoenix/experiments/functions.py

@@ -116,8 +116,17 @@ def run_experiment(
     - `metadata`: Metadata associated with the dataset example
     - `example`: The dataset `Example` object with all associated fields
 
-    An `evaluator` is either a synchronous or asynchronous function that returns either a boolean
-    or numeric "score". If the `evaluator` is a function of one argument then that argument will be
+    An `evaluator` is either a synchronous or asynchronous function that returns an evaluation
+    result object, which can take any of the following forms.
+
+    - phoenix.experiments.types.EvaluationResult with optional fields for score, label, explanation
+      and metadata
+    - a `bool`, which will be interpreted as a score of 0 or 1 plus a label of "True" or "False"
+    - a `float`, which will be interpreted as a score
+    - a `str`, which will be interpreted as a label
+    - a 2-`tuple` of (`float`, `str`), which will be interpreted as (score, explanation)
+
+    If the `evaluator` is a function of one argument then that argument will be
     bound to the `output` of the task. Alternatively, the `evaluator` can be a function of any
     combination of specific argument names that will be bound to special values:
 

{arize_phoenix-9.4.0 → arize_phoenix-9.6.0}/src/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",

{arize_phoenix-9.4.0 → arize_phoenix-9.6.0}/src/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
 
 

{arize_phoenix-9.4.0 → arize_phoenix-9.6.0}/src/phoenix/server/api/types/Project.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
 import operator
-from datetime import datetime
+from datetime import datetime, timedelta
 from typing import TYPE_CHECKING, Annotated, Any, ClassVar, Optional
 
 import strawberry
 from aioitertools.itertools import islice
 from openinference.semconv.trace import SpanAttributes
 from sqlalchemy import desc, distinct, func, or_, select
+from sqlalchemy.dialects import postgresql, sqlite
 from sqlalchemy.sql.elements import ColumnElement
 from sqlalchemy.sql.expression import tuple_
 from strawberry import ID, UNSET, Private, lazy
@@ -17,6 +18,7 @@ from typing_extensions import assert_never
 
 from phoenix.datetime_utils import right_open_time_range
 from phoenix.db import models
+from phoenix.db.helpers import SupportedSQLDialect
 from phoenix.server.api.context import Context
 from phoenix.server.api.input_types.ProjectSessionSort import (
     ProjectSessionColumn,
@@ -38,6 +40,7 @@ from phoenix.server.api.types.pagination import (
 from phoenix.server.api.types.ProjectSession import ProjectSession, to_gql_project_session
 from phoenix.server.api.types.SortDir import SortDir
 from phoenix.server.api.types.Span import Span
+from phoenix.server.api.types.TimeSeries import TimeSeries, TimeSeriesDataPoint
 from phoenix.server.api.types.Trace import Trace
 from phoenix.server.api.types.ValidationResult import ValidationResult
 from phoenix.trace.dsl import SpanFilter
@@ -528,19 +531,46 @@ class Project(Node):
         return info.context.last_updated_at.get(self._table, self.project_rowid)
 
     @strawberry.field
-    async def validate_span_filter_condition(self, condition: str) -> ValidationResult:
+    async def validate_span_filter_condition(
+        self,
+        info: Info[Context, None],
+        condition: str,
+    ) -> ValidationResult:
+        """Validates a span filter condition by attempting to compile it for both SQLite and PostgreSQL.
+
+        This method checks if the provided filter condition is syntactically valid and can be compiled
+        into SQL queries for both SQLite and PostgreSQL databases. It does not execute the query,
+        only validates its syntax. Any exception during compilation (syntax errors, invalid expressions,
+        etc.) will result in an invalid validation result.
+
+        Args:
+            condition (str): The span filter condition string to validate.
+
+        Returns:
+            ValidationResult: A result object containing:
+                - is_valid (bool): True if the condition is valid, False otherwise
+                - error_message (Optional[str]): Error message if validation fails, None if valid
+        """  # noqa: E501
         # This query is too expensive to run on every validation
         # valid_eval_names = await self.span_annotation_names()
         try:
-            SpanFilter(
+            span_filter = SpanFilter(
                 condition=condition,
                 # valid_eval_names=valid_eval_names,
             )
+            stmt = span_filter(select(models.Span))
+            dialect = info.context.db.dialect
+            if dialect is SupportedSQLDialect.POSTGRESQL:
+                str(stmt.compile(dialect=sqlite.dialect()))  # type: ignore[no-untyped-call]
+            elif dialect is SupportedSQLDialect.SQLITE:
+                str(stmt.compile(dialect=postgresql.dialect()))  # type: ignore[no-untyped-call]
+            else:
+                assert_never(dialect)
             return ValidationResult(is_valid=True, error_message=None)
-        except SyntaxError as e:
+        except Exception as e:
             return ValidationResult(
                 is_valid=False,
-                error_message=e.msg,
+                error_message=str(e),
             )
 
     @strawberry.field
@@ -610,6 +640,97 @@ class Project(Node):
             )
         return updated_at
 
+    @strawberry.field(
+        description="Hourly span count for the project.",
+    )  # type: ignore
+    async def span_count_time_series(
+        self,
+        info: Info[Context, None],
+        time_range: Optional[TimeRange] = UNSET,
+    ) -> SpanCountTimeSeries:
+        """Returns a time series of span counts grouped by hour for the project.
+
+        This field provides hourly aggregated span counts, which can be useful for
+        visualizing span activity over time. The data points represent the number
+        of spans that started in each hour.
+
+        Args:
+            info: The GraphQL info object containing context information.
+            time_range: Optional time range to filter the spans. If provided, only
+                spans that started within this range will be counted.
+
+        Returns:
+            A SpanCountTimeSeries object containing data points with timestamps
+            (rounded to the nearest hour) and corresponding span counts.
+
+        Notes:
+            - The timestamps are rounded down to the nearest hour.
+            - If a time range is provided, the start time is rounded down to the
+              nearest hour, and the end time is rounded up to the nearest hour.
+            - The SQL query is optimized for both PostgreSQL and SQLite databases.
+        """
+        # Determine the appropriate SQL function to truncate timestamps to hours
+        # based on the database dialect
+        if info.context.db.dialect is SupportedSQLDialect.POSTGRESQL:
+            # PostgreSQL uses date_trunc for timestamp truncation
+            hour = func.date_trunc("hour", models.Span.start_time)
+        elif info.context.db.dialect is SupportedSQLDialect.SQLITE:
+            # SQLite uses strftime for timestamp formatting
+            hour = func.strftime("%Y-%m-%dT%H:00:00.000+00:00", models.Span.start_time)
+        else:
+            assert_never(info.context.db.dialect)
+
+        # Build the base query to count spans grouped by hour
+        stmt = (
+            select(hour, func.count())
+            .join(models.Trace)
+            .where(models.Trace.project_rowid == self.project_rowid)
+            .group_by(hour)
+            .order_by(hour)
+        )
+
+        # Apply time range filtering if provided
+        if time_range:
+            if t := time_range.start:
+                # Round down to nearest hour for the start time
+                start = t.replace(minute=0, second=0, microsecond=0)
+                stmt = stmt.where(start <= models.Span.start_time)
+            if t := time_range.end:
+                # Round up to nearest hour for the end time
+                # If the time is already at the start of an hour, use it as is
+                if t.minute == 0 and t.second == 0 and t.microsecond == 0:
+                    end = t
+                else:
+                    # Otherwise, round up to the next hour
+                    end = t.replace(minute=0, second=0, microsecond=0) + timedelta(hours=1)
+                stmt = stmt.where(models.Span.start_time < end)
+
+        # Execute the query and convert the results to a time series
+        async with info.context.db() as session:
+            data = await session.stream(stmt)
+            return SpanCountTimeSeries(
+                data=[
+                    TimeSeriesDataPoint(
+                        timestamp=_as_datetime(t),
+                        value=v,
+                    )
+                    async for t, v in data
+                ]
+            )
+
+
+@strawberry.type
+class SpanCountTimeSeries(TimeSeries):
+    """A time series of span count"""
+
 
 INPUT_VALUE = SpanAttributes.INPUT_VALUE.split(".")
 OUTPUT_VALUE = SpanAttributes.OUTPUT_VALUE.split(".")
+
+
+def _as_datetime(value: Any) -> datetime:
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, str):
+        return datetime.fromisoformat(value)
+    raise ValueError(f"Cannot convert {value} to datetime")

{arize_phoenix-9.4.0 → arize_phoenix-9.6.0}/src/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

arize_phoenix-9.6.0/src/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]

arize_phoenix-9.6.0/src/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()