flightdeck-sensor 0.6.0__tar.gz → 0.7.0__tar.gz

{flightdeck_sensor-0.6.0 → flightdeck_sensor-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flightdeck-sensor
-Version: 0.6.0
+Version: 0.7.0
 Summary: In-process agent observability sensor for Flightdeck
 Project-URL: Repository, https://github.com/flightdeckhq/flightdeck
 Author-email: Omri Arnon <omri.arnon@gmail.com>

{flightdeck_sensor-0.6.0 → flightdeck_sensor-0.7.0}/flightdeck_sensor/__init__.py

@@ -94,6 +94,10 @@ __all__ = [
 
 _log = logging.getLogger("flightdeck_sensor")
 
+# Billing modes init(billing_mode=) / FLIGHTDECK_BILLING_MODE accept; the
+# ingestion API rejects any other value on the wire.
+_BILLING_MODES = frozenset({"metered", "subscription", "local"})
+
 # Agent-type vocabulary lock. Any other value raises ConfigurationError
 # at init time. See CHANGELOG.md for the v0.4.0 breaking change that
 # narrowed this from {autonomous, supervised, batch, developer}.
@@ -241,6 +245,7 @@ def init(
     langgraph_agent_node_pattern: str | None = None,
     mcp_block_on_uncertainty: bool = False,
     allow_insecure_transport: bool = False,
+    billing_mode: str | None = None,
 ) -> None:
     """Initialize the sensor and start the run.
 
@@ -307,6 +312,17 @@ def init(
     - ``FLIGHTDECK_ALLOW_INSECURE_TRANSPORT`` -- ``"true"`` to allow plain
       ``http://`` egress to a non-local control plane (overrides
       *allow_insecure_transport*)
+    - ``FLIGHTDECK_BILLING_MODE`` -- ``metered``, ``subscription`` or
+      ``local`` (overrides *billing_mode*)
+
+    ``billing_mode`` says how this agent's LLM calls are paid for, which
+    decides whether the dashboard counts them as spend. Left unset, every
+    call is ``metered`` except calls to a model server on this machine
+    (a loopback base URL), which are ``local``. Set it when the sensor
+    cannot tell: ``local`` for a self-hosted server elsewhere on your
+    network, ``subscription`` for a flat-rate plan. Case and surrounding
+    whitespace are ignored; any other value raises
+    :class:`ConfigurationError`.
 
     ``allow_insecure_transport`` opts in to plaintext ``http://`` egress
     for a **non-local** control-plane host. Off by default: the resolved
@@ -389,6 +405,14 @@ def init(
             resolved_api_url = resolved_server.rstrip("/").replace("/ingest", "/api")
 
         capture = _env_bool(_env.ENV_CAPTURE_PROMPTS, capture_prompts)
+        resolved_billing_mode = (
+            os.environ.get(_env.ENV_BILLING_MODE) or billing_mode or ""
+        ).strip().lower() or None
+        if resolved_billing_mode is not None and resolved_billing_mode not in _BILLING_MODES:
+            raise ConfigurationError(
+                f"billing_mode must be one of {sorted(_BILLING_MODES)}, "
+                f"got {resolved_billing_mode!r}"
+            )
 
         # session_id resolution follows the same env-wins pattern as
         # FLIGHTDECK_SERVER / AGENT_FLAVOR: env var overrides kwarg,
@@ -469,6 +493,7 @@ def init(
             "token": resolved_token,
             "api_url": resolved_api_url,
             "capture_prompts": capture,
+            "billing_mode": resolved_billing_mode,
             "allow_insecure_transport": resolved_allow_insecure,
             "unavailable_policy": os.environ.get(_env.ENV_UNAVAILABLE_POLICY, "continue"),
             # Legacy wire-level ``flavor`` field stays populated for

{flightdeck_sensor-0.6.0 → flightdeck_sensor-0.7.0}/flightdeck_sensor/config.py

@@ -44,6 +44,9 @@ ENV_UNAVAILABLE_POLICY = "FLIGHTDECK_UNAVAILABLE_POLICY"
 # Opt-in to plaintext http:// egress for a non-local control
 # plane. Bool-coerced; default False forces https:// for public hosts.
 ENV_ALLOW_INSECURE_TRANSPORT = "FLIGHTDECK_ALLOW_INSECURE_TRANSPORT"
+# How LLM calls are paid for: "metered", "subscription" or "local".
+# Overrides the per-call detection (loopback servers are local).
+ENV_BILLING_MODE = "FLIGHTDECK_BILLING_MODE"
 
 
 # Stable list of every FLIGHTDECK_* env var the sensor consults, in
@@ -60,4 +63,5 @@ ALL_ENV_VARS: tuple[str, ...] = (
     ENV_CAPTURE_PROMPTS,
     ENV_UNAVAILABLE_POLICY,
     ENV_ALLOW_INSECURE_TRANSPORT,
+    ENV_BILLING_MODE,
 )

{flightdeck_sensor-0.6.0 → flightdeck_sensor-0.7.0}/flightdeck_sensor/core/types.py

@@ -262,18 +262,68 @@ class TokenUsage:
     read as ``cached_tokens``, which lands in ``cache_read_tokens``, and
     its cache write as ``cache_write_tokens``, which lands in
     ``cache_creation_tokens`` (0 when the response carries none).
+
+    ``reasoning_tokens`` is the reasoning or thinking share of
+    ``output_tokens`` and ``cache_creation_1h_tokens`` the one-hour share
+    of ``cache_creation_tokens`` (Anthropic's extended cache TTL). Both
+    are subsets already counted in their totals, and ``None`` when the
+    provider reported no such split.
     """
 
     input_tokens: int = 0
     output_tokens: int = 0
     cache_read_tokens: int = 0
     cache_creation_tokens: int = 0
+    reasoning_tokens: int | None = None
+    cache_creation_1h_tokens: int | None = None
 
     @property
     def total(self) -> int:
         return self.input_tokens + self.output_tokens
 
 
+@dataclass(frozen=True)
+class CallDetails:
+    """What a provider reports about one LLM call beyond its token counts
+    (ARCHITECTURE.md, POST /v1/events, token, model and cost fields).
+
+    Every field is ``None`` when the response did not carry it.
+    ``model_served`` is the model id the response named, verbatim;
+    ``cost_reported`` and ``cost_source`` are a cost the client library
+    or a gateway reported for the call (``cost_source`` ``"agent"`` or
+    ``"provider"``).
+    """
+
+    model_served: str | None = None
+    service_tier: str | None = None
+    speed: str | None = None
+    inference_geo: str | None = None
+    server_tool_use: dict[str, int] | None = None
+    cost_reported: float | None = None
+    cost_source: str | None = None
+
+    def merged(self, newer: CallDetails) -> CallDetails:
+        """Fold details read from a later stream event over these: a
+        field the later event carries wins, and server-tool counters,
+        which streams report cumulatively, keep the larger count."""
+        tools: dict[str, int] | None = None
+        if self.server_tool_use or newer.server_tool_use:
+            tools = dict(self.server_tool_use or {})
+            for name, count in (newer.server_tool_use or {}).items():
+                tools[name] = max(count, tools.get(name, 0))
+        return CallDetails(
+            model_served=newer.model_served or self.model_served,
+            service_tier=newer.service_tier or self.service_tier,
+            speed=newer.speed or self.speed,
+            inference_geo=newer.inference_geo or self.inference_geo,
+            server_tool_use=tools,
+            cost_reported=(
+                newer.cost_reported if newer.cost_reported is not None else self.cost_reported
+            ),
+            cost_source=newer.cost_source or self.cost_source,
+        )
+
+
 @dataclass
 class SensorConfig:
     """Configuration for a sensor session.
@@ -299,6 +349,11 @@ class SensorConfig:
     client_type: str = "flightdeck_sensor"
     api_url: str = ""
     capture_prompts: bool = False
+    # Billing mode stamped on every LLM call ("metered", "subscription",
+    # "local"); None lets each call's endpoint decide (loopback servers
+    # are local, everything else metered). Set from init(billing_mode=)
+    # or FLIGHTDECK_BILLING_MODE.
+    billing_mode: str | None = None
     # Opt-in to plaintext http:// egress for a non-local control
     # plane. Default False forces https:// for any public host; local /
     # loopback / private targets are always allowed over http regardless.

{flightdeck_sensor-0.6.0 → flightdeck_sensor-0.7.0}/flightdeck_sensor/interceptor/anthropic.py

@@ -103,6 +103,11 @@ from typing import TYPE_CHECKING, Any
 
 from flightdeck_sensor.core.exceptions import BudgetExceededError, DirectiveError
 from flightdeck_sensor.interceptor import base
+from flightdeck_sensor.interceptor.platform import (
+    PLATFORM_ANTHROPIC,
+    PLATFORM_VERTEX,
+    endpoint_of,
+)
 from flightdeck_sensor.providers.anthropic import AnthropicProvider
 
 if TYPE_CHECKING:
@@ -245,76 +250,12 @@ _PATCHED_SENTINEL = "_flightdeck_patched"
 # through create / stream, which are already intercepted.
 _PATCHED_METHODS = ("create", "stream", "parse")
 
-# Platform reported when the client is Anthropic's own API; also the
-# fallback when a client exposes no usable base_url at all (a test
-# double), since the SDK is Anthropic's.
-PLATFORM_ANTHROPIC = "anthropic"
-
-# Hosts the SDK's own client classes default to, mapped to the platform
-# name reported on the event: (host prefix, host suffix, platform). The
-# first matching row wins. A host that matches no row -- a gateway or a
-# proxy the caller pointed the SDK at -- is reported verbatim, so the
-# deployment topology stays visible instead of being mislabelled as
-# Anthropic's own API.
-_PLATFORM_HOSTS: tuple[tuple[str, str, str], ...] = (
-    # Every suffix starts with a separator so a look-alike such as
-    # evilanthropic.com or anthropic.com.evil.example stays bare, and
-    # Vertex matches only the Vertex AI API hosts (aiplatform.<...>
-    # .googleapis.com and the regional <region>-aiplatform.googleapis.com)
-    # and google-cloud only Claude Platform on Google Cloud's gateway
-    # (claude.googleapis.com), not every Google API host.
-    ("", ".anthropic.com", PLATFORM_ANTHROPIC),
-    ("bedrock-runtime.", ".amazonaws.com", "bedrock"),
-    ("bedrock-mantle.", ".api.aws", "bedrock-mantle"),
-    ("aws-external-anthropic.", ".api.aws", "aws"),
-    ("claude.", ".googleapis.com", "google-cloud"),
-    ("aiplatform.", ".googleapis.com", "vertex"),
-    ("", "-aiplatform.googleapis.com", "vertex"),
-    ("", ".services.ai.azure.com", "foundry"),
-)
-
-
-# A platform value is one of the names above or a hostname. Hostnames are
-# bounded by the DNS limit on a fully qualified name, and only letters,
-# digits, dots and hyphens are accepted once lowercased; anything longer
-# or containing other characters is reported as PLATFORM_INVALID_HOST,
-# so a malformed or hostile base_url cannot put arbitrary bytes into
-# every post_call of a session.
-_MAX_PLATFORM_HOST_LENGTH = 253
-_PLATFORM_HOST_CHARS = frozenset("abcdefghijklmnopqrstuvwxyz0123456789.-")
-PLATFORM_INVALID_HOST = "invalid-host"
-
-
-def platform_for_host(host: str) -> str:
-    """The platform name for an API host: a known platform (see
-    ``_PLATFORM_HOSTS``), else the host itself when it is a well-formed
-    hostname, else :data:`PLATFORM_INVALID_HOST`."""
-    lowered = host.lower()
-    if (
-        not lowered
-        or len(lowered) > _MAX_PLATFORM_HOST_LENGTH
-        or not set(lowered) <= _PLATFORM_HOST_CHARS
-    ):
-        return PLATFORM_INVALID_HOST
-    for prefix, suffix, platform in _PLATFORM_HOSTS:
-        if lowered.startswith(prefix) and lowered.endswith(suffix):
-            return platform
-    return lowered
-
 
 def platform_of(client: Any) -> str:
-    """The platform a client talks to: the platform of
-    ``client.base_url.host`` (see :func:`platform_for_host`), else
-    :data:`PLATFORM_ANTHROPIC` when the client exposes no usable host.
-    The host is the only source, so a first-party client pointed at a
-    gateway reports the gateway rather than a label its class carries."""
-    try:
-        host = getattr(getattr(client, "base_url", None), "host", None)
-        if isinstance(host, str) and host:
-            return platform_for_host(host)
-    except Exception:
-        _log.debug("platform attribution failed", exc_info=True)
-    return PLATFORM_ANTHROPIC
+    """The platform a client talks to (see
+    :func:`flightdeck_sensor.interceptor.platform.endpoint_of`), else
+    :data:`PLATFORM_ANTHROPIC` when the client exposes no usable host."""
+    return endpoint_of(client, PLATFORM_ANTHROPIC).platform
 
 
 def _is_async_client(client: Any) -> bool:
@@ -344,12 +285,27 @@ def _raw_response_mode(kwargs: dict[str, Any]) -> str | None:
 
 
 def _provider_for(client: Any, session: Session) -> AnthropicProvider:
+    endpoint = endpoint_of(client, PLATFORM_ANTHROPIC)
     return AnthropicProvider(
         capture_prompts=session.config.capture_prompts,
-        platform=platform_of(client),
+        platform=endpoint.platform,
+        local=endpoint.local,
+        inference_scope=_vertex_scope(client, endpoint.platform),
     )
 
 
+def _vertex_scope(client: Any, platform: str) -> str | None:
+    """``global`` or ``regional`` for a Vertex AI client, from the region
+    it was configured with (``AnthropicVertex(region=...)``, defaulting
+    to ``CLOUD_ML_REGION``); ``None`` for every other platform."""
+    if platform != PLATFORM_VERTEX:
+        return None
+    region = getattr(client, "region", None)
+    if not isinstance(region, str) or not region:
+        return None
+    return "global" if region == "global" else "regional"
+
+
 # ----------------------------------------------------------------------
 # Deferred metering for the streaming view
 # ----------------------------------------------------------------------

{flightdeck_sensor-0.6.0 → flightdeck_sensor-0.7.0}/flightdeck_sensor/interceptor/base.py

@@ -40,6 +40,7 @@ from flightdeck_sensor.core.exceptions import (
     MCPPolicyBlocked,
 )
 from flightdeck_sensor.core.types import (
+    CallDetails,
     EventType,
     PolicyDecision,
     PolicyDecisionSummary,
@@ -371,9 +372,36 @@ def _merge_usage(current: TokenUsage | None, new: TokenUsage) -> TokenUsage:
         output_tokens=max(new.output_tokens, current.output_tokens),
         cache_read_tokens=max(new.cache_read_tokens, current.cache_read_tokens),
         cache_creation_tokens=max(new.cache_creation_tokens, current.cache_creation_tokens),
+        reasoning_tokens=_max_reported(new.reasoning_tokens, current.reasoning_tokens),
+        cache_creation_1h_tokens=_max_reported(
+            new.cache_creation_1h_tokens, current.cache_creation_1h_tokens
+        ),
     )
 
 
+def _max_reported(a: int | None, b: int | None) -> int | None:
+    """The larger of two optional cumulative counters; ``None`` only when
+    neither was reported."""
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return max(a, b)
+
+
+# Billing modes the sensor stamps (ARCHITECTURE.md, Cost estimation): a
+# call to a model server on this machine is local, every other call is
+# paid per token unless init(billing_mode=) / FLIGHTDECK_BILLING_MODE
+# says otherwise.
+BILLING_METERED = "metered"
+BILLING_LOCAL = "local"
+
+# The ingestion API's cap on the free-form strings of the token and cost
+# fields (model ids, tier, speed, residency, stop reason), in UTF-8 bytes;
+# a longer value would get the whole event rejected, so it is cut to fit
+# instead.
+_MAX_DETAIL_BYTES = 256
+
 # Set on an exception once an intercept has reported it, so a stream's
 # with-exit does not report the same failure of a nested call again.
 _REPORTED_ATTR = "_flightdeck_reported"
@@ -509,6 +537,9 @@ class _GuardCore:
         # The stop reason a streamed event announced (a raw
         # stream has no final message to read it from at settle time).
         self._stop_reason: str | None = None
+        # Call details the streamed events reported (served model, tier,
+        # server-tool counters), folded event by event.
+        self._details: CallDetails | None = None
         self._hooks_failed: set[str] = set()
         self._open_error: BaseException | None = None
         drain_deferred_settles(session)
@@ -654,6 +685,15 @@ class _GuardCore:
             reason = None
         if isinstance(reason, str):
             self._stop_reason = reason
+        try:
+            details = self._provider.call_details_from_stream_chunk(chunk)
+        except Exception:
+            self._hook_failed("call_details_from_stream_chunk")
+            details = None
+        # Chat chunks repeat the same model and tier on every chunk; fold
+        # only a chunk that reports something new.
+        if details is not None and details != self._details:
+            self._details = details if self._details is None else self._details.merged(details)
 
     def _merge_settled_usage(self) -> None:
         """Fold in the usage the SDK stream object holds at settle time
@@ -765,6 +805,7 @@ class _GuardCore:
                 estimated_via=self._estimated_via,
                 usage_override=self._usage,
                 stop_reason=self._stop_reason,
+                details_override=self._details,
             )
         except Exception as emit_exc:
             # No exc_info: the provider exception is the active context and
@@ -1392,6 +1433,7 @@ def _post_call(
     estimated_via: str = "none",
     usage_override: TokenUsage | None = None,
     stop_reason: str | None = None,
+    details_override: CallDetails | None = None,
 ) -> None:
     """Extract actual usage, reconcile with estimate, post event.
 
@@ -1408,6 +1450,10 @@ def _post_call(
     the streamed events; when ``None`` the provider is asked to read it
     from the response. A reason that means the call did not succeed files
     an llm_error beside the post_call.
+
+    ``details_override`` carries the call details a stream guard folded
+    from the streamed events; the response's own details (a helper
+    stream's final message) are laid over them.
     """
     # ``usage_override`` carries the counts a stream guard read from the
     # provider's in-stream usage events; stream objects themselves expose
@@ -1507,6 +1553,16 @@ def _post_call(
         payload["content"] = content_dict
     if streaming is not None:
         payload["streaming"] = streaming
+    _add_token_cost_fields(
+        payload,
+        session,
+        provider,
+        response,
+        call_kwargs,
+        usage,
+        details_override,
+        stop_reason,
+    )
 
     # provider_metadata: rate-limit headers, request id, processing
     # time. Always-included when the provider exposes any of them so
@@ -1749,6 +1805,83 @@ def _response_request_id(response: Any, prov_meta: dict[str, Any] | None) -> str
     return None
 
 
+def _add_token_cost_fields(
+    payload: dict[str, Any],
+    session: Session,
+    provider: Provider,
+    response: Any,
+    call_kwargs: dict[str, Any] | None,
+    usage: TokenUsage,
+    details_override: CallDetails | None,
+    stop_reason: str | None,
+) -> None:
+    """Add the token, model and cost fields of the event contract
+    (ARCHITECTURE.md, POST /v1/events) to an LLM call's payload. A field
+    is sent only when known, so the wire stays as before for whatever a
+    provider does not report. Never raises."""
+    try:
+        details = details_override
+        try:
+            own = provider.call_details(response)
+        except Exception:
+            own = None
+        if own is not None:
+            details = own if details is None else details.merged(own)
+
+        fields: dict[str, Any] = {
+            "model_requested": provider.get_model(call_kwargs or {}) or None,
+            "provider": provider.vendor,
+            "billing_mode": session.config.billing_mode
+            or (BILLING_LOCAL if provider.local else BILLING_METERED),
+            "inference_scope": provider.inference_scope,
+            # Each share must fit inside its total, or ingestion rejects
+            # the whole event; a share that does not is left out.
+            "tokens_reasoning": _share(usage.reasoning_tokens, usage.output_tokens),
+            "tokens_cache_creation_1h": _share(
+                usage.cache_creation_1h_tokens, usage.cache_creation_tokens
+            ),
+        }
+        reason = stop_reason
+        if reason is None:
+            with contextlib.suppress(Exception):
+                reason = provider.response_stop_reason(response)
+        if isinstance(reason, str) and reason:
+            fields["stop_reason"] = reason
+        if details is not None:
+            fields.update(
+                model_served=details.model_served,
+                service_tier=details.service_tier,
+                speed=details.speed,
+                inference_geo=details.inference_geo,
+                server_tool_use=details.server_tool_use,
+                cost_reported=details.cost_reported,
+                cost_source=details.cost_source,
+            )
+        for key, value in fields.items():
+            if value is None:
+                continue
+            if isinstance(value, str):
+                value = _clip_utf8(value, _MAX_DETAIL_BYTES)
+            payload[key] = value
+    except Exception:
+        _log.debug("token and cost fields failed", exc_info=True)
+
+
+def _clip_utf8(value: str, max_bytes: int) -> str:
+    """``value`` cut to at most ``max_bytes`` of UTF-8, never splitting a
+    character."""
+    encoded = value.encode("utf-8")
+    if len(encoded) <= max_bytes:
+        return value
+    return encoded[:max_bytes].decode("utf-8", errors="ignore")
+
+
+def _share(part: int | None, whole: int) -> int | None:
+    """A reported share of a token total, or ``None`` when it was not
+    reported or exceeds the total."""
+    return part if part is not None and 0 <= part <= whole else None
+
+
 def _emit_stop_reason_error(
     session: Session,
     provider: Provider,

{flightdeck_sensor-0.6.0 → flightdeck_sensor-0.7.0}/flightdeck_sensor/interceptor/openai.py

@@ -74,6 +74,7 @@ from typing import TYPE_CHECKING, Any
 
 from flightdeck_sensor.core.errors import classify_stop_reason
 from flightdeck_sensor.interceptor import base
+from flightdeck_sensor.interceptor.platform import PLATFORM_OPENAI, endpoint_of
 from flightdeck_sensor.providers.openai import OpenAIProvider
 
 if TYPE_CHECKING:
@@ -103,6 +104,19 @@ except ImportError:
     _OPENAI_AVAILABLE = False
 
 
+def _provider_for(client: Any, session: Session) -> OpenAIProvider:
+    """An OpenAI provider for a client, attributed to the endpoint the
+    client talks to (``openai``, ``azure``, or the host of an
+    OpenAI-compatible server; see
+    :func:`flightdeck_sensor.interceptor.platform.endpoint_of`)."""
+    endpoint = endpoint_of(client, PLATFORM_OPENAI)
+    return OpenAIProvider(
+        capture_prompts=session.config.capture_prompts,
+        platform=endpoint.platform,
+        local=endpoint.local,
+    )
+
+
 def _is_async_client(client: Any) -> bool:
     """Detect async OpenAI client using the captured class reference."""
     if _OrigAsyncOpenAI is None:
@@ -727,9 +741,7 @@ class SensorOpenAI:
         self._client = client
         self._session = session
         self._is_async = _is_async_client(client)
-        self._provider = provider or OpenAIProvider(
-            capture_prompts=session.config.capture_prompts,
-        )
+        self._provider = provider or _provider_for(client, session)
 
     @property
     def chat(self) -> SensorChat:
@@ -867,9 +879,7 @@ class _OpenAIChatDescriptor:
         if session is None:
             return raw
 
-        provider = OpenAIProvider(
-            capture_prompts=session.config.capture_prompts,
-        )
+        provider = _provider_for(instance, session)
         wrapped = SensorChat(
             raw,
             session,
@@ -913,9 +923,7 @@ class _OpenAIResponsesDescriptor:
         if session is None:
             return raw
 
-        provider = OpenAIProvider(
-            capture_prompts=session.config.capture_prompts,
-        )
+        provider = _provider_for(instance, session)
         wrapped = SensorResponses(
             raw,
             session,
@@ -959,9 +967,7 @@ class _OpenAIEmbeddingsDescriptor:
         if session is None:
             return raw
 
-        provider = OpenAIProvider(
-            capture_prompts=session.config.capture_prompts,
-        )
+        provider = _provider_for(instance, session)
         wrapped = SensorEmbeddings(
             raw,
             session,

flightdeck_sensor-0.7.0/flightdeck_sensor/interceptor/platform.py

@@ -0,0 +1,126 @@
+"""Endpoint attribution shared by the SDK interceptors.
+
+Every ``post_call`` names the endpoint the client talked to under
+``provider_metadata.platform``: a fixed label for the hosts the SDKs'
+own client classes default to, else the bare host of whatever the client
+was pointed at (a gateway, a proxy, a local model server). The worker
+copies it into ``events.platform`` and the cost model picks the price
+list from it. The host is the only source, so a first-party client
+pointed at a gateway reports the gateway rather than a label its class
+carries.
+
+A client pointed at a loopback host (``localhost``, ``127.0.0.0/8``,
+``::1``) is a self-hosted model server, whose calls carry the ``local``
+billing mode.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import ipaddress
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+_log = logging.getLogger("flightdeck_sensor.interceptor.platform")
+
+PLATFORM_ANTHROPIC = "anthropic"
+PLATFORM_OPENAI = "openai"
+PLATFORM_AZURE = "azure"
+PLATFORM_VERTEX = "vertex"
+# The platform of a client pointed at this machine, whatever spelling of
+# the loopback host it uses (an IPv6 literal would otherwise fail the
+# hostname check below and read as invalid-host).
+PLATFORM_LOCALHOST = "localhost"
+
+# Hosts the SDKs' own client classes default to, mapped to the platform
+# name reported on the event: (host prefix, host suffix, platform). The
+# first matching row wins. A host that matches no row -- a gateway or a
+# proxy the caller pointed the SDK at -- is reported verbatim, so the
+# deployment topology stays visible instead of being mislabelled as the
+# provider's own API.
+_PLATFORM_HOSTS: tuple[tuple[str, str, str], ...] = (
+    # Every suffix starts with a separator so a look-alike such as
+    # evilanthropic.com or anthropic.com.evil.example stays bare, and
+    # Vertex matches only the Vertex AI API hosts (aiplatform.<...>
+    # .googleapis.com and the regional <region>-aiplatform.googleapis.com)
+    # and google-cloud only Claude Platform on Google Cloud's gateway
+    # (claude.googleapis.com), not every Google API host.
+    ("", ".anthropic.com", PLATFORM_ANTHROPIC),
+    ("bedrock-runtime.", ".amazonaws.com", "bedrock"),
+    ("bedrock-mantle.", ".api.aws", "bedrock-mantle"),
+    ("aws-external-anthropic.", ".api.aws", "aws"),
+    ("claude.", ".googleapis.com", "google-cloud"),
+    ("aiplatform.", ".googleapis.com", PLATFORM_VERTEX),
+    ("", "-aiplatform.googleapis.com", PLATFORM_VERTEX),
+    ("", ".services.ai.azure.com", "foundry"),
+    ("", ".openai.com", PLATFORM_OPENAI),
+    ("", ".openai.azure.com", PLATFORM_AZURE),
+    ("", ".cognitiveservices.azure.com", PLATFORM_AZURE),
+)
+
+# A platform value is one of the names above or a hostname. Hostnames are
+# bounded by the DNS limit on a fully qualified name, and only letters,
+# digits, dots and hyphens are accepted once lowercased; anything longer
+# or containing other characters is reported as PLATFORM_INVALID_HOST,
+# so a malformed or hostile base_url cannot put arbitrary bytes into
+# every post_call of a session.
+_MAX_PLATFORM_HOST_LENGTH = 253
+_PLATFORM_HOST_CHARS = frozenset("abcdefghijklmnopqrstuvwxyz0123456789.-")
+PLATFORM_INVALID_HOST = "invalid-host"
+
+
+def platform_for_host(host: str) -> str:
+    """The platform name for an API host: a known platform (see
+    ``_PLATFORM_HOSTS``), else the host itself when it is a well-formed
+    hostname, else :data:`PLATFORM_INVALID_HOST`."""
+    lowered = host.lower()
+    if (
+        not lowered
+        or len(lowered) > _MAX_PLATFORM_HOST_LENGTH
+        or not set(lowered) <= _PLATFORM_HOST_CHARS
+    ):
+        return PLATFORM_INVALID_HOST
+    for prefix, suffix, platform in _PLATFORM_HOSTS:
+        if lowered.startswith(prefix) and lowered.endswith(suffix):
+            return platform
+    return lowered
+
+
+def is_loopback_host(host: str) -> bool:
+    """Whether an API host is this machine: ``localhost`` (or a name under
+    it) or a loopback address. A server elsewhere on a private network is
+    not treated as local, since gateways and metered proxies often sit on
+    such addresses."""
+    lowered = host.lower().strip("[]").rstrip(".")
+    if lowered == "localhost" or lowered.endswith(".localhost"):
+        return True
+    with contextlib.suppress(ValueError):
+        address = ipaddress.ip_address(lowered)
+        mapped = getattr(address, "ipv4_mapped", None)
+        return (mapped or address).is_loopback
+    return False
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    """Where a client sends its requests: the platform label, and whether
+    that is a model server on this machine."""
+
+    platform: str
+    local: bool = False
+
+
+def endpoint_of(client: Any, default_platform: str) -> Endpoint:
+    """The endpoint of a client, read from ``client.base_url.host``;
+    ``default_platform`` when the client exposes no usable host (a test
+    double)."""
+    try:
+        host = getattr(getattr(client, "base_url", None), "host", None)
+        if isinstance(host, str) and host:
+            if is_loopback_host(host):
+                return Endpoint(platform=PLATFORM_LOCALHOST, local=True)
+            return Endpoint(platform=platform_for_host(host))
+    except Exception:
+        _log.debug("platform attribution failed", exc_info=True)
+    return Endpoint(platform=default_platform)