Skip to content

Product Book Model Groups

Grzegorz Nowak edited this page Oct 12, 2026 · 7 revisions

Model Groups — Roles Independent of Providers

Part of the Product Book. Observable product behaviour at pi-schematic @ 36bd569 (main, 2026-10-12).

A Model Group is a named delegation role. Its members are provider/model references that can be swapped without changing the workflow that names the role. Keeping the role separate from its members lets a saved prompt or a spawn call ask for "the review role" while the operator decides, in one place, which models fill it. A group also advertises the capabilities its members offer, so a delegated task can require what it needs and fail early when the role cannot supply it. This chapter covers how you name, store, edit, and route groups.

1. Names, scopes, and persistence

A group name maps to a list of provider/model references, each optionally carrying its own thinking level. The store trims leading and trailing whitespace from names and rejects a name that is empty after trimming.

Groups live in one of two scopes. Global groups persist at ~/.pi/agent/pi-schematic/model-groups.json, while project groups persist at <cwd>/.pi/pi-schematic/model-groups.json, using Pi's project config directory name. Both scopes use the same persisted shape: a version 2 document with a groups map. A project's groups are available only when the project is trusted; otherwise group access is global-only. When both scopes define the same name, the project group shadows the global group while the router resolves an effective role. Saving a group writes a temporary JSON file and renames it into the selected scope's persistent path, so a reader never observes a half-written document.

2. The /model-groups manager

/model-groups opens an interactive manager, but only in TUI mode; a non-TUI RPC call receives a notification that a TUI is required.

Selecting + Add group creates an empty group immediately, defaulting to project scope in a trusted project and to global scope otherwise. The editor can later move a group between the project and global locations. Selecting the Name row activates an inline group-name input, and committing it renames the persisted group.

Adding a member is a short walk through provider, model, and thinking selection. The model picker offers only models that are available in the registry with configured authentication, and its search covers the complete results for the selected provider, matching on model ID, provider, provider/ID, or display name. It shows ten model rows at a time without limiting the underlying search results to ten. The thinking options the manager offers for a member are inherit, the levels the screen derives for the member's selected model, and the member's stored level when it falls outside that set; the screen offers no off level for a model that does not reason. The edit-model screen opens with the cursor on the member's configured level and marks that row ✓ current, so pressing Enter preserves the setting. A stored level the screen does not offer — a level the model no longer lists, off on a model that does not reason, or any level when the model is not in the registry — stays visible as its own row immediately after inherit, marked ⚠ current, unavailable, and survives unless the operator deliberately chooses another option. The same screen removes the member. Deleting a whole group requires choosing Delete group rather than the default Keep group; deleting a group in one scope leaves a same-named group in the other scope intact. Group rows summarize their scope, member count, thinking selections, capability letters, and any applicable validation warnings.

3. Capabilities and how they are derived

Capabilities describe what a group's members can accept or do. The production capability registry defines exactly one constraint type, modalities. Its vocabulary is text, image, and reasoning.

A model's text and image capabilities follow its registry input modalities, and a model advertises reasoning when its registry entry carries reasoning: true. Without an override, a group's advertised capabilities are the union of its resolved members' modalities. An explicit override can narrow that set when you create or update a group, but cannot add a modality that none of its members supports.

The manager's optional-media toggle edits image capability only: text is a required base when the members support it, and reasoning is not toggleable there. The add-model and member rows show compact T/I capability chips; the manager deliberately omits reasoning from those media chips. The agent's own group guidance includes only effective group names and capabilities, not membership or thinking levels, while the interactive composer's #-prefixed group mention autocompletes effective names and shows model and thinking details.

pi-schematic validates configuration on load. Boot validation marks references that are missing from the registry, or that lack configured authentication, as unavailable, and notifies the operator when its warning counts are nonzero. Corrupt or schema-invalid JSON loads as an empty configuration for that scope, with a backup attempt and an operator warning.

4. Routing a spawn through a group

You can also name the role inline. Type #group-name in a message, and the agent reads the mention as a request to route the spawn through that exact group; type # and the composer autocompletes the effective group names with each candidate's model and thinking.

spawn accepts an optional exact group name; when you omit the name, the child inherits the parent's model and thinking. Routing is by exact name, and the outcomes are deliberate. An unknown group name produces a visible fallback to the parent's model and thinking instead of selecting a different group. A known group with zero members fails before creating any child session, and so does a known group with no registry-resolved, authenticated, usable member.

When a group does have usable members, the router draws one uniformly by entry position on every spawn, so repeated calls can draw the same entry. A caller may declare requirements with spawn.constraints.modalities, which must be an object shaped { required: ["text", ...] } rather than a bare array; spawn rejects unknown or invalid constraint keys and values. When the caller declares capabilities, the router preferentially samples usable members that satisfy the exact model requirement. A declared capability must pass both the group's effective capability ceiling and the selected model's own capability check, and the router fails before creating the child.

