unitysvc-services 0.1.1__py3-none-any.whl → 0.1.5__py3-none-any.whl

unitysvc_services/models/base.py

@@ -1,3 +1,4 @@
+import re
 from enum import StrEnum
 from typing import Any
 
@@ -210,6 +211,7 @@ class ProviderStatusEnum(StrEnum):
     """Provider status enum."""
 
     active = "active"
+    pending = "pending"
     disabled = "disabled"
     incomplete = "incomplete"  # Provider information is incomplete
 
@@ -218,6 +220,7 @@ class SellerStatusEnum(StrEnum):
     """Seller status enum."""
 
     active = "active"
+    pending = "pending"
     disabled = "disabled"
     incomplete = "incomplete"  # Seller information is incomplete
 
@@ -228,16 +231,10 @@ class Document(BaseModel):
     # 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"
-    )
+    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"
-    )
+    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",
@@ -258,6 +255,18 @@ class Document(BaseModel):
         default=False,
         description="Whether document is publicly accessible without authentication",
     )
+    requirements: list[str] | None = Field(
+        default=None,
+        description="Required packages/modules for running this code example (e.g., ['openai', 'httpx'])",
+    )
+    expect: str | None = Field(
+        default=None,
+        max_length=500,
+        description=(
+            "Expected output substring for code example validation. "
+            "If specified, test passes only if stdout contains this string."
+        ),
+    )
 
 
 class RateLimit(BaseModel):
@@ -271,12 +280,8 @@ class RateLimit(BaseModel):
     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"
-    )
+    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")
@@ -286,105 +291,57 @@ 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"
-    )
+    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"
-    )
+    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"
-    )
+    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"
-    )
+    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"
-    )
+    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"
-    )
+    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"
-    )
+    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"
-    )
+    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"
-    )
+    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"
@@ -398,13 +355,9 @@ class AccessInterface(BaseModel):
         default=None,
         description="Rate limit",
     )
-    constraint: ServiceConstraints | None = Field(
-        default=None, description="Service constraints and conditions"
-    )
+    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"
-    )
+    is_primary: bool = Field(default=False, description="Whether this is the primary interface")
     sort_order: int = Field(default=0, description="Display order")
 
 
@@ -412,13 +365,9 @@ 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)"
-    )
+    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"
-    )
+    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)")
@@ -431,6 +380,124 @@ class Pricing(BaseModel):
     )
 
     # Optional reference to upstream pricing
