unitysvc-core 0.2.4__tar.gz → 0.2.7__tar.gz

{unitysvc_core-0.2.4/src/unitysvc_core.egg-info → unitysvc_core-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.4
+Version: 0.2.7
 Summary: Shared data models and validation helpers for UnitySVC packages
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>

{unitysvc_core-0.2.4 → unitysvc_core-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitysvc-core"
-version = "0.2.4"
+version = "0.2.7"
 description = "Shared data models and validation helpers for UnitySVC packages"
 readme = "README.md"
 authors = [{ name = "Bo Peng", email = "bo.peng@unitysvc.com" }]

{unitysvc_core-0.2.4 → unitysvc_core-0.2.7}/src/unitysvc_core/models/__init__.py

@@ -33,6 +33,7 @@ from .offering_v1 import OfferingV1
 from .pricing import (
     AddPriceData,
     BasePriceData,
+    ChannelPriceData,
     ConstantPriceData,
     CountPriceData,
     DataPriceData,
@@ -43,7 +44,6 @@ from .pricing import (
     ImagePriceData,
     MaxPriceData,
     MinPriceData,
-    ModePriceData,
     MultiplyPriceData,
     PercentageStr,
     PriceStr,
@@ -159,7 +159,7 @@ __all__ = [
     "MultiplyPriceData",
     "MaxPriceData",
     "MinPriceData",
-    "ModePriceData",
+    "ChannelPriceData",
     "FirstPriceData",
     "TieredPriceData",
     "GraduatedPriceData",

{unitysvc_core-0.2.4 → unitysvc_core-0.2.7}/src/unitysvc_core/models/base.py

@@ -216,8 +216,8 @@ class PricingTypeEnum(StrEnum):
     graduated = "graduated"  # Graduated tiers (each tier's units at that rate)
     # Expression-based pricing (payout_price only)
     expr = "expr"  # Arbitrary expression using usage metrics
-    # Mode-based pricing: select a sub-price by the request's resolved mode
-    mode = "mode"  # Per-mode pricing keyed by mode name (e.g. managed, byok)
+    # Channel-based pricing: select a sub-price by the request's resolved channel
+    channel = "channel"  # Per-channel pricing keyed by channel name (e.g. managed, byok)
 
 
 class QuotaResetCycleEnum(StrEnum):

{unitysvc_core-0.2.4 → unitysvc_core-0.2.7}/src/unitysvc_core/models/offering_data.py

@@ -91,10 +91,10 @@ class ServiceOfferingData(BaseModel):
         description="Payout pricing: How to calculate seller payout",
     )
 
-    # Access interfaces (keyed by name)
+    # Access channels (keyed by channel name)
     upstream_access_config: dict[str, dict[str, Any]] | None = Field(
         default=None,
-        description="Upstream access interfaces, keyed by name",
+        description="Upstream access channels, keyed by channel name",
     )
 
     # Documents (keyed by title)

{unitysvc_core-0.2.4 → unitysvc_core-0.2.7}/src/unitysvc_core/models/offering_v1.py

@@ -7,7 +7,7 @@ from .documents import DocumentData
 from .offering_data import ServiceOfferingData
 from .pricing import Pricing
 from .service import UpstreamAccessConfigData
-from .validators import validate_service_identifier
+from .validators import validate_channel_name, validate_service_identifier
 
 
 class OfferingV1(ServiceOfferingData):
@@ -46,7 +46,7 @@ class OfferingV1(ServiceOfferingData):
 
     # Override with typed models for file validation
     upstream_access_config: dict[str, UpstreamAccessConfigData] = Field(  # type: ignore[assignment]
-        description="Upstream access interfaces, keyed by name",
+        description="Upstream access channels, keyed by channel name",
     )
 
     documents: dict[str, DocumentData] | None = Field(  # type: ignore[assignment]
@@ -69,3 +69,16 @@ class OfferingV1(ServiceOfferingData):
         ``validate_service_identifier`` for full rules.
         """
         return validate_service_identifier(v, "service")
+
+    @field_validator("upstream_access_config")
+    @classmethod
+    def validate_channel_names(cls, v: dict[str, UpstreamAccessConfigData]) -> dict[str, UpstreamAccessConfigData]:
+        """Validate every channel name (key of ``upstream_access_config``).
+
+        Channel names are selected via the ``<name>@<channel>`` identifier
+        suffix, so each must follow the channel-name grammar and must not
+        contain ``@``. See ``validate_channel_name``.
+        """
+        for channel_name in v:
+            validate_channel_name(channel_name)
+        return v

{unitysvc_core-0.2.4 → unitysvc_core-0.2.7}/src/unitysvc_core/models/pricing.py

@@ -280,7 +280,7 @@ class TokenPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost for token-based pricing.
 
@@ -347,7 +347,7 @@ class TimePriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost for time-based pricing.
 
@@ -388,7 +388,7 @@ class ImagePriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost for image-based pricing.
 
@@ -425,7 +425,7 @@ class StepPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost for step-based pricing.
 
@@ -465,7 +465,7 @@ class DataPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost for data-volume pricing.
 
@@ -509,7 +509,7 @@ class CountPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost for count-scaled pricing.
 
@@ -572,7 +572,7 @@ class RevenueSharePriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost for revenue share pricing.
 
@@ -612,7 +612,7 @@ class ConstantPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Return the constant price regardless of usage.
 
@@ -685,7 +685,7 @@ class AddPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate total cost by summing all price components.
 
@@ -700,7 +700,7 @@ class AddPriceData(BasePriceData):
         total = Decimal("0")
         for price_data in self.prices:
             component = validate_pricing(price_data)
-            total += component.calculate_cost(usage, customer_charge, request_count, mode)
+            total += component.calculate_cost(usage, customer_charge, request_count, channel)
         return total
 
 
@@ -745,7 +745,7 @@ class MultiplyPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost by multiplying base price by factor.
 
@@ -758,7 +758,7 @@ class MultiplyPriceData(BasePriceData):
             Base cost multiplied by factor
         """
         base_pricing = validate_pricing(self.base)
-        base_cost = base_pricing.calculate_cost(usage, customer_charge, request_count, mode)
+        base_cost = base_pricing.calculate_cost(usage, customer_charge, request_count, channel)
         return base_cost * Decimal(self.factor)
 
 
@@ -799,7 +799,7 @@ class MaxPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Return the highest cost among applicable children.
 
@@ -810,7 +810,7 @@ class MaxPriceData(BasePriceData):
         for price_data in self.prices:
             try:
                 component = validate_pricing(price_data)
-                costs.append(component.calculate_cost(usage, customer_charge, request_count, mode))
+                costs.append(component.calculate_cost(usage, customer_charge, request_count, channel))
             except ValueError:
                 continue
         if not costs:
@@ -857,7 +857,7 @@ class MinPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Return the lowest cost among applicable children.
 
@@ -868,7 +868,7 @@ class MinPriceData(BasePriceData):
         for price_data in self.prices:
             try:
                 component = validate_pricing(price_data)
-                costs.append(component.calculate_cost(usage, customer_charge, request_count, mode))
+                costs.append(component.calculate_cost(usage, customer_charge, request_count, channel))
             except ValueError:
                 continue
         if not costs:
@@ -914,7 +914,7 @@ class FirstPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Return the cost from the first child that can handle the usage.
 
@@ -925,7 +925,7 @@ class FirstPriceData(BasePriceData):
         for price_data in self.prices:
             try:
                 component = validate_pricing(price_data)
-                return component.calculate_cost(usage, customer_charge, request_count, mode)
+                return component.calculate_cost(usage, customer_charge, request_count, channel)
             except ValueError:
                 continue
         raise ValueError("No child pricing could handle the provided usage data")
@@ -1140,7 +1140,7 @@ class ExprPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost by evaluating the expression with usage data.
 
@@ -1214,7 +1214,7 @@ class TieredPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost based on which tier the usage falls into.
 
@@ -1232,7 +1232,7 @@ class TieredPriceData(BasePriceData):
         for tier in self.tiers:
             if tier.up_to is None or metric_value <= tier.up_to:
                 tier_pricing = validate_pricing(tier.price)
-                return tier_pricing.calculate_cost(usage, customer_charge, request_count, mode)
+                return tier_pricing.calculate_cost(usage, customer_charge, request_count, channel)
 
         # Should not reach here if tiers are properly configured
         raise ValueError("No matching tier found")
@@ -1297,7 +1297,7 @@ class GraduatedPriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
         """Calculate cost with graduated pricing across tiers.
 
@@ -1333,56 +1333,56 @@ class GraduatedPriceData(BasePriceData):
         return total_cost
 
 
-class ModePriceData(BasePriceData):
+class ChannelPriceData(BasePriceData):
     """
-    Mode-based pricing that selects a sub-price by the request's resolved mode.
+    Channel-based pricing that selects a sub-price by the request's resolved channel.
 
-    The active mode is decided elsewhere — e.g. the gateway picks which keyed
-    ``upstream_access_config`` a request routes through (``"managed"``,
-    ``"byok"``, ``"byoe"``, …) — and threads it into
-    ``calculate_cost(..., mode=...)``. The matching entry in ``modes`` is
-    evaluated; when the mode is unknown or unset, the ``default`` mode is used.
+    The active channel is decided elsewhere — e.g. the gateway picks which keyed
+    ``upstream_access_config`` (upstream access channel) a request routes through
+    (``"managed"``, ``"byok"``, ``"byoe"``, …) — and threads it into
+    ``calculate_cost(..., channel=...)``. The matching entry in ``channels`` is
+    evaluated; when the channel is unknown or unset, the ``default`` channel is used.
 
     There is no special-casing on the consumer side: every pricing type accepts
-    an optional ``mode`` and a mode-independent price simply ignores it, so a
-    plain price behaves identically for all modes. Mode-dependent pricing is
+    an optional ``channel`` and a channel-independent price simply ignores it, so a
+    plain price behaves identically for all channels. Channel-dependent pricing is
     just this one extra optional pricing type.
 
-    Each ``modes`` value is itself any pricing object (flat, composite, tiered,
-    or even nested mode-based), validated lazily — mirroring how tiered pricing
+    Each ``channels`` value is itself any pricing object (flat, composite, tiered,
+    or even nested channel-based), validated lazily — mirroring how tiered pricing
     holds per-tier prices.
 
     Example:
         {
-            "type": "mode",
+            "type": "channel",
             "default": "managed",
-            "modes": {
+            "channels": {
                 "managed": {"type": "one_million_tokens", "input": "0.50", "output": "1.50"},
                 "byok": {"type": "constant", "price": "0"}
             }
         }
     """
 
-    type: Literal["mode"] = "mode"
+    type: Literal["channel"] = "channel"
 
     default: str = Field(
-        description="Mode key evaluated when the request's mode is unknown or unset. "
-        "Must be one of the keys in `modes`.",
+        description="Channel name evaluated when the request's channel is unknown or unset. "
+        "Must be one of the keys in `channels`.",
     )
 
-    modes: dict[str, dict[str, Any]] = Field(
-        description="Per-mode pricing keyed by mode name (e.g. 'managed', 'byok'). "
+    channels: dict[str, dict[str, Any]] = Field(
+        description="Per-channel pricing keyed by channel name (e.g. 'managed', 'byok'). "
         "Each value is a nested pricing object of any type.",
         min_length=1,
     )
 
     @model_validator(mode="after")
-    def _validate_default_and_price(self) -> ModePriceData:
+    def _validate_default_and_price(self) -> ChannelPriceData:
         """Require ``default`` to exist and auto-compute the nominal price from it."""
-        if self.default not in self.modes:
-            raise ValueError(f"default mode {self.default!r} is not defined in modes ({sorted(self.modes)})")
+        if self.default not in self.channels:
+            raise ValueError(f"default channel {self.default!r} is not defined in channels ({sorted(self.channels)})")
         if self.price is None:
-            self.price = _extract_nominal_price(self.modes[self.default])
+            self.price = _extract_nominal_price(self.channels[self.default])
         return self
 
     def calculate_cost(
@@ -1390,24 +1390,24 @@ class ModePriceData(BasePriceData):
         usage: UsageData,
         customer_charge: Decimal | None = None,
         request_count: int | None = None,
-        mode: str | None = None,
+        channel: str | None = None,
     ) -> Decimal:
-        """Evaluate the price for the resolved ``mode`` (falling back to ``default``).
+        """Evaluate the price for the resolved ``channel`` (falling back to ``default``).
 
         Args:
-            usage: Usage data passed to the selected mode's price.
+            usage: Usage data passed to the selected channel's price.
             customer_charge: Customer charge passed through.
             request_count: Request count passed through.
-            mode: The resolved mode; unknown/``None`` falls back to ``default``.
+            channel: The resolved channel; unknown/``None`` falls back to ``default``.
 
         Returns:
-            Cost from the selected mode's pricing.
+            Cost from the selected channel's pricing.
         """
-        selected = self.modes.get(mode) if mode is not None else None
+        selected = self.channels.get(channel) if channel is not None else None
         if selected is None:
-            selected = self.modes[self.default]
+            selected = self.channels[self.default]
         pricing = validate_pricing(selected)
-        return pricing.calculate_cost(usage, customer_charge, request_count, mode)
+        return pricing.calculate_cost(usage, customer_charge, request_count, channel)
 
 
 # Discriminated union of all pricing types
@@ -1430,7 +1430,7 @@ Pricing = Annotated[
     | TieredPriceData
     | GraduatedPriceData
     | ExprPriceData
-    | ModePriceData,
+    | ChannelPriceData,
     Field(discriminator="type"),
 ]
 
@@ -1454,7 +1454,7 @@ def validate_pricing(
     | TieredPriceData
     | GraduatedPriceData
     | ExprPriceData
-    | ModePriceData
+    | ChannelPriceData
 ):
     """
     Validate pricing dict and return the appropriate typed model.

{unitysvc_core-0.2.4 → unitysvc_core-0.2.7}/src/unitysvc_core/models/service.py

@@ -116,7 +116,18 @@ class AccessInterfaceData(BaseModel):
 
 
 class UpstreamAccessConfigData(AccessInterfaceData):
-    """Upstream (seller-facing) access config data.
+    """One upstream access channel — a named entry in ``upstream_access_config``.
+
+    Each channel is a complete way for the gateway to reach the upstream: a wire
+    protocol (``access_method``), endpoint (``base_url``), credential (``api_key``),
+    routing key, and rate-limit/quality restrictions. A service may declare several
+    channels (keyed by free-form channel name, e.g. ``"managed"``, ``"byok"``,
+    ``"managed-eu"``); the gateway selects one per request.
+
+    The channel's *type* is derived from its credential/endpoint provenance:
+    ``managed`` (seller's key, ``${ secrets.* }``), ``byok`` (customer's key,
+    ``${ customer_secrets.* }``), or ``byoe`` (customer's key + customer-templated
+    ``base_url``).
 
     Extends AccessInterfaceData with extra="allow" to support protocol-specific
     configuration fields (e.g., S3 bucket/region, SMTP host/port) that the

{unitysvc_core-0.2.4 → unitysvc_core-0.2.7}/src/unitysvc_core/models/validators.py

@@ -191,6 +191,67 @@ def validate_service_identifier(name: str, entity_type: str) -> str:
     return name
 
 
+def validate_channel_name(name: str, entity_type: str = "channel") -> str:
+    """Validate an upstream access-channel name.
+
+    A channel name is the key of an entry in ``upstream_access_config`` (and
+    the keys of channel-based pricing). It is also the value selected by the
+    ``@<channel>`` suffix of a service identifier (``<name>@<channel>``), so it
+    must satisfy the same per-segment grammar as a variant tag and, critically,
+    must **not** contain ``@`` — that character is the channel-selector
+    delimiter and would make the identifier ambiguous.
+
+    Rules:
+
+    - Non-empty.
+    - No ``@`` (reserved as the ``<name>@<channel>`` selector delimiter).
+    - Each ``/``-separated segment uses only letters, digits, ``.``, ``-``,
+      ``_`` and must start with an alphanumeric character. (Single-character
+      channel names are allowed, matching variant-tag rules — only bare
+      *service* names carry the ≥2-char primitive-prefix restriction.)
+
+    Args:
+        name: The channel name to validate.
+        entity_type: Label used in error messages (default ``"channel"``).
+
+    Returns:
+        The validated channel name (unchanged if valid).
+
+    Raises:
+        ValueError: If the channel name is empty, contains ``@``, or has an
+            invalid segment.
+
+    Examples:
+        Valid: ``managed``, ``byok``, ``byoe``, ``gateway``, ``apprise``,
+        ``eu-west``, ``p``.
+
+        Invalid: ``""`` (empty), ``byok@eu`` (contains ``@``),
+        ``-byok`` (must start alphanumeric), ``by//ok`` (empty segment).
+    """
+    if not name:
+        raise ValueError(f"Invalid {entity_type} name: name cannot be empty")
+
+    if "@" in name:
+        raise ValueError(
+            f"Invalid {entity_type} name '{name}': '@' is not allowed — it is the "
+            f"channel-selector delimiter in '<name>@<channel>' identifiers."
+        )
+
+    for segment in name.split("/"):
+        if not segment:
+            raise ValueError(
+                f"Invalid {entity_type} name '{name}': empty segment (consecutive or leading/trailing '/')."
+            )
+        if not _SERVICE_NAME_SEGMENT_RE.match(segment):
+            raise ValueError(
+                f"Invalid {entity_type} name '{name}': segment '{segment}' "
+                f"has invalid characters (allowed: letters, digits, '.', '-', "
+                f"'_'; must start with an alphanumeric character)."
+            )
+
+    return name
+
+
 SUPPORTED_SERVICE_OPTIONS: dict[str, type | tuple[type, ...]] = {
     "enrollment": dict,  # Per-enrollment config: {scope, limit, limit_per_customer, limit_per_user}
     "routing_vars": dict,  # Seller-managed operational variables for template resolution at request time