unitysvc-services 0.1.0__py3-none-any.whl

unitysvc_services/models/base.py

@@ -0,0 +1,352 @@
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AccessMethodEnum(StrEnum):
+    http = "http"
+    websocket = "websocket"
+    grpc = "grpc"
+
+
+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):
+    access_interface = "access_interface"  # Documents belong to AccessInterface
+    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
+
+
+class DocumentCategoryEnum(StrEnum):
+    getting_started = "getting_started"
+    api_reference = "api_reference"
+    tutorials = "tutorials"
+    code_examples = "code_examples"
+    use_cases = "use_cases"
+    troubleshooting = "troubleshooting"
+    changelog = "changelog"
+    best_practices = "best_practices"
+    specification = "specification"
+    service_level_agreement = "service_level_agreement"
+    terms_of_service = "terms_of_service"
+    invoice = "invoice"
+    logo = "logo"
+    avatar = "avatar"
+    other = "other"
+
+
+class MimeTypeEnum(StrEnum):
+    markdown = "markdown"
+    python = "python"
+    javascript = "javascript"
+    bash = "bash"
+    html = "html"
+    text = "text"
+    pdf = "pdf"
+    jpeg = "jpeg"
+    png = "png"
+    svg = "svg"
+    url = "url"
+
+
+class InterfaceContextTypeEnum(StrEnum):
+    service_offering = "service_offering"  # Pricing from upstream provider
+    service_listing = "service_listing"  # Pricing shown to end users
+
+
+class SellerTypeEnum(StrEnum):
+    individual = "individual"
+    organization = "organization"
+    partnership = "partnership"
+    corporation = "corporation"
+
+
+class ListingStatusEnum(StrEnum):
+    # Not yet determined
+    unknown = "unknown"
+    # step 1: upstream is ready to be used
+    upstream_ready = "upstream_ready"
+    # step 2: downstream is ready, with proper routing, logging, and billing
+    downstream_ready = "downstream_ready"
+    # step 3: service is operationally ready (with proper documentation and initial
+    # performance metrics, and pricing strategy)
+    ready = "ready"
+    # step 4: service is in service
+    in_service = "in_service"
+    # step 5.1: service is deprecated from upstream
+    upstream_deprecated = "upstream_deprecated"
+    # step 5.2: service is no longer offered to users (due to business reasons)
+    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):
+    upstream = "upstream"  # Pricing from upstream provider
+    user_facing = "user_facing"  # Pricing shown to end users
+
+
+class PricingUnitEnum(StrEnum):
+    one_million_tokens = "one_million_tokens"
+    one_second = "one_second"
+    image = "image"
+    step = "step"
+
+
+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"
+
+
+class ServiceTypeEnum(StrEnum):
+    llm = "llm"
+    # generate embedding from texts
+    embedding = "embedding"
+    # generation of images from prompts
+    image_generation = "image_generation"
+    # streaming trancription needs websocket connection forwarding, and cannot
+    # be provided for now.
+    streaming_transcription = "streaming_transcription"
+    # prerecorded transcription
+    prerecorded_transcription = "prerecorded_transcription"
+    # prerecorded translation
+    prerecorded_translation = "prerecorded_translation"
+    # describe images
+    vision_language_model = "vision_language_model"
+    #
+    speech_to_text = "speech_to_text"
+    #
+    text_to_speech = "text_to_speech"
+    #
+    video_generation = "video_generation"
+    #
+    text_to_image = "text_to_image"
+    #
+    undetermined = "undetermined"
+    #
+    text_to_3d = "text_to_3d"
+
+
+class SubscriptionStatusEnum(StrEnum):
+    active = "active"
+    cancelled = "cancelled"
+    expired = "expired"
+    pending = "pending"
+    trialing = "trialing"
+    failed = "failed"
+    paused = "paused"
+    incomplete = "incomplete"
+    incomplete_expired = "incomplete_expired"
+    unpaid = "unpaid"
+
+
+class TagEnum(StrEnum):
+    """
+    Allowed enums, currently not enforced.
+    """
+
+    # Service requires users to provide their own API key for access.
+    byop = "byop"
+
+
+class TimeWindowEnum(StrEnum):
+    second = "second"
+    minute = "minute"
+    hour = "hour"
+    day = "day"
+    month = "month"
+
+
+class UpstreamStatusEnum(StrEnum):
+    # uploading (not ready)
+    uploading = "uploading"
+    # upstream is ready to be used
+    ready = "ready"
+    # service is deprecated from upstream
+    deprecated = "deprecated"
+
+
+class Document(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    # fields that will be stored in backend database
+    #
+    title: str = Field(min_length=5, max_length=255, description="Document title")
+    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",
+    )
+
+
+class RateLimit(BaseModel):
+    """Store rate limiting rules for services."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Core rate limit definition
+    limit: int = Field(description="Maximum allowed in the time window")
+    unit: RateLimitUnitEnum = Field(description="What is being limited")
+    window: TimeWindowEnum = Field(description="Time window for the limit")
+
+    # Optional additional info
+    description: str | None = Field(default=None, max_length=255, description="Human-readable description")
+    burst_limit: int | None = Field(default=None, description="Short-term burst allowance")
+
+    # Status
+    is_active: bool = Field(default=True, description="Whether rate limit is active")
+
+
+class ServiceConstraints(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    # Usage Quotas & Billing
+    monthly_quota: int | None = Field(default=None, description="Monthly usage quota (requests, tokens, etc.)")
+    daily_quota: int | None = Field(default=None, description="Daily usage quota (requests, tokens, etc.)")
+    quota_unit: RateLimitUnitEnum | None = Field(default=None, description="Unit for quota limits")
+    quota_reset_cycle: QuotaResetCycleEnum | None = Field(default=None, description="How often quotas reset")
+    overage_policy: OveragePolicyEnum | None = Field(default=None, description="What happens when quota is exceeded")
+
+    # Authentication & Security
+    auth_methods: list[AuthMethodEnum] | None = Field(default=None, description="Supported authentication methods")
+    ip_whitelist_required: bool | None = Field(default=None, description="Whether IP whitelisting is required")
+    tls_version_min: str | None = Field(default=None, description="Minimum TLS version required")
+
+    # Request/Response Constraints
+    max_request_size_bytes: int | None = Field(default=None, description="Maximum request payload size in bytes")
+    max_response_size_bytes: int | None = Field(default=None, description="Maximum response payload size in bytes")
+    timeout_seconds: int | None = Field(default=None, description="Request timeout in seconds")
+    max_batch_size: int | None = Field(default=None, description="Maximum number of items in batch requests")
+
+    # Content & Model Restrictions
+    content_filters: list[ContentFilterEnum] | None = Field(
+        default=None, description="Active content filtering policies"
+    )
+    input_languages: list[str] | None = Field(default=None, description="Supported input languages (ISO 639-1 codes)")
+    output_languages: list[str] | None = Field(default=None, description="Supported output languages (ISO 639-1 codes)")
+    max_context_length: int | None = Field(default=None, description="Maximum context length in tokens")
+    region_restrictions: list[str] | None = Field(
+        default=None, description="Geographic restrictions (ISO country codes)"
+    )
+
+    # Availability & SLA
+    uptime_sla_percent: float | None = Field(default=None, description="Uptime SLA percentage (e.g., 99.9)")
+    response_time_sla_ms: int | None = Field(default=None, description="Response time SLA in milliseconds")
+    maintenance_windows: list[str] | None = Field(default=None, description="Scheduled maintenance windows")
+
+    # Concurrency & Connection Limits
+    max_concurrent_requests: int | None = Field(default=None, description="Maximum concurrent requests allowed")
+    connection_timeout_seconds: int | None = Field(default=None, description="Connection timeout in seconds")
+    max_connections_per_ip: int | None = Field(default=None, description="Maximum connections per IP address")
+
+
+class AccessInterface(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    access_method: AccessMethodEnum = Field(default=AccessMethodEnum.http, description="Type of access method")
+
+    api_endpoint: str = Field(max_length=500, description="API endpoint URL")
+
+    api_key: str | None = Field(default=None, max_length=2000, description="API key if required")
+
+    name: str | None = Field(default=None, max_length=100, description="Interface name")
+
+    description: str | None = Field(default=None, max_length=500, description="Interface description")
+
+    request_transformer: dict[RequestTransformEnum, dict[str, Any]] | None = Field(
+        default=None, description="Request transformation configuration"
+    )
+
+    documents: list[Document] | None = Field(
+        default=None, description="List of documents associated with the interface"
+    )
+
+    rate_limits: list[RateLimit] | None = Field(
+        default=None,
+        description="Rate limit",
+    )
+    constraint: ServiceConstraints | None = Field(default=None, description="Service constraints and conditions")
+    is_active: bool = Field(default=True, description="Whether interface is active")
+    is_primary: bool = Field(default=False, description="Whether this is the primary interface")
+    sort_order: int = Field(default=0, description="Display order")
+
+
+class Pricing(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    # Pricing tier name (Basic, Pro, Enterprise, etc.)
+    name: str | None = Field(default=None, description="Pricing tier name (e.g., Basic, Pro, Enterprise)")
+
+    description: str | None = Field(default=None, description="Pricing model description")
+
+    # Currency and description
+    currency: str | None = Field(default=None, description="Currency code (e.g., USD)")
+
+    unit: PricingUnitEnum = Field(description="Unit of pricing")
+
+    # Store price as JSON - flexible structure for different pricing models
+    price_data: dict[str, Any] = Field(
+        description="JSON containing price data (single price, tiered, usage-based, etc.)",
+    )
+
+    # Optional reference to upstream pricing
+    reference: str | None = Field(default=None, description="Reference URL to upstream pricing")

unitysvc_services/models/listing_v1.py

@@ -0,0 +1,72 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from unitysvc_services.models.base import (
+    AccessInterface,
+    Document,
+    ListingStatusEnum,
+    Pricing,
+)
+
+
+class ListingV1(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    #
+    # fields for business data collection and maintenance
+    #
+    schema_version: str = Field(default="listing_v1", description="Schema identifier", alias="schema")
+    time_created: datetime
+
+    #
+    # fields that will be stored in backend database
+    #
+    service_name: str | None = Field(
+        default=None,
+        description=(
+            "Name of the service (ServiceV1.name), optional if only one service is defined under the same directory."
+        ),
+    )
+
+    seller_name: str = Field(
+        description="Name of the seller offering this service listing"
+    )
+
+    # unique name for each provider, usually following upstream naming convention
+    # status of the service, public, deprecated etc
+    listing_status: ListingStatusEnum = Field(
+        default=ListingStatusEnum.unknown,
+        description="Operation status of the service",
+    )
+
+    #
+    # how to users access the service from upstream, which can include
+    #  - endpoint
+    #  - access_method
+    #  - code_examples
+    # multiple access interfaces can be provided, for example, if the service
+    # is available through multiple interfaces or service groups
+    user_access_interfaces: list[AccessInterface] = Field(description="Dictionary of user access interfaces")
+
+    #
+    # how upstream charges for their services, which can include
+    # a list of pricing models
+    #
+    user_price: Pricing | None = Field(description="Dictionary of pricing information")
+
+    documents: list[Document] | None = Field(
+        default=None,
+        description="List of documents associated with the listing (e.g. service level agreements)",
+    )
+    #
+    # schema for accepting user parameters for the service
+    #
+    user_parameters_schema: dict[str, Any] | None = Field(
+        default=None, description="Dictionary of user parameters schema"
+    )
+
+    user_parameters_ui_schema: dict[str, Any] | None = Field(
+        default=None, description="Dictionary of user parameters UI schema"
+    )

unitysvc_services/models/provider_v1.py

@@ -0,0 +1,53 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, HttpUrl
+
+from unitysvc_services.models.base import AccessInterface, Document
+
+
+class ProviderV1(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    #
+    # fields for business data collection and maintenance
+    #
+    schema_version: str = Field(default="provider_v1", description="Schema identifier", alias="schema")
+    time_created: datetime
+    # how to automatically populate service data, if available
+    services_populator: dict[str, Any] | None = None
+    # parameters for accessing service provider, which typically
+    # include "api_endpoint" and "api_key"
+    provider_access_info: AccessInterface = Field(description="Dictionary of upstream access interface")
+    #
+    # fields that will be stored in backend database
+    #
+
+    # name of the provider should be the same as directory name
+    name: str
+
+    # this field is added for convenience. It will be converted to
+    # documents during importing.
+    logo: str | HttpUrl | None = None
+
+    # this field is added for convenience. It will be converted to
+    # documents during importing.
+    terms_of_service: None | str | HttpUrl = Field(
+        default=None,
+        description="Either a path to a .md file or a URL to terms of service",
+    )
+
+    documents: list[Document] | None = Field(
+        default=None,
+        description="List of documents associated with the provider (e.g. logo)",
+    )
+    #
+    # fields for business operation purposes, not stored in backend database
+    #
+
+    # internal business data, usually not expose to users, and may not store
+    # in database
+    description: str | None = None
+    homepage: HttpUrl
+    contact_email: EmailStr
+    secondary_contact_email: EmailStr | None = None

unitysvc_services/models/seller_v1.py

@@ -0,0 +1,110 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, HttpUrl
+
+from unitysvc_services.models.base import Document, SellerTypeEnum
+
+
+class SellerV1(BaseModel):
+    """
+    Seller information for marketplace sellers.
+
+    Each repository can only have one seller.json file at the root of the data directory.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    #
+    # fields for business data collection and maintenance
+    #
+    schema_version: str = Field(default="seller_v1", description="Schema identifier", alias="schema")
+    time_created: datetime
+
+    #
+    # fields that will be stored in backend database
+    #
+
+    # Seller name must be unique and URL-friendly (lowercase, hyphens)
+    name: str = Field(
+        description="Unique seller identifier (URL-friendly, e.g., 'acme-corp', 'john-doe')",
+        min_length=2,
+        max_length=100,
+    )
+
+    # Display name for UI
+    display_name: str | None = Field(
+        default=None,
+        max_length=200,
+        description="Human-readable seller name (e.g., 'ACME Corporation', 'John Doe')",
+    )
+
+    # Seller type
+    seller_type: SellerTypeEnum = Field(
+        default=SellerTypeEnum.individual,
+        description="Type of seller entity",
+    )
+
+    # Contact information
+    contact_email: EmailStr = Field(description="Primary contact email for the seller")
+
+    secondary_contact_email: EmailStr | None = Field(default=None, description="Secondary contact email")
+
+    # Account manager
+    account_manager: str | None = Field(
+        default=None,
+        max_length=100,
+        description="Email or username of the user managing this seller account",
+    )
+
+    homepage: HttpUrl | None = Field(default=None, description="Seller's homepage URL")
+
+    # Business information
+    description: str | None = Field(
+        default=None,
+        max_length=1000,
+        description="Brief description of the seller",
+    )
+
+    business_registration: str | None = Field(
+        default=None,
+        max_length=100,
+        description="Business registration number (if organization)",
+    )
+
+    tax_id: str | None = Field(
+        default=None,
+        max_length=100,
+        description="Tax identification number (EIN, VAT, etc.)",
+    )
+
+    # Stripe Connect integration
+    stripe_connect_id: str | None = Field(
+        default=None,
+        max_length=255,
+        description="Stripe Connect account ID for payment processing",
+    )
+
+    # Documents (logo, business docs, etc.)
+    # This field is added for convenience. It will be converted to
+    # documents during importing.
+    logo: str | HttpUrl | None = None
+
+    documents: list[Document] | None = Field(
+        default=None,
+        description="List of documents associated with the seller (e.g. business registration, tax documents)",
+    )
+
+    #
+    # fields for business operation purposes
+    #
+
+    # Status flags - these would typically be set by the backend
+    is_active: bool = Field(
+        default=True,
+        description="Whether the seller is active on the marketplace",
+    )
+
+    is_verified: bool = Field(
+        default=False,
+        description="Whether the seller has been verified (KYC/business verification)",
+    )

