unitysvc-core 0.1.0__py3-none-any.whl

unitysvc_core/__init__.py

@@ -0,0 +1,32 @@
+"""UnitySVC Core — shared data models and validation helpers.
+
+This package is audience-neutral. It contains the pydantic models, JSON
+schemas, and validator consumed by the UnitySVC backend, the customer SDK,
+the admin CLI, and the seller SDK.
+
+It intentionally does NOT include any CLI, HTTP client, or audience-
+specific helpers (seller catalog builders, customer query helpers, etc.).
+Those live in the corresponding audience packages (``unitysvc-sellers``,
+``unitysvc`` customer SDK, ``unitysvc-admin``).
+"""
+
+__author__ = """Bo Peng"""
+__email__ = "bo.peng@unitysvc.com"
+
+# Shared file / data utilities used by the backend and SDK consumers
+from .utils import (
+    compute_file_hash,
+    generate_content_based_key,
+    get_basename,
+    get_file_extension,
+    mime_type_to_extension,
+)
+
+__all__ = [
+    # File utilities
+    "compute_file_hash",
+    "generate_content_based_key",
+    "get_basename",
+    "get_file_extension",
+    "mime_type_to_extension",
+]

unitysvc_core/models/__init__.py

@@ -0,0 +1,171 @@
+from .base import (
+    AccessMethodEnum,
+    AuthMethodEnum,
+    ContentFilterEnum,
+    CurrencyEnum,
+    DocumentCategoryEnum,
+    DocumentContextEnum,
+    ListingStatusEnum,
+    MimeTypeEnum,
+    OfferingStatusEnum,
+    OveragePolicyEnum,
+    PriceRuleApplyAtEnum,
+    PriceRuleStatusEnum,
+    PricingTypeEnum,
+    ProviderStatusEnum,
+    QuotaResetCycleEnum,
+    RateLimitUnitEnum,
+    RequestTransformEnum,
+    SellerTypeEnum,
+    ServiceGroupStatusEnum,
+    ServiceTypeEnum,
+    TimeWindowEnum,
+    UpstreamStatusEnum,  # Backwards compatibility alias for OfferingStatusEnum
+)
+from .documents import DocumentData
+from .listing_data import ServiceListingData
+from .listing_v1 import ListingV1
+from .offering_data import ServiceOfferingData
+from .offering_v1 import OfferingV1
+from .pricing import (
+    AddPriceData,
+    BasePriceData,
+    ConstantPriceData,
+    CountPriceData,
+    DataPriceData,
+    ExprPriceData,
+    FirstPriceData,
+    GraduatedPriceData,
+    GraduatedTier,
+    ImagePriceData,
+    MaxPriceData,
+    MinPriceData,
+    MultiplyPriceData,
+    PercentageStr,
+    PriceStr,
+    PriceTier,
+    Pricing,
+    RevenueSharePriceData,
+    StepPriceData,
+    TieredPriceData,
+    TimePriceData,
+    TokenPriceData,
+    UsageData,
+    validate_pricing,
+)
+from .promotion_data import (
+    PROMOTION_SCHEMA_VERSION,
+    PromotionData,
+    describe_scope,
+    is_promotion_file,
+    strip_schema_field,
+    validate_promotion,
+)
+from .promotion_v1 import PromotionV1
+from .provider_data import ProviderData
+from .provider_v1 import ProviderV1
+from .service import (
+    AccessInterfaceData,
+    RateLimit,
+    ServiceConstraints,
+    UpstreamAccessConfigData,
+)
+from .service_group_data import (
+    SERVICE_GROUP_SCHEMA_VERSION,
+    ServiceGroupData,
+    is_service_group_file,
+    validate_service_group,
+)
+from .service_group_v1 import ServiceGroupV1
+from .validators import (
+    SUPPORTED_SERVICE_OPTIONS,
+    suggest_valid_name,
+    validate_name,
+    validate_service_options,
+)
+
+__all__ = [
+    # V1 models (for file validation)
+    "ProviderV1",
+    "OfferingV1",
+    "ListingV1",
+    "PromotionV1",
+    "ServiceGroupV1",
+    # Data models (for API/backend use)
+    "ProviderData",
+    "ServiceOfferingData",
+    "ServiceListingData",
+    "PromotionData",
+    "ServiceGroupData",
+    # Shared / access models
+    "DocumentData",
+    "AccessInterfaceData",
+    "UpstreamAccessConfigData",
+    "RateLimit",
+    "ServiceConstraints",
+    # Enums
+    "AccessMethodEnum",
+    "AuthMethodEnum",
+    "ContentFilterEnum",
+    "CurrencyEnum",
+    "DocumentCategoryEnum",
+    "DocumentContextEnum",
+    "ListingStatusEnum",
+    "MimeTypeEnum",
+    "OfferingStatusEnum",
+    "OveragePolicyEnum",
+    "PriceRuleApplyAtEnum",
+    "PriceRuleStatusEnum",
+    "PricingTypeEnum",
+    "ProviderStatusEnum",
+    "QuotaResetCycleEnum",
+    "RateLimitUnitEnum",
+    "RequestTransformEnum",
+    "SellerTypeEnum",
+    "ServiceGroupStatusEnum",
+    "ServiceTypeEnum",
+    "TimeWindowEnum",
+    "UpstreamStatusEnum",  # Backwards compatibility alias for OfferingStatusEnum
+    # Pricing — primitives
+    "PriceStr",
+    "PercentageStr",
+    "UsageData",
+    "Pricing",
+    "validate_pricing",
+    "BasePriceData",
+    # Pricing — simple types
+    "TokenPriceData",
+    "TimePriceData",
+    "DataPriceData",
+    "CountPriceData",
+    "ImagePriceData",
+    "StepPriceData",
+    "RevenueSharePriceData",
+    "ConstantPriceData",
+    # Pricing — composite types
+    "AddPriceData",
+    "MultiplyPriceData",
+    "MaxPriceData",
+    "MinPriceData",
+    "FirstPriceData",
+    "TieredPriceData",
+    "GraduatedPriceData",
+    "ExprPriceData",
+    "PriceTier",
+    "GraduatedTier",
+    # Validators
+    "SUPPORTED_SERVICE_OPTIONS",
+    "validate_name",
+    "validate_service_options",
+    "suggest_valid_name",
+    # Promotions
+    "PROMOTION_SCHEMA_VERSION",
+    "is_promotion_file",
+    "describe_scope",
+    "strip_schema_field",
+    "validate_promotion",
+    # Service Groups
+    "SERVICE_GROUP_SCHEMA_VERSION",
+    "is_service_group_file",
+    "validate_service_group",
+]

