unitysvc-services 0.1.4__tar.gz → 0.1.6__tar.gz

{unitysvc_services-0.1.4/src/unitysvc_services.egg-info → unitysvc_services-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-services
-Version: 0.1.4
+Version: 0.1.6
 Summary: SDK for digital service providers on UnitySVC
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>
@@ -40,22 +40,23 @@ Requires-Dist: mkdocs-material; extra == "docs"
 Requires-Dist: mkdocs-autorefs; extra == "docs"
 Dynamic: license-file
 
-# UnitySVC Provider SDK
+# UnitySVC Services SDK
 
 ![PyPI version](https://img.shields.io/pypi/v/unitysvc-services.svg)
 [![Documentation Status](https://readthedocs.org/projects/unitysvc-services/badge/?version=latest)](https://unitysvc-services.readthedocs.io/en/latest/?version=latest)
 
-Client library and CLI tools for digital service providers to interact with the UnitySVC platform.
+Client library and CLI tools for sellers and providers of digital service to interact with the UnitySVC platform.
 
 **📚 [Full Documentation](https://unitysvc-services.readthedocs.io)** | **🚀 [Getting Started](https://unitysvc-services.readthedocs.io/en/latest/getting-started/)** | **📖 [CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/)**
 
 ## Overview
 
-UnitySVC Provider SDK enables digital service providers to manage their service offerings through a **local-first, version-controlled workflow**:
+UnitySVC Services SDK enables digital service sellers and providers to manage their service offerings through a **local-first, version-controlled workflow**:
 
 -   **Define** service data using schema-validated files (JSON/TOML)
 -   **Manage** everything locally in git-controlled directories
--   **Validate** data against schemas before publishing
+-   **Validate** data against schemas
+-   **Test** code examples using provider credentials
 -   **Publish** to UnitySVC platform when ready
 -   **Automate** with populate scripts for dynamic catalogs
 
@@ -67,31 +68,34 @@ pip install unitysvc-services
 
 Requires Python 3.11+
 
+**CLI Alias:** The command `unitysvc_services` can also be invoked using the shorter alias `usvc`.
+
 ## Quick Example
 
 ```bash
-# Initialize provider and service
-unitysvc_services init provider my-provider
-unitysvc_services init offering my-service
-unitysvc_services init seller my-marketplace
+# Initialize provider and service (using short alias 'usvc')
+usvc init provider my-provider
+usvc init offering my-service
+usvc init seller my-marketplace
 
 # Validate and format
-unitysvc_services validate
-unitysvc_services format
+usvc validate
+usvc format
+
+# Test code examples with upstream credentials
+usvc test list --provider fireworks
+usvc test run --provider fireworks --services "llama*"
+
+# if you write a script to manage services
+usvc populate
 
 # Publish to platform (publishes all: sellers, providers, offerings, listings)
 export UNITYSVC_BASE_URL="https://api.unitysvc.com/api/v1"
 export UNITYSVC_API_KEY="your-api-key"
-unitysvc_services publish
-
-# Or publish specific types only
-unitysvc_services publish providers
-
-# Verify with default fields
-unitysvc_services query offerings
+usvc publish
 
-# Query with custom fields
-unitysvc_services query providers --fields id,name,contact_email
+# Query unitysvc backend to verify data
+usvc query providers --fields id,name,contact_email
 ```
 
 ## Key Features
@@ -108,13 +112,13 @@ unitysvc_services query providers --fields id,name,contact_email
 ### Manual Workflow (small catalogs)
 
 ```bash
-init → edit files → validate → format → publish → verify
+init → edit files → validate → test → format → publish → verify
 ```
 
 ### Automated Workflow (large/dynamic catalogs)
 
 ```bash
-init provider → configure populate script → populate → validate → publish
+init → configure populate script → populate → validate → publish
 ```
 
 See [Workflows Documentation](https://unitysvc-services.readthedocs.io/en/latest/workflows/) for details.
@@ -137,24 +141,27 @@ See [Data Structure Documentation](https://unitysvc-services.readthedocs.io/en/l
 
 ## CLI Commands
 
-| Command    | Description                            |
-| ---------- | -------------------------------------- |
-| `init`     | Initialize new data files from schemas |
-| `list`     | List local data files                  |
-| `query`    | Query backend API for published data   |
-| `publish`  | Publish data to backend                |
-| `update`   | Update local file fields               |
-| `validate` | Validate data consistency              |
-| `format`   | Format data files                      |
-| `populate` | Execute provider populate scripts      |
+| Command    | Description                                      |
+| ---------- | ------------------------------------------------ |
+| `init`     | Initialize new data files from schemas           |
+| `list`     | List local data files                            |
+| `query`    | Query backend API for published data             |
+| `publish`  | Publish data to backend                          |
+| `update`   | Update local file fields                         |
+| `validate` | Validate data consistency                        |
+| `format`   | Format data files                                |
+| `populate` | Execute provider populate scripts                |
+| `test`     | Test code examples with upstream API credentials |
 
-Run `unitysvc_services --help` or see [CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/) for complete documentation.
+Run `usvc --help` or see [CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/) for complete documentation.
 
 ## Documentation
 
 -   **[Getting Started](https://unitysvc-services.readthedocs.io/en/latest/getting-started/)** - Installation and first steps
 -   **[Data Structure](https://unitysvc-services.readthedocs.io/en/latest/data-structure/)** - File organization rules
 -   **[Workflows](https://unitysvc-services.readthedocs.io/en/latest/workflows/)** - Manual and automated patterns
+-   **[Documenting Service Listings](https://unitysvc-services.readthedocs.io/en/latest/documenting-services/)** - Add documentation to services
+-   **[Creating Code Examples](https://unitysvc-services.readthedocs.io/en/latest/code-examples/)** - Develop and test code examples
 -   **[CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/)** - All commands and options
 -   **[File Schemas](https://unitysvc-services.readthedocs.io/en/latest/file-schemas/)** - Schema specifications
 -   **[Python API](https://unitysvc-services.readthedocs.io/en/latest/api-reference/)** - Programmatic usage

{unitysvc_services-0.1.4 → unitysvc_services-0.1.6}/README.md

@@ -1,19 +1,20 @@
-# UnitySVC Provider SDK
+# UnitySVC Services SDK
 
 ![PyPI version](https://img.shields.io/pypi/v/unitysvc-services.svg)
 [![Documentation Status](https://readthedocs.org/projects/unitysvc-services/badge/?version=latest)](https://unitysvc-services.readthedocs.io/en/latest/?version=latest)
 
-Client library and CLI tools for digital service providers to interact with the UnitySVC platform.
+Client library and CLI tools for sellers and providers of digital service to interact with the UnitySVC platform.
 
 **📚 [Full Documentation](https://unitysvc-services.readthedocs.io)** | **🚀 [Getting Started](https://unitysvc-services.readthedocs.io/en/latest/getting-started/)** | **📖 [CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/)**
 
 ## Overview
 
-UnitySVC Provider SDK enables digital service providers to manage their service offerings through a **local-first, version-controlled workflow**:
+UnitySVC Services SDK enables digital service sellers and providers to manage their service offerings through a **local-first, version-controlled workflow**:
 
 -   **Define** service data using schema-validated files (JSON/TOML)
 -   **Manage** everything locally in git-controlled directories
--   **Validate** data against schemas before publishing
+-   **Validate** data against schemas
+-   **Test** code examples using provider credentials
 -   **Publish** to UnitySVC platform when ready
 -   **Automate** with populate scripts for dynamic catalogs
 
@@ -25,31 +26,34 @@ pip install unitysvc-services
 
 Requires Python 3.11+
 
+**CLI Alias:** The command `unitysvc_services` can also be invoked using the shorter alias `usvc`.
+
 ## Quick Example
 
 ```bash
-# Initialize provider and service
-unitysvc_services init provider my-provider
-unitysvc_services init offering my-service
-unitysvc_services init seller my-marketplace
+# Initialize provider and service (using short alias 'usvc')
+usvc init provider my-provider
+usvc init offering my-service
+usvc init seller my-marketplace
 
 # Validate and format
-unitysvc_services validate
-unitysvc_services format
+usvc validate
+usvc format
+
+# Test code examples with upstream credentials
+usvc test list --provider fireworks
+usvc test run --provider fireworks --services "llama*"
+
+# if you write a script to manage services
+usvc populate
 
 # Publish to platform (publishes all: sellers, providers, offerings, listings)
 export UNITYSVC_BASE_URL="https://api.unitysvc.com/api/v1"
 export UNITYSVC_API_KEY="your-api-key"
-unitysvc_services publish
-
-# Or publish specific types only
-unitysvc_services publish providers
-
-# Verify with default fields
-unitysvc_services query offerings
+usvc publish
 
-# Query with custom fields
-unitysvc_services query providers --fields id,name,contact_email
+# Query unitysvc backend to verify data
+usvc query providers --fields id,name,contact_email
 ```
 
 ## Key Features
@@ -66,13 +70,13 @@ unitysvc_services query providers --fields id,name,contact_email
 ### Manual Workflow (small catalogs)
 
 ```bash
-init → edit files → validate → format → publish → verify
+init → edit files → validate → test → format → publish → verify
 ```
 
 ### Automated Workflow (large/dynamic catalogs)
 
 ```bash
-init provider → configure populate script → populate → validate → publish
+init → configure populate script → populate → validate → publish
 ```
 
 See [Workflows Documentation](https://unitysvc-services.readthedocs.io/en/latest/workflows/) for details.
@@ -95,24 +99,27 @@ See [Data Structure Documentation](https://unitysvc-services.readthedocs.io/en/l
 
 ## CLI Commands
 
-| Command    | Description                            |
-| ---------- | -------------------------------------- |
-| `init`     | Initialize new data files from schemas |
-| `list`     | List local data files                  |
-| `query`    | Query backend API for published data   |
-| `publish`  | Publish data to backend                |
-| `update`   | Update local file fields               |
-| `validate` | Validate data consistency              |
-| `format`   | Format data files                      |
-| `populate` | Execute provider populate scripts      |
+| Command    | Description                                      |
+| ---------- | ------------------------------------------------ |
+| `init`     | Initialize new data files from schemas           |
+| `list`     | List local data files                            |
+| `query`    | Query backend API for published data             |
+| `publish`  | Publish data to backend                          |
+| `update`   | Update local file fields                         |
+| `validate` | Validate data consistency                        |
+| `format`   | Format data files                                |
+| `populate` | Execute provider populate scripts                |
+| `test`     | Test code examples with upstream API credentials |
 
-Run `unitysvc_services --help` or see [CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/) for complete documentation.
+Run `usvc --help` or see [CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/) for complete documentation.
 
 ## Documentation
 
 -   **[Getting Started](https://unitysvc-services.readthedocs.io/en/latest/getting-started/)** - Installation and first steps
 -   **[Data Structure](https://unitysvc-services.readthedocs.io/en/latest/data-structure/)** - File organization rules
 -   **[Workflows](https://unitysvc-services.readthedocs.io/en/latest/workflows/)** - Manual and automated patterns
+-   **[Documenting Service Listings](https://unitysvc-services.readthedocs.io/en/latest/documenting-services/)** - Add documentation to services
+-   **[Creating Code Examples](https://unitysvc-services.readthedocs.io/en/latest/code-examples/)** - Develop and test code examples
 -   **[CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/)** - All commands and options
 -   **[File Schemas](https://unitysvc-services.readthedocs.io/en/latest/file-schemas/)** - Schema specifications
 -   **[Python API](https://unitysvc-services.readthedocs.io/en/latest/api-reference/)** - Programmatic usage

{unitysvc_services-0.1.4 → unitysvc_services-0.1.6}/docs/api-reference.md

@@ -140,6 +140,145 @@ else:
 
 -   `tuple[Path, str, dict] | None`: (file_path, format, data) or None if not found
 
+#### resolve_provider_name()
+
+Resolve the provider name from a file path.
+
+```python
+from pathlib import Path
+from unitysvc_services.utils import resolve_provider_name
+
+provider_name = resolve_provider_name(
+    Path("data/fireworks/services/llama-3-1/listing.json")
+)
+# Returns: "fireworks"
+```
+
+**Parameters:**
+
+-   `file_path` (Path): Path to the service offering or listing file
+
+**Returns:**
+
+-   `str | None`: Provider name if found, None otherwise
+
+**How it works:**
+
+-   Checks if file is under a "services" directory
+-   Provider name is the directory before "services"
+-   Validates by looking for provider data file in that directory
+-   Returns the name from the provider file if found
+
+#### resolve_service_name_for_listing()
+
+Resolve the service name for a listing file.
+
+```python
+from pathlib import Path
+from unitysvc_services.utils import (
+    load_data_file,
+    resolve_service_name_for_listing
+)
+
+listing_file = Path("data/fireworks/services/llama-3-1/listing.json")
+listing_data, _ = load_data_file(listing_file)
+
+service_name = resolve_service_name_for_listing(listing_file, listing_data)
+# Returns: service name from listing or from co-located service.json
+```
+
+**Parameters:**
+
+-   `listing_file` (Path): Path to the listing file
+-   `listing_data` (dict): Listing data dictionary
+
+**Returns:**
+
+-   `str | None`: Service name if found, None otherwise
+
+**Resolution Rules:**
+
+1. If `service_name` is defined in listing_data, return it
+2. Otherwise, find the only service offering in the same directory and return its name
+3. Return None if multiple or no service offerings found
+
+#### convert_convenience_fields_to_documents()
+
+Convert convenience fields (logo, terms_of_service) to Document objects.
+
+```python
+from pathlib import Path
+from unitysvc_services.utils import convert_convenience_fields_to_documents
+
+data = {
+    "logo": "assets/logo.png",
+    "terms_of_service": "https://example.com/terms",
+    "documents": []
+}
+
+updated_data = convert_convenience_fields_to_documents(
+    data,
+    base_path=Path("/data/provider")
+)
+# logo and terms_of_service fields are removed
+# Corresponding Document objects added to documents list
+```
+
+**Parameters:**
+
+-   `data` (dict): Data dictionary containing potential convenience fields
+-   `base_path` (Path): Base path for resolving relative file paths
+-   `logo_field` (str): Name of the logo field (default: "logo")
+-   `terms_field` (str | None): Name of the terms field (default: "terms_of_service", None to skip)
+
+**Returns:**
+
+-   `dict`: Updated data dictionary with convenience fields converted to documents list
+
+**What it does:**
+
+-   Converts file paths or URLs to proper Document structures
+-   Automatically determines MIME types from file extensions
+-   Removes convenience fields after conversion
+-   Adds Document objects to the documents list
+
+#### render_template_file()
+
+Render a Jinja2 template file and return content and new filename.
+
+```python
+from pathlib import Path
+from unitysvc_services.utils import render_template_file
+
+rendered_content, new_filename = render_template_file(
+    Path("test.py.j2"),
+    listing={"service_name": "gpt-4"},
+    offering={"name": "gpt-4-turbo"},
+    provider={"provider_name": "openai"},
+    seller={"seller_name": "marketplace"}
+)
+# rendered_content: Template rendered with data
+# new_filename: "test.py" (without .j2 extension)
+```
+
+**Parameters:**
+
+-   `file_path` (Path): Path to the file (may or may not be a .j2 template)
+-   `listing` (dict, optional): Listing data for template rendering
+-   `offering` (dict, optional): Offering data for template rendering
+-   `provider` (dict, optional): Provider data for template rendering
+-   `seller` (dict, optional): Seller data for template rendering
+
+**Returns:**
+
+-   `tuple[str, str]`: (rendered_content, new_filename_without_j2)
+
+**Behavior:**
+
+-   If file ends with `.j2`: Renders as Jinja2 template and strips `.j2` from filename
+-   If file does not end with `.j2`: Returns content as-is with original filename
+-   All template variables default to empty dict if not provided
+
 ### unitysvc_services.cli
 
 Main CLI application built with Typer.
@@ -156,6 +295,7 @@ from unitysvc_services.cli import app
 # - validate: Validate data
 # - format: Format files
 # - populate: Run populate scripts
+# - test: Test code examples with upstream credentials
 ```
 
 ### unitysvc_services.publisher
@@ -319,6 +459,65 @@ for provider, success, output in results:
 
 -   `list[tuple[str, bool, str]]`: List of (provider_name, success, output)
 
+### unitysvc_services.test
+
+Code example testing operations.
+
+#### list_code_examples()
+
+List available code examples from listing files.
+
+```python
+from pathlib import Path
+from unitysvc_services.test import list_code_examples
+
+# This is typically called via CLI, but can be used programmatically
+# Note: This function uses Typer and is designed for CLI use
+```
+
+**Functionality:**
+
+-   Scans for listing files (schema: listing_v1)
+-   Extracts documents with category = "code_examples"
+-   Displays results in table format with file paths
+-   Supports filtering by provider and service patterns
+
+#### run_tests()
+
+Execute code examples with upstream credentials.
+
+```python
+from pathlib import Path
+from unitysvc_services.test import run
+
+# This is typically called via CLI, but can be used programmatically
+# Note: This function uses Typer and is designed for CLI use
+```
+
+**Functionality:**
+
+-   Discovers code examples from listing files
+-   Loads related data (offering, provider, seller)
+-   Renders Jinja2 templates with context data
+-   Executes code with appropriate interpreter
+-   Validates output based on exit code and `expect` field
+-   Saves failed test content for debugging
+
+**Test Execution:**
+
+1. Template rendering with listing, offering, provider, seller data
+2. Environment variable setup (API_KEY, API_ENDPOINT)
+3. Interpreter detection (.py → python3, .js → node, .sh → bash)
+4. Script execution with timeout
+5. Output validation (exit code + optional expect string)
+
+**Test Pass Criteria:**
+
+-   Exit code is 0 AND
+-   If `expect` field exists: expected string found in stdout
+
+See [Creating Code Examples](https://unitysvc-services.readthedocs.io/en/latest/code-examples/) guide for detailed workflow.
+
 ## Pydantic Models
 
 ### Provider
@@ -524,5 +723,7 @@ def get_service(name: str, data_dir: Path = Path("data")) -> dict[str, Any] | No
 ## See Also
 
 -   [CLI Reference](cli-reference.md) - Command-line interface
+-   [Documenting Service Listings](documenting-services.md) - Add documentation to services
+-   [Creating Code Examples](code-examples.md) - Develop and test code examples
 -   [File Schemas](file-schemas.md) - Data schema specifications
 -   [Workflows](workflows.md) - Usage patterns and examples