unitysvc_services/models/service_v1.py

@@ -0,0 +1,80 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl
+
+from unitysvc_services.models.base import (
+    AccessInterface,
+    Document,
+    Pricing,
+    ServiceTypeEnum,
+    TagEnum,
+    UpstreamStatusEnum,
+)
+
+
+class ServiceV1(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    #
+    # fields for business data collection and maintenance
+    #
+    schema_version: str = Field(default="service_v1", description="Schema identifier", alias="schema")
+    time_created: datetime
+
+    #
+    # fields that will be stored in backend database
+    #
+    # unique name for each provider, usually following upstream naming convention
+    name: str
+    # type of service to group services
+    service_type: ServiceTypeEnum
+    # common display name for the service, allowing across provider linking
+    display_name: str
+    # version of the service, this, combined with display_name, allowing across provider linking
+    # of specific services, despite of provider internal naming conventions. Note that
+    # same display_name and version does not guarantee the same service (e.g. context window
+    # can be different)
+    version: str | None
+
+    # description of service, mandatory
+    description: str
+
+    # this field is added for convenience. It will be converted to
+    # documents during importing.
+    logo: str | HttpUrl | None = None
+
+    # Short elevator pitch or description for the service
+    tagline: str | None = None
+
+    # Tags for the service, e.g., bring your own API key
+    tags: list[TagEnum] | None = Field(
+        default=None,
+        description="List of tags for the service, e.g., bring your own API key",
+    )
+
+    # status of the service, public, deprecated etc
+    upstream_status: UpstreamStatusEnum = Field(
+        default=UpstreamStatusEnum.ready,
+        description="Status of the service from upstream service provider",
+    )
+
+    # static information from upstream, each service_type will have a
+    # set of mandatory fields
+    details: dict[str, Any] = Field(description="Dictionary of static features and information")
+
+    documents: list[Document] | None = Field(
+        default=None,
+        description="List of documents associated with the service (e.g. tech spec.)",
+    )
+    #
+    # how to access the service from upstream, which can include
+    #  - endpoint
+    #  - apikey
+    #  - access_method
+    upstream_access_interface: AccessInterface = Field(description="Dictionary of upstream access interface")
+    #
+    # how upstream charges for their services, which can include
+    # a list of pricing models
+    #
+    upstream_price: Pricing | None = Field(description="List of pricing information")