docs/asset-engine: promote services.yaml to first-class contract

Adds the supporting infra around the service catalog now that it
has external consumers (the asset_engine UI being the first; CLIs,
monitoring, other services may follow):

- CATALOG-CONTRACT.md: the consumer-facing contract. Defines
  versioning policy (catalog_version vs per-service version),
  closed field-type and response-type vocabularies, recommended
  vendor+drift-check sync workflow, known-consumers list, service
  authoring notes.
- services.schema.json: JSON Schema (draft 2020-12) for the
  catalog. Generated from the Pydantic model in
  ~/development/asset_engine/src/asset_engine/catalog.py via
  `uv run scripts/dump_schema.py --publish`. Lets non-Python
  consumers validate against the same shape.
- services.yaml: adds catalog_version: 1 at the root and reframes
  the file's header to call out its first-class-contract status.
  Quotes a vibevoice label that contained an unescaped colon
  (caught by the asset_engine's strict YAML parser on first sync).
This commit is contained in:
vh
2026-05-11 08:57:35 -07:00
parent 8d8d45b7ca
commit 0157066d6e
3 changed files with 789 additions and 10 deletions
+17 -10
View File
@@ -1,15 +1,22 @@
# services.yaml — inference services catalog on irv-ml1
# services.yaml — canonical catalog of inference services on irv-ml1
#
# Drives the forthcoming asset-generation UI: each entry produces one
# form (auto-generated from `fields:`) and one response renderer
# (dispatched on `response.type`).
# THIS IS A FIRST-CLASS CONTRACT. External consumers depend on the
# shape and contents of this file. See CATALOG-CONTRACT.md alongside
# for: schema reference, change-management policy, sync workflow for
# downstream consumers, and known consumers list.
#
# Generated by an Explore-agent pass over stacks/<service>/{README.md,
# compose.yaml,.env.example,server.py|infer-api.py}. Pydantic models
# in code are the ground truth where they disagree with READMEs.
# Drives form generators that auto-render UIs against the inference
# services. Each entry produces one form (from `fields:`) and one
# response renderer (dispatched on `response.type`). The field-type
# vocabulary and response-type vocabulary are closed sets — see the
# JSON Schema at services.schema.json or the contract doc.
#
# Schema is v1; bump per-service `version:` when fields change so old
# Asset rows can still be interpreted.
# `catalog_version`: bump when the SCHEMA changes (a field type added,
# a required field removed, etc). Per-service `version:` bumps when a
# specific service's parameter shape changes. Both let downstream
# consumers detect drift.
catalog_version: 1
services:
- id: kokoro
@@ -438,7 +445,7 @@ services:
default: vibevoice
- name: input
type: textarea
label: Text (or Speaker N: ... script)
label: "Text (or Speaker N: ... script)"
required: true
description: >
Single-speaker: plain text. Multi-speaker: "Speaker 0: ...\nSpeaker 1: ..."