unitysvc_core/models/base.py

@@ -0,0 +1,317 @@
+"""Enum types and basic definitions shared across the data models.
+
+This module contains only enums and simple constants. Data classes with
+behavior (pricing, documents, service constraints, etc.) and validation
+functions live in their own modules:
+
+- ``pricing.py`` — pricing types and cost calculation
+- ``documents.py`` — DocumentData
+- ``service.py`` — RateLimit, ServiceConstraints, AccessInterfaceData, UpstreamAccessConfigData
+- ``validators.py`` — validate_name, validate_service_options, suggest_valid_name
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class AccessMethodEnum(StrEnum):
+    http = "http"
+    websocket = "websocket"
+    grpc = "grpc"
+    smtp = "smtp"
+
+
+class CurrencyEnum(StrEnum):
+    """Supported currency codes for pricing."""
+
+    # Traditional currencies
+    USD = "USD"  # US Dollar
+    EUR = "EUR"  # Euro
+    GBP = "GBP"  # British Pound
+    JPY = "JPY"  # Japanese Yen
+    CNY = "CNY"  # Chinese Yuan
+    CAD = "CAD"  # Canadian Dollar
+    AUD = "AUD"  # Australian Dollar
+    CHF = "CHF"  # Swiss Franc
+    INR = "INR"  # Indian Rupee
+    KRW = "KRW"  # Korean Won
+
+    # Cryptocurrencies
+    BTC = "BTC"  # Bitcoin
+    ETH = "ETH"  # Ethereum
+    USDT = "USDT"  # Tether
+    USDC = "USDC"  # USD Coin
+    TAO = "TAO"  # Bittensor TAO
+
+    # Credits/Points (for platforms that use credits)
+    CREDITS = "CREDITS"  # Generic credits system
+
+
+class AuthMethodEnum(StrEnum):
+    api_key = "api_key"
+    oauth = "oauth"
+    jwt = "jwt"
+    bearer_token = "bearer_token"
+    basic_auth = "basic_auth"
+
+
+class ContentFilterEnum(StrEnum):
+    adult = "adult"
+    violence = "violence"
+    hate_speech = "hate_speech"
+    profanity = "profanity"
+    pii = "pii"  # Personally Identifiable Information
+
+
+class DocumentContextEnum(StrEnum):
+    service_definition = "service_definition"  # Documents belong to ServiceDefinition
+    service_offering = "service_offering"  # Documents belong to ServiceOffering
+    service_listing = "service_listing"  # Documents belong to ServiceListing
+    user = "user"  # can be for seller, subscriber, consumer
+    # Backend-specific contexts
+    seller = "seller"  # Documents belong to Seller
+    provider = "provider"  # Documents belong to Provider
+    blog_post = "blog_post"  # Documents belong to BlogPost
+    #
+    customer_statement = "customer_statement"
+    seller_invoice = "seller_invoice"
+
+
+class DocumentCategoryEnum(StrEnum):
+    getting_started = "getting_started"
+    api_reference = "api_reference"
+    tutorial = "tutorial"
+    code_example = "code_example"
+    code_example_output = "code_example_output"
+    connectivity_test = "connectivity_test"  # Test connectivity & performance (not visible to users)
+    request_template = "request_template"  # Default request body for playground pre-fill
+    use_case = "use_case"
+    troubleshooting = "troubleshooting"
+    changelog = "changelog"
+    best_practice = "best_practice"
+    specification = "specification"
+    service_level_agreement = "service_level_agreement"
+    terms_of_service = "terms_of_service"
+    statement = "statement"
+    invoice = "invoice"
+    logo = "logo"
+    avatar = "avatar"
+    blog_content = "blog_content"  # Main content for blog posts
+    blog_banner = "blog_banner"  # Banner/cover image for blog posts
+    attachment = "attachment"  # Attachments for markdown documents
+    other = "other"
+
+
+class MimeTypeEnum(StrEnum):
+    markdown = "markdown"
+    python = "python"
+    javascript = "javascript"
+    bash = "bash"
+    html = "html"
+    json = "json"
+    text = "text"
+    pdf = "pdf"
+    jpeg = "jpeg"
+    png = "png"
+    svg = "svg"
+    url = "url"
+
+
+class ServiceGroupStatusEnum(StrEnum):
+    draft = "draft"
+    active = "active"
+    private = "private"
+    archived = "archived"
+
+
+class SellerTypeEnum(StrEnum):
+    individual = "individual"
+    organization = "organization"
+    partnership = "partnership"
+    corporation = "corporation"
+
+
+class ListingStatusEnum(StrEnum):
+    """
+    Status values that sellers can set for listings.
+
+    Seller-accessible statuses:
+    - draft: Work in progress, skipped during publish (won't be sent to backend)
+    - ready: Complete and ready for admin review/testing
+    - deprecated: Retired/end of life, no longer offered
+
+    Note: Admin-managed workflow statuses (upstream_ready, downstream_ready, in_service)
+    are set by the backend admin after testing and validation. These are not included in this
+    enum since sellers cannot set them through the CLI tool.
+    """
+
+    draft = "draft"
+    ready = "ready"
+    deprecated = "deprecated"
+
+
+class OveragePolicyEnum(StrEnum):
+    block = "block"  # Block requests when quota exceeded
+    throttle = "throttle"  # Reduce rate when quota exceeded
+    charge = "charge"  # Allow with additional charges
+    queue = "queue"  # Queue requests until quota resets
+
+
+class PricingTypeEnum(StrEnum):
+    """
+    Pricing type determines the structure and calculation method.
+    The type is stored as the 'type' field in the pricing object.
+    """
+
+    # Basic pricing types
+    one_million_tokens = "one_million_tokens"
+    one_thousand_tokens = "one_thousand_tokens"
+    one_token = "one_token"
+    one_second = "one_second"
+    one_minute = "one_minute"
+    one_hour = "one_hour"
+    one_day = "one_day"
+    one_month = "one_month"
+    one_byte = "one_byte"
+    one_kilobyte = "one_kilobyte"
+    one_megabyte = "one_megabyte"
+    one_gigabyte = "one_gigabyte"
+    one_thousand = "one_thousand"
+    one_million = "one_million"
+    image = "image"
+    step = "step"
+    # Seller-only: seller receives a percentage of what customer pays
+    revenue_share = "revenue_share"
+    # Composite pricing types
+    constant = "constant"  # Fixed amount (fee or discount)
+    add = "add"  # Sum of multiple prices
+    multiply = "multiply"  # Base price multiplied by factor
+    max = "max"  # Highest of multiple prices (lenient)
+    min = "min"  # Lowest of multiple prices (lenient)
+    first = "first"  # First applicable price (lenient)
+    # Tiered pricing types
+    tiered = "tiered"  # Volume-based tiers (all units at one tier's price)
+    graduated = "graduated"  # Graduated tiers (each tier's units at that rate)
+    # Expression-based pricing (payout_price only)
+    expr = "expr"  # Arbitrary expression using usage metrics
+
+
+
+class QuotaResetCycleEnum(StrEnum):
+    daily = "daily"
+    weekly = "weekly"
+    monthly = "monthly"
+    yearly = "yearly"
+
+
+class RateLimitUnitEnum(StrEnum):
+    requests = "requests"
+    tokens = "tokens"
+    input_tokens = "input_tokens"
+    output_tokens = "output_tokens"
+    bytes = "bytes"
+    concurrent = "concurrent"
+
+
+class RequestTransformEnum(StrEnum):
+    # https://docs.api7.ai/hub/proxy-rewrite
+    proxy_rewrite = "proxy_rewrite"
+    # https://docs.api7.ai/hub/body-transformer
+    body_transformer = "body_transformer"
+    # Simple body replacement from rendered enrollment data
+    set_body = "set_body"
+
+
+class ServiceTypeEnum(StrEnum):
+    """Broad service category — defines the access pattern and protocol.
+
+    AI modalities (vision, tools, rerank, etc.) are tracked via the
+    `capabilities` list on ServiceOffering, not service_type.
+    """
+
+    # === AI / ML services (HTTP API) ===
+    llm = "llm"  # Language models, chat completions
+    embedding = "embedding"  # Text/vector embedding
+    image_generation = "image_generation"  # Image creation/editing
+
+    # === Communication services ===
+    notification = "notification"  # Push notifications (HTTP)
+    email = "email"  # Email delivery (SMTP gateway)
+
+    # === Content services ===
+    content = "content"  # Downloadable files, datasets, images, software
+    streaming = "streaming"  # Video, audio, live feeds (persistent connection)
+
+    # === Compute services ===
+    compute = "compute"  # GPU instances, dev environments (SSH/WireGuard)
+
+    # === Infrastructure services ===
+    database = "database"  # Managed DB/cache access (SSH tunnel)
+    monitoring = "monitoring"  # Uptime checks, health monitoring
+    analytics = "analytics"  # Recommendation, anomaly detection, forecasting
+
+
+class TimeWindowEnum(StrEnum):
+    second = "second"
+    minute = "minute"
+    hour = "hour"
+    day = "day"
+    month = "month"
+
+
+class OfferingStatusEnum(StrEnum):
+    """
+    Status values that sellers can set for service offerings.
+
+    Seller-accessible statuses:
+    - draft: Work in progress, skipped during publish
+    - ready: Complete and ready for admin review
+    - deprecated: Service is retired/end of life
+    """
+
+    draft = "draft"
+    ready = "ready"
+    deprecated = "deprecated"
+
+
+# Backwards compatibility alias
+UpstreamStatusEnum = OfferingStatusEnum
+
+
+class ProviderStatusEnum(StrEnum):
+    """
+    Status values that sellers can set for providers.
+
+    Seller-accessible statuses:
+    - draft: Work in progress, skipped during publish
+    - ready: Complete and ready for admin review
+    - deprecated: Provider is retired/end of life
+    """
+
+    draft = "draft"
+    ready = "ready"
+    deprecated = "deprecated"
+
+
+class PriceRuleApplyAtEnum(StrEnum):
+    """When the price rule is applied."""
+
+    request = "request"  # Applied per API call
+    statement = "statement"  # Applied during billing/statement generation
+
+
+
+class PriceRuleStatusEnum(StrEnum):
+    """Seller-facing status values for promotions.
+
+    The backend may define additional statuses (scheduled, expired,
+    cancelled) for internal lifecycle management, but sellers only
+    interact with these three.
+    """
+
+    draft = "draft"  # Not yet active, can be edited
+    active = "active"  # Currently active and applied
+    paused = "paused"  # Temporarily disabled
+
+

unitysvc_core/models/documents.py

@@ -0,0 +1,46 @@
+"""Document data model — used by provider, offering, listing, and promotion files."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .base import DocumentCategoryEnum, MimeTypeEnum
+
+
+class DocumentData(BaseModel):
+    """Document data for SDK/API payloads.
+
+    Note: The document title is NOT stored here - it's the key in the documents dict.
+    When stored in the database, the backend extracts the key as the title field.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    description: str | None = Field(default=None, max_length=500, description="Document description")
+    mime_type: MimeTypeEnum = Field(description="Document MIME type")
+    version: str | None = Field(default=None, max_length=50, description="Document version")
+    category: DocumentCategoryEnum = Field(description="Document category for organization and filtering")
+    meta: dict[str, Any] | None = Field(
+        default=None,
+        description="JSON containing operation stats",
+    )
+    file_path: str | None = Field(
+        default=None,
+        max_length=1000,
+        description="Path to file to upload (mutually exclusive with external_url)",
+    )
+    external_url: str | None = Field(
+        default=None,
+        max_length=1000,
+        description="External URL for the document (mutually exclusive with object_key)",
+    )
+    sort_order: int = Field(default=0, description="Sort order within category")
+    is_active: bool = Field(default=True, description="Whether document is active")
+    is_public: bool = Field(
+        default=False,
+        description="Whether document is publicly accessible without authentication",
+    )
+
+

unitysvc_core/models/listing_data.py

@@ -0,0 +1,115 @@
+"""Base data models for service listings.
+
+This module defines `ServiceListingData`, a base model containing the core fields
+for service listing data that is shared between:
+- unitysvc-core (CLI): Used for file-based listing definitions
+- unitysvc (backend): Used for API payloads and database operations
+
+The `ListingV1` model extends this with file-specific fields like `schema_version`
+and `time_created` for data file validation.
+"""
+
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from .base import CurrencyEnum, ListingStatusEnum
+
+
+class ServiceListingData(BaseModel):
+    """
+    Base data structure for service listing information.
+
+    This model contains the core fields needed to describe a service listing,
+    without file-specific validation fields. It serves as:
+
+    1. The base class for `ListingV1` in unitysvc-core (with additional
+       schema_version and time_created fields for file validation)
+
+    2. The data structure imported by unitysvc backend for:
+       - API payload validation
+       - Database comparison logic in find_and_compare_service_listing()
+       - Publish operations from CLI
+
+    Key characteristics:
+    - Contains all user-provided data without system-generated IDs
+    - Does not include permission/audit fields (handled by backend CRUD layer)
+    - Uses dict types for nested structures to maintain flexibility between
+      file definitions and database operations
+    - Service/provider relationships are determined by file location (SDK mode) or
+      by being published together in a single API call (API mode)
+    """
+
+    model_config = {"extra": "ignore"}
+
+    # Service ID for updates (set by SDK after first publish)
+    # When provided, updates the existing service. When absent, creates a new service.
+    service_id: UUID | None = Field(
+        default=None,
+        description="Service ID from previous publish. If provided, updates existing service. "
+        "Stored in override file (e.g., listing.override.json) by SDK after first publish.",
+    )
+
+    # Listing identification
+    name: str | None = Field(
+        default=None,
+        max_length=255,
+        description="Name identifier for the service listing (defaults to offering name if not provided)",
+    )
+
+    # Display name for UI (optional - falls back to Service.name derived from offering/listing name)
+    display_name: str | None = Field(
+        default=None,
+        max_length=200,
+        description="Human-readable listing name (e.g., 'Premium GPT-4 Access', 'Enterprise AI Services')",
+    )
+
+    # Status - seller-accessible statuses
+    status: ListingStatusEnum = Field(
+        default=ListingStatusEnum.draft,
+        description="Listing status: draft (skip publish), ready (ready for admin review), or deprecated (retired)",
+    )
+
+    # List pricing
+    list_price: dict[str, Any] | None = Field(
+        default=None,
+        description="List price: Listed price for customers per unit of service usage",
+    )
+
+    # Currency for list_price
+    currency: CurrencyEnum = Field(
+        default=CurrencyEnum.USD,
+        description="Currency for list_price (indexed for filtering)",
+    )
+
+    # Access interfaces (keyed by name)
+    user_access_interfaces: dict[str, dict[str, Any]] | None = Field(
+        default=None,
+        description="User access interfaces for the listing, keyed by name",
+    )
+
+    # Documents (keyed by title)
+    documents: dict[str, dict[str, Any]] | None = Field(
+        default=None,
+        description="Documents associated with the listing, keyed by title (e.g., service level agreements)",
+    )
+
+    # User parameters
+    user_parameters_schema: dict[str, Any] | None = Field(
+        default=None,
+        description="JSON Schema for user parameters",
+    )
+
+    user_parameters_ui_schema: dict[str, Any] | None = Field(
+        default=None,
+        description="UI schema for user parameters form rendering",
+    )
+
+    # Service-specific options
+    service_options: dict[str, Any] | None = Field(
+        default=None,
+        description="Service-specific options that modify backend behavior. "
+        "Keys are option names, values are option configurations. "
+        "The backend decides which options it supports.",
+    )