4.7 KiB
Use one Installation Model Catalog with runtime projections
ThothII currently declares model availability independently in installation
metadataGeneration, Pi configuration, and workspace llm_policy and embedding settings. The
Installation Model Catalog in thothii-installation.yaml becomes the sole authored authority for
session, metadata-generation, and embedding models, including their allowed usages and per-usage
defaults. Workspace descriptors retain database identity and scope plus Evidence concerns, but no
model policy or selection; installation-local Database Bindings remain separate from them.
Pi, the backend metadata-generation helper, and the embedding runtime consume generated Model Runtime Projections of that catalog. Runtime Model Selection stores only a canonical catalog model identity and use-specific controls such as thinking level; endpoint, provider, capabilities, and credential references remain catalog facts, while secret values remain in protected secret stores. The metadata-generation helper continues to use LiteLLM independently of Pi, as established by ADR-0009: unifying model declaration does not unify execution lifecycles.
The migration is intentionally fail-closed. Workspace schema v4 removes llm_policy and the
entire redundant semantic_index; collection identity is derived from the workspace identity,
while vector-store and embedding facts come from the installation. A deterministic migration
rewrites existing descriptors. The
installation loader replaces metadataGeneration with modelCatalog and rejects the legacy form
with an actionable migration error rather than keeping two live sources. Existing Pi
models.json and enabled-model settings become generated artifacts and are never edited as
authoritative configuration.
Catalog identities use the canonical provider/model form; runtime-specific upstream names are
adapter facts, not additional ThothII identities. Installation descriptors use schema version 2
and model-free workspace descriptors use schema version 4. Removing a model never substitutes it
inside an existing session: an unresolvable resume fails explicitly. Published semantic indexes
record the embedding identity and dimensions that produced them and require explicit
reprocessing when those facts change.
Model eligibility is expressed by the presence of a session or metadataGeneration block,
without a duplicate usages list. The installation declares one active embedding identity and its
dimensions rather than a selectable embedding catalog. Runtime projections are regenerated
deterministically and atomically at start, so they require no persisted digest and are excluded
from installation backups; restore regenerates them from the validated installation descriptor.
A provider owns one endpoint, one explicit authentication mode, and only the runtime adapters it needs. Authentication is either a protected secret-environment reference, Pi-owned authentication for session-only built-in models, or explicit keyless operation for an explicit endpoint; models cannot override it. Pi built-in model facts are not copied into the installation. A session default and the single embedding definition are required, while metadata generation and its default may be omitted together. The schema deliberately excludes unused abstractions and future properties until runtime behavior requires them.
The catalog session default replaces PI_PROVIDER, PI_MODEL, and persisted installation model
defaults as configuration sources. A user or session selection is only a canonical catalog
reference, and an existing session keeps that reference without silently switching models. A
generated Compose projection supplies the catalog-derived embedding values and projection mounts
to every affected service, so neither the base Compose files nor operator.env repeat model facts.
Workspace v3-to-v4 migration is a deterministic removal of llm_policy and semantic_index.
Installation migration instead inspects the legacy installation metadata block and both Pi model
files: it emits a v2 candidate only when their identities and settings can be reconciled without
guessing. Conflicts produce an actionable report and leave every source untouched.
Considered Options
- A separate catalog file referenced by the installation was rejected because it adds path, permission, backup, and atomic-update coordination without a current need for cross-installation sharing.
- Pi
models.jsonwas rejected as the authority because it is a Pi-specific projection that does not express all ThothII usages, built-in providers, metadata-generation controls, or embedding facts. - Transitional dual reading was rejected because it would preserve the configuration discrepancy this decision is intended to eliminate.