unitysvc-data 0.1.0__py3-none-any.whl

unitysvc_data/__init__.py

@@ -0,0 +1,119 @@
+"""Standard examples and presets for UnitySVC data packages.
+
+Pure-data package: ships example files under ``examples/`` organised by
+gateway and preset family, preset factories that return populated
+document records, and a JSON sentinel walker the sellers SDK calls at
+upload time. The same machinery is intended to serve other parts of the
+platform that need versioned, named references to bundled content.
+
+Preferred (preset-name) API:
+
+- :func:`doc_preset` — return a full document record for a preset,
+  from a bare name or a ``{"$preset": ..., "$with": {...}}`` sentinel.
+- :func:`file_preset` — return the raw UTF-8 content of a preset's
+  bundled example file.
+- :func:`list_presets` — enumerate every registered preset name
+  (versioned + aliases).
+- :data:`PRESETS` — mapping of preset name → factory function.
+- :data:`ALIASES` — mapping of version-less family name → latest
+  versioned preset name.
+- :data:`MANIFEST` — parsed ``_manifest.json`` content.
+- :data:`OVERRIDABLE` — fields that may be overridden in ``$with``.
+- :func:`register_jinja_globals` — expose every preset factory as a
+  Jinja2 global (for generated repos that render ``listing.json.j2``).
+
+Low-level (path-based) API — prefer the preset API above unless you
+specifically need to address files by their on-disk layout:
+
+- :func:`example_path`, :func:`read_example`, :func:`list_examples` —
+  resolve and read bundled example files by their path under
+  ``examples/``. These break if we ever reorganise the tree; preset
+  names don't.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files as _files
+from pathlib import Path
+
+from ._version import __version__
+
+_ROOT = _files(__name__).joinpath("examples")
+
+
+def example_path(name: str) -> Path:
+    """Return an absolute filesystem path for the bundled example *name*.
+
+    **Low-level.** Prefer :func:`file_preset` and :func:`doc_preset`
+    for anything that can key off a preset name — those are stable
+    across any future reorganisation of ``examples/``.
+
+    *name* is a path relative to ``examples/`` (e.g.
+    ``"s3/connectivity/connectivity-v1.py.j2"``). Raises
+    :class:`FileNotFoundError` if the file is not part of the
+    installed package.
+    """
+    target = _ROOT.joinpath(name)
+    if not target.is_file():
+        raise FileNotFoundError(f"Unknown example: {name!r}")
+    return Path(str(target))
+
+
+def read_example(name: str) -> str:
+    """Read the raw UTF-8 content of a bundled example by path.
+
+    **Low-level.** See :func:`example_path` for the name contract and
+    why :func:`file_preset` is usually the right choice.
+    """
+    return example_path(name).read_text(encoding="utf-8")
+
+
+def list_examples() -> list[str]:
+    """Return every bundled example filename, relative to ``examples/``.
+
+    **Low-level.** For enumerating presets by name, use
+    :func:`list_presets`. This function exposes on-disk paths
+    (including the gateway/family structure), which is rarely what a
+    consumer wants.
+
+    README files and hidden files are excluded.
+    """
+    root = Path(str(_ROOT))
+    return sorted(
+        path.relative_to(root).as_posix()
+        for path in root.rglob("*")
+        if path.is_file()
+        and path.name != "README.md"
+        and not path.name.startswith(".")
+    )
+
+
+# Imported last so presets.py can compute its own _EXAMPLES_ROOT without
+# reaching back into this module while __init__ is still loading.
+from .presets import (  # noqa: E402  (placement is deliberate)
+    ALIASES,
+    MANIFEST,
+    OVERRIDABLE,
+    PRESETS,
+    doc_preset,
+    file_preset,
+    list_presets,
+    register_jinja_globals,
+)
+
+__all__ = [
+    "__version__",
+    # Preferred preset API.
+    "doc_preset",
+    "file_preset",
+    "list_presets",
+    "PRESETS",
+    "ALIASES",
+    "MANIFEST",
+    "OVERRIDABLE",
+    "register_jinja_globals",
+    # Low-level path-based API.
+    "example_path",
+    "read_example",
+    "list_examples",
+]

unitysvc_data/_manifest.json

@@ -0,0 +1,91 @@
+{
+  "aliases": {
+    "api_connectivity": "api_connectivity_v1",
+    "llm_request_template": "llm_request_template_v1",
+    "s3_code_example": "s3_code_example_v1",
+    "s3_connectivity": "s3_connectivity_v1",
+    "s3_description": "s3_description_v1",
+    "smtp_connectivity": "smtp_connectivity_v1"
+  },
+  "presets": {
+    "api_connectivity_v1": {
+      "category": "connectivity_test",
+      "description": "Verify HTTP endpoint is reachable and returns a healthy status",
+      "example_file": "api/connectivity/connectivity-v1.sh.j2",
+      "is_active": true,
+      "is_public": false,
+      "meta": {
+        "output_contains": "connectivity ok"
+      },
+      "mime_type": "bash",
+      "preset_name": "api_connectivity",
+      "source_readme": "api/connectivity/README.md",
+      "version": 1
+    },
+    "llm_request_template_v1": {
+      "category": "request_template",
+      "description": "Minimal OpenAI-compatible chat completion request body",
+      "example_file": "llm/request-template/request-template-v1.json",
+      "is_active": true,
+      "is_public": false,
+      "meta": {},
+      "mime_type": "json",
+      "preset_name": "llm_request_template",
+      "source_readme": "llm/request-template/README.md",
+      "version": 1
+    },
+    "s3_code_example_v1": {
+      "category": "usage_example",
+      "description": "Python example: list objects in an S3 bucket via boto3",
+      "example_file": "s3/code-example/code-example-v1.py.j2",
+      "is_active": true,
+      "is_public": true,
+      "meta": {},
+      "mime_type": "python",
+      "preset_name": "s3_code_example",
+      "source_readme": "s3/code-example/README.md",
+      "version": 1
+    },
+    "s3_connectivity_v1": {
+      "category": "connectivity_test",
+      "description": "Verify S3 endpoint accepts the configured credentials",
+      "example_file": "s3/connectivity/connectivity-v1.py.j2",
+      "is_active": true,
+      "is_public": false,
+      "meta": {
+        "output_contains": "connectivity ok"
+      },
+      "mime_type": "python",
+      "preset_name": "s3_connectivity",
+      "source_readme": "s3/connectivity/README.md",
+      "version": 1
+    },
+    "s3_description_v1": {
+      "category": "description",
+      "description": "Customer-facing overview of the S3 gateway service",
+      "example_file": "s3/description/description-v1.md",
+      "is_active": true,
+      "is_public": true,
+      "meta": {},
+      "mime_type": "markdown",
+      "preset_name": "s3_description",
+      "source_readme": "s3/description/README.md",
+      "version": 1
+    },
+    "smtp_connectivity_v1": {
+      "category": "connectivity_test",
+      "description": "Verify SMTP server returns a 220 greeting on connect",
+      "example_file": "smtp/connectivity/connectivity-v1.sh.j2",
+      "is_active": true,
+      "is_public": false,
+      "meta": {
+        "output_contains": "connectivity ok"
+      },
+      "mime_type": "bash",
+      "preset_name": "smtp_connectivity",
+      "source_readme": "smtp/connectivity/README.md",
+      "version": 1
+    }
+  },
+  "version": "1"
+}

unitysvc_data/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

unitysvc_data/cli.py

@@ -0,0 +1,222 @@
+"""``usvc_data`` — browse and expand bundled presets from the shell.
+
+Subcommands:
+
+- ``usvc_data list`` — print every preset name (versioned + aliases).
+- ``usvc_data info <name>`` — print a preset's README prose (metadata
+  is shown on the list view / doc-preset output).
+- ``usvc_data doc-preset <name> [--with JSON]`` — print the expanded
+  document record as JSON on stdout.
+- ``usvc_data file-preset <name>`` — print the raw content of the
+  preset's bundled file on stdout. For ``.j2`` templates the raw
+  template source is returned — Jinja2 rendering is the caller's
+  responsibility (the sellers SDK does it per-listing).
+
+Example:
+
+    $ usvc_data doc-preset s3_connectivity --with '{"description": "ours"}'
+    {
+      "category": "connectivity_test",
+      "description": "ours",
+      ...
+    }
+    $ usvc_data file-preset s3_connectivity > /tmp/smoke.py
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from typing import Any
+
+from . import ALIASES, MANIFEST, PRESETS, __version__, doc_preset, file_preset
+
+# Matches a TOML front-matter block delimited by '+++' lines at the top
+# of a README. Mirrors the parser in tools/build.py.
+_FRONT_MATTER_RE = re.compile(r"^\+\+\+\s*\n(.*?)\n\+\+\+\s*\n", re.DOTALL)
+
+
+def _parse_with(value: str | None) -> tuple[dict[str, Any] | None, str | None]:
+    """Parse the ``--with`` JSON argument.
+
+    Returns ``(overrides, None)`` on success or ``(None, error_message)``
+    on failure. Callers print the error to stderr and return 1 — this
+    keeps error handling symmetric with the other subcommands (all
+    errors flow through the ``main()`` return value; no ``SystemExit``
+    bypass).
+    """
+    if value is None:
+        return {}, None
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        return None, f"--with must be a JSON object: {exc}"
+    if not isinstance(parsed, dict):
+        return None, f"--with must be a JSON object, got {type(parsed).__name__}"
+    return parsed, None
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    versioned = sorted(MANIFEST["presets"])
+    aliases = sorted(ALIASES)
+
+    if args.json:
+        json.dump(
+            {"versioned": versioned, "aliases": {a: ALIASES[a] for a in aliases}},
+            sys.stdout,
+            indent=2,
+            sort_keys=True,
+        )
+        sys.stdout.write("\n")
+        return 0
+
+    print(f"Versioned presets ({len(versioned)}):")
+    for name in versioned:
+        entry = MANIFEST["presets"][name]
+        print(f"  {name:40s}  {entry['category']:20s}  {entry['mime_type']}")
+    print()
+    print(f"Aliases ({len(aliases)}):")
+    for alias in aliases:
+        print(f"  {alias:40s}  -> {ALIASES[alias]}")
+    return 0
+
+
+def _cmd_info(args: argparse.Namespace) -> int:
+    """Print the README prose (front-matter stripped) for a preset."""
+    name = args.name
+    # Resolve via the same alias logic the runtime uses.
+    target = ALIASES.get(name, name)
+    entry = MANIFEST["presets"].get(target)
+    if entry is None:
+        print(
+            f"error: Unknown preset: {name!r}. Available: {sorted(set(MANIFEST['presets']) | set(ALIASES))!r}",
+            file=sys.stderr,
+        )
+        return 1
+
+    # source_readme is stored relative to examples/; resolve through
+    # the package's example_path so it works from any install layout.
+    from . import example_path
+
+    text = example_path(entry["source_readme"]).read_text(encoding="utf-8")
+    match = _FRONT_MATTER_RE.match(text)
+    prose = text[match.end():] if match else text
+    # Strip leading blank lines so the first visible line is the first
+    # heading / paragraph of the README.
+    sys.stdout.write(prose.lstrip("\n"))
+    if not prose.endswith("\n"):
+        sys.stdout.write("\n")
+    return 0
+
+
+def _cmd_doc_preset(args: argparse.Namespace) -> int:
+    overrides, err = _parse_with(args.with_json)
+    if err is not None:
+        print(f"error: {err}", file=sys.stderr)
+        return 1
+    try:
+        record = doc_preset(args.name, **overrides)
+    except (KeyError, ValueError, TypeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    indent = None if args.compact else 2
+    json.dump(record, sys.stdout, indent=indent, sort_keys=args.sort_keys)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _cmd_file_preset(args: argparse.Namespace) -> int:
+    try:
+        content = file_preset(args.name)
+    except (KeyError, ValueError, TypeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    # Write exactly what the file contains — don't add/trim a trailing
+    # newline. Consumers piping to a file should get byte-identical
+    # content to the bundled source.
+    sys.stdout.write(content)
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="usvc_data",
+        description="Browse and expand presets bundled with unitysvc-data.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    p_list = sub.add_parser("list", help="List every bundled preset.")
+    p_list.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    p_list.set_defaults(func=_cmd_list)
+
+    p_info = sub.add_parser(
+        "info",
+        help="Print the README prose for a preset.",
+        description=(
+            "Print the human-readable description of a preset — the "
+            "family README with its TOML front-matter stripped off. "
+            "Handy for browsing what a preset does without opening the "
+            "GitHub tree."
+        ),
+    )
+    p_info.add_argument("name", help="Preset name (versioned or alias).")
+    p_info.set_defaults(func=_cmd_info)
+
+    p_doc = sub.add_parser(
+        "doc-preset",
+        help="Print the expanded document record for a preset as JSON.",
+    )
+    p_doc.add_argument("name", help="Preset name (versioned or alias).")
+    p_doc.add_argument(
+        "--with",
+        dest="with_json",
+        metavar="JSON",
+        help=(
+            "Per-field overrides as a JSON object. "
+            "Allowed keys: description, is_active, is_public, meta."
+        ),
+    )
+    p_doc.add_argument("--compact", action="store_true", help="Emit single-line JSON.")
+    p_doc.add_argument(
+        "--sort-keys",
+        action="store_true",
+        help="Sort JSON keys for stable diffs.",
+    )
+    p_doc.set_defaults(func=_cmd_doc_preset)
+
+    p_file = sub.add_parser(
+        "file-preset",
+        help="Print the raw content of a preset's bundled example file.",
+        description=(
+            "Print the raw content of a preset's bundled example file. "
+            "For .j2 templates the output is the raw template source — "
+            "Jinja2 constructs like '{% if ... %}' are preserved verbatim "
+            "and are expected to be rendered later by the SDK with "
+            "per-listing context. Piping the result to an executable "
+            "file only works cleanly for non-.j2 presets."
+        ),
+    )
+    p_file.add_argument("name", help="Preset name (versioned or alias).")
+    p_file.set_defaults(func=_cmd_file_preset)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+# Silence unused-import warnings where PRESETS is only kept for debugging
+# at the REPL via ``python -m unitysvc_data.cli``.
+_ = PRESETS
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

unitysvc_data/examples/api/connectivity/README.md

@@ -0,0 +1,45 @@
++++
+preset_name = "api_connectivity"
+category = "connectivity_test"
+mime_type = "bash"
+file = "connectivity.sh.j2"
+description = "Verify HTTP endpoint is reachable and returns a healthy status"
+is_active = true
+is_public = false
+meta = { output_contains = "connectivity ok" }
++++
+
+# api / connectivity — generic HTTP connectivity test
+
+Bash smoke test for any HTTP-based service (echo relays, mock LLMs,
+proxy variants, any endpoint fronted by an HTTP gateway). The script
+`curl`s the endpoint and classifies the response.
+
+## Pass / fail classification
+
+| HTTP status | Verdict | Rationale |
+|-------------|---------|-----------|
+| 2xx, 3xx    | pass    | endpoint responding normally |
+| 401, 403    | pass    | endpoint is alive and enforcing auth |
+| 404         | fail    | wrong path — misconfigured |
+| 5xx         | fail    | upstream broken |
+| 000         | fail    | connect / DNS / timeout |
+
+## Environment variables
+
+Provided identically by the test harness in both local and gateway
+modes, so the script does not branch on `local_testing`:
+
+- `SERVICE_BASE_URL` — upstream URL (local) or gateway URL (online).
+- `UNITYSVC_API_KEY` — optional. Seller's upstream api key if present
+  in `upstream_access_config` (local mode), or the customer's gateway
+  key (online mode). Sent as `Authorization: Bearer ...` when set.
+
+## Versions
+
+### v1 — initial release
+
+- Classifies 2xx/3xx/401/403 as pass; 404/5xx/000 as fail.
+- Timeout: 5 seconds.
+- Works under `set -u` and `set -o pipefail` on bash 3.2 (macOS
+  default).

unitysvc_data/examples/api/connectivity/connectivity-v1.sh.j2

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Connectivity test for HTTP-based services (echo relay, mock LLM, proxy
+# variants). Verifies the endpoint is reachable AND serves a sensible
+# response. 404 / 5xx / DNS / timeout all count as failure.
+#
+# The harness sets the same env var names in both modes:
+#   $SERVICE_BASE_URL  — upstream URL (local) or gateway URL (online)
+#   $UNITYSVC_API_KEY  — upstream api_key if defined in upstream_access_config
+#                        (local), or the customer's gateway key (online)
+# Because the variable names are identical we don't branch on
+# local_testing for this test — the script works in both modes.
+set -o pipefail
+
+URL="${SERVICE_BASE_URL:?SERVICE_BASE_URL is not set}"
+
+# Split the curl invocation rather than expanding an empty array under
+# `set -u` (bash 3.2 on macOS raises on "${arr[@]}" when arr is empty).
+if [ -n "${UNITYSVC_API_KEY:-}" ]; then
+    status=$(curl -sS --max-time 5 \
+        -H "Authorization: Bearer ${UNITYSVC_API_KEY}" \
+        -o /dev/null -w "%{http_code}" "$URL" 2>/dev/null)
+else
+    status=$(curl -sS --max-time 5 \
+        -o /dev/null -w "%{http_code}" "$URL" 2>/dev/null)
+fi
+
+# Accept 2xx/3xx (alive) and 401/403 (alive, auth challenge).
+# Reject 000 (connect/DNS failure), 404 (wrong path), 5xx (broken).
+case "$status" in
+  2??|3??|401|403)
+    echo "connectivity ok (HTTP $status)"
+    exit 0
+    ;;
+  000)
+    echo "connectivity failed: could not connect to $URL" >&2
+    exit 1
+    ;;
+  *)
+    echo "connectivity failed: HTTP $status from $URL" >&2
+    exit 1
+    ;;
+esac

unitysvc_data/examples/llm/request-template/README.md

@@ -0,0 +1,50 @@
++++
+preset_name = "llm_request_template"
+category = "request_template"
+mime_type = "json"
+file = "request-template.json"
+description = "Minimal OpenAI-compatible chat completion request body"
+is_active = true
+is_public = false
++++
+
+# llm / request-template — minimal chat completion payload
+
+Canonical JSON request body for OpenAI-compatible chat completion
+services routed through the UnitySVC LLM gateway. Suitable as a test
+payload for seller-side validation, and as `request_template`
+metadata attached to a listing.
+
+## Body
+
+```json
+{
+  "max_tokens": 100,
+  "messages": [
+    { "role": "system", "content": "You are a helpful assistant." },
+    { "role": "user",   "content": "Say hello in one sentence." }
+  ]
+}
+```
+
+## What's intentionally missing
+
+- **No `model` field.** The gateway's routing config or the listing's
+  `upstream_access_config` selects the upstream model; hard-coding
+  one here would tie the template to a specific service.
+- **No `stream` field.** Non-streaming responses are simpler to
+  validate in tests; streaming variants belong in separate presets.
+
+## Conventions
+
+- `max_tokens` is kept small (≤ 100) so the request completes fast
+  against any upstream regardless of per-token latency.
+- Response format is standard OpenAI `chat.completions`. Tests should
+  assert `choices[0].message.content` exists and is non-empty.
+
+## Versions
+
+### v1 — initial release
+
+- Two messages (system + user), `max_tokens = 100`, no model field,
+  non-streaming.