-    reference: str | None = Field(
-        default=None, description="Reference URL to upstream pricing"
-    )
+    reference: str | None = Field(default=None, description="Reference URL to upstream pricing")
+
+
+def validate_name(name: str, entity_type: str, display_name: str | None = None, *, allow_slash: bool = False) -> str:
+    """
+    Validate that a name field uses valid identifiers.
+
+    Name format rules:
+    - Only letters (upper/lowercase), numbers, dots, dashes, and underscores allowed
+    - If allow_slash=True, slashes are also allowed for hierarchical names
+    - Must start and end with alphanumeric characters (not special characters)
+    - Cannot have consecutive slashes (when allow_slash=True)
+    - Cannot be empty
+
+    Args:
+        name: The name value to validate
+        entity_type: Type of entity (provider, seller, service, listing) for error messages
+        display_name: Optional display name to suggest a valid name from
+        allow_slash: Whether to allow slashes for hierarchical names (default: False)
+
+    Returns:
+        The validated name (unchanged if valid)
+
+    Raises:
+        ValueError: If the name doesn't match the required pattern
+
+    Examples:
+        Without slashes (providers, sellers):
+            - name='amazon-bedrock' or name='Amazon-Bedrock'
+            - name='fireworks.ai' or name='Fireworks.ai'
+            - name='llama-3.1' or name='Llama-3.1'
+
+        With slashes (services, listings):
+            - name='gpt-4' or name='GPT-4'
+            - name='models/gpt-4' or name='models/GPT-4'
+            - name='black-forest-labs/FLUX.1-dev'
+            - name='api/v1/completion'
+    """
+    # Build pattern based on allow_slash parameter
+    if allow_slash:
+        # Pattern: starts with alphanumeric, can contain alphanumeric/dot/dash/underscore/slash, ends with alphanumeric
+        name_pattern = r"^[a-zA-Z0-9]([a-zA-Z0-9._/-]*[a-zA-Z0-9])?$"
+        allowed_chars = "letters, numbers, dots, dashes, underscores, and slashes"
+    else:
+        # Pattern: starts with alphanumeric, can contain alphanumeric/dot/dash/underscore, ends with alphanumeric
+        name_pattern = r"^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$"
+        allowed_chars = "letters, numbers, dots, dashes, and underscores"
+
+    # Check for consecutive slashes if slashes are allowed
+    if allow_slash and "//" in name:
+        raise ValueError(f"Invalid {entity_type} name '{name}'. Name cannot contain consecutive slashes.")
+
+    if not re.match(name_pattern, name):
+        # Build helpful error message
+        error_msg = (
+            f"Invalid {entity_type} name '{name}'. "
+            f"Name must contain only {allowed_chars}. "
+            f"It must start and end with an alphanumeric character.\n"
+        )
+
+        # Suggest a valid name based on display_name if available
+        if display_name:
+            suggested_name = suggest_valid_name(display_name, allow_slash=allow_slash)
+            if suggested_name and suggested_name != name:
+                error_msg += f"  Suggestion: Set name='{suggested_name}' and display_name='{display_name}'\n"
+
+        # Add appropriate examples based on allow_slash
+        if allow_slash:
+            error_msg += (
+                "  Examples:\n"
+                "    - name='gpt-4' or name='GPT-4'\n"
+                "    - name='models/gpt-4' or name='models/GPT-4'\n"
+                "    - name='black-forest-labs/FLUX.1-dev'\n"
+                "    - name='api/v1/completion'"
+            )
+        else:
+            error_msg += (
+                "  Note: Use 'display_name' field for brand names with spaces and special characters.\n"
+                "  Examples:\n"
+                "    - name='amazon-bedrock' or name='Amazon-Bedrock'\n"
+                "    - name='fireworks.ai' or name='Fireworks.ai'\n"
+                "    - name='llama-3.1' or name='Llama-3.1'"
+            )
+
+        raise ValueError(error_msg)
+
+    return name
+
+
+def suggest_valid_name(display_name: str, *, allow_slash: bool = False) -> str:
+    """
+    Suggest a valid name based on a display name.
+
+    Replaces invalid characters with hyphens and ensures it follows the naming rules.
+    Preserves the original case.
+
+    Args:
+        display_name: The display name to convert
+        allow_slash: Whether to allow slashes for hierarchical names (default: False)
+
+    Returns:
+        A suggested valid name
+    """
+    if allow_slash:
+        # Replace characters that aren't alphanumeric, dot, dash, underscore, or slash with hyphens
+        suggested = re.sub(r"[^a-zA-Z0-9._/-]+", "-", display_name)
+        # Remove leading/trailing special characters
+        suggested = suggested.strip("._/-")
+        # Collapse multiple consecutive dashes
+        suggested = re.sub(r"-+", "-", suggested)
+        # Remove consecutive slashes
+        suggested = re.sub(r"/+", "/", suggested)
+    else:
+        # Replace characters that aren't alphanumeric, dot, dash, or underscore with hyphens
+        suggested = re.sub(r"[^a-zA-Z0-9._-]+", "-", display_name)
+        # Remove leading/trailing dots, dashes, or underscores
+        suggested = suggested.strip("._-")
+        # Collapse multiple consecutive dashes
+        suggested = re.sub(r"-+", "-", suggested)
+
+    return suggested

unitysvc_services/models/listing_v1.py

@@ -1,13 +1,14 @@
 from datetime import datetime
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from unitysvc_services.models.base import (
     AccessInterface,
     Document,
     ListingStatusEnum,
     Pricing,
+    validate_name,
 )
 
 
