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

{unitysvc_services-0.1.5/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.5
+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>

{unitysvc_services-0.1.5 → unitysvc_services-0.1.6}/docs/code-examples.md

@@ -77,8 +77,10 @@ Code examples are referenced in your `listing.json` or `listing.toml` file under
                     "file_path": "../../docs/example.py.j2",
                     "mime_type": "python",
                     "is_public": true,
-                    "requirements": ["httpx"],
-                    "expect": "✓ Test passed"
+                    "meta": {
+                        "requirements": ["httpx"],
+                        "expect": "✓ Test passed"
+                    }
                 }
             ]
         }
@@ -94,10 +96,25 @@ Code examples are referenced in your `listing.json` or `listing.toml` file under
 -   **`mime_type`**: File type (`python`, `javascript`, `shell`, etc.)
 -   **`is_public`**: Should be `true` for code examples
 
-**Optional but Recommended Fields:**
+**Optional but Recommended Fields (in `meta` object):**
 
--   **`requirements`**: Package dependencies (e.g., `["httpx", "openai"]`)
--   **`expect`**: Expected substring in stdout for validation (e.g., `"✓ Test passed"`)
+-   **`meta.requirements`**: _(User-maintained)_ Package dependencies needed to run the code example
+    -   For Python: PyPI packages (e.g., `["httpx", "openai"]`)
+    -   For JavaScript: npm packages (e.g., `["node-fetch"]`)
+    -   For Shell scripts: commands (e.g., `["curl"]`)
+    -   Helps users understand what to install before running the example
+-   **`meta.expect`**: _(User-maintained)_ Expected substring in stdout for validation
+    -   Examples: `"✓ Test passed"`, `"\"choices\""`, `"Status: 200"`
+    -   If specified, test passes only if stdout contains this string
+    -   Without this field, tests only check exit code (0 = pass, non-zero = fail)
+
+**System-Maintained Fields (in `meta` object):**
+
+-   **`meta.output`**: _(System-maintained)_ Actual output from successful test execution
+    -   Automatically populated by `usvc test run` when a test passes
+    -   Contains the stdout from the last successful test run
+    -   Included in your service listing during `usvc publish`
+    -   Displayed alongside code examples for documentation
 
 ### 4. Use Relative Paths
 
@@ -220,8 +237,11 @@ usvc test run --verbose
 3. Sets environment variables (`API_KEY`, `API_ENDPOINT`) from provider credentials
 4. Executes the code example using appropriate interpreter (python3, node, bash)
 5. Validates results:
-    - Test passes if exit code is 0 AND (no `expect` field OR expected string found in stdout)
+    - Test passes if exit code is 0 AND (no `meta.expect` field OR expected string found in stdout)
     - Test fails if exit code is non-zero OR expected string not found
+6. **Saves output**: When a test passes, stdout is saved to listing directory as `{listing_stem}_{code_filename}.out`
+    - Example: For `svclisting.json` with code file `test.py`, output is saved as `svclisting_test.py.out`
+    - Saved in the same directory as the listing file for easy version control
 
 **Failed test debugging:**
 
@@ -382,8 +402,10 @@ Reference the code example in your `listing.json` file.
                     "file_path": "../../docs/test.py.j2",
                     "mime_type": "python",
                     "is_public": true,
-                    "requirements": ["httpx"],
-                    "expect": "✓ Test passed"
+                    "meta": {
+                        "requirements": ["httpx"],
+                        "expect": "✓ Test passed"
+                    }
                 }
             ]
         }
@@ -398,17 +420,23 @@ Reference the code example in your `listing.json` file.
 -   `file_path`: Relative path from listing file to your `.j2` template
 -   `mime_type`: File type (`python`, `javascript`, `shell`, etc.)
 -   `is_public`: Should be `true` for code examples