unitysvc_data/examples/llm/request-template/request-template-v1.json

@@ -0,0 +1,13 @@
+{
+  "max_tokens": 100,
+  "messages": [
+    {
+      "content": "You are a helpful assistant.",
+      "role": "system"
+    },
+    {
+      "content": "Say hello in one sentence.",
+      "role": "user"
+    }
+  ]
+}

unitysvc_data/examples/s3/code-example/README.md

@@ -0,0 +1,49 @@
++++
+preset_name = "s3_code_example"
+category = "usage_example"
+mime_type = "python"
+file = "code-example.py.j2"
+description = "Python example: list objects in an S3 bucket via boto3"
+is_active = true
+is_public = true
++++
+
+# s3 / code-example — list objects via boto3
+
+Customer-facing primary example for S3 gateway services. Lists up to
+five objects from the bucket using `boto3` and prints their keys.
+
+## Branches (rendered at upload time with the listing context)
+
+| `local_testing` | `interface.access_key` | Behaviour |
+|-----------------|------------------------|-----------|
+| `true`          | present                | Uses seller credentials + optional `S3_ENDPOINT`. |
+| `true`          | absent                 | Unsigned `boto3` client against a public bucket. |
+| `false`         | —                      | Gateway-routed with the customer's `UNITYSVC_API_KEY`. |
+
+## Environment variables (local mode)
+
+- `REGION`, `ACCESS_KEY`, `SECRET_KEY` — seller credentials (only when
+  `interface.access_key` is set).
+- `S3_ENDPOINT` — optional, for non-AWS S3.
+- `BUCKET` — bucket to list.
+- `BASE_PATH` — optional prefix; stripped from printed keys.
+
+## Environment variables (gateway mode)
+
+- `SERVICE_BASE_URL` — split on `/` to extract `endpoint_url` and
+  `bucket`.
+- `UNITYSVC_API_KEY` — used as `aws_access_key_id`.
+
+## Conventions
+
+- Ends with `print("connectivity ok")` so the same script is usable as
+  a smoke test if a seller wants to reuse it.
+- Prints `<key>  (<size> bytes)` per object, up to five.
+
+## Versions
+
+### v1 — initial release
+
+- Three-branch (seller creds / unsigned / gateway) rendering based on
+  `local_testing` and `interface.access_key`.

unitysvc_data/examples/s3/code-example/code-example-v1.py.j2

@@ -0,0 +1,48 @@
+import boto3
+import os
+{% if local_testing %}
+{% if interface.get("access_key") %}
+# Local testing: access S3 with seller credentials
+s3_kwargs = {
+    'region_name': os.environ['REGION'],
+    'aws_access_key_id': os.environ['ACCESS_KEY'],
+    'aws_secret_access_key': os.environ['SECRET_KEY'],
+}
+# Use S3_ENDPOINT for non-AWS endpoints (DigitalOcean Spaces, MinIO, etc.)
+if os.environ.get('S3_ENDPOINT'):
+    s3_kwargs['endpoint_url'] = os.environ['S3_ENDPOINT']
+s3 = boto3.client('s3', **s3_kwargs)
+{% else %}
+from botocore import UNSIGNED
+from botocore.config import Config
+
+# Local testing: access public S3 bucket directly (no authentication needed)
+s3 = boto3.client('s3',
+    region_name=os.environ['REGION'],
+    config=Config(signature_version=UNSIGNED),
+)
+{% endif %}
+bucket = os.environ['BUCKET']
+prefix = os.environ.get('BASE_PATH', '')
+{% else %}
+# Access via UnitySVC S3 gateway
+service_url = os.environ['SERVICE_BASE_URL']
+endpoint_url = service_url.rsplit('/', 1)[0]
+bucket = service_url.rsplit('/', 1)[1]
+prefix = ''
+
+s3 = boto3.client('s3',
+    endpoint_url=endpoint_url,
+    aws_access_key_id=os.environ['UNITYSVC_API_KEY'],
+    aws_secret_access_key='not-used',
+)
+{% endif %}
+
+# List files in the bucket
+response = s3.list_objects_v2(Bucket=bucket, MaxKeys=5, Prefix=prefix)
+for obj in response.get('Contents', []):
+    key = obj['Key']
+    if prefix and key.startswith(prefix):
+        key = key[len(prefix):]
+    print(f"{key}  ({obj['Size']} bytes)")
+print("connectivity ok")