@@ -17,9 +18,7 @@ class ListingV1(BaseModel):
     #
     # fields for business data collection and maintenance
     #
-    schema_version: str = Field(
-        default="listing_v1", description="Schema identifier", alias="schema"
-    )
+    schema_version: str = Field(default="listing_v1", description="Schema identifier", alias="schema")
     time_created: datetime
 
     #
@@ -32,8 +31,19 @@ class ListingV1(BaseModel):
         ),
     )
 
-    seller_name: str | None = Field(
-        default=None, description="Name of the seller offering this service listing"
+    seller_name: str | None = Field(default=None, description="Name of the seller offering this service listing")
+
+    name: str | None = Field(
+        default=None,
+        max_length=255,
+        description="Name identifier for the service listing, default to filename",
+    )
+
+    # Display name for UI (human-readable 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')",
     )
 
     # unique name for each provider, usually following upstream naming convention
@@ -50,9 +60,7 @@ class ListingV1(BaseModel):
     #  - 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"
-    )
+    user_access_interfaces: list[AccessInterface] = Field(description="Dictionary of user access interfaces")
 
     #
     # how upstream charges for their services, which can include
@@ -74,3 +82,11 @@ class ListingV1(BaseModel):
     user_parameters_ui_schema: dict[str, Any] | None = Field(
         default=None, description="Dictionary of user parameters UI schema"
     )
+
+    @field_validator("name")
+    @classmethod
+    def validate_name_format(cls, v: str | None) -> str | None:
+        """Validate that listing name uses valid identifiers (allows slashes for hierarchical names)."""
+        if v is None:
+            return v
+        return validate_name(v, "listing", allow_slash=True)

unitysvc_services/models/provider_v1.py

@@ -1,9 +1,9 @@
 from datetime import datetime
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, EmailStr, Field, HttpUrl
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, HttpUrl, field_validator
 
-from unitysvc_services.models.base import AccessInterface, Document, ProviderStatusEnum
+from unitysvc_services.models.base import AccessInterface, Document, ProviderStatusEnum, validate_name
 
 
 class ProviderV1(BaseModel):
@@ -12,17 +12,13 @@ class ProviderV1(BaseModel):
     #
     # fields for business data collection and maintenance
     #
-    schema_version: str = Field(
-        default="provider_v1", description="Schema identifier", alias="schema"
-    )
+    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"
-    )
+    provider_access_info: AccessInterface = Field(description="Dictionary of upstream access interface")
     #
     # fields that will be stored in backend database
     #
@@ -30,6 +26,13 @@ class ProviderV1(BaseModel):
     # name of the provider should be the same as directory name
     name: str
 
+    # Display name for UI (human-readable brand name)
+    display_name: str | None = Field(
+        default=None,
+        max_length=200,
+        description="Human-readable provider name (e.g., 'Amazon Bedrock', 'Fireworks.ai')",
+    )
+
     # this field is added for convenience. It will be converted to
     # documents during importing.
     logo: str | HttpUrl | None = None
@@ -61,3 +64,11 @@ class ProviderV1(BaseModel):
         default=ProviderStatusEnum.active,
         description="Provider status: active, disabled, or incomplete",
     )
+
+    @field_validator("name")
+    @classmethod
+    def validate_name_format(cls, v: str) -> str:
+        """Validate that provider name uses URL-safe identifiers."""
+        # Note: display_name is not available in the validator context for suggesting
+        # Display name will be shown in error if user provides it
+        return validate_name(v, "provider", allow_slash=False)

unitysvc_services/models/seller_v1.py

@@ -1,8 +1,8 @@
 from datetime import datetime
 
-from pydantic import BaseModel, ConfigDict, EmailStr, Field, HttpUrl
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, HttpUrl, field_validator
 
-from unitysvc_services.models.base import Document, SellerStatusEnum, SellerTypeEnum
+from unitysvc_services.models.base import Document, SellerStatusEnum, SellerTypeEnum, validate_name
 
 
 class SellerV1(BaseModel):
@@ -17,9 +17,7 @@ class SellerV1(BaseModel):
     #
     # fields for business data collection and maintenance
     #
-    schema_version: str = Field(
-        default="seller_v1", description="Schema identifier", alias="schema"
-    )
+    schema_version: str = Field(default="seller_v1", description="Schema identifier", alias="schema")
     time_created: datetime
 
     #
@@ -49,9 +47,7 @@ class SellerV1(BaseModel):
     # 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"
-    )
+    secondary_contact_email: EmailStr | None = Field(default=None, description="Secondary contact email")
 
     # Account manager
     account_manager: str | None = Field(
@@ -112,3 +108,9 @@ class SellerV1(BaseModel):
         default=False,
         description="Whether the seller has been verified (KYC/business verification)",
     )
+
+    @field_validator("name")
+    @classmethod
+    def validate_name_format(cls, v: str) -> str:
+        """Validate that seller name uses URL-safe identifiers."""
+        return validate_name(v, "seller", allow_slash=False)

unitysvc_services/models/service_v1.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field, HttpUrl
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, field_validator
 
 from unitysvc_services.models.base import (
     AccessInterface,
@@ -10,6 +10,7 @@ from unitysvc_services.models.base import (
     ServiceTypeEnum,
     TagEnum,
     UpstreamStatusEnum,
+    validate_name,
 )
 
 
@@ -78,3 +79,9 @@ class ServiceV1(BaseModel):
     # a list of pricing models
     #
     upstream_price: Pricing | None = Field(description="List of pricing information")
+
+    @field_validator("name")
+    @classmethod
+    def validate_name_format(cls, v: str) -> str:
+        """Validate that service name uses valid identifiers (allows slashes for hierarchical names)."""
+        return validate_name(v, "service", allow_slash=True)

unitysvc_services/populate.py

@@ -9,6 +9,7 @@ from pathlib import Path
 import typer
 from rich.console import Console
 
+from .format_data import format_data
 from .utils import find_files_by_schema
 
 app = typer.Typer(help="Populate services")
@@ -19,7 +20,7 @@ console = Console()
 def populate(
     data_dir: Path | None = typer.Argument(
         None,
-        help="Directory containing provider data files (default: ./data or UNITYSVC_DATA_DIR env var)",
+        help="Directory containing provider data files (default: current directory)",
     ),
     provider_name: str | None = typer.Option(
         None,
@@ -38,14 +39,13 @@ def populate(
 
     This command scans provider files for 'services_populator' configuration and executes
     the specified commands with environment variables from 'provider_access_info'.
+
+    After successful execution, automatically runs formatting on all generated files to
+    ensure they conform to the format specification (equivalent to running 'usvc format').
     """
     # Set data directory
     if data_dir is None:
-        data_dir_str = os.getenv("UNITYSVC_DATA_DIR")
-        if data_dir_str:
-            data_dir = Path(data_dir_str)
-        else:
-            data_dir = Path.cwd() / "data"
+        data_dir = Path.cwd()
 
     if not data_dir.is_absolute():
         data_dir = Path.cwd() / data_dir
@@ -182,5 +182,19 @@ def populate(
     console.print(f"  [yellow]⏭️  Skipped: {total_skipped}[/yellow]")
     console.print(f"  [red]✗ Failed: {total_failed}[/red]")
 
+    # Format generated files if any populate scripts executed successfully
+    if total_executed > 0 and not dry_run:
+        console.print("\n" + "=" * 50)
+        console.print("[bold cyan]Formatting generated files...[/bold cyan]")
+        console.print("[dim]Running automatic formatting to ensure data conforms to format specification[/dim]\n")
+
+        try:
+            # Run format command on the data directory
+            format_data(data_dir)
+            console.print("\n[green]✓ Formatting completed successfully[/green]")
+        except Exception as e:
+            console.print(f"\n[yellow]⚠ Warning: Formatting failed: {e}[/yellow]")
+            console.print("[dim]You may want to run 'usvc format' manually to fix formatting issues[/dim]")
+
     if total_failed > 0:
         raise typer.Exit(code=1)