unitysvc-services 0.1.10__tar.gz → 0.1.11__tar.gz

{unitysvc_services-0.1.10/src/unitysvc_services.egg-info → unitysvc_services-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-services
-Version: 0.1.10
+Version: 0.1.11
 Summary: SDK for digital service providers on UnitySVC
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>

{unitysvc_services-0.1.10 → unitysvc_services-0.1.11}/docs/cli-reference.md

@@ -34,92 +34,212 @@ usvc [OPTIONS] COMMAND [ARGS]...
 
 ## init - Initialize Data Files
 
-Create new data file skeletons from schemas.
+Create new data files through **interactive prompts** or by **copying from existing data**.
 
-### init offering
+All `init` commands support two modes:
+
+1. **Interactive Mode** (default): Prompts you step-by-step for field values with validation and smart defaults
+2. **Copy Mode**: Uses `--source` to copy structure from an existing directory
+
+### Key Features
+
+**Interactive Mode Features:**
+- ✅ **Auto-discovery**: Automatically detects seller and service names from existing files
+- ✅ **Validation**: Email format, URI validation, integer checks, and more
+- ✅ **Smart defaults**: Computed defaults based on previous inputs or filesystem discovery
+- ✅ **Skip optional fields**: Press Enter to skip any optional field
+- ✅ **Complex objects**: Add documents and pricing information interactively
+- ✅ **File validation**: Checks document file paths exist before saving
+- ✅ **Cancellation**: Press Ctrl+C to cancel at any time
+
+### init seller
 
-Create a new service offering skeleton.
+Create a new seller file interactively or copy from existing.
 
 ```bash
-unitysvc_services init offering <name> [OPTIONS]
+usvc init seller <name> [OPTIONS]
 ```
 
 **Arguments:**
 
--   `<name>` - Name of the service offering (required)
+-   `<name>` - Seller identifier (URL-friendly name)
 
 **Options:**
 
--   `--format {json|toml}` - Output format (default: toml)
--   `--source PATH` - Source directory to copy from
--   `--output PATH` - Output directory (default: ./data)
+-   `--format {json|toml}` - Output format (default: json)
+-   `--source PATH` - Copy from existing seller directory (skips interactive prompts)
+-   `--output-dir PATH` - Output directory (default: ./data)
+
+**Interactive Mode** prompts for:
+
+- **Basic Information**: seller type (individual/organization/partnership/corporation), display name, description
+- **Contact Information**: primary email, secondary email, homepage URL
+- **Additional Details**: business registration, tax ID, account manager
+- **Status & Verification**: status (active/pending/disabled), KYC verification
 
 **Examples:**
 
 ```bash
-# Create TOML offering
-usvc init offering my-service
+# Interactive mode - will prompt for all fields
+usvc init seller acme-corp
 
-# Create JSON offering
-usvc init offering my-service --format json
+# Interactive mode with JSON format
+usvc init seller acme-corp --format json
 
-# Copy from existing
-usvc init offering new-service --source ./data/old-service
+# Copy from existing seller
+usvc init seller new-seller --source ./data/acme-corp
 ```
 
-### init listing
+### init provider
 
-Create a new service listing skeleton.
+Create a new provider file interactively or copy from existing.
 
 ```bash
-unitysvc_services init listing <name> [OPTIONS]
+usvc init provider <name> [OPTIONS]
 ```
 
 **Arguments:**
 
--   `<name>` - Name of the service listing (required)
+-   `<name>` - Provider identifier (e.g., 'openai', 'fireworks')
 
 **Options:**
 
--   `--format {json|toml}` - Output format (default: toml)
--   `--source PATH` - Source directory to copy from
--   `--output PATH` - Output directory (default: ./data)
+-   `--format {json|toml}` - Output format (default: json)
+-   `--source PATH` - Copy from existing provider directory
+-   `--output-dir PATH` - Output directory (default: ./data)
 
-### init provider
+**Interactive Mode** prompts for:
+
+- **Basic Information**: display name, description
+- **Contact & Web**: contact email, secondary email, homepage URL
+- **Provider Access**: API endpoint, API key, access method (http/websocket/grpc)
+- **Status**: provider status
+- **Service Population** (optional): Command to auto-generate service offerings via `usvc populate`
+
+**Examples:**
+
+```bash
+# Interactive mode
+usvc init provider openai
+
+# Copy mode
+usvc init provider new-provider --source ./data/openai
+```
+
+**Auto-Population Feature:**
+
+If you enable the services populator, you can create a script that automatically generates service offerings:
+
+```bash
+# During init, answer "yes" to "Enable automated service population?"
+# Provide command: python scripts/populate_openai.py
+
+# Later, run populate to generate services
+usvc populate
+```
+
+### init offering
 
-Create a new provider skeleton.
+Create a new service offering file interactively or copy from existing.
 
 ```bash
-unitysvc_services init provider <name> [OPTIONS]
+usvc init offering <name> [OPTIONS]
 ```
 
 **Arguments:**
 
--   `<name>` - Provider name (required)
+-   `<name>` - Service name (e.g., 'gpt-4', 'llama-3-1-405b')
 
 **Options:**
 
--   `--format {json|toml}` - Output format (default: toml)
--   `--source PATH` - Source directory to copy from
--   `--output PATH` - Output directory (default: ./data)
+-   `--format {json|toml}` - Output format (default: json)
+-   `--source PATH` - Copy from existing offering directory
+-   `--output-dir PATH` - Output directory (default: ./data)
 
-### init seller
+**Interactive Mode** prompts for:
+
+- **Basic Information**: service name, display name, version, description
+- **Classification**: service type (llm/embedding/vision/audio/image/video), upstream status
+- **Upstream Access Interface**: API endpoint, API key, documents (optional)
+- **Upstream Pricing** (optional): pricing unit, tier name, currency, price structure
+- **Additional Information**: tagline
+
+**Pricing Structures:**
+
+When adding pricing, you can choose from three types:
+
+1. **Simple**: `{"amount": 10.00}`
+2. **Input/Output** (for LLMs): `{"input": 5.00, "output": 15.00}`
+3. **Custom JSON**: `{"base": 5.00, "per_unit": 0.001}` or any custom structure
+
+**Examples:**
+
+```bash
+# Interactive mode - will create data/gpt-4/service.json
+usvc init offering gpt-4
 
-Create a new seller skeleton.
+# Interactive with TOML format
+usvc init offering gpt-4 --format toml
+
+# Copy from existing offering
+usvc init offering gpt-4-turbo --source ./data/gpt-4
+```
+
+### init listing
+
+Create a new service listing file interactively or copy from existing.
 
 ```bash
-unitysvc_services init seller <name> [OPTIONS]
+usvc init listing <name> [OPTIONS]
 ```
 
 **Arguments:**
 
--   `<name>` - Seller name (required)
+-   `<name>` - Listing identifier
 
 **Options:**
 
--   `--format {json|toml}` - Output format (default: toml)
--   `--source PATH` - Source directory to copy from
--   `--output PATH` - Output directory (default: ./data)
+-   `--format {json|toml}` - Output format (default: json)
+-   `--source PATH` - Copy from existing listing directory
+-   `--output-dir PATH` - Output directory (default: ./data)
+
+**Interactive Mode** prompts for:
+
+- **Basic Information**: service name (auto-detected), listing name, display name
+- **Seller Information**: seller name (auto-detected from seller.json)
+- **Status**: listing status (unknown/upstream_ready/downstream_ready/ready/in_service/deprecated)
+- **Documents** (optional): Add multiple documents interactively
+
+**Auto-Discovery:**
+
+The listing workflow automatically discovers:
+- **seller_name**: Searches ./data, ./, ../data, ../ for seller.json/seller.toml
+- **service_name**: Searches ./, ../ for service.json/service.toml
+
+This means you don't need to manually type names - they're auto-filled!
+
+**Document Support:**
+
+When adding documents, you can specify:
+- **Required**: title, MIME type, category
+- **Optional**: description, file path (relative to listing dir), external URL, public flag
+- **Validation**: File existence checks, at least one of file_path or external_URL required
+
+**Examples:**
+
+```bash
+# Interactive mode from project root
+usvc init listing premium-gpt4
+# Auto-detects seller from ./data/seller.json
+
+# From inside service directory
+cd data/my-provider/gpt-4
+usvc init listing standard
+# Auto-detects service from ./service.json and seller from ../../data/seller.json
+
+# Copy mode
+usvc init listing new-listing --source ./data/old-listing
+```
 
 ## list - List Local Files
 
@@ -297,6 +417,7 @@ unitysvc_services publish COMMAND [OPTIONS]
 **Common Options:**
 
 -   `--data-path, -d PATH` - Data directory path (default: current directory)
+-   `--dryrun` - Preview what would be created/updated without making actual changes
 
 **Required Environment Variables:**
 
@@ -314,8 +435,80 @@ usvc publish --data-path ./data
 
 # Publish only providers
 usvc publish providers
+
+# Preview changes before publishing (dryrun mode)
+usvc publish --dryrun
+
+# Preview specific type
+usvc publish providers --dryrun
+```
+
+**Dryrun Mode:**
+
+The `--dryrun` option allows you to preview what would happen during publish without making actual changes to the backend. This is useful for:
+
+- Verifying which entities would be created vs updated
+- Checking that all dependencies exist before publishing
+- Confirming changes before committing them
+
+In dryrun mode:
+- No actual data is sent to the backend
+- Backend returns what action would be taken (create/update)
+- Missing dependencies are reported but don't cause errors
+- Summary shows what would happen if published
+
+**Dryrun Output Format:**
+
+Dryrun mode displays a summary table showing what actions would be taken:
+
+```bash
+$ usvc publish --dryrun
+
+Publishing Sellers...
+╭──────────┬─────────┬─────────┬────────╮
+│ Type     │ Created │ Updated │ Failed │
+├──────────┼─────────┼─────────┼────────┤
+│ Sellers  │ 1       │ 0       │        │
+╰──────────┴─────────┴─────────┴────────╯
+
+Publishing Providers...
+╭───────────┬─────────┬─────────┬────────╮
+│ Type      │ Created │ Updated │ Failed │
+├───────────┼─────────┼─────────┼────────┤
+│ Providers │ 2       │ 0       │        │
+╰───────────┴─────────┴─────────┴────────╯
+
+Publishing Offerings...
+╭───────────┬─────────┬─────────┬────────╮
+│ Type      │ Created │ Updated │ Failed │
+├───────────┼─────────┼─────────┼────────┤
+│ Offerings │ 5       │ 3       │        │
+╰───────────┴─────────┴─────────┴────────╯
+
+Publishing Listings...
+╭──────────┬─────────┬─────────┬────────╮
+│ Type     │ Created │ Updated │ Failed │
+├──────────┼─────────┼─────────┼────────┤
+│ Listings │ 8       │ 0       │        │
+╰──────────┴─────────┴─────────┴────────╯
+
+Summary
+╭───────────┬─────────┬─────────┬────────╮
+│ Type      │ Created │ Updated │ Failed │
+├───────────┼─────────┼─────────┼────────┤
+│ Sellers   │ 1       │ 0       │        │
+│ Providers │ 2       │ 0       │        │
+│ Offerings │ 5       │ 3       │        │
+│ Listings  │ 8       │ 0       │        │
+╰───────────┴─────────┴─────────┴────────╯
 ```
 
+Notes:
+- Created: Entities that would be created (don't exist on backend)
+- Updated: Entities that would be updated (exist but have changes)
+- Failed: Entities that encountered errors (shown in red if > 0, blank if 0)
+- Blank cells indicate zero count for easier reading
+
 **Publishing Order (when publishing all):**
 
 1. Sellers - Must exist before listings
@@ -334,6 +527,7 @@ unitysvc_services publish providers [OPTIONS]
 **Options:**
 
 -   `--data-path, -d PATH` - File or directory path (default: current directory)
+-   `--dryrun` - Preview what would be created/updated without making actual changes
 
 **Examples:**
 
@@ -346,6 +540,9 @@ usvc publish providers --data-path ./data/my-provider/provider.json
 
 # Publish from custom directory
 usvc publish providers --data-path ./custom-data
+
+# Preview provider changes
+usvc publish providers --dryrun
 ```
 
 ### publish sellers
@@ -359,6 +556,7 @@ unitysvc_services publish sellers [OPTIONS]
 **Options:**
 
 -   `--data-path, -d PATH` - File or directory path (default: current directory)
+-   `--dryrun` - Preview what would be created/updated without making actual changes
 
 ### publish offerings
 
@@ -371,6 +569,7 @@ unitysvc_services publish offerings [OPTIONS]
 **Options:**
 
 -   `--data-path, -d PATH` - File or directory path (default: current directory)
+-   `--dryrun` - Preview what would be created/updated without making actual changes
 
 ### publish listings
 
@@ -383,6 +582,7 @@ unitysvc_services publish listings [OPTIONS]
 **Options:**
 
 -   `--data-path, -d PATH` - File or directory path (default: current directory)
+-   `--dryrun` - Preview what would be created/updated without making actual changes
 
 **Publishing Order:**
 
@@ -739,6 +939,76 @@ usvc --show-completion
 
 ## Common Workflows
 
+### Creating Data from Scratch (Interactive)
+
+Create a complete data structure interactively:
+
+```bash
+# 1. Create seller (will prompt for contact info, etc.)
+usvc init seller acme-corp
+# Follow prompts: enter email, homepage, etc.
+
+# 2. Create provider (will prompt for API endpoint, etc.)
+cd data/acme-corp
+usvc init provider openai
+# Follow prompts: API endpoint, contact, optional services_populator
+
+# 3. Create service offering (will prompt for service details)
+cd openai
+usvc init offering gpt-4
+# Follow prompts: description, upstream API, optional pricing
+
+# 4. Create listing (auto-detects seller and service!)
+cd gpt-4
+usvc init listing standard
+# Auto-fills seller from data/seller.json and service from service.json
+# Add optional documents
+
+# 5. Validate everything
+cd ../../../..  # Back to project root
+usvc validate
+
+# 6. Format files
+usvc format
+
+# 7. Preview before publishing
+cd data
+usvc publish --dryrun
+
+# 8. Publish if everything looks good
+usvc publish
+```
+
+**Note**: The interactive prompts include:
+- ✅ Auto-discovery of seller/service names
+- ✅ Validation of emails, URLs, and required fields
+- ✅ Smart defaults (e.g., display name from ID)
+- ✅ Optional document and pricing support
+
+### Copying from Existing Data
+
+Quickly create new data by copying from existing structures:
+
+```bash
+# Copy an existing service offering to create a similar one
+usvc init offering gpt-4-turbo --source ./data/acme-corp/openai/gpt-4
+
+# Copy a listing
+usvc init listing premium --source ./data/acme-corp/openai/gpt-4/standard
+
+# Copy a provider
+usvc init provider anthropic --source ./data/acme-corp/openai
+
+# Copy a seller
+usvc init seller new-seller --source ./data/acme-corp
+```
+
+**Benefits of copy mode:**
+- 🚀 Skip interactive prompts for similar services
+- 📋 Preserves structure and documents
+- ⚡ Faster than manual entry for bulk creation
+- 🔄 Updates names and IDs automatically
+
 ### Full Publish Flow
 
 ```bash
@@ -750,8 +1020,11 @@ export UNITYSVC_API_KEY=your-key
 usvc validate
 usvc format
 
-# Publish all (handles order automatically)
+# Preview changes before publishing (recommended)
 cd data
+usvc publish --dryrun
+
+# If preview looks good, publish all (handles order automatically)
 usvc publish
 
 # Verify
@@ -767,6 +1040,9 @@ usvc update offering --name my-service --status ready
 # Validate
 usvc validate
 
+# Preview changes
+usvc publish offerings --dryrun
+
 # Publish changes
 usvc publish offerings
 ```
@@ -781,8 +1057,11 @@ usvc populate
 usvc validate
 usvc format
 
-# Publish all
+# Preview generated data
 cd data
+usvc publish --dryrun
+
+# Publish all
 usvc publish
 ```
 

{unitysvc_services-0.1.10 → unitysvc_services-0.1.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitysvc-services"
-version = "0.1.10"
+version = "0.1.11"
 description = "SDK for digital service providers on UnitySVC"
 readme = "README.md"
 authors = [{ name = "Bo Peng", email = "bo.peng@unitysvc.com" }]

{unitysvc_services-0.1.10 → unitysvc_services-0.1.11}/src/unitysvc_services/api.py

@@ -88,7 +88,7 @@ class UnitySvcAPI:
             stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=30.0)
 
             if proc.returncode != 0:
-                error_msg = stderr.decode().strip() if stderr else "Curl command failed"
+                error_msg = stderr.decode().strip() if stderr else "curl command failed"
                 raise RuntimeError(f"Curl error: {error_msg}")
 
             # Parse response: last line is status code, rest is body
@@ -165,7 +165,7 @@ class UnitySvcAPI:
             stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=30.0)
 
             if proc.returncode != 0:
-                error_msg = stderr.decode().strip() if stderr else "Curl command failed"
+                error_msg = stderr.decode().strip() if stderr else "curl command failed"
                 raise RuntimeError(f"Curl error: {error_msg}")
 
             # Parse response: last line is status code, rest is body