--   `requirements`: **[Optional]** List of package dependencies needed to run the code example
-    -   For Python: PyPI packages (e.g., `["httpx", "openai"]`)
-    -   For JavaScript: npm packages (e.g., `["node-fetch"]`)
-    -   For Shell scripts: commands (e.g., `["curl"]`)
-    -   Helps users understand what to install before running the example
--   `expect`: **[Optional but strongly recommended]** Expected substring that should appear in stdout when the test passes
-    -   Examples:
-        -   `"✓ Test passed"` - Explicit success message
-        -   `"\"choices\""` - Check for JSON field in API response
-        -   `"Status: 200"` - Check for HTTP status
-    -   Without this field, tests only check exit code (0 = pass, non-zero = fail), which is unreliable.
+-   `meta`: **[Optional]** Metadata object containing:
+    -   `requirements`: _(User-maintained)_ List of package dependencies needed to run the code example
+        -   For Python: PyPI packages (e.g., `["httpx", "openai"]`)
+        -   For JavaScript: npm packages (e.g., `["node-fetch"]`)
+        -   For Shell scripts: commands (e.g., `["curl"]`)
+        -   Helps users understand what to install before running the example
+    -   `expect`: _(User-maintained, strongly recommended)_ Expected substring that should appear in stdout when the test passes
+        -   Examples:
+            -   `"✓ Test passed"` - Explicit success message
+            -   `"\"choices\""` - Check for JSON field in API response
+            -   `"Status: 200"` - Check for HTTP status
+        -   Without this field, tests only check exit code (0 = pass, non-zero = fail), which is unreliable
+    -   `output`: _(System-maintained)_ Automatically populated by `usvc test run`
+        -   Contains stdout from the last successful test execution
+        -   Saved to `{listing_stem}_{code_filename}.out` file during test run
+        -   Embedded into `meta.output` during `usvc publish`
+        -   Displayed alongside code examples in your service listing
 
 ### Step 5: Validate and Test Before Publishing
 
@@ -500,8 +528,14 @@ curl ${API_ENDPOINT}/chat/completions \
 
 ```json
 {
+    "category": "code_examples",
+    "title": "Shell Example",
     "file_path": "test.sh.j2",
-    "expect": "\"choices\""
+    "mime_type": "bash",
+    "is_public": true,
+    "meta": {
+        "expect": "\"choices\""
+    }
 }
 ```
 
@@ -532,9 +566,15 @@ if "choices" in data:
 
 ```json
 {
+    "category": "code_examples",
+    "title": "Python Example",
     "file_path": "test.py.j2",
-    "expect": "✓ Validation passed",
-    "requirements": ["httpx"]
+    "mime_type": "python",
+    "is_public": true,
+    "meta": {
+        "requirements": ["httpx"],
+        "expect": "✓ Validation passed"
+    }
 }
 ```
 
