Skip to content

Flow settings with explained choices, author defaults, fixed and hidden settings - #481

Closed
wmobley wants to merge 8 commits into
developfrom
feat/flow-setting-schemas
Closed

wmobley wants to merge 8 commits into
developfrom
feat/flow-setting-schemas

Conversation

@wmobley

@wmobley wmobley commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Design spec: docs/design/2026-11-20-flow-setting-schemas.md (Approved; implementation deviations recorded).

What it does

  • Run form: flow settings render from each piece's settings JSON Schema like Tapis app.json arguments: titles, dropdowns whose choices are each explained (oneOf const/title/description), number inputs with bounds, defaults pre-filled, advanced settings collapsed, hidden settings omitted, fixed ones read-only. Model parameters with has_accepted_values become a multi-select (several values still mean several runs).
  • Flow builder: per setting the author sets a value (default or fixed) and a visibility (shown / advanced / hidden).
  • Storage: new modelcatalog_configuration_flow.settings_json (migration 1771300000047, insert-only like thread_bindings_json); the catalog API's POST /flows mirrors default, fixed, accepted values, bounds and type onto the flow parameter rows.
  • Adapter: _piece_summary passes the new schema keys; new GET /flows/{id}/settings (relayed by the catalog API like /availability); one resolver for plan, submit and the route. Precedence: fixed > runner > author default > piece default.
  • Enforcement (server side): FLOW_SETTING_REFUSED for runner values on fixed or hidden settings (names compared trimmed, case-insensitive, through aliases). Flow check: FLOW_SETTING_HIDDEN_WITHOUT_VALUE, FLOW_SETTING_FIXED_WITHOUT_VALUE, FLOW_SETTING_INVALID, FLOW_SETTING_CONFLICT, FLOW_SETTING_LOOKS_SECRET (no author values on credential-like names), FLOW_THREAD_BINDING_FIXED. The accept-the-author's-settings dialog lists every author value, hidden and fixed included.
  • Older pieces (type + description only) and existing flows (settings_json = {}) render and run as before.

Reviews

QA and security reviews ran on the diff; all findings were fixed in 499b4c3 (no high-severity security findings).

Tests

  • Adapter: 1516 passed; 4 pre-existing local test_demo_api failures (git-ignored .env). test_flow_settings.py: 45 tests.
  • model-catalog-api: 226 passed, 38 skipped; tsc --noEmit clean.
  • ui-react: 157 files / 1628 tests pass; tsc -b, prettier clean; eslint 0 errors.
  • Not yet verified live: Hasura applying the migration and metadata, the text[] write, a browser run.

Rollout

Apply the migration and metadata before the new code. Library pieces with the new schemas are on wmobley/Semantic-Sensemaking feat/setting-schemas (stacked on upstream PR #3); registering them and re-registering the Sensemaking flows is a separate dev step.

Do not merge until dev testing is scheduled.

🤖 Generated with Claude Code

Add modelcatalog_configuration_flow.settings_json (visibility and fixed per
setting) and expose it to the same roles as thread_bindings_json. The adapter
passes a piece's setting description (title, choices, bounds, advanced) through
its piece summary and plan parameters, resolves each setting for a runner
(GET /flows/{id}/settings), checks hidden and fixed settings have a value, and
refuses a runner's value for a fixed or hidden setting at submit. The catalog
API writes the settings and mirrors defaults, fixed values, choices and bounds
onto the flow's parameter rows, and relays the settings read.
…x, hide or default them

Add a shared setting input (dropdown with the chosen choice's explanation, bounded
number box, checkbox, text). Each setting in a step card now shows the piece's
title and explanation and lets the author choose a default or a fixed value and
whether it is shown, advanced or hidden. The choices are saved as the flow's
settings and sent to the check.
…el multi-select

A flow's settings show the piece's title and explanation, with a dropdown for
choices, a bounded number box and a checkbox, filled with the flow's default.
Advanced settings sit in a collapsed section, hidden ones are not shown, and
fixed ones are listed read-only. A value left at the default is not bound, so the
author's defaults are still accepted at run. A model parameter with accepted values
is a multi-select, and several values are several runs. Settings are read through
the catalog API's new GET /flows/{id}/settings, falling back to the parameter rows.
…s, conflicts

Compare refused runner values trimmed, without case and through aliases. The flow
check now refuses values for credential-like setting names, a thread-filled setting
that is also fixed or hidden, and pieces that describe a shared setting two ways;
the hidden message names the setting and step. A model multi-select keeps values
that are not accepted, flagged. The builder says hidden is not secret. Tests and
docs updated.
@vercel

vercel Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
monorepo Ready Ready Preview Nov 20, 2026 8:05pm UTC

@wmobley

wmobley commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

Combined into #482 so all five build and deploy together.

@wmobley wmobley closed this Nov 20, 2026

This branch was successfully deployed

1 active deployment
Preview — 499b4c3c Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant