unitysvc-core
Shared data models, JSON schemas, and validation helpers for the UnitySVC ecosystem. This package is audience-neutral: it contains only the foundational types and helpers that are consumed by the UnitySVC backend, the customer SDK, the admin CLI, and the seller SDK.
It intentionally does not include any CLI, HTTP client, or audience-specific helpers. Those live in the corresponding packages:
unitysvc-sellers— seller SDK +usvc_sellerCLI, catalog builders (populate_from_iterator,render_template_file,convert_convenience_fields_to_documents, etc.)unitysvc— customer SDK +usvcCLIunitysvc-admin— admin CLI
What's inside
src/unitysvc_core/
├── models/
│ ├── base.py # All enums (status, type, currency, rate-limit, etc.)
│ ├── pricing.py # PriceStr, UsageData, all *PriceData classes,
│ │ # Pricing union, validate_pricing, cost calculation
│ ├── documents.py # DocumentData
│ ├── service.py # RateLimit, ServiceConstraints, AccessInterfaceData,
│ │ # UpstreamAccessConfigData
│ ├── validators.py # validate_name, validate_service_options,
│ │ # suggest_valid_name, SUPPORTED_SERVICE_OPTIONS
│ ├── provider_v1.py # Provider file schema + ProviderData
│ ├── offering_v1.py # Offering file schema + ServiceOfferingData
│ ├── listing_v1.py # Listing file schema + ServiceListingData
│ ├── promotion_v1.py # Promotion file schema + PromotionData
│ └── service_group_v1.py
├── schema/ # Generated JSON schemas (run scripts/generate_schemas.py; CI enforces sync)
├── validator.py # DataValidator — per-file schema validation,
│ # union-field reference checks, API-key secret
│ # scanning, Jinja2 syntax validation, etc.
└── utils.py # Content hashing, mime/extension helpers,
# data file loaders (JSON/TOML + overrides),
# schema-based file discovery
What's deliberately NOT here
- CLI code —
typer,rich, no entry points - HTTP clients — no
httpx, no API wrappers - Seller catalog builders —
populate_from_iterator,render_template_file,convert_convenience_fields_to_documents,execute_script_contentlive inunitysvc-sellers - Seller-catalog-layout validation —
validate_provider_status,validate_all_service_directories,resolve_provider_name,resolve_service_name_for_listinglive inunitysvc-sellers
Installation
pip install unitysvc-core
Dependencies: pydantic, email-validator, jsonschema, jinja2,
tomli-w. No typer, no rich, no httpx.
Usage
from pathlib import Path
import unitysvc_core
from unitysvc_core.models import ProviderV1, OfferingV1, ListingV1
from unitysvc_core.models.pricing import UsageData, validate_pricing
from unitysvc_core.validator import DataValidator
# Validate a single catalog directory
validator = DataValidator(
data_dir=Path("./catalog"),
schema_dir=Path(unitysvc_core.__file__).parent / "schema",
)
results = validator.validate_all()
# Typed pricing + cost calculation
pricing = validate_pricing({
"type": "one_million_tokens",
"input": "0.50",
"output": "1.50",
})
cost = pricing.calculate_cost(UsageData(input_tokens=1_000, output_tokens=500))
History
This package was split out of unitysvc-services (see
unitysvc/unitysvc-services#99).
The seller CLI, catalog builders, and seller-catalog-layout validators
moved to unitysvc-sellers.
License
MIT
Required enrollment parameter usage
The shared validator rejects required user parameters that no channel, interface,
or document consumes. Only those consumer fields count — the offering's
upstream_access_config, the listing's user_access_interfaces, and document
content (a .j2 document's template source, which the seller validator reads from
disk as the SDK uploads it); metadata such as display_name or description is
never rendered with params. File validation checks a listing against its paired offering
when present; backend ingest calls the same validate_required_parameter_usage
helper with the complete listing and offering. Schema declarations alone are not
consumers. Jinja attribute access, string-key lookups, and params.get("name")
are inspected; dynamic access and whole-map iteration conservatively consume all
parameters. Deprecated content can still be retired.
This validates usage, not channel attribution: a document reference counts as a consumer without proving that the intended paid channel takes enrollment.
Canonical user access interfaces
A user access interface is the service's canonical address, the same for every caller, so validate_listing_interfaces_are_canonical refuses one that reads a per-enrollment value (enrollment.*, params.*). An enrollment is reached through the address the platform gives it: /e/<CODE> on the API gateway, which a listing never declares. The only per-enrollment form allowed is where the protocol has no such path and the code itself is the address: an SMTP routing_key.username or an S3 bucket segment that is exactly {{ enrollment.code }}. Values the same for every caller (service_name, routing_vars) stay allowed. The shared validator runs it on every listing_v1; backend ingest calls the same function (unitysvc/unitysvc#2726).
Listing audience
A listing may say who the service is for and what a buyer must know before enrolling, as audience: a short list of plain-text phrases (unitysvc/unitysvc#2717):
"audience": [
"Rice University students (enrollment at Rice required)",
"US customers only / export restrictions may apply"
]
At most 8 phrases, each 1-120 characters after trimming, no URLs or markup (details belong in the description or documents), and no phrase twice. The phrases are shown before enrollment and read by assistants matching services to customers; the platform never enforces them. capabilities says what a service does; audience says who it is for.
Exports and customer access requests
Three stages (unitysvc/unitysvc#2720): a target service's exports (what it exposes), a seller's customer_access_requests (what the seller asks the enrolling customer to approve: using other services through that customer's account and authority), and the issued key's policy (what the customer actually approved). There is no central list of services. unitysvc_core.grants holds the formats and the checks; it does no I/O.
Invariant. Calls made under an approved request run under the enrolling customer's delegated identity, within the approved permissions, options and limits. Looking up a target's exports validates a request's capabilities; customer consent and key issuance establish its authority. A request grants nothing by itself.
1. The exports format (the offering, top level). How other services may use this one:
"exports": {
"permissions": {"read": ["GET /records/*"], "write": ["POST /records", "PUT /records/*"]},
"options": {
"type": "object",
"properties": {
"log_level": {"type": "string", "enum": ["debug", "info", "warn", "error"], "default": "info",
"title": "Lowest level recorded"},
"max_size": {"type": "integer", "minimum": 1, "maximum": 10000}
}
},
"options_ui_schema": {"log_level": {"ui:widget": "radio"}}
}
- Without
permissions(most services, including one that declares onlyoptions), the service exports one permission,invoke, on every route ("* /*");service:<name>and theservice:*wildcard grant it. - With
permissions, the service exports exactly those, andinvokeonly if it declares it too. A data service (me,log,needs) declaresread/writeand noinvoke: it holds the customer's own data, so only a grant that names its permissions reaches it, neverinvokeor a wildcard. permissions: a name (lowercase letters, digits and_) → the routes it covers, each"<METHOD> /<path>"(*for any method,*globs in the path). Permissions are never inferred from HTTP methods.options: a JSON Schema (draft 7) object of the customizations a grant may set on the service, like an enrollment'suser_parameters_schema, with an optional react-jsonschema-formoptions_ui_schema; the frontend renders it with the same form component. It covers limits only the service can apply (a message size). Restrictions so a grant can write every value in query-string syntax: property names are lowercase letters, digits and_; each property is astring,integer,number,booleanor anarrayof strings, serialized as an OpenAPI form-style query parameter with arrays comma-joined (style: form, explode: false); options are optional (norequired) and only declared properties are accepted; the schema is self-contained (no$ref), so validating against it never fetches anything. A property'sdefaultis what the service does when the policy does not set the option.
2. A customer access request (upstream_access_config.<channel>.customer_access_requests), and the policy entry it becomes. Any channel may declare its own list; each approved request becomes an entry (a grant) in the issued key's policy, in the same shape:
"customer_access_requests": [{"object": "service:log", "permissions": ["invoke"], "required": true,
"justification": "Records each check you run",
"options": "log_level=warn",
"limits": {"count_per_day": 1000}}]
objectnames one service (service:<name>, no wildcards).enrollment:<CODE>(one enrollment of an enrollable service) may be allowed later.optionsis written in query-string syntax (parse_options; a notation, not how options are delivered): each name once, each value non-empty; with a catalog, each value is converted to its declared type and validated against the target'soptionsschema.- Enrollment is where options and limits are set. In a request,
optionsandlimitsonly pre-fill the enrollment form for convenience. When enrolling, the customer confirms and sets the options (a form rendered from the target'soptionsschema) and the limits, and adds their own limits; the result is the issued key's policy. limits(validate_limits):count_per_hour/count_per_day/count_per_month/count_total(positive integer) and the same foramount_(finite positive decimal, as a number or a string). Limits are universal: the platform meters every call, so any service can be limited without exporting anything. The seller's limits are a pre-fill; the customer sets them at enrollment, and an enrollment's own limits (unitysvc/unitysvc#2687) use the same shape. They are counted per policy entry (the enrollment's calls to that service) from the usage stream (counters keyed by scope, metric and window bucket), and the gateway refuses calls once one is exceeded.
3. How options reach the service. Not through the upstream URL: the gateway never changes a target's base_url or query to carry policy. How an option is applied is up to the service's implementation:
- A service implemented in the gateway (
me,log,ai,notify,email,bill) reads the calling key's policy from the routing context and applies the option itself (megives values only for the grant'sprofilepaths;logwould drop entries below a grant'slog_level). - A proxied service can only be influenced through its own upstream's interface, so it applies an option only where its configuration maps it into the upstream request in a form that upstream understands, for example a request transformer setting a body field. Until such a mapping exists, options are enforced by gateway-implemented services only.
- The policy itself never reaches a seller: a seller's upstream sees at most the effect of an option, in its own vocabulary.
- An option the policy does not set takes the service's
default. A plainservice:*key sets none. - Enrollment parameters are unchanged and keep working alongside:
{{ params.X }}still renders into the channel config.
4. Where exports are published. In the public catalog bundle: every service row carries its exports exactly as declared (null when none). GET /v1/catalog/bundle returns the bundle's URL; a service:<name> is the row whose name is <name>.
5. Validating customer_access_requests. validate_channel_access_requests(upstream_access_config, resolve) checks every channel's requests. Limits need no lookup. Every claim's permissions and options, invoke included (a service that declares permissions may not export it), are looked up: resolve(name) returns the target's exports from the catalog ({} when it declares none) or None when no such service is published; core parses it with parse_exports and checks the claimed permissions and the options (names, then values against its options schema) against it, refusing an unpublished target. Without a resolver only the shape is checked.
DataValidator(data_dir, schema_dir, exports_resolver=...)runs both checks on everyoffering_v1(exportsand each channel'scustomer_access_requests). The seller SDK passes a resolver that downloads the catalog bundle once and reads the target row'sexports; offline it passes none and gets the shape checks.- Backend ingest calls the same function with a resolver over the published services, so an unknown target, permission or option fails at upload.
Enrollment parameters on channels
A channel may declare its own enrollment parameters, so each plan of a service asks for what it needs (unitysvc/unitysvc#2726):
"upstream_access_config": {
"plus": {
"base_url": "https://u/{{ params.folder }}",
"params": {
"schema": {"type": "object", "properties": {"folder": {"type": "string"}}, "required": ["folder"]},
"ui_schema": {},
"testing_defaults": {"folder": "ops"}
}
}
}
params.schema is a JSON Schema of the parameters (a property's own default pre-fills the customer's form), params.ui_schema holds form hints, and params.testing_defaults holds the values the platform tests the channel with. Once any channel declares params:
- a channel reads only the parameters its
params.schemadeclares, and a channel that reads{{ params.* }}must declare its ownparams(validate_channel_parameters, on everyoffering_v1); - each required parameter has a value in that channel's
params.testing_defaults; - each required parameter is read by its own channel or by document content; another channel's use does not count (
validate_required_parameter_usage, which backend ingest also calls); - the listing must not also declare
user_parameters_schema.
When no channel declares params, the listing-level user_parameters_schema applies to the whole service as before.
Metadata
Release files for unitysvc-core 0.2.37
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| unitysvc_core-0.2.37.tar.gz | 166.2 kB | With provenance | Details for unitysvc_core-0.2.37.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| unitysvc_core-0.2.37-py3-none-any.whl | Python 3 | none | any | Details for unitysvc_core-0.2.37-py3-none-any.whl |
Total release size: 295.1 kB
Release files / unitysvc_core-0.2.37.tar.gz
| Download URL | unitysvc_core-0.2.37.tar.gz |
|---|---|
| Size | 166.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2a09e3a22c0d559f7ff4ad030949b70f837f6af3a962a09b3af497b2412746c0
|
|
BLAKE2b-256 checksum How to use checksums |
4e186b80289e7e3422d810cf17b10e1939106babe7a235ec00b524753feaefa6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logRelease files / unitysvc_core-0.2.37-py3-none-any.whl
| Download URL | unitysvc_core-0.2.37-py3-none-any.whl |
|---|---|
| Size | 128.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0af93b486b819afac145e8b52a688f9bc4df8ef85098124ecb6f2753fecdbcc2
|
|
BLAKE2b-256 checksum How to use checksums |
bbe3f452258cb059968d5944a1d865041ece91e7d6ef90434838aad7721a0690
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logSecurity for unitysvc-core 0.2.37
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for unitysvc_core-0.2.37.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.