Model Recommendations

modelRecommendations lets an extension publisher describe portable models that make the extension useful. During the dashboard Add Extension flow, the host reviews those declarations with the administrator and can add selected missing model records to the workspace before adding the extension.

This is an implemented, model-only provisioning aid. It is not a general resource bundle and does not currently provision tools, agents, servers, groups, files, or model-to-group links.

21.1 What a recommendation does

A recommendation can:

• explain why an extension benefits from a model;
• mark that exact model as required or recommended during installation review;
• recognize an exact model that is already in workspace inventory;
• create a missing normalHttp or openAICompatibleAPI workspace model by calling the existing dashboard model API;
• ask the administrator for an API key when a missing API model is selected.

A recommendation does not:

• give extension code a model object or runtime model ID;
• make key available through get_app_info or another bridge command;
• make a workspace model available to a group;
• download local model bytes during extension installation;
• prove that a remote endpoint is reachable or that local bytes are ready;
• guarantee that a required model remains available after installation;
• reprocess recommendations automatically when an installed extension updates;
• delete a model when the extension is uninstalled.

The model becomes an administrator-owned workspace resource. Extension code must continue to use the documented capability and provider discovery APIs and must handle the model being unavailable at runtime.

21.2 Author workflow

Use this sequence for every extension that publishes model recommendations:

1. Decide whether the extension needs one exact portable model or merely benefits from it.
2. Add a versioned modelRecommendations block inline to the source extension.json.
3. Use a stable extension-local key for each item. Do not use a dashboard record ID or a credential as the key.
4. Choose required only when the administrator should not be able to install the extension without selecting that exact model. Otherwise use recommended.
5. Declare either a normalHttp source or an openAICompatibleAPI source.
6. Run the extension's normal build. Its final step must run isa-ext package.
7. Inspect the generated dist/<id>.isax/extension.json and confirm the block is present without credentials.
8. Preview the package through Add Extension and test existing, missing, deselected, failed, and retry states.
9. Test the extension at runtime with no linked group model. The extension must show a clear unavailable/setup state instead of assuming installation made the model usable.

A complete version 1 block is available in examples/model-recommendations-v1.json. The formal manifest contract is in Manifest specification.

21.3 Choosing required or recommended

importance controls only the dashboard installation review:

Value	Installation behavior	Runtime meaning
required	Selected and locked. A missing selected model must be added successfully before the extension is created.	No runtime guarantee. The model can still be unlinked, deleted, not downloaded, or unavailable to the launch group.
recommended	Selected by default, but the administrator can deselect it individually or with the recommended-model selection action.	The extension must work without it or clearly disable the optional feature that needs it.

Use required sparingly. Exact matching is based on source identity, not on general model capability. If multiple providers or models can satisfy the feature, recommend a preferred model and let the extension discover an available compatible provider at runtime.

21.4 Manifest fields

The top-level modelRecommendations block contains schemaVersion: 1 and a non-empty items array. Each array entry is one of the recommendation objects shown in the source examples below.

Every item uses these fields:

Field	Required	Processing
key	Yes	Stable identity inside this extension manifest. Lowercase ASCII letters, digits, _, and - only. It is installation metadata, not a runtime resource handle.
importance	Yes	required or recommended; controls selection in the review.
name	Yes	Administrator-facing model name. It is used when creating a model but never for existing-model matching.
reason	Yes	Short administrator-facing explanation of why the extension uses the model.
modelTypes	Yes	Non-empty, duplicate-free list of chatLlm, text2Video, text2Image, textEmbedding, other, or speechToText. An existing model must contain every declared type; extra existing types are allowed.
location	Yes	local for normalHttp; privateServer or cloud for openAICompatibleAPI.
safetyLevel	Yes	high, medium, or low; copied to a newly created model record.
modelSettings	No	Plain JSON object copied to a newly created model record. It is not merged into an existing model and may not contain credential-looking fields.
source	Yes	Exactly one supported source variant described below.

The host validates the public distribution manifest before showing a review. Invalid schema versions, empty item lists, duplicate keys, unsupported enum values, unknown source fields, unsafe paths, and credentials reject the preview instead of being ignored.

21.5 Normal HTTP models

Use normalHttp for a model whose files can be downloaded to the current device later through the normal model-library flow:

{
	"key": "local-analysis",
	"importance": "recommended",
	"name": "Local analysis",
	"reason": "Runs analysis on this device.",
	"modelTypes": ["chatLlm"],
	"location": "local",
	"safetyLevel": "high",
	"source": {
		"normalHttp": {
			"url": "https://models.example/acme/analysis.gguf",
			"outputFile": "acme/analysis.gguf",
			"autoDownload": false,
			"mmprojPath": "acme/analysis-mmproj.gguf"
		}
	}
}

Processing rules:

• url must use HTTPS. Plain HTTP is accepted only for localhost or a loopback IP during development.
• URL userinfo and credential-like query parameters are rejected.
• outputFile, mmprojPath, and mtpPath are portable relative output paths, not local absolute paths and not separate URLs.
• autoDownload must be omitted or false. The host also forces it to false in the add-model request.
• Adding the extension creates only the workspace model record. It does not download any files.
• A later normal model download derives a companion URL by replacing the main outputFile suffix in url with mmprojPath or mtpPath. When companion files are declared, keep the URL and output paths aligned so that replacement is possible.
• Normal HTTP model files do not currently have a publisher-declared content digest in this contract. Use a stable trusted HTTPS source and never describe automatic download as part of extension installation.

localFile and dashboardArtifact are deliberately unsupported in public recommendations because their paths or identifiers are not portable between workspaces.

21.6 OpenAI-compatible API models

Use openAICompatibleAPI for a remote provider:

{
	"key": "remote-summary",
	"importance": "recommended",
	"name": "Remote summary",
	"reason": "Creates concise summaries.",
	"modelTypes": ["chatLlm"],
	"location": "cloud",
	"safetyLevel": "medium",
	"source": {
		"openAICompatibleAPI": {
			"baseUrl": "https://api.example/v1",
			"model": "summary-1"
		}
	}
}

The source contains only baseUrl and the provider's model identifier. Never publish apiKey, authorization headers, bearer tokens, query credentials, or credentials inside modelSettings.

If no exact workspace model exists, the review asks the administrator for the API key. The key is removed from review state as the request is submitted and is passed only to the existing add-model command, which stores it with the workspace model. It is never written to the source manifest, public distribution manifest, extension manifestJson, logs, or extension runtime.

21.7 How the host processes recommendations

The dashboard add flow processes a valid block in this order:

1. Fetch and validate the public distribution extension.json.
2. Compare every item with the current workspace model inventory.
3. Show required/recommended selection, existing-model status, missing-model status, and API-key configuration where needed.
4. Immediately before submission, refresh workspace inventory and run exact matching again.
5. Add each selected missing model sequentially through add_model, always with an empty groupIds list.
6. Add the extension only after all selected missing models have succeeded.
7. If the add flow was opened for a group, attempt the existing extension-to- group link. Model-to-group links are not created.

Existing-model identity is intentionally narrow:

• normalHttp: canonical URL with the fragment removed, exact outputFile, and every declared model type. A trailing slash on a download path remains significant.
• openAICompatibleAPI: normalized baseUrl with an optional trailing slash ignored, exact provider model, and every declared model type. The stored API key is ignored.

Display name, reason, location, safety level, and modelSettings are not used for matching. If an existing source match needs different settings, the administrator must review or update that existing model separately.

21.8 Failure and retry behavior

Model creation and extension creation use separate existing dashboard calls; the complete sequence is not one database transaction.

• If any selected model fails, the extension is not created and the review stays open on the failing item.
• Models created earlier in the sequence remain in workspace inventory.
• A retry refreshes inventory and recognizes those exact models instead of intentionally creating them again.
• If model creation succeeds but extension creation fails, the models remain and the administrator can retry adding the extension.
• If extension creation succeeds but its optional current-group link fails, the extension remains in the workspace and the retry is limited to that group link.
• Cancelling after a partial failure does not roll back created resources.

Do not promise all-or-nothing installation in extension copy or documentation.

21.9 Administrator permissions and follow-up

The acting user needs:

• manage_extensions to add the extension;
• manage_models when selected missing models must be created;
• link_resources, or the corresponding group manage_resources authority, to link extensions or models to a group.

After installation, the administrator must separately:

1. link each workspace model to every group that should use it;
2. download local model bytes on each device that will run a normalHttp model;
3. verify remote endpoint policy, connectivity, and credentials where an API model is used.

An extension can therefore be linked to a group while its recommended model is still workspace-only. Group-scoped runtime code must not fall back to an unlinked workspace model.

Required extension documentation

The extension's own README or marketplace description must tell administrators:

• which feature uses each model and whether it is required or recommended;
• who publishes the model or operates the endpoint;
• for local models, the expected download size, license, and device requirements when known;
• for remote models, what data leaves the device and any provider terms, privacy, or cost implications;
• that group assignment and local model download remain separate steps;
• what fallback or unavailable state the extension provides without the model;
• whether an extension update requires manual model changes;
• that uninstalling the extension leaves provisioned workspace models intact.

21.10 Runtime, updates, and uninstall

Recommendation key has no runtime binding. Extensions must not store it as if it were a dashboard model ID. Use the normal runtime discovery API for the feature. For example, transcription extensions call transcription_list_providers and use only the models available to their exact launch group; see Audio capture and transcription.

The automated review currently runs only when an administrator uses the dashboard Add Extension flow:

• mounting a developer extension validates its manifest but does not provision its recommendations;
• changing recommendations in a later package or extension update does not automatically add, change, or remove models in existing workspaces;
• uninstalling the extension does not remove models that were created during its installation.

Treat recommendation keys as stable across versions, document material source changes in release notes, and tell existing administrators when an update requires manual model changes.

21.11 Validation before publication

Run the extension's documented full build, normally:

npm run build

Then verify:

• isa-ext package completed without a recommendation validation error;
• the public distribution manifest contains the expected schemaVersion: 1 block;
• required and recommended choices are intentional;
• no source URL, settings object, generated manifest, or log contains a credential;
• an exact existing model is recognized without relying on its display name;
• missing API models require administrator input;
• selected missing models are workspace-only after creation;
• local model bytes are not downloaded automatically;
• retry after a forced model or extension failure does not intentionally duplicate models;
• the extension handles no group-visible runtime model;
• extension documentation explains any manual group-link, device-download, or endpoint requirements.

The repository-wide checklist is in Validation checklist.