68 lines
4.7 KiB
Markdown
68 lines
4.7 KiB
Markdown
# 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.json` was 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.
|