feat: establish unified administration and model context baseline
This commit is contained in:
Codex
@@ -14,8 +14,7 @@ provider/model environment defaults. Those former sources are retired.
|
||||
schemaVersion: 2
|
||||
modelCatalog:
|
||||
defaults:
|
||||
session: zai/glm-5.3
|
||||
metadataGeneration: zai/glm-5.3
|
||||
interaction: zai/glm-5.3
|
||||
|
||||
embedding:
|
||||
id: ollama/qwen3-embedding:0.6b
|
||||
@@ -50,23 +49,63 @@ it contains that use block:
|
||||
- `metadataGeneration` makes it selectable for description generation;
|
||||
- `embedding` is a single installation-level model rather than a selectable list.
|
||||
|
||||
`defaults.session` is required. `defaults.metadataGeneration` is required exactly when at least
|
||||
one metadata-generation model exists. A session manifest pins its canonical identity, so removing a
|
||||
model never silently changes an existing session: resume fails with `model_unavailable`.
|
||||
`defaults.interaction` is the only LLM default, required once per installation, never per workspace.
|
||||
Core and Administration share the user's operational model choice. An explicit choice takes priority
|
||||
over the default and is remembered in this browser for the authenticated user and application mount.
|
||||
Switching workspace does not change the model. Browser-storage restrictions may limit remembering
|
||||
to the current visit; preferences do not synchronize across devices or change installation YAML.
|
||||
An unavailable remembered model is not silently replaced: select another configured model.
|
||||
|
||||
When any metadata-generation models are configured, the default and the operational list must
|
||||
support both `session` and `metadataGeneration`. Entries for just one adapter may remain in the
|
||||
installation inventory, but are not selectable for global interaction. Core-only installations remain
|
||||
supported when no metadata-generation model is configured; Admin AI is then unavailable.
|
||||
The embedding model remains separate and is unaffected by the interaction selector.
|
||||
|
||||
New sessions record the selected model in their manifest. Resume retains the session's workspace and
|
||||
revision, but uses the current global model (the installation default for clients that omit a model).
|
||||
Historical manifest model fields are not rewritten by resume. Archived/finalized sessions remain read-only.
|
||||
|
||||
### Required operator verification for every model
|
||||
|
||||
Catalog validation checks configuration, not model behavior. Before offering a model to users, and
|
||||
after changing its endpoint, adapters, or the Pi/LiteLLM versions, the operator must verify **both**:
|
||||
|
||||
1. **Core / Pi:** select the model, start a test session in a prepared test workspace, exercise an
|
||||
actual tool call and its returned result, a human review gate, and stop/resume. Check streaming,
|
||||
tool arguments, authentication, and reasoning/token-limit compatibility. A plain chat reply or
|
||||
`tht pi test` alone is not sufficient.
|
||||
2. **Administration / LiteLLM:** select the same model and generate descriptions for a small,
|
||||
non-sensitive test table. Check the structured result is accepted and the generation completes.
|
||||
Review the output quality before using it on real metadata. This action writes test metadata
|
||||
and may incur provider charges: use an authorized test database and approved data.
|
||||
|
||||
There is no automatic certification flag or startup model probe. The operator owns this verification;
|
||||
do not infer compatibility from the model label or from success in just one path. Both adapters point
|
||||
to one catalog identity; Pi does not need to route through a new LiteLLM proxy. Models using only
|
||||
`pi_auth` cannot serve the current LiteLLM path and are excluded from shared selection.
|
||||
|
||||
## Session adapters
|
||||
|
||||
Use `pi_builtin` for a model whose technical definition ships with Pi:
|
||||
Use `pi_builtin` for a model whose technical definition ships with Pi. This does not require
|
||||
`pi_auth`: a shared bundle credential lets native Pi and LiteLLM use the same provider identity:
|
||||
|
||||
```yaml
|
||||
deepseek:
|
||||
authentication:
|
||||
mode: pi_auth
|
||||
mode: secret_env
|
||||
apiKeyEnv: DEEPSEEK_API_KEY
|
||||
session:
|
||||
mode: pi_builtin
|
||||
metadataGeneration:
|
||||
litellmProvider: deepseek
|
||||
models:
|
||||
deepseek-v4-pro:
|
||||
session: {}
|
||||
metadataGeneration: {}
|
||||
deepseek-v4-flash:
|
||||
session: {}
|
||||
metadataGeneration: {}
|
||||
```
|
||||
|
||||
Use `openai_compatible` for an explicit compatible endpoint. Each eligible session model must then
|
||||
@@ -89,6 +128,18 @@ Secret values never belong in installation YAML, generated files, logs, CLI argu
|
||||
requests. The YAML contains only an environment-variable name or an authentication mode. Pi's
|
||||
protected credential file remains selected by the installation authentication configuration.
|
||||
|
||||
For catalog providers using `secret_env`, the bundle is authoritative in both Core and Admin.
|
||||
ThothII removes only the selected provider's old auth entry from the temporary Pi session snapshot;
|
||||
the operator's original Pi auth store and other providers are unchanged. Provider smoke checks use
|
||||
the same precedence, and model enumeration receives the catalog-declared bundle keys. A missing
|
||||
declared key is an error, not permission to fall back to Pi auth or the legacy generic key file.
|
||||
After rotating a bundle key, apply the normal installation lifecycle so processes reload it.
|
||||
|
||||
The PSD descriptor now declares only `deepseek/deepseek-v4-pro` and `deepseek/deepseek-v4-flash`
|
||||
for both uses; it no longer duplicates them under `deepseek-metadata`. Historical records are not
|
||||
rewritten. A saved obsolete identity must be explicitly reselected from the current catalog;
|
||||
it is not silently remapped to another model or account.
|
||||
|
||||
## Generated runtime projections
|
||||
|
||||
Before Compose starts, `tht` validates the installation and atomically writes deterministic files
|
||||
@@ -133,6 +184,16 @@ configuration command. There is no `tht pi configure` and no separate apply comm
|
||||
|
||||
## Migrating a legacy installation
|
||||
|
||||
For schema-v2 descriptors with the former `defaults.session` and `defaults.metadataGeneration`,
|
||||
replace both with `defaults.interaction`. Equal legacy values are accepted and normalized in memory;
|
||||
the loader never rewrites the descriptor. Different values fail with `migration_required`: explicitly
|
||||
choose a model supporting both uses, remove both old fields, and set the single new field. Do not mix
|
||||
new and legacy fields. A Core-only legacy session default can be normalized when Admin AI is absent.
|
||||
|
||||
The generated runtime catalog now uses schema version **2** and only `defaultInteraction`. Regenerate
|
||||
and apply all runtime projections with the matching host/backend release using the normal installation
|
||||
lifecycle; do not deploy only the backend against an old generated catalog or hand-edit generated JSON.
|
||||
|
||||
The migrator reads the former installation `metadataGeneration` block and the two former Pi JSON
|
||||
files, but never modifies them. Supply the facts that cannot be inferred safely and write a separate
|
||||
candidate:
|
||||
@@ -148,13 +209,15 @@ tht --installation /absolute/path/legacy/thothii-installation.yaml installation
|
||||
Review the candidate, move the legacy source files out of the installation only after approval,
|
||||
then select the v2 descriptor. Ambiguous aliases, endpoint conflicts, or missing authentication
|
||||
facts produce field-level errors; the migrator does not guess.
|
||||
The legacy CLI flag `--session-default` now supplies the unified interaction default in the candidate;
|
||||
if it conflicts with the legacy metadata default, align that choice explicitly before retrying.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Meaning | Action |
|
||||
| --- | --- | --- |
|
||||
| `migration_required` | A retired model source or installation schema is still present | Run the installation migrator and review its candidate |
|
||||
| Unknown session or metadata default | The canonical ID is missing the corresponding use block | Correct the provider/model key or add the intended use block |
|
||||
| Invalid interaction default | The canonical ID does not support all configured uses | Correct `defaults.interaction` or the intended adapter blocks |
|
||||
| Generated projection drift | Runtime files differ from the descriptor-derived bytes | Run `tht start` or `tht pi restart --yes --drain` |
|
||||
| `model_unavailable` on resume | The session's pinned model is no longer session-eligible | Restore that catalog entry or keep the session unavailable; do not remap it |
|
||||
| `model_unavailable` on create/resume | The selected global model is no longer eligible | Explicitly choose an eligible model; no fallback is applied |
|
||||
| Provider smoke failure | Credentials, endpoint, or provider availability is invalid | Correct the protected credential or catalog endpoint, restart, then run `tht pi test` |
|
||||
|
||||
Reference in New Issue
Block a user