@@ -568,8 +608,14 @@ if (data.choices) {
 
 ```json
 {
+    "category": "code_examples",
+    "title": "JavaScript Example",
     "file_path": "test.js.j2",
-    "expect": "✓ Success"
+    "mime_type": "javascript",
+    "is_public": true,
+    "meta": {
+        "expect": "✓ Success"
+    }
 }
 ```
 
@@ -625,12 +671,12 @@ If a field might not exist, use Jinja2 defaults:
 ## Tips for Effective Code Examples
 
 1. **Keep examples short and focused** - Test one thing at a time
-2. **Use `expect` field** - Makes validation automatic and reliable
+2. **Use `meta.expect` field** - Makes validation automatic and reliable
 3. **Print clear success messages** - Makes debugging easier
 4. **Handle errors gracefully** - Exit with non-zero code on failure
 5. **Test locally first** - Always verify with hardcoded values before templating
 6. **Use meaningful output** - Print enough info to understand what happened
-7. **Add requirements** - List all dependencies in the `requirements` field
+7. **Add requirements** - List all dependencies in `meta.requirements` field
 
 ## Workflow Summary
 
@@ -648,21 +694,89 @@ python3 test.py
 mv test.py test.py.j2
 vim test.py.j2  # Replace with {{ offering.name }}, etc.
 
-# 4. Add to listing.json
-vim listing.json  # Add document entry
+# 4. Add to listing.json with meta fields
+vim listing.json  # Add document entry with meta.requirements and meta.expect
 
 # 5. Validate and test
 usvc validate
 usvc test list
 usvc test run --provider your-provider
+# ✓ Successful tests create .out files (e.g., listing_test.py.out in listing directory)
 
 # 6. Debug if needed
-cat failed_*  # Check saved test files
+cat failed_*  # Check saved test files (in current directory)
+cat services/*/listing_*.out  # Review successful test outputs (in listing directories)
 
-# 7. Publish when tests pass
+# 7. Publish - embeds .out files into meta.output
 usvc publish
+# ✓ Reads .out files from listing directories and adds content to meta.output
+# ✓ Output will appear alongside code examples in your service listing
 ```
 
+## Understanding meta.output Workflow
+
+The `meta.output` field follows an automated workflow from test execution to publication:
+
+### 1. Testing Phase: `usvc test run`
+
+When you run tests, successful executions generate `.out` files:
+
+```bash
+$ usvc test run --provider fireworks
+
+Testing: llama-3-1-405b - Python code example
+  ✓ Success (exit code: 0)
+  → Output saved to: /path/to/fireworks/services/llama-3-1-405b/listing_test.py.out
+```
+
+**Output file naming:** `{listing_stem}_{code_filename}.out`
+
+-   `listing_stem`: The listing filename without extension (e.g., "listing" from "listing.json")
+-   `code_filename`: The code filename after template expansion (e.g., "test.py" from "test.py.j2")
+-   Example: `listing_test.py.out`, `svclisting_example.sh.out`
+
+**File location:** Same directory as the listing file that references the code example
+
+### 2. Publishing Phase: `usvc publish`
+
+During publish, the SDK automatically:
+
+1. Expands `.j2` templates for each model if a template is used
+2. Looks for matching `.out` files in the listing's base directory
+3. Reads the output content and embeds it into `meta.output`
+
+**Example published document:**
+
+```json
+{
+    "category": "code_examples",
+    "title": "Python code example",
+    "file_path": "chat-completion.py",
+    "file_content": "#!/usr/bin/env python3\nimport httpx...",
+    "mime_type": "python",
+    "meta": {
+        "requirements": ["httpx"],
+        "expect": "✓ Test passed",
+        "output": "{'id': 'chatcmpl-...', 'choices': [{'message': {'content': 'Hello!'}}]}\n✓ Test passed"
+    }
+}
+```
+
+### 3. Display in Service Listing
+
+After publishing, the output will automatically appear alongside the code example in your service listing documentation, allowing users to see both the code and its expected output together.
+
+### 4. Key Points
+
+-   **`.out` files are model-specific**: Since templates expand per model, each model gets its own output file
+-   **`.out` files location**: Saved in the **same directory as the listing file**, making them easy to find and version control
+-   **`.out` file naming**: Format is `{listing_stem}_{code_filename}.out` to clearly associate output with both listing and code
+-   **Version control**: You **can** commit `.out` files to version control since they're co-located with listings
+-   **Publishing is flexible**: `usvc publish` works even if `.out` files are missing (gracefully skips)
+-   **User vs System fields**:
+    -   `meta.requirements` and `meta.expect` are **user-maintained** (you write these)
+    -   `meta.output` is **system-maintained** (auto-generated by `usvc test run` and `usvc publish`)
+
 ## Interpreter Detection
 
 The test framework automatically detects the appropriate interpreter based on file extension:
@@ -710,7 +824,7 @@ If the required interpreter is not found, the test will fail with a clear error
 
 **Problem:** Exit code is 0 but test still fails
 
-**Solution:** Check the `expect` field - test requires the expected string to appear in stdout
+**Solution:** Check the `meta.expect` field - test requires the expected string to appear in stdout
 
 ### Validation Errors
 

{unitysvc_services-0.1.5 → unitysvc_services-0.1.6}/docs/data-structure.md

@@ -114,6 +114,148 @@ display_name = "My Service"
 description = "A high-performance digital service"
 ```
 
+## Override Files
+
+Override files provide a way to complement and customize data files without modifying the base files. This is particularly useful when base files are auto-generated by scripts, and you need to manually curate specific values like status, logo URLs, or other metadata.
+
+### Naming Pattern
+
+Override files follow the pattern: `<base_name>.override.<extension>`
+
+Examples:
+- `service.json` → `service.override.json`
+- `provider.toml` → `provider.override.toml`
+- `listing-premium.json` → `listing-premium.override.json`
+
+### How Override Files Work
+
+When any data file is loaded by the SDK:
+
+1. The base file is loaded first
+2. The system checks for a corresponding `.override.*` file
+3. If found, the override file is loaded and **deep-merged** into the base data
+4. Override values take precedence over base values
+
+This merge happens automatically and transparently - you don't need to do anything special.
+
+### Merge Behavior
+
+**Nested Dictionaries**: Recursively merged - override values complement and replace base values
+
+**Example**:
+```json
+// Base: service.json
+{
+  "name": "my-service",
+  "config": {
+    "host": "localhost",
+    "port": 8080,
+    "timeout": 30
+  }
+}
+
+// Override: service.override.json
+{
+  "config": {
+    "port": 9000,
+    "ssl": true
+  },
+  "status": "active"
+}
+
+// Merged Result
+{
+  "name": "my-service",
+  "config": {
+    "host": "localhost",    // preserved from base
+    "port": 9000,           // overridden
+    "timeout": 30,          // preserved from base
+    "ssl": true             // added from override
+  },
+  "status": "active"        // added from override
+}
+```
+
+**Lists and Primitives**: Completely replaced (not merged)
+
+```json
+// Base: service.json
+{
+  "tags": ["python", "web", "api"],
+  "version": 1
+}
+
+// Override: service.override.json
+{
+  "tags": ["backend", "production"]
+}
+
+// Merged Result
+{
+  "tags": ["backend", "production"],  // completely replaced
+  "version": 1
+}
+```
+
+This replacement behavior for lists is intentional and predictable - if you want to change a list, simply specify the complete desired list in the override file.
+
+### Common Use Cases
+
+**1. Manual curation of auto-generated data**
+```json
+// service.json (auto-generated by script)
+{
+  "schema": "service_v1",
+  "name": "gpt-4",
+  "description": "Auto-generated description",
+  "status": "draft"
+}
+
+// service.override.json (manually maintained)
+{
+  "status": "active",
+  "logo_url": "https://example.com/custom-logo.png",
+  "featured": true
+}
+```
+
+**2. Environment-specific configuration**
+```toml
+# provider.toml (base configuration)
+schema = "provider_v1"
+name = "my-provider"
+api_endpoint = "https://api.example.com"
+
+# provider.override.toml (local testing overrides)
+api_endpoint = "http://localhost:8000"
+debug_mode = true
+```
+
+**3. Maintaining custom metadata**
+```json
+// listing-premium.json (generated from template)
+{
+  "schema": "listing_v1",
+  "name": "premium-tier",
+  "pricing": { /* auto-generated */ }
+}
+
+// listing-premium.override.json (manual customization)
+{
+  "featured": true,
+  "promotional_badge": "Best Value",
+  "custom_cta": "Try Premium Now!"
+}
+```
+
+### Version Control
+
+Override files should be committed to version control alongside base files. They are part of your data and represent intentional manual customizations that should be preserved and tracked.
+
+### File Location
+
+Override files must be in the same directory as their corresponding base files, following the directory structure rules described above.
+
 ## Schema Requirements
 
 Each file must include a `schema` field identifying its type:

{unitysvc_services-0.1.5 → unitysvc_services-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unitysvc-services"
-version = "0.1.5"
+version = "0.1.6"
 description = "SDK for digital service providers on UnitySVC"
 readme = "README.md"
 authors = [{ name = "Bo Peng", email = "bo.peng@unitysvc.com" }]

{unitysvc_services-0.1.5 → unitysvc_services-0.1.6}/src/unitysvc_services/models/base.py

@@ -255,18 +255,6 @@ 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):

{unitysvc_services-0.1.5 → unitysvc_services-0.1.6}/src/unitysvc_services/publisher.py

@@ -67,6 +67,7 @@ class ServiceDataPublisher(UnitySvcAPI):
         offering: dict[str, Any] | None = None,
         provider: dict[str, Any] | None = None,
         seller: dict[str, Any] | None = None,
+        listing_filename: str | None = None,
     ) -> dict[str, Any]:
         """Recursively resolve file references and include content in data.
 
@@ -80,6 +81,7 @@ class ServiceDataPublisher(UnitySvcAPI):
             offering: Offering data for template rendering (optional)
             provider: Provider data for template rendering (optional)
             seller: Seller data for template rendering (optional)
+            listing_filename: Listing filename for constructing output filenames (optional)
 
         Returns:
             Data with file references resolved and content loaded
@@ -90,14 +92,26 @@ class ServiceDataPublisher(UnitySvcAPI):
             if isinstance(value, dict):
                 # Recursively process nested dictionaries
                 result[key] = self.resolve_file_references(
-                    value, base_path, listing=listing, offering=offering, provider=provider, seller=seller
+                    value,
+                    base_path,
+                    listing=listing,
+                    offering=offering,
+                    provider=provider,
+                    seller=seller,
+                    listing_filename=listing_filename,
                 )
             elif isinstance(value, list):
                 # Process lists
                 result[key] = [
                     (
                         self.resolve_file_references(
-                            item, base_path, listing=listing, offering=offering, provider=provider, seller=seller
+                            item,
+                            base_path,
+                            listing=listing,
+                            offering=offering,
+                            provider=provider,
+                            seller=seller,
+                            listing_filename=listing_filename,
                         )
                         if isinstance(item, dict)
                         else item
@@ -135,6 +149,41 @@ class ServiceDataPublisher(UnitySvcAPI):
             else:
                 result[key] = value
 
+        # After processing all fields, check if this is a code_examples document
+        # If so, try to load corresponding .out file and add to meta.output
+        if result.get("category") == "code_examples" and result.get("file_content") and listing_filename:
+            # Get the actual filename (after .j2 stripping if applicable)
+            # If file_path was updated (e.g., from "test.py.j2" to "test.py"), use that
+            # Otherwise, extract basename from original file_path
+            output_base_filename: str | None = None
+
+            # Check if file_path was modified (original might have had .j2)
+            file_path_value = result.get("file_path", "")
+            if file_path_value:
+                output_base_filename = Path(file_path_value).name
+
+            if output_base_filename:
+                # Construct output filename: {listing_stem}_{output_base_filename}.out
+                # e.g., "svclisting_test.py.out" for svclisting.json and test.py
+                listing_stem = Path(listing_filename).stem
+                output_filename = f"{listing_stem}_{output_base_filename}.out"
+
+                # Try to find the .out file in base_path (listing directory)
+                output_path = base_path / output_filename
+
+                if output_path.exists():
+                    try:
+                        with open(output_path, encoding="utf-8") as f:
+                            output_content = f.read()
+
+                        # Add output to meta field
+                        if "meta" not in result or result["meta"] is None:
+                            result["meta"] = {}
+                        result["meta"]["output"] = output_content
+                    except Exception:
+                        # Don't fail if output file can't be read, just skip it
+                        pass
+
         return result
 
     async def post(  # type: ignore[override]
@@ -401,6 +450,7 @@ class ServiceDataPublisher(UnitySvcAPI):
             offering=service_data,
             provider=provider_data,
             seller=seller_data,
+            listing_filename=listing_file.name,
         )
 
         # Post to the endpoint using retry helper

{unitysvc_services-0.1.5 → unitysvc_services-0.1.6}/src/unitysvc_services/test.py

@@ -79,6 +79,9 @@ def extract_code_examples_from_listing(listing_data: dict[str, Any], listing_fil
                     # Resolve relative path
                     absolute_path = (listing_file.parent / file_path).resolve()
 
+                    # Extract meta fields for code examples (expect, requirements, etc.)
+                    meta = doc.get("meta", {}) or {}
+
                     code_example = {
                         "service_name": service_name,
                         "title": doc.get("title", "Untitled"),
@@ -86,7 +89,8 @@ def extract_code_examples_from_listing(listing_data: dict[str, Any], listing_fil
                         "file_path": str(absolute_path),
                         "listing_data": listing_data,  # Full listing data for templates
                         "listing_file": listing_file,  # Path to listing file for loading related data
-                        "expect": doc.get("expect"),  # Expected output substring for validation
+                        "expect": meta.get("expect"),  # Expected output substring for validation (from meta)
+                        "requirements": meta.get("requirements"),  # Required packages (from meta)
                     }
                     code_examples.append(code_example)
 
@@ -200,6 +204,8 @@ def execute_code_example(code_example: dict[str, Any], credentials: dict[str, st
         "stderr": None,
         "rendered_content": None,
         "file_suffix": None,
+        "listing_file": None,
+        "actual_filename": None,
     }
 
     file_path = code_example.get("file_path")
@@ -237,6 +243,8 @@ def execute_code_example(code_example: dict[str, Any], credentials: dict[str, st
         # Store rendered content and file suffix for later use (e.g., writing failed tests)
         result["rendered_content"] = file_content
         result["file_suffix"] = file_suffix
+        result["listing_file"] = listing_file
+        result["actual_filename"] = actual_filename
 
         # Determine interpreter to use
         lines = file_content.split("\n")
@@ -686,6 +694,27 @@ def run(
             console.print(f"  [green]✓ Success[/green] (exit code: {result['exit_code']})")
             if verbose and result["stdout"]:
                 console.print(f"  [dim]stdout:[/dim] {result['stdout'][:200]}")
+
+            # Save successful test output to .out file
+            if result.get("stdout") and result.get("listing_file") and result.get("actual_filename"):
+                listing_file = Path(result["listing_file"])
+                actual_filename = result["actual_filename"]
+
+                # Create filename: {listing_stem}_{actual_filename}.out
+                # e.g., "svclisting_test.py.out" for svclisting.json and test.py
+                listing_stem = listing_file.stem
+                output_filename = f"{listing_stem}_{actual_filename}.out"
+
+                # Save to listing directory
+                output_path = listing_file.parent / output_filename
+
+                # Write stdout to .out file
+                try:
+                    with open(output_path, "w", encoding="utf-8") as f:
+                        f.write(result["stdout"])
+                    console.print(f"  [dim]→ Output saved to:[/dim] {output_path}")
+                except Exception as e:
+                    console.print(f"  [yellow]⚠ Failed to save output: {e}[/yellow]")
         else:
             console.print(f"  [red]✗ Failed[/red] - {result['error']}")
             if verbose:
@@ -695,15 +724,13 @@ def run(
                     console.print(f"  [dim]stderr:[/dim] {result['stderr'][:200]}")
 
             # Write failed test content to current directory
-            if result.get("rendered_content"):
-                # Create safe filename: failed_<service_name>_<title><ext>
-                # Sanitize service name and title for filename
-                safe_service = service_name.replace("/", "_").replace(" ", "_")
-                safe_title = title.replace("/", "_").replace(" ", "_")
-                file_suffix = result.get("file_suffix", ".txt")
-
-                # Create filename
-                failed_filename = f"failed_{safe_service}_{safe_title}{file_suffix}"
+            if result.get("rendered_content") and result.get("listing_file") and result.get("actual_filename"):
+                listing_file = Path(result["listing_file"])
+                actual_filename = result["actual_filename"]
+                listing_stem = listing_file.stem
+
+                # Create filename: failed_{listing_stem}_{actual_filename}
+                failed_filename = f"failed_{listing_stem}_{actual_filename}"
 
                 # Prepare content with environment variables as header comments
                 content_with_env = result["rendered_content"]

{unitysvc_services-0.1.5 → unitysvc_services-0.1.6}/src/unitysvc_services/utils.py

@@ -10,10 +10,47 @@ import tomli_w
 from jinja2 import Template
 
 
+def deep_merge_dicts(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """
+    Deep merge two dictionaries, with override values taking precedence.
+
+    For nested dictionaries, performs recursive merge. For all other types
+    (lists, primitives), the override value completely replaces the base value.
+
+    Args:
+        base: Base dictionary
+        override: Override dictionary (values take precedence)
+
+    Returns:
+        Merged dictionary
+    """
+    result = base.copy()
+
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            # Recursively merge nested dictionaries
+            result[key] = deep_merge_dicts(result[key], value)
+        else:
+            # For all other types (lists, primitives, etc.), override completely
+            result[key] = value
+
+    return result
+
+
 def load_data_file(file_path: Path) -> tuple[dict[str, Any], str]:
     """
     Load a data file (JSON or TOML) and return (data, format).
 
+    Automatically checks for and merges override files with the pattern:
+    <base_name>.override.<extension>
+
+    For example:
+    - service.json -> service.override.json
+    - provider.toml -> provider.override.toml
+
+    If an override file exists, it will be deep-merged with the base file,
+    with override values taking precedence.
+
     Args:
         file_path: Path to the data file
 
@@ -23,15 +60,41 @@ def load_data_file(file_path: Path) -> tuple[dict[str, Any], str]:
     Raises:
         ValueError: If file format is not supported
     """
+    # Load the base file
     if file_path.suffix == ".json":
         with open(file_path, encoding="utf-8") as f:
-            return json.load(f), "json"
+            data = json.load(f)
+        file_format = "json"
     elif file_path.suffix == ".toml":
         with open(file_path, "rb") as f:
-            return tomllib.load(f), "toml"
+            data = tomllib.load(f)
+        file_format = "toml"
     else:
         raise ValueError(f"Unsupported file format: {file_path.suffix}")
 
+    # Check for override file
+    # Pattern: <stem>.override.<suffix>
+    # Example: service.json -> service.override.json
+    override_path = file_path.with_stem(f"{file_path.stem}.override")
+
+    if override_path.exists():
+        # Load the override file (same format as base file)
+        if override_path.suffix == ".json":
+            with open(override_path, encoding="utf-8") as f:
+                override_data = json.load(f)
+        elif override_path.suffix == ".toml":
+            with open(override_path, "rb") as f:
+                override_data = tomllib.load(f)
+        else:
+            # This shouldn't happen since we're using the same suffix as base
+            # But handle it gracefully
+            override_data = {}
+
+        # Deep merge the override data into the base data
+        data = deep_merge_dicts(data, override_data)
+
+    return data, file_format
+
 
 def write_data_file(file_path: Path, data: dict[str, Any], format: str) -> None:
     """

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-services
-Version: 0.1.5
+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>

{unitysvc_services-0.1.5 → unitysvc_services-0.1.6}/tests/test_utils.py

@@ -6,6 +6,8 @@ import pytest
 
 from unitysvc_services.utils import (
     convert_convenience_fields_to_documents,
+    deep_merge_dicts,
+    load_data_file,
     resolve_provider_name,
     resolve_service_name_for_listing,
 )
@@ -221,3 +223,179 @@ def test_convert_mime_type_detection(tmp_path: Path) -> None:
         data = {"logo": file_path}
         result = convert_convenience_fields_to_documents(data, tmp_path, terms_field=None)
         assert result["documents"][0]["mime_type"] == expected_mime
+
+
+def test_deep_merge_dicts_simple() -> None:
+    """Test simple dictionary merge."""
+    base = {"a": 1, "b": 2, "c": 3}
+    override = {"b": 20, "d": 4}
+
+    result = deep_merge_dicts(base, override)
+
+    assert result == {"a": 1, "b": 20, "c": 3, "d": 4}
+
+
+def test_deep_merge_dicts_nested() -> None:
+    """Test deep merge with nested dictionaries."""
+    base = {"config": {"host": "localhost", "port": 8080}, "name": "service1"}
+    override = {"config": {"port": 9000, "ssl": True}, "status": "active"}
+
+    result = deep_merge_dicts(base, override)
+
+    assert result == {
+        "config": {"host": "localhost", "port": 9000, "ssl": True},
+        "name": "service1",
+        "status": "active",
+    }
+
+
+def test_deep_merge_dicts_lists_replaced() -> None:
+    """Test that lists are replaced, not merged."""
+    base = {"tags": ["python", "web"], "name": "service1"}
+    override = {"tags": ["backend"]}
+
+    result = deep_merge_dicts(base, override)
+
+    # Lists should be replaced, not merged
+    assert result == {"tags": ["backend"], "name": "service1"}
+
+
+def test_deep_merge_dicts_empty_override() -> None:
+    """Test merge with empty override."""
+    base = {"a": 1, "b": 2}
+    override: dict[str, int] = {}
+
+    result = deep_merge_dicts(base, override)
+
+    assert result == {"a": 1, "b": 2}
+
+
+def test_deep_merge_dicts_deeply_nested() -> None:
+    """Test deeply nested dictionary merge."""
+    base = {"level1": {"level2": {"level3": {"value": "old", "keep": True}}}}
+    override = {"level1": {"level2": {"level3": {"value": "new"}}}}
+
+    result = deep_merge_dicts(base, override)
+
+    assert result == {"level1": {"level2": {"level3": {"value": "new", "keep": True}}}}
+
+
+def test_load_data_file_json_no_override(tmp_path: Path) -> None:
+    """Test loading JSON file without override."""
+    import json
+
+    # Create a base JSON file
+    base_file = tmp_path / "test.json"
+    base_data = {"schema": "test_v1", "name": "test", "value": 100}
+    with open(base_file, "w", encoding="utf-8") as f:
+        json.dump(base_data, f)
+
+    data, file_format = load_data_file(base_file)
+
+    assert file_format == "json"
+    assert data == base_data
+
+
+def test_load_data_file_json_with_override(tmp_path: Path) -> None:
+    """Test loading JSON file with override."""
+    import json
+
+    # Create base JSON file
+    base_file = tmp_path / "service.json"
+    base_data = {"schema": "service_v1", "name": "my-service", "status": "draft", "version": 1}
+    with open(base_file, "w", encoding="utf-8") as f:
+        json.dump(base_data, f)
+
+    # Create override JSON file
+    override_file = tmp_path / "service.override.json"
+    override_data = {"status": "active", "logo_url": "https://example.com/logo.png"}
+    with open(override_file, "w", encoding="utf-8") as f:
+        json.dump(override_data, f)
+
+    data, file_format = load_data_file(base_file)
+
+    assert file_format == "json"
+    assert data == {
+        "schema": "service_v1",
+        "name": "my-service",
+        "status": "active",  # overridden
+        "version": 1,
+        "logo_url": "https://example.com/logo.png",  # added from override
+    }
+
+
+def test_load_data_file_toml_no_override(tmp_path: Path) -> None:
+    """Test loading TOML file without override."""
+    import tomli_w
+
+    # Create a base TOML file
+    base_file = tmp_path / "test.toml"
+    base_data = {"schema": "test_v1", "name": "test", "value": 100}
+    with open(base_file, "wb") as f:
+        tomli_w.dump(base_data, f)
+
+    data, file_format = load_data_file(base_file)
+
+    assert file_format == "toml"
+    assert data == base_data
+
+
+def test_load_data_file_toml_with_override(tmp_path: Path) -> None:
+    """Test loading TOML file with override."""
+    import tomli_w
+
+    # Create base TOML file
+    base_file = tmp_path / "provider.toml"
+    base_data = {"schema": "provider_v1", "name": "my-provider", "tier": "free"}
+    with open(base_file, "wb") as f:
+        tomli_w.dump(base_data, f)
+
+    # Create override TOML file
+    override_file = tmp_path / "provider.override.toml"
+    override_data = {"tier": "premium", "featured": True}
+    with open(override_file, "wb") as f:
+        tomli_w.dump(override_data, f)
+
+    data, file_format = load_data_file(base_file)
+
+    assert file_format == "toml"
+    assert data == {
+        "schema": "provider_v1",
+        "name": "my-provider",
+        "tier": "premium",  # overridden
+        "featured": True,  # added from override
+    }
+
+
+def test_load_data_file_with_nested_override(tmp_path: Path) -> None:
+    """Test loading file with nested dictionary override."""
+    import json
+
+    # Create base file with nested config
+    base_file = tmp_path / "config.json"
+    base_data = {
+        "schema": "config_v1",
+        "database": {"host": "localhost", "port": 5432, "name": "testdb"},
+        "cache": {"enabled": False},
+    }
+    with open(base_file, "w", encoding="utf-8") as f:
+        json.dump(base_data, f)
+
+    # Create override file with partial nested override
+    override_file = tmp_path / "config.override.json"
+    override_data = {"database": {"port": 3306, "ssl": True}, "cache": {"enabled": True}}
+    with open(override_file, "w", encoding="utf-8") as f:
+        json.dump(override_data, f)
+
+    data, file_format = load_data_file(base_file)
+
+    assert data == {
+        "schema": "config_v1",
+        "database": {
+            "host": "localhost",  # preserved from base
+            "port": 3306,  # overridden
+            "name": "testdb",  # preserved from base
+            "ssl": True,  # added from override
+        },
+        "cache": {"enabled": True},  # overridden
+    }