The router resolves thinking alongside the model. A routed member's thinking override wins over both spawn.thinking and inherited thinking, and the router clamps the result to that model's supported levels. The result identifies the route: a routed spawn shows group → provider/model • thinking, while an unknown group shows group? fallback → provider/model • thinking.

5. Limits and failure modes

Selection is per call: there is no weighting, no-repeat exclusion, health-based routing, retry or failover, and no selection optimizer (model-groups/router.ts:130-136, spawn/index.ts:405-416). Routing must not silently replace an explicitly named group that lacks required capabilities with another role (index.ts:461-464). For a stale non-empty override that lies entirely outside the currently supported union, the router falls back to the member union and flags the override as stale; an explicitly empty override leaves supported text as the base (model-groups/constraints/modalities.ts:43-69). The manager does not load or overwrite unsupported future config versions (model-groups/store.ts:124-140, model-groups/store.ts:235-250). Routing uses the available model registry to choose a member, but a separately created child runtime can still reject the chosen model: routing does not provide an alternate model on that failure (spawn/index.ts:488-494). No confirmed unintended model-group behaviour has been identified from this baseline.

Appendix — baseline behaviour rows

Rows are atomic; IDs are stable (PB-GROUPS-<nn> — never renumber or reuse).

PB-GROUPS-01 … PB-GROUPS-47 — 47 atomic behaviour rows

1. Names, scopes, and persistence

ID Behaviour Evidence
PB-GROUPS-01 A group name maps to a list of provider/model references, each optionally carrying its own thinking level. model-groups/types.ts:13-21
PB-GROUPS-02 Global groups persist at ~/.pi/agent/pi-schematic/model-groups.json. model-groups/store.ts:20
PB-GROUPS-03 Project groups persist at <cwd>/.pi/pi-schematic/model-groups.json (using Pi's project config directory name). model-groups/store.ts:20
PB-GROUPS-04 The persisted group document uses version 2 and a groups map. model-groups/store.ts:15, model-groups/types.ts:22
PB-GROUPS-05 Groups are addressed by names trimmed of leading/trailing whitespace; names empty after trimming are rejected. model-groups/store.ts:66-71
PB-GROUPS-06 Project groups are available only in a trusted project; otherwise group access is global-only. model-groups/command.ts:19, model-groups/store.ts:34
PB-GROUPS-07 A project group shadows a global group with the same name when resolving an effective role. model-groups/router.ts:74-83
PB-GROUPS-08 Group saves write a temporary JSON file and rename it into the selected scope's persistent path. model-groups/store.ts:199-216

2. Interactive /model-groups manager

ID Behaviour Evidence
PB-GROUPS-09 /model-groups opens the interactive manager in TUI mode. model-groups/command.ts:6-27
PB-GROUPS-10 The manager cannot run in non-TUI mode; RPC calls receive a TUI-required notification. model-groups/command.ts:9-13
PB-GROUPS-11 Selecting + Add group immediately creates an empty group, defaulting to project scope when trusted and global otherwise. model-groups/tui.ts:369-383
PB-GROUPS-12 The group editor allows moving a group between project and global locations. model-groups/tui.ts:222-235, model-groups/tui.ts:712-720
PB-GROUPS-13 Selecting the Name row activates an inline group-name input; committing renames the persisted group. model-groups/tui.ts:190-209, model-groups/tui.ts:388
PB-GROUPS-14 Adding a member walks through provider, model, and thinking selection. model-groups/tui.ts:459-478, model-groups/tui.ts:839-861
PB-GROUPS-15 The add-model picker offers only registry-available models with configured authentication. model-groups/tui.ts:259-261
PB-GROUPS-16 The add-model picker searches the complete selected provider's results using model ID, provider, provider/ID, and display name. model-groups/tui.ts:268-279
PB-GROUPS-17 The add-model picker displays ten model rows at a time, without limiting the underlying search results to ten. model-groups/tui.ts:649-660
PB-GROUPS-18 The thinking options the manager offers for a member are inherit, the levels the screen derives for the member's selected model, and the member's stored level when that level falls outside that set. model-groups/tui.ts:288-292, model-groups/tui.ts:302-308
PB-GROUPS-19 The edit-model screen permits changing a member's thinking level or removing that member. model-groups/tui.ts:441-457, model-groups/tui.ts:798-820
PB-GROUPS-20 Deleting a group requires selecting Delete group rather than the default Keep group. model-groups/tui.ts:480-491, model-groups/tui.ts:868-875
PB-GROUPS-21 Deleting a same-named group in one scope leaves the other scope's group intact. model-groups/tui.ts:870-872, model-groups/store.ts:299-313
PB-GROUPS-22 Group rows identify their scope, member count, thinking selections, capability letters, and applicable validation warnings. model-groups/tui.ts:678-702

3. Capabilities and visibility

ID Behaviour Evidence
PB-GROUPS-23 The production capability registry contains one constraint type, modalities. model-groups/constraints/registry.ts:19-21
PB-GROUPS-24 The supported modality vocabulary is text, image, and reasoning. model-groups/types.ts:4-5
PB-GROUPS-25 A model's text and image capabilities follow its registry input modalities. model-groups/constraints/modalities.ts:27-29
PB-GROUPS-26 A model advertises reasoning capability when its registry model has reasoning: true. model-groups/constraints/modalities.ts:27-29
PB-GROUPS-27 Without an override, a group's advertised capabilities are the union of its resolved members' modalities. model-groups/constraints/modalities.ts:35-39, model-groups/constraints/modalities.ts:43-52
PB-GROUPS-28 An explicit modality override may narrow the group but cannot add a modality that none of its members supports when creating/updating it. model-groups/store.ts:258-284, model-groups/constraints/modalities.ts:108-112
PB-GROUPS-29 The manager's optional-media toggle edits image capability; text is a required base when supported, while reasoning is not toggleable there. model-groups/tui.ts:333-343, model-groups/tui.ts:757-776
PB-GROUPS-30 Add-model and member rows show compact T/I capability chips; reasoning is intentionally omitted from these media chips. model-groups/tui.ts:649-654, model-groups/tui.ts:732-745, model-groups/modality.ts:46-61
PB-GROUPS-31 The agent's group guidance includes only effective group names and capabilities, not provider/model membership or thinking levels. index.ts:457-464
PB-GROUPS-32 In the interactive composer, a #-prefixed group mention autocompletes effective names and shows model/thinking details. model-groups/autocomplete.ts:13-25, model-groups/autocomplete.ts:69-96
PB-GROUPS-33 Boot validation marks refs missing from the registry or lacking configured authentication as unavailable and notifies the operator when its warning counts are nonzero. model-groups/store.ts:341-349, index.ts:951-954
PB-GROUPS-34 Corrupt or schema-invalid JSON loads as an empty configuration for that scope with a backup attempt and operator warning. model-groups/store.ts:105-140, index.ts:943-950

4. Spawn routing and requirements

ID Behaviour Evidence
PB-GROUPS-35 spawn accepts an optional exact group name; omitting it inherits the parent's model and thinking. spawn/index.ts:303-322, model-groups/router.ts:202-213
PB-GROUPS-36 Unknown group names cause a visible fallback to the parent model/thinking rather than selecting a different group. model-groups/router.ts:202-213, spawn/renderer.ts:239-253
PB-GROUPS-37 A known group with zero members fails before a child session is created. model-groups/router.ts:212-217, spawn/index.ts:405-410
PB-GROUPS-38 A known group with no registry-resolved, authenticated usable member fails before a child session is created. model-groups/router.ts:121-128, model-groups/router.ts:212-217, spawn/index.ts:405-410
PB-GROUPS-39 A usable routed member is drawn uniformly by entry position on every spawn, so repeated calls can draw the same entry. model-groups/router.ts:130-136
PB-GROUPS-40 spawn.constraints.modalities requires an object shaped { required: ["text", ...] }, not a bare array; unknown or invalid constraint keys/values are rejected. model-groups/constraints/modalities.ts:76-83, spawn/index.ts:363-377
PB-GROUPS-41 For declared capabilities, the router preferentially samples usable members satisfying the exact model requirement. model-groups/router.ts:130-136
PB-GROUPS-42 A declared capability must pass both the group's effective capability ceiling and the selected model's capability check; failure occurs before child creation. model-groups/router.ts:158-173, model-groups/router.ts:218-225, spawn/index.ts:405-410
PB-GROUPS-43 A routed member's thinking override wins over spawn.thinking or inherited thinking; the result is clamped to that model's supported levels. spawn/index.ts:404-416, model-groups/router.ts:139-148
PB-GROUPS-44 Routed spawn identity shows group → provider/model • thinking; unknown-group identity shows group? fallback → provider/model • thinking. spawn/renderer.ts:239-253
PB-GROUPS-45 Mentioning #group-name in a message directs the agent to route the spawn through that exact group; the guidance reads the mention as the request and passes the exact name, with no fallback. index.ts:457-464

5. Edit-screen cursor and stale-level preservation

ID Behaviour Evidence
PB-GROUPS-46 The edit-model screen opens with the cursor on the member's configured thinking level and marks that row ✓ current when the screen offers it. The marker reflects the screen's offered options, independently of authentication, which the Status: line reports separately. model-groups/tui.ts:310-318, model-groups/tui.ts:392-397, model-groups/tui.ts:802-812
PB-GROUPS-47 A member's stored thinking level that the edit screen does not offer for its model — a level the model no longer lists, off on a model that does not reason, or any level when the model is not in the registry — stays on screen as its own row immediately after inherit, marked ⚠ current, unavailable, and is preserved unless the operator deliberately chooses another option. model-groups/tui.ts:302-308, model-groups/tui.ts:445-456, model-groups/tui.ts:803-812

Clone this wiki locally