ThothII/docs/plans/2026-09-02-installation-model-catalog.md

Installation Model Catalog

Status: implemented on 2026-09-02.

Outcome

thothii-installation.yaml is the only operator-authored source for models used by interactive sessions, metadata generation, and embedding. Runtime-specific files are deterministic projections, not additional configuration sources. Workspace descriptors contain database and Evidence concerns and no model, provider, allowlist, default, embedding, or vector-store configuration.

This design does not merge execution lifecycles. Pi continues to run interactive sessions, the short-lived LiteLLM helper continues to perform metadata generation, and the internal Ollama service continues to provide embeddings. They share model declaration, not execution machinery.

Canonical installation shape

The following example covers all currently required cases: a Pi built-in model, an authenticated custom endpoint, a keyless internal endpoint, metadata generation, and the single embedding model.

schemaVersion: 2
profile: server
projectDirectory: /srv/thothii
envFile: /srv/thothii/operator.env

workspaceRepository:
  remote: git@git.example.com:organization/workspaces.git
  branch: main
  access: ssh

modelCatalog:
  defaults:
    session: zai/glm-5.3
    metadataGeneration: local-qwen/qwen3.6-35b-a3b

  embedding:
    id: ollama/qwen3-embedding:0.6b
    dimensions: 1024

  providers:
    deepseek:
      authentication:
        mode: pi_auth
      session:
        mode: pi_builtin
      models:
        deepseek-v4-pro:
          session: {}
        deepseek-v4-flash:
          session: {}

    zai:
      endpoint:
        baseUrl: https://api.z.ai/api/coding/paas/v4
      authentication:
        mode: secret_env
        apiKeyEnv: ZAI_API_KEY
      session:
        mode: openai_compatible
      metadataGeneration:
        litellmProvider: openai
      models:
        glm-5.3:
          label: GLM-5.3
          session:
            reasoning: true
            contextWindow: 200000
            maxTokens: 131072
          metadataGeneration: {}

    local-qwen:
      endpoint:
        baseUrl: https://ml-aritmolab.policlinicosandonato.it/v1
      authentication:
        mode: none
      session:
        mode: openai_compatible
      metadataGeneration:
        litellmProvider: openai
      models:
        qwen3.6-35b-a3b:
          label: Qwen3.6 35B A3B
          session:
            reasoning: false
            contextWindow: 131072
            maxTokens: 16384
            compatibility:
              supportsDeveloperRole: false
              supportsReasoningEffort: false
              supportsStore: false
              maxTokensField: max_tokens
          metadataGeneration:
            disableThinking: true

authentication:
  configDirectory: /srv/thothii/auth-canonical
  runtimeProjection:
    directory: /srv/thothii/auth-runtime
    uid: 10001
    gid: 10001

The catalog uses maps instead of repeated IDs. The canonical identity of a model is always derived as <provider-key>/<model-key>. upstreamModel may be added to a model only when the endpoint uses a different identifier. label is optional and falls back to the canonical identity.

Model eligibility is not repeated in an usages array. A session block makes the model eligible for sessions; a metadataGeneration block makes it eligible for metadata generation. The embedding is a single required installation value rather than a list plus default.

Provider and authentication rules

A provider owns one endpoint, one authentication mode, and zero or one adapter for each runtime. Model entries cannot override provider endpoint or credentials. If the same upstream service needs different endpoints or credentials, the installation declares two provider identities.

Supported session modes are intentionally closed:

• pi_builtin: Pi already owns the model's technical descriptor; the model's session block is empty and ThothII does not copy context-window or compatibility facts.
• openai_compatible: ThothII generates a Pi custom-provider descriptor; each session model supplies the technical values required by Pi.

Metadata generation uses the provider-level litellmProvider. A model-level metadataGeneration.disableThinking: true is permitted only for an explicit compatible endpoint. There is no generic adapter or plugin abstraction in schema version 2.

Exactly one provider authentication mode is allowed:

• secret_env requires an approved API-key environment reference present in the protected secret bundle. Secret values never enter YAML, generated files, logs, arguments, or API responses.
• pi_auth is valid only for session-only pi_builtin providers and resolves through Pi's protected authentication projection.
• none is valid only for an explicit endpoint. Runtime projections may supply a fixed non-secret compatibility placeholder when a client library requires a non-empty key.

Defaults and selections

defaults.session and embedding are required. defaults.metadataGeneration is required exactly when at least one model has a metadataGeneration block; metadata generation may otherwise be absent and its UI controls are disabled.

modelCatalog.defaults.session is the only configured session-model default. PI_PROVIDER, PI_MODEL, and provider/model fields in installation-default settings are removed. A user choice is a Model Selection containing only the canonical model identity and runtime controls such as thinking level. A session manifest pins the selected canonical identity.

Removing the currently selected model causes new-session selection to fall back to the catalog default with an explicit administrative warning. An existing session is never silently moved to a different model; resume fails with model_unavailable when its pinned identity can no longer be resolved.

Generated runtime projections

Before Compose starts, tht strictly validates schema version 2 and generates installation-local artifacts below deploy/<installation-id>/generated/:

• a normalized catalog JSON consumed defensively by the backend;
• Pi models.json for custom providers;
• Pi settings.json, combining fixed product settings with the session-eligible canonical IDs;
• a Compose override that mounts the projections and supplies embedding identity and dimensions to core, preprocessing, and embedding-model-init.

Generation is deterministic and published only after every candidate artifact validates. A failed generation aborts start before Compose is invoked. tht doctor recomputes expected bytes and reports differences; no digest manifest or separate apply command exists. When projection bytes change, tht start recreates the affected services so they cannot continue with an older bind mount. Pi-only restart, update, and rollback operations reject projection drift and direct the operator to tht start, because applying only the core-facing files could leave embedding services stale.

Generated projections are not backed up. Restore validates the canonical installation descriptor, regenerates every projection, and only then starts services. Base Compose files and operator.env must contain no model identities, defaults, endpoints, or dimensions.

Workspace schema v4

Workspace schema v4 removes both top-level llm_policy and semantic_index. The entire latter block is redundant today: its engine and distance are product constants, its collection duplicates the workspace ID, and its model and dimensions are installation facts.

The runtime derives:

• Qdrant collection identity from the workspace ID;
• engine and distance from the supported product contract;
• embedding identity and dimensions from the Installation Model Catalog.

The published index generation records the canonical embedding identity and dimensions that created it. A mismatch makes the index explicitly incompatible and requires operator-triggered preprocessing. No existing index is deleted or rebuilt automatically.

The v3-to-v4 workspace migration is deterministic: set workspace.schema_version to 4, remove llm_policy, and remove semantic_index. It does not alter database, Evidence, diagnostics, or binding data.

Installation migration

Legacy installation migration must inspect all three former sources:

1. metadataGeneration in thothii-installation.yaml;
2. deploy/pi/models.json;
3. deploy/pi/settings.json.

The migrator emits a version-2 candidate only when it can reconcile identities, endpoints, credentials, and runtime-specific facts without guessing. Ambiguous aliases such as glm-53, zai/glm-5.3, and openai/glm-5.3 are not silently equated. A conflict produces a field-level report and leaves every input unchanged for operator resolution.

After migration, the strict loader rejects metadataGeneration, workspace llm_policy, workspace semantic_index, legacy Pi source files, unknown fields, duplicate YAML keys, invalid defaults, and incompatible authentication/adapter combinations with an actionable migration_required or validation error.

Final simplicity audit

The accepted design removes every configuration duplication that can be removed without inference:

• one authored installation file instead of an installation block plus two Pi files;
• one canonical provider/model identity instead of display IDs and runtime IDs;
• per-use blocks instead of a duplicated usages list;
• one embedding entry instead of a selectable embedding catalog;
• one catalog session default instead of environment and settings defaults;
• no model or vector-store fields in workspace descriptors;
• provider-level credentials instead of per-model credentials;
• no generic runtime-plugin abstraction;
• no persisted digest, apply command, or backup of generated projections.

The remaining generated files are necessary boundary adapters, not configuration concepts. Making the backend parse the authoring YAML independently would remove one file but restore two semantic validators. Hard-coding embedding values in Compose would remove one projection but restore a model source outside the catalog. Inferring authentication from missing fields would save one YAML key but turn a safe explicit choice into ambiguity. These apparent simplifications are therefore rejected.

No further reduction was found that preserves one authority, strict validation, explicit security, session determinism, and model-free workspaces.

Implementation surface

Implementation must update the host tht installation loader, setup and lifecycle projection, doctor, backup/restore, Compose mounts and embedding inputs, backend catalog/settings/session model resolution, workspace schema and migration, runtime rendering and diagnostics, frontend workspace drafts and model filtering, examples, fixtures, and documentation. Existing session manifests remain readable and keep their pinned provider/model identity; only resume resolution changes to the new catalog.

Implementation completed after explicit approval. The installation schema, deterministic runtime projections, migration path, model-free workspace schema v4, backend consumers, operator UI, fixtures, and documentation now enforce this contract.