From 058891a3b4427d211976d7bc72ccbc8eb8622706 Mon Sep 17 00:00:00 2001 From: Will Mobley Date: Fri, 20 Nov 2026 13:27:52 -0600 Subject: [PATCH 1/8] Design spec: flow settings with choices, explanations and author defaults --- .../design/2026-11-20-flow-setting-schemas.md | 261 ++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 docs/design/2026-11-20-flow-setting-schemas.md diff --git a/docs/design/2026-11-20-flow-setting-schemas.md b/docs/design/2026-11-20-flow-setting-schemas.md new file mode 100644 index 00000000..ef251ff7 --- /dev/null +++ b/docs/design/2026-11-20-flow-setting-schemas.md @@ -0,0 +1,261 @@ +# Flow settings with choices, explanations and author defaults + +## Status + +In Review (2026-11-20). Nothing implemented. + +Checked against `origin/develop` at the time of writing, and against the dev catalog +(`mintdevgraphql`) with read-only queries. Paths are relative to the monorepo root unless they +name the `Semantic-Sensemaking` library. Items marked **[unverified]** were not confirmed in code +or data. + +## Objective + +Make a flow's settings as clear to configure as a Tapis app's `app.json` arguments. Each setting +gets a readable title, an explanation, a type, a default, and, when it has a fixed set of +values, a dropdown where every choice carries its own explanation. The flow's author, a data +scientist, sets the flow's own defaults. The author can also fix a value so runners cannot +change it, and keep rarely changed settings out of the way. The mechanism must work for any +piece and any flow, not only Semantic Sensemaking. + +## User need + +- **Primary user:** a domain scientist running a flow from a thread. Knows the subject, does not + know the pieces' code. +- **Secondary user:** the flow's author, a data scientist, who builds the flow from pieces and + decides its defaults. +- **Current pain, seen on dev:** + - The thread's settings form shows every flow setting as a free-text box labelled with the raw + name, for example "match mode". + - The choices are hidden in a sentence ("How terms are counted: auto, word_boundary or + longest_match.") and are checked only after the user types a value. + - No setting on the three Sensemaking flows has a default. Every parameter row has + `has_default_value` and `has_accepted_values` set to null. + - The meaning of each choice is written nowhere. +- **Definition of success:** + - A runner opening a Sensemaking flow sees readable titles, and dropdowns for `match_mode`, + `mapping_method`, `unmapped_groups`, `embedding_kind`, `chat_kind` and `grounding`, each + choice explained. + - Each setting is filled with the flow's default. + - Settings marked advanced are hidden behind an "Advanced settings" toggle. + - An author can change a default or fix a value in the flow builder without code. + +## Current code/system summary + +- **Pieces.** + - A piece (`modelcatalog_etl_process`) describes its settings as JSON Schema in + `runtime_json.parameters_schema_json`. + - On dev each property has only `type` and `description`. For example, map-and-project has + `match_mode`, `output_uri`, `taxonomy_uri`, `mapping_method` and `unmapped_groups`. + - The schema is produced by `Semantic-Sensemaking/src/semantic_sensemaking/pieces/flow_catalog.py` + from a `{name: description}` map (`SCORING`, `EMBEDDING`, `CHAT`, and per-piece arguments). + - A piece is never changed in place. A changed declaration is registered under a new id + (`REVISION` in `flow_catalog.py`). +- **The adapter's piece summary.** `_piece_summary` in `svo-adapter-service/app/main.py` (around + line 2786) passes `type`, `default` and `description` of each setting to the UI as + `setting_details`. It drops every other schema key. +- **The flow builder.** + - `ui-react/src/components/flows/StepCard.tsx` lists a step's settings as "the flow's + defaults; a runner can change them", one text box each, with the piece default as the + placeholder. + - Values are saved as the step's `settings_json` (`ui-react/src/lib/flow-authoring.ts`). + - Each distinct setting name becomes one flow parameter row named + `{configurationId}_setting_{name}` (`docs/design/2026-11-20-flow-authoring-in-the-ui.md`). +- **Catalog parameter rows.** `modelcatalog_parameter` has `has_data_type`, `has_default_value`, + `has_fixed_value`, `has_accepted_values` (a string list), `has_minimum_accepted_value` and + `has_maximum_accepted_value`. It has no field for a title separate from `label`, which is the + key a run binds to, and none for per-choice explanations. +- **The run form** (`ui-react/src/pages/modeling/thread/MintParameters.tsx`): + - It renders text inputs only. + - `has_accepted_values` is used only to reject a value ("Accepted values: …"). + - Min, max and default show as a grey hint. + - Parameters with a fixed value appear in a read-only table, "Expert modeler has selected the + following parameters". So locking already has a display. + - It has two parameter tables: catalog parameters, and adapter-plan parameters. **[unverified]** + which of the two renders a flow's settings in every case. The implementation must confirm + this and make both read the same setting description. + +## Proposed design + +### 1. A setting description in the piece's schema (no new catalog column) + +Each property in `parameters_schema_json` may carry these keys. All of them are standard JSON +Schema except `x-advanced`. + +| Key | Meaning | `app.json` equivalent | +|---|---|---| +| `title` | readable name shown instead of the key | `notes.label` | +| `description` | what the setting does | `description` | +| `type` | `string`, `integer`, `number`, `boolean` | `inputMode`/type | +| `default` | the piece's default | `arg` default | +| `oneOf: [{const, title, description}]` | the choices, each explained | `notes.enum_values` | +| `minimum`, `maximum` | numeric bounds | — | +| `x-advanced: true` | hidden behind "Advanced settings" unless set | — | + +A plain `enum` without `oneOf` stays valid. It renders as a dropdown without per-choice +explanations. + +### 2. The library describes its settings properly + +`flow_catalog.py` replaces the prose maps with structured specs. The titles, defaults, choices +and choice meanings are taken from the library code, never guessed. Each must be traced to the +function that reads the argument (for example, how `match_mode` is applied in `score_lexicon`). +The pieces are registered again as new revisions, because their declaration changes. + +### 3. The adapter passes the description through + +`_piece_summary` keeps `title`, `oneOf`, `enum`, `minimum`, `maximum` and `x-advanced` in +`setting_details`, alongside the keys it keeps today. The adapter's flow-plan parameter list, +which the run form reads, carries the same keys. **[unverified]** where that list is built; the +implementation finds it first. + +### 4. The flow's author sets defaults, fixes values, and shows advanced settings + +Each setting in the flow builder's step card renders from the description: a dropdown with +explanations, or a number box with bounds. Next to each setting, the author picks one of: + +- **Default:** the runner sees this value and can change it. It is saved in the step's + `settings_json` (as today) and copied to the flow parameter row's `has_default_value`. +- **Fixed:** the runner sees the value read-only, in the existing "selected by the expert" + table. It is copied to `has_fixed_value`. +- **Show always:** an advanced setting the author wants runners to see. It is stored on the flow + parameter row **[open question: which field; see Open questions]**. + +When a run starts, a setting takes the first value found in this order: + +1. a fixed value from the flow's author; +2. the runner's value; +3. the flow author's default; +4. the piece's default. + +The adapter already rejects a run value for a setting wired from an earlier step. That rule +stays. + +### 5. The run form renders the description + +In `MintParameters.tsx`, for flows: + +- A setting with choices is a ` change(event.target.value)} + className={cn(base, 'w-full bg-background')} + > + {/* A value the choices do not hold (an old one) stays visible rather than + silently becoming the first choice. */} + {(current === '' || !known) && } + {choices.map((choice: SettingChoice) => ( + + ))} + + {chosen?.description && ( +

+ {chosen.description} +

+ )} + + ); + } + + if (kind === 'boolean') { + return ( + change(String(event.target.checked))} + className={className} + /> + ); + } + + return ( + change(event.target.value)} + className={cn(base, 'w-full', className)} + /> + ); +} diff --git a/ui-react/src/components/common/__tests__/SettingInput.test.tsx b/ui-react/src/components/common/__tests__/SettingInput.test.tsx new file mode 100644 index 00000000..60c778c4 --- /dev/null +++ b/ui-react/src/components/common/__tests__/SettingInput.test.tsx @@ -0,0 +1,93 @@ +import { fireEvent, render, screen } from '@testing-library/react'; +import { describe, expect, it, vi } from 'vitest'; + +import { settingInputKind } from '@/lib/flow-settings'; + +import { SettingInput } from '../SettingInput'; + +const choices = [ + { value: 'auto', title: 'Automatic', description: 'Words and phrases.' }, + { value: 'longest', title: 'Longest match', description: 'No double counting.' }, +]; + +describe('SettingInput', () => { + it('picks the input from the description', () => { + expect(settingInputKind({ choices })).toBe('choice'); + expect(settingInputKind({ type: 'integer' })).toBe('number'); + expect(settingInputKind({ type: 'number' })).toBe('number'); + expect(settingInputKind({ type: 'boolean' })).toBe('boolean'); + expect(settingInputKind({ type: 'string' })).toBe('text'); + expect(settingInputKind(undefined)).toBe('text'); + }); + + it('shows choices by their titles and explains the chosen one', () => { + render(); + const select = screen.getByTestId('setting-input-mode') as HTMLSelectElement; + expect(select.value).toBe('auto'); + expect(Array.from(select.options).map((option) => option.textContent)).toEqual([ + 'Automatic', + 'Longest match', + ]); + expect(screen.getByTestId('setting-input-mode-explanation')).toHaveTextContent( + 'Words and phrases.', + ); + fireEvent.change(select, { target: { value: 'longest' } }); + expect(screen.getByTestId('setting-input-mode-explanation')).toHaveTextContent( + 'No double counting.', + ); + }); + + it('shows plain choices (an enum) with no explanation', () => { + render(); + expect(screen.queryByTestId('setting-input-c-explanation')).not.toBeInTheDocument(); + expect(screen.getByRole('option', { name: 'green' })).toBeInTheDocument(); + }); + + it('keeps a value the choices do not hold, and says what an empty dropdown means', () => { + const { rerender } = render(); + expect(screen.getByRole('option', { name: 'old' })).toBeInTheDocument(); + rerender(); + expect(screen.getByRole('option', { name: 'Piece default' })).toBeInTheDocument(); + }); + + it('gives a number box its bounds, and whole steps for an integer', () => { + render( + , + ); + const input = screen.getByTestId('setting-input-n'); + expect(input).toHaveAttribute('type', 'number'); + expect(input).toHaveAttribute('min', '1'); + expect(input).toHaveAttribute('max', '500'); + expect(input).toHaveAttribute('step', '1'); + expect(input).toHaveAttribute('placeholder', '200'); + }); + + it('is a checkbox for a yes or no', () => { + const onChange = vi.fn(); + render( + , + ); + const box = screen.getByTestId('setting-input-b') as HTMLInputElement; + expect(box.type).toBe('checkbox'); + expect(box.checked).toBe(false); + fireEvent.click(box); + expect(onChange).toHaveBeenCalledWith('true'); + }); + + it('is text otherwise, and reports what is typed', () => { + const onChange = vi.fn(); + render(); + fireEvent.change(screen.getByTestId('setting-input-t'), { target: { value: 'x' } }); + expect(onChange).toHaveBeenCalledWith('x'); + expect((screen.getByTestId('setting-input-t') as HTMLInputElement).value).toBe('x'); + }); + + it('follows `value` when it is given', () => { + const { rerender } = render(); + rerender(); + expect((screen.getByTestId('setting-input-t') as HTMLInputElement).value).toBe('b'); + }); +}); diff --git a/ui-react/src/components/flows/FlowAuthoringForm.tsx b/ui-react/src/components/flows/FlowAuthoringForm.tsx index bad6bfb3..d2970406 100644 --- a/ui-react/src/components/flows/FlowAuthoringForm.tsx +++ b/ui-react/src/components/flows/FlowAuthoringForm.tsx @@ -39,6 +39,7 @@ import { setInputWire, setPause, sortProblems, + setSettingRule, updateStep, type BindingRole, type DraftOutput, @@ -108,7 +109,16 @@ export function FlowAuthoringForm({ }, [pieces]); // --- the live check --------------------------------------------------------- - const body = useMemo(() => buildCheckBody(draft), [draft]); + // The setting names the pieces have, once every step's piece has been read: a decision + // about a setting whose step was removed is then left out rather than failing the check. + const knownSettings = useMemo( + () => + draft.steps.every((step) => summaries[step.pieceId]) + ? new Set(draft.steps.flatMap((step) => summaries[step.pieceId]?.settings ?? [])) + : undefined, + [draft.steps, summaries], + ); + const body = useMemo(() => buildCheckBody(draft, knownSettings), [draft, knownSettings]); const bodyKey = JSON.stringify(body); useEffect(() => { if (!token || draft.steps.length === 0) return; @@ -141,7 +151,7 @@ export function FlowAuthoringForm({ const ask = async (slot: SlotKey, purpose: Purpose, snapshot: FlowDraft) => { setSuggestion({ slot, result: 'loading' }); const result = token - ? await proposeForFlow(buildCheckBody(snapshot), purpose, token) + ? await proposeForFlow(buildCheckBody(snapshot, knownSettings), purpose, token) : { error: 'Sign in to get proposals.' }; setSuggestion({ slot, result }); }; @@ -202,7 +212,7 @@ export function FlowAuthoringForm({ const save = async () => { if (!token || !canSave) return; setSaving(true); - setSaved(await saveFlow(buildSaveBody(draft), token)); + setSaved(await saveFlow(buildSaveBody(draft, knownSettings), token)); setSaving(false); }; @@ -527,6 +537,8 @@ export function FlowAuthoringForm({ updateStep(draft, index, { settings: { ...step.settings, [name]: value } }), ) } + rules={draft.settings} + onRule={(name, rule) => change(setSettingRule(draft, name, rule))} onRemoveWire={(wireIndex) => change(removeWire(draft, index, wireIndex))} onPause={(pause) => change(setPause(draft, index, pause))} editable={editableChoice(draft, position)} diff --git a/ui-react/src/components/flows/StepCard.tsx b/ui-react/src/components/flows/StepCard.tsx index a3608d4e..a24ade9b 100644 --- a/ui-react/src/components/flows/StepCard.tsx +++ b/ui-react/src/components/flows/StepCard.tsx @@ -11,6 +11,7 @@ import { Trash2 } from 'lucide-react'; import { Button } from '@/components/ui/button'; import { Input } from '@/components/ui/input'; +import { SettingInput } from '@/components/common/SettingInput'; import type { PieceSummary } from '@/lib/flow-authoring-api'; import { EDIT_CHECKS, @@ -20,6 +21,13 @@ import { type DraftStep, type FlowProblem, } from '@/lib/flow-authoring'; +import { + settingText, + settingTitle, + visibilityOf, + type SettingRule, + type Visibility, +} from '@/lib/flow-settings'; import { describeWire, parseWires, type FlowLabels } from '@/lib/flow-steps'; import { ProposalList, type ProposalListProps } from './ProposalList'; @@ -45,6 +53,9 @@ export interface StepCardProps { onSuggestInput: (inputPosition: number) => void; onSuggestNext: (outputPosition: number) => void; onSetting: (name: string, value: string) => void; + /** What the author decided about each setting of the flow, by name. */ + rules: Record; + onRule: (name: string, rule: SettingRule) => void; onRemoveWire: (wireIndex: number) => void; onPause: (pause: boolean) => void; /** The file this step's pause makes editable, and the change of it (`null` clears). */ @@ -202,31 +213,76 @@ export function StepCard(props: StepCardProps) { {summary && summary.settings.length > 0 && (
- Settings (the flow's defaults; a runner can change them, so the model that runs - this flow must accept them) + Settings. The value is the flow's default, which a runner can change, unless you + fix it. The model that runs this flow must accept a default. {summary.settings.map((name) => { const details = summary.setting_details[name]; const wired = settingWired.has(name); + const rule = props.rules[name]; + const fixed = rule?.fixed === true; + const shown = visibilityOf(rule, details); + const title = settingTitle(name, details); return ( -
- - props.onSetting(name, event.target.value)} - /> - {wired && ( - - linked to an earlier step; it cannot also have a default - +
+
+ +
+ props.onSetting(name, value)} + disabled={wired} + unsetLabel={ + details?.default === undefined + ? 'Not set' + : `Piece default: ${settingText(details.default)}` + } + className="h-8" + /> +
+ {wired ? ( + + linked to an earlier step; it cannot also have a default + + ) : ( + <> + + + + )} +
+ {details?.description && ( +

{details.description}

)}
); diff --git a/ui-react/src/components/flows/__tests__/FlowAuthoringForm.test.tsx b/ui-react/src/components/flows/__tests__/FlowAuthoringForm.test.tsx index 053559cc..ea1427c8 100644 --- a/ui-react/src/components/flows/__tests__/FlowAuthoringForm.test.tsx +++ b/ui-react/src/components/flows/__tests__/FlowAuthoringForm.test.tsx @@ -1,7 +1,7 @@ import userEvent from '@testing-library/user-event'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; -import { draftFromStoredFlow, type StoredFlowSource } from '@/lib/flow-authoring'; +import { draftFromStoredFlow, emptyDraft, type StoredFlowSource } from '@/lib/flow-authoring'; import { renderWithProviders, screen, waitFor, within } from '@/test/utils/render'; import { setMintConfig } from '@/test/utils/mint-config'; @@ -27,6 +27,7 @@ vi.mock('@/components/autocomplete/StandardVariableCombobox', () => ({ const PIECES = [ { id: 'piece-a', label: 'Ingest' }, { id: 'piece-b', label: 'Score' }, + { id: 'piece-c', label: 'Count' }, ]; const SUMMARIES = { 'piece-a': { @@ -38,6 +39,27 @@ const SUMMARIES = { output_contracts: { '1': { standard_variable_uri: 'https://x.org/clean' } }, setting_details: { top_n: { type: 'string', default: '10' } }, }, + 'piece-c': { + inputs: [1], + outputs: [1], + settings: ['match_mode', 'max_files'], + values: [], + input_contracts: { '1': { standard_variable_uri: 'https://x.org/corpus' } }, + output_contracts: { '1': {} }, + setting_details: { + match_mode: { + type: 'string', + title: 'How terms are counted', + description: 'The counting rule.', + default: 'auto', + choices: [ + { value: 'auto', title: 'Automatic', description: 'Words and phrases.' }, + { value: 'longest', title: 'Longest match', description: 'No double counting.' }, + ], + }, + max_files: { type: 'integer', title: 'Most files', minimum: 1, maximum: 500, advanced: true }, + }, + }, 'piece-b': { inputs: [1], outputs: [1], @@ -155,7 +177,7 @@ describe('FlowAuthoringForm', () => { await addStepOf(user, 'Ingest'); const step = screen.getByTestId('flow-form-step-1'); expect(await within(step).findByLabelText('Source of input 1 of step 1')).toBeInTheDocument(); - expect(within(step).getByLabelText('top_n')).toBeInTheDocument(); + expect(within(step).getByLabelText('top n')).toBeInTheDocument(); expect(await within(step).findByText('input 1 of step 1 is not linked')).toBeInTheDocument(); expect(screen.getByRole('button', { name: 'Save flow' })).toBeDisabled(); }); @@ -205,7 +227,7 @@ describe('FlowAuthoringForm', () => { expect(proposal.url).toBe('http://em.test/v1/adapter/flows/propose'); expect(proposal.body.purpose).toEqual({ step: 2, input: 1 }); - await user.type(within(screen.getByTestId('flow-form-step-1')).getByLabelText('top_n'), '5'); + await user.type(within(screen.getByTestId('flow-form-step-1')).getByLabelText('top n'), '5'); const save = screen.getByRole('button', { name: 'Save flow' }); await waitFor(() => expect(save).toBeEnabled()); await user.click(save); @@ -239,6 +261,100 @@ describe('FlowAuthoringForm', () => { ); }); + describe('settings described by their piece', () => { + const counting = () => ({ + ...emptyDraft(), + software: { id: '', label: 'Sensemaking' }, + version: { id: '', label: '1' }, + configuration: { label: 'My flow', description: '' }, + inputs: [ + { + key: 'input1', + label: 'Docs', + standardVariable: 'sv:corpus', + standardVariableLabel: 'Corpus', + format: '', + optional: false, + }, + ], + steps: [ + { + pieceId: 'piece-c', + settings: {}, + wires: [{ to: { input: 1 }, from: { flow_input: 'input1' } }], + pauseAfter: false, + }, + ], + }); + + it('shows titles, a dropdown with explanations and a bounded number box', async () => { + fakeServer(); + const user = userEvent.setup(); + render({ initial: counting() }); + const step = await screen.findByTestId('flow-form-step-1'); + const mode = await within(step).findByLabelText('How terms are counted'); + expect(mode.tagName).toBe('SELECT'); + await user.selectOptions(mode, 'Longest match'); + expect(within(step).getByText('No double counting.')).toBeInTheDocument(); + const files = within(step).getByLabelText('Most files'); + expect(files).toHaveAttribute('type', 'number'); + expect(files).toHaveAttribute('max', '500'); + // The piece suggests this one is advanced, and the author may change that. + expect(within(step).getByLabelText('Who sees Most files')).toHaveValue('advanced'); + expect(within(step).getByLabelText('Who sees How terms are counted')).toHaveValue('shown'); + }); + + it('saves the value, whether it is fixed and who sees it, in the check and the save', async () => { + fakeServer(); + const user = userEvent.setup(); + render({ initial: counting() }); + const step = await screen.findByTestId('flow-form-step-1'); + await user.selectOptions( + await within(step).findByLabelText('How terms are counted'), + 'Longest match', + ); + await user.selectOptions( + within(step).getByLabelText('Is the value of How terms are counted a default or fixed'), + 'fixed', + ); + await user.selectOptions( + within(step).getByLabelText('Who sees How terms are counted'), + 'hidden', + ); + const save = screen.getByRole('button', { name: 'Save flow' }); + await waitFor(() => expect(save).toBeEnabled()); + await user.click(save); + await waitFor(() => + expect(calls.some((c) => c.url === 'http://catalog.test/v2.0.0/flows')).toBe(true), + ); + const sent = calls.find((c) => c.url === 'http://catalog.test/v2.0.0/flows')!; + expect(sent.body.steps[0].settings).toEqual({ match_mode: 'longest' }); + expect(sent.body.settings).toEqual({ match_mode: { fixed: true, visibility: 'hidden' } }); + const check = [...calls].reverse().find((c) => c.url.endsWith('/flows/check'))!; + expect(check.body.settings).toEqual({ match_mode: { fixed: true, visibility: 'hidden' } }); + }); + + it('sends no decisions when the author made none', async () => { + fakeServer(); + render({ initial: counting() }); + await screen.findByTestId('flow-form-step-1'); + await waitFor(() => expect(calls.some((c) => c.url.endsWith('/flows/check'))).toBe(true)); + expect(calls.find((c) => c.url.endsWith('/flows/check'))!.body.settings).toEqual({}); + }); + + it('leaves out a decision about a setting no step has any more', async () => { + fakeServer(); + const draft = { ...counting(), settings: { gone: { visibility: 'hidden' as const } } }; + render({ initial: draft }); + await screen.findByLabelText('How terms are counted'); + await waitFor(() => + expect(calls.filter((c) => c.url.endsWith('/flows/check')).at(-1)?.body.settings).toEqual( + {}, + ), + ); + }); + }); + it('adds a proposed next step wired from the output it was asked about', async () => { const user = userEvent.setup(); render(); @@ -437,7 +553,7 @@ describe('FlowAuthoringForm', () => { ).toBeInTheDocument(); expect(screen.getByLabelText('Input 1 takes a collection of files')).toBeChecked(); expect(screen.getByLabelText('Region is filled in by')).toHaveValue('input:Corpus'); - expect(await screen.findByLabelText('top_n')).toHaveValue('25'); + expect(await screen.findByLabelText('top n')).toHaveValue('25'); const save = screen.getByRole('button', { name: 'Save flow' }); await waitFor(() => expect(save).toBeEnabled()); diff --git a/ui-react/src/graphql/queries/flow-authoring.ts b/ui-react/src/graphql/queries/flow-authoring.ts index 499fc4bf..0d76d315 100644 --- a/ui-react/src/graphql/queries/flow-authoring.ts +++ b/ui-react/src/graphql/queries/flow-authoring.ts @@ -94,6 +94,7 @@ export const GET_FLOW_FOR_COPY = gql` flow { thread_bindings_json outputs_json + settings_json steps(order_by: { position: asc }) { position etl_process_id diff --git a/ui-react/src/lib/__tests__/flow-authoring.test.ts b/ui-react/src/lib/__tests__/flow-authoring.test.ts index 0ec26de3..a83d8e3d 100644 --- a/ui-react/src/lib/__tests__/flow-authoring.test.ts +++ b/ui-react/src/lib/__tests__/flow-authoring.test.ts @@ -12,6 +12,8 @@ import { removeInput, removeStep, setInputWire, + setSettingRule, + settingRulesJson, sortProblems, type FlowDraft, type StoredFlowSource, @@ -285,3 +287,58 @@ describe('editing as a copy', () => { expect(draft.bindings.collections).toEqual([]); }); }); + +describe('what the author decides about a setting', () => { + it('records a decision, and removes a decision that decides nothing', () => { + let draft = setSettingRule(emptyDraft(), 'match_mode', { visibility: 'hidden', fixed: true }); + expect(draft.settings).toEqual({ match_mode: { visibility: 'hidden', fixed: true } }); + draft = setSettingRule(draft, 'match_mode', { fixed: false }); + expect(draft.settings).toEqual({}); + }); + + it('sends only decisions, and only for settings a step has once that is known', () => { + const draft: FlowDraft = { + ...emptyDraft(), + settings: { + a: { visibility: 'advanced' }, + b: { fixed: true }, + c: { fixed: false }, + gone: { visibility: 'hidden' }, + }, + }; + expect(settingRulesJson(draft)).toEqual({ + a: { visibility: 'advanced' }, + b: { fixed: true }, + gone: { visibility: 'hidden' }, + }); + expect(settingRulesJson(draft, new Set(['a', 'b', 'c']))).toEqual({ + a: { visibility: 'advanced' }, + b: { fixed: true }, + }); + expect(buildCheckBody(draft).settings).toEqual(settingRulesJson(draft)); + expect(buildSaveBody(draft, new Set(['a'])).settings).toEqual({ + a: { visibility: 'advanced' }, + }); + }); + + it('is read back from a stored flow, ignoring what it cannot read', () => { + const base: StoredFlowSource = { + configuration: { label: 'F', inputs: [], outputs: [], parameters: [] }, + flow: { + steps: [], + settings_json: { + a: { visibility: 'hidden', fixed: true }, + b: { visibility: 'sideways' }, + c: 'nope', + }, + }, + }; + expect(draftFromStoredFlow(base).settings).toEqual({ + a: { visibility: 'hidden', fixed: true }, + b: {}, + }); + expect( + draftFromStoredFlow({ ...base, flow: { steps: [], settings_json: 7 } }).settings, + ).toEqual({}); + }); +}); diff --git a/ui-react/src/lib/__tests__/flow-settings.test.ts b/ui-react/src/lib/__tests__/flow-settings.test.ts new file mode 100644 index 00000000..0036c0eb --- /dev/null +++ b/ui-react/src/lib/__tests__/flow-settings.test.ts @@ -0,0 +1,86 @@ +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import { + choiceLabel, + fetchFlowSettings, + settingText, + settingTitle, + visibilityOf, +} from '../flow-settings'; + +const SETTING = { + name: 'match_mode', + parameter_id: 'cfg_setting_match_mode', + visibility: 'shown', + title: 'How terms are counted', +}; + +afterEach(() => vi.unstubAllGlobals()); + +describe('naming and showing a setting', () => { + it('prefers the piece title and falls back to the name with spaces', () => { + expect(settingTitle('match_mode', { title: 'How terms are counted' })).toBe( + 'How terms are counted', + ); + expect(settingTitle('match_mode', {})).toBe('match mode'); + expect(settingTitle('match_mode', { title: ' ' })).toBe('match mode'); + expect(settingTitle('top_n')).toBe('top n'); + }); + + it('labels a choice by its title, else its value', () => { + expect(choiceLabel({ value: 'a', title: 'Automatic' })).toBe('Automatic'); + expect(choiceLabel({ value: 5 })).toBe('5'); + }); + + it('writes a value as the text an input shows', () => { + expect(settingText('x')).toBe('x'); + expect(settingText(25)).toBe('25'); + expect(settingText(false)).toBe('false'); + expect(settingText(undefined)).toBe(''); + expect(settingText(null)).toBe(''); + }); + + it('takes the authors choice, else the pieces hint, else shown', () => { + expect(visibilityOf({ visibility: 'hidden' }, { advanced: true })).toBe('hidden'); + expect(visibilityOf({ fixed: true }, { advanced: true })).toBe('advanced'); + expect(visibilityOf(undefined, {})).toBe('shown'); + expect(visibilityOf({ visibility: 'bogus' as never }, undefined)).toBe('shown'); + }); +}); + +describe('fetchFlowSettings', () => { + const answers = (body: unknown, ok = true) => { + const fetchMock = vi.fn().mockResolvedValue({ ok, json: async () => body }); + vi.stubGlobal('fetch', fetchMock); + return fetchMock; + }; + + it('reads the settings of a flow with the callers token', async () => { + const fetchMock = answers({ + settings: [SETTING, { name: 'broken' }], + thread_bound: ['start', 3], + }); + const found = await fetchFlowSettings('https://w3id.org/okn/i/mint/dict', 'tok'); + expect(found?.settings).toEqual([SETTING]); + expect(found?.thread_bound).toEqual(['start']); + const [url, init] = fetchMock.mock.calls[0]!; + expect(String(url)).toContain( + `/flows/${encodeURIComponent('https://w3id.org/okn/i/mint/dict')}/settings`, + ); + expect((init as RequestInit).headers).toEqual({ Authorization: 'Bearer tok' }); + }); + + it.each([ + ['no token', null, { settings: [] }, true], + ['a refusal', 'tok', { settings: [] }, false], + ['a malformed answer', 'tok', { nope: 1 }, true], + ])('is null for %s', async (_name, token, body, ok) => { + answers(body, ok); + expect(await fetchFlowSettings('f', token)).toBeNull(); + }); + + it('is null when the adapter cannot be reached', async () => { + vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('down'))); + expect(await fetchFlowSettings('f', 'tok')).toBeNull(); + }); +}); diff --git a/ui-react/src/lib/flow-authoring-api.ts b/ui-react/src/lib/flow-authoring-api.ts index cbd966a6..f0fe2ff9 100644 --- a/ui-react/src/lib/flow-authoring-api.ts +++ b/ui-react/src/lib/flow-authoring-api.ts @@ -11,6 +11,7 @@ */ import { getEnsembleManagerApiUrl, getModelCatalogApiUrl } from './config'; import type { FlowProblem, ProposedChain, ProposedSource, WireJson } from './flow-authoring'; +import type { SettingDetails } from './flow-settings'; export interface PieceSummary { inputs: number[]; @@ -25,7 +26,7 @@ export interface PieceSummary { string, { standard_variable_uri?: string; unit?: string; format?: string } >; - setting_details: Record; + setting_details: Record; } export interface FlowCheck { diff --git a/ui-react/src/lib/flow-authoring.ts b/ui-react/src/lib/flow-authoring.ts index 6619e0f9..3439ef6b 100644 --- a/ui-react/src/lib/flow-authoring.ts +++ b/ui-react/src/lib/flow-authoring.ts @@ -15,6 +15,7 @@ */ import type { FlowPieceRow } from '@/graphql/queries/flows'; import { parseWires, parseSettings } from './flow-steps'; +import { VISIBILITIES, type SettingRule } from './flow-settings'; export interface WireJson { to: Record; @@ -70,6 +71,12 @@ export interface FlowDraft { steps: DraftStep[]; outputs: DraftOutput[]; bindings: DraftBindings; + /** + * What the author decided about each setting, by name: whether it is fixed, and + * whether a runner sees it, finds it under "Advanced settings", or does not see it. + * One setting name used by several steps is one setting of the flow. + */ + settings: Record; } export const MAX_STEPS = 24; @@ -85,6 +92,7 @@ export function emptyDraft(): FlowDraft { steps: [], outputs: [], bindings: { region: '', start_date: '', end_date: '', collections: [] }, + settings: {}, }; } @@ -114,6 +122,24 @@ function stepsJson(draft: FlowDraft) { })); } +/** + * The author's decisions as the catalog and the adapter take them: only a setting that + * has one, and only a setting some step has when `known` is given (a setting whose step + * was removed must not linger and fail the check). + */ +export function settingRulesJson(draft: FlowDraft, known?: ReadonlySet): Json { + const rules: Json = {}; + for (const [name, rule] of Object.entries(draft.settings)) { + if (known && !known.has(name)) continue; + const kept: SettingRule = { + ...(rule.visibility ? { visibility: rule.visibility } : {}), + ...(rule.fixed ? { fixed: true } : {}), + }; + if (Object.keys(kept).length > 0) rules[name] = kept; + } + return rules; +} + /** `editable` as the catalog takes it: a blank check or key is left out. */ function editableJson(editable: Json): Json { const { check, key, ...rest } = editable; @@ -136,8 +162,11 @@ function outputJson(output: DraftOutput, forSave: boolean): Json { return where; } -/** The body of the adapter's `POST /flows/check` and `POST /flows/propose`. */ -export function buildCheckBody(draft: FlowDraft) { +/** + * The body of the adapter's `POST /flows/check` and `POST /flows/propose`. `known` is + * the set of setting names the steps' pieces have, once the form has read them all. + */ +export function buildCheckBody(draft: FlowDraft, known?: ReadonlySet) { const bindings: Json = {}; for (const role of BINDING_ROLES) { const target = bindingJson(draft.bindings[role], false); @@ -155,11 +184,16 @@ export function buildCheckBody(draft: FlowDraft) { steps: stepsJson(draft), outputs: draft.outputs.map((output) => outputJson(output, false)), thread_bindings: bindings, + settings: settingRulesJson(draft, known), }; } -/** The body of `POST /flows` on the model catalog API. */ -export function buildSaveBody(draft: FlowDraft) { +/** + * The body of `POST /flows` on the model catalog API. The catalog writes each step's + * settings and the flow's `settings`, and copies the defaults, fixed values, choices and + * bounds onto the flow's parameter rows. + */ +export function buildSaveBody(draft: FlowDraft, known?: ReadonlySet) { const bindings: Json = {}; for (const role of BINDING_ROLES) { const target = bindingJson(draft.bindings[role], true); @@ -187,6 +221,7 @@ export function buildSaveBody(draft: FlowDraft) { steps: stepsJson(draft), outputs: draft.outputs.map((output) => outputJson(output, true)), thread_bindings: bindings, + settings: settingRulesJson(draft, known), }; } @@ -246,6 +281,13 @@ export function removeStep(draft: FlowDraft, index: number): FlowDraft { }; } +/** Record what the author decided about a setting. A rule with nothing in it is removed. */ +export function setSettingRule(draft: FlowDraft, name: string, rule: SettingRule): FlowDraft { + const { [name]: _dropped, ...others } = draft.settings; + const kept = Boolean(rule.visibility || rule.fixed); + return { ...draft, settings: kept ? { ...others, [name]: rule } : others }; +} + export function updateStep(draft: FlowDraft, index: number, change: Partial): FlowDraft { return { ...draft, @@ -606,6 +648,7 @@ export interface StoredFlowSource { flow: { thread_bindings_json?: unknown; outputs_json?: unknown; + settings_json?: unknown; steps: { position: number; etl_process_id?: string | null; @@ -718,6 +761,20 @@ export function draftFromStoredFlow(stored: StoredFlowSource): FlowDraft { ); } + const settings: Record = {}; + for (const [name, raw] of Object.entries( + isRecord(flow.settings_json) ? flow.settings_json : {}, + )) { + if (!isRecord(raw)) continue; + const visibility = (VISIBILITIES as readonly unknown[]).includes(raw.visibility) + ? (raw.visibility as SettingRule['visibility']) + : undefined; + settings[name] = { + ...(visibility ? { visibility } : {}), + ...(raw.fixed === true ? { fixed: true } : {}), + }; + } + return { software: { id: version?.software?.id ?? '', label: version?.software?.label ?? '' }, version: { id: version?.id ?? '', label: version?.version_id ?? '' }, @@ -729,5 +786,6 @@ export function draftFromStoredFlow(stored: StoredFlowSource): FlowDraft { steps, outputs, bindings, + settings, }; } diff --git a/ui-react/src/lib/flow-settings.ts b/ui-react/src/lib/flow-settings.ts new file mode 100644 index 00000000..4d14fc12 --- /dev/null +++ b/ui-react/src/lib/flow-settings.ts @@ -0,0 +1,128 @@ +/** + * What a runner or a flow's author needs to know about a setting of a flow: the piece's + * description of it (a title, an explanation, a type, explained choices, bounds), the value + * a run starts from, and what the author decided (fixed, and whether it is shown, advanced + * or hidden). + * + * The description comes from the piece's JSON Schema through the adapter, and the author's + * decisions from the flow. Every key is optional: an older piece has only a type and a + * description, and a setting without them is described by its name. + */ +import { getModelCatalogApiUrl } from './config'; + +export const VISIBILITIES = ['shown', 'advanced', 'hidden'] as const; +export type Visibility = (typeof VISIBILITIES)[number]; + +export interface SettingChoice { + value: string | number | boolean; + title?: string; + description?: string; +} + +/** The piece's own description of one setting. */ +export interface SettingDetails { + type?: string; + default?: unknown; + description?: string; + title?: string; + choices?: SettingChoice[]; + minimum?: number; + maximum?: number; + /** The piece suggests keeping it out of the way. */ + advanced?: boolean; +} + +/** What the author decided about one setting of the flow. */ +export interface SettingRule { + visibility?: Visibility; + fixed?: boolean; +} + +/** One setting of a stored flow as a runner meets it. */ +export interface FlowSetting extends SettingDetails { + name: string; + /** The flow parameter row the thread binds a value to. */ + parameter_id: string; + visibility: Visibility; + fixed?: boolean; +} + +export interface FlowSettings { + settings: FlowSetting[]; + /** Settings the thread fills in itself (the dates). */ + thread_bound: string[]; +} + +export type SettingInputKind = 'choice' | 'number' | 'boolean' | 'text'; + +/** Which input suits a setting: a dropdown for choices, a number box, a tick box, or text. */ +export function settingInputKind(details: SettingDetails | undefined): SettingInputKind { + if (details?.choices?.length) return 'choice'; + if (details?.type === 'integer' || details?.type === 'number') return 'number'; + if (details?.type === 'boolean') return 'boolean'; + return 'text'; +} + +/** The name a person reads: the piece's title, else the name with its underscores spaced. */ +export function settingTitle(name: string, details?: Pick): string { + return details?.title?.trim() || name.replace(/_/g, ' '); +} + +export const choiceLabel = (choice: SettingChoice): string => choice.title ?? String(choice.value); + +/** The value a setting starts from, as the text an input shows. */ +export function settingText(value: unknown): string { + if (value === undefined || value === null) return ''; + return typeof value === 'string' ? value : JSON.stringify(value); +} + +/** Where a setting belongs in the form, from the author's choice or the piece's hint. */ +export function visibilityOf(rule: SettingRule | undefined, details?: SettingDetails): Visibility { + if (rule?.visibility && VISIBILITIES.includes(rule.visibility)) return rule.visibility; + return details?.advanced ? 'advanced' : 'shown'; +} + +const isRecord = (value: unknown): value is Record => + typeof value === 'object' && value !== null && !Array.isArray(value); + +function isSetting(value: unknown): value is FlowSetting { + return ( + isRecord(value) && + typeof value.name === 'string' && + typeof value.parameter_id === 'string' && + typeof value.visibility === 'string' && + (VISIBILITIES as readonly string[]).includes(value.visibility) + ); +} + +/** + * The adapter's answer for a flow, or null when it cannot be had (no token, no adapter, + * a catalog without the route, a malformed answer). The form then falls back to the flow's + * parameter rows, which carry the defaults, choices and bounds but not titles, explanations + * or the author's visibility. + */ +export async function fetchFlowSettings( + flowId: string, + token: string | null, + signal?: AbortSignal, +): Promise { + const base = getModelCatalogApiUrl(); + if (!base || !token) return null; + try { + const response = await fetch(`${base}/flows/${encodeURIComponent(flowId)}/settings`, { + headers: { Authorization: `Bearer ${token}` }, + signal, + }); + if (!response.ok) return null; + const body: unknown = await response.json(); + if (!isRecord(body) || !Array.isArray(body.settings)) return null; + return { + settings: body.settings.filter(isSetting), + thread_bound: Array.isArray(body.thread_bound) + ? body.thread_bound.filter((name): name is string => typeof name === 'string') + : [], + }; + } catch { + return null; + } +} From f22c7a35e9d0b26bb7cc2f461fd58861beedb3fa Mon Sep 17 00:00:00 2001 From: Will Mobley Date: Fri, 20 Nov 2026 13:50:45 -0600 Subject: [PATCH 6/8] Thread run form: titles, dropdowns, advanced and hidden settings, model 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. --- ui-react/docs/docs/facilitator/run-a-flow.md | 13 +- ui-react/src/hooks/useFlowSettings.ts | 30 ++ .../src/lib/__tests__/flow-errors.test.ts | 8 + ui-react/src/lib/flow-errors.ts | 13 + .../pages/modeling/thread/MintParameters.tsx | 327 +++++++++++++----- .../thread/__tests__/MintParameters.test.tsx | 245 ++++++++++++- 6 files changed, 553 insertions(+), 83 deletions(-) create mode 100644 ui-react/src/hooks/useFlowSettings.ts diff --git a/ui-react/docs/docs/facilitator/run-a-flow.md b/ui-react/docs/docs/facilitator/run-a-flow.md index 9cdf1e5a..d74d58aa 100644 --- a/ui-react/docs/docs/facilitator/run-a-flow.md +++ b/ui-react/docs/docs/facilitator/run-a-flow.md @@ -39,7 +39,18 @@ You can upload up to 500 files at once, 2 GB in all. A flow can read private fil ### Parameters step -Review each setting and enter a value. A setting the flow's author has already fixed is shown with that value. If a required setting has no value, the run is not started. The message says *This flow needs a setting filled in*, and names the settings. Fill them in, save, and run again. +Review each setting. Each shows a readable title and an explanation. The form fills in the flow's default: + +- **A setting with choices** is a dropdown. The explanation of the choice you pick appears under it. +- **A number** is a number box. Saving is refused, with a message, for a value outside the setting's limits. +- **A yes or no** is a tick box. +- **Anything else** is a text box. + +Rarely changed settings are inside **Advanced settings**, which is closed until you open it. Settings the flow's author hid are not shown at all, and the run uses the author's value for them. A setting the author has fixed is listed under *Expert modeler has selected the following parameters* with its value, and you cannot change it. If something sends a value for a fixed or hidden setting anyway, the run is refused with *A setting is fixed or hidden by the flow*. + +If a required setting has no value, the run is not started. The message says *This flow needs a setting filled in*, and names the settings. Fill them in, save, and run again. + +For a model (not a flow), a parameter that has a fixed list of accepted values is a list you pick from, with its default selected. Pick more than one value to make one run for each, the same as typing several values separated by commas. A parameter with no such list stays a text box where you can type values separated by commas. ### Runs step diff --git a/ui-react/src/hooks/useFlowSettings.ts b/ui-react/src/hooks/useFlowSettings.ts new file mode 100644 index 00000000..35f7353f --- /dev/null +++ b/ui-react/src/hooks/useFlowSettings.ts @@ -0,0 +1,30 @@ +import { useEffect, useState } from 'react'; + +import { useAuth } from '@/lib/auth/useAuth'; +import { fetchFlowSettings, type FlowSettings } from '@/lib/flow-settings'; + +/** + * The settings of each flow in `flowIds` as a runner meets them, by flow id. A flow + * whose settings could not be read is absent, so the form falls back to the catalog's + * parameter rows and stays usable. + */ +export function useFlowSettings(flowIds: string[]): Record { + const { isAuthenticated, accessToken } = useAuth(); + const [found, setFound] = useState>({}); + const wanted = flowIds.join('\n'); + + useEffect(() => { + if (!wanted || !isAuthenticated || !accessToken) return; + const controller = new AbortController(); + for (const id of wanted.split('\n')) { + void fetchFlowSettings(id, accessToken, controller.signal).then((settings) => { + if (settings && !controller.signal.aborted) { + setFound((previous) => ({ ...previous, [id]: settings })); + } + }); + } + return () => controller.abort(); + }, [wanted, isAuthenticated, accessToken]); + + return found; +} diff --git a/ui-react/src/lib/__tests__/flow-errors.test.ts b/ui-react/src/lib/__tests__/flow-errors.test.ts index ce508894..ce095d55 100644 --- a/ui-react/src/lib/__tests__/flow-errors.test.ts +++ b/ui-react/src/lib/__tests__/flow-errors.test.ts @@ -95,6 +95,14 @@ describe('flowErrorMessage', () => { expect(fixed?.lines).toContain('title'); }); + it('names the settings the author fixed or hid, and which', () => { + const refused = refuse('FLOW_SETTING_REFUSED', { fixed: ['match_mode'], hidden: ['internal'] }); + expect(refused?.title).toBe('A setting is fixed or hidden by the flow'); + expect(refused?.lines).toEqual( + expect.arrayContaining(['match_mode (fixed)', 'internal (hidden)']), + ); + }); + it('lists the pieces that are not approved and the problems with their steps', () => { const stored = refuse('STORED_SOURCE_REFUSED', { problems: [{ code: 'NOT_APPROVED', message: 'piece p1 is not approved', step: 'clean' }], diff --git a/ui-react/src/lib/flow-errors.ts b/ui-react/src/lib/flow-errors.ts index 79ba9346..de93f8c1 100644 --- a/ui-react/src/lib/flow-errors.ts +++ b/ui-react/src/lib/flow-errors.ts @@ -22,6 +22,7 @@ export const FLOW_ERROR_CODES = [ 'FLOW_ALREADY_RUNNING', 'FLOW_PLAN_NOT_YOURS', 'FLOW_ARGUMENT_FIXED', + 'FLOW_SETTING_REFUSED', 'STORED_SOURCE_REFUSED', 'FLOW_DOES_NOT_CHECK_OUT', 'FLOW_REGION_INVALID', @@ -305,6 +306,18 @@ export function flowErrorMessage(error: unknown): FlowErrorMessage | null { ], }; } + case 'FLOW_SETTING_REFUSED': { + const fixed = list(field(details, 'fixed')).map(text); + const hidden = list(field(details, 'hidden')).map(text); + return { + title: 'A setting is fixed or hidden by the flow', + lines: [ + "The flow's author fixed or hid these settings, so a run cannot change them. Remove your value and run again.", + ...fixed.map((name) => `${name} (fixed)`), + ...hidden.map((name) => `${name} (hidden)`), + ], + }; + } case 'STORED_SOURCE_REFUSED': { const problems = problemLines(list(field(details, 'problems'))); return { diff --git a/ui-react/src/pages/modeling/thread/MintParameters.tsx b/ui-react/src/pages/modeling/thread/MintParameters.tsx index 0776f463..0100e95f 100644 --- a/ui-react/src/pages/modeling/thread/MintParameters.tsx +++ b/ui-react/src/pages/modeling/thread/MintParameters.tsx @@ -31,6 +31,15 @@ import { type ThreadAdapterPlan, } from '@/lib/adapter-execution'; import type { UnifiedParameterDefinition } from '@/lib/ensemble-manager'; +import { SettingInput } from '@/components/common/SettingInput'; +import { useFlowSettings } from '@/hooks/useFlowSettings'; +import { + settingText, + settingTitle, + type FlowSettings, + type SettingDetails, + type Visibility, +} from '@/lib/flow-settings'; import type { SpatialSelection } from './SpatialScopeMap'; // ─── Constants ───────────────────────────────────────────────────────────────── @@ -104,6 +113,51 @@ function spatialParameterOverride( } } +/** What a flow's setting is, for the form: how to describe it, and who sees it. */ +interface FlowSettingView { + details: SettingDetails; + visibility: Visibility; + fixed: boolean; + /** The value a run starts from, as text. Empty when nothing gives one. */ + defaultText: string; + /** The text of the fixed value, when the author fixed it. */ + fixedText: string; +} + +/** + * A flow setting as the form shows it. The adapter's description (titles, explained + * choices, the author's visibility and fixed flag) is used when it was read; without it + * the flow's parameter row still carries the type, default, choices and bounds, so a + * setting is never less than a text box. + */ +function flowSettingView(parameter: ModelParameter, settings: FlowSettings | undefined) { + const found = settings?.settings.find((setting) => setting.parameter_id === parameter.id); + const fromRow: SettingDetails = { + ...(parameter.type ? { type: parameter.type } : {}), + ...(parameter.description ? { description: parameter.description } : {}), + ...(parameter.default != null ? { default: parameter.default } : {}), + ...(parameter.accepted_values?.length + ? { choices: parameter.accepted_values.map((value) => ({ value })) } + : {}), + ...(parameter.min != null && Number.isFinite(Number(parameter.min)) + ? { minimum: Number(parameter.min) } + : {}), + ...(parameter.max != null && Number.isFinite(Number(parameter.max)) + ? { maximum: Number(parameter.max) } + : {}), + }; + const details: SettingDetails = found ? { ...fromRow, ...found } : fromRow; + const fixedText = parameter.value ?? (found?.fixed ? settingText(found.default) : ''); + const view: FlowSettingView = { + details, + visibility: found?.visibility ?? 'shown', + fixed: Boolean(parameter.value) || found?.fixed === true, + defaultText: settingText(details.default), + fixedText, + }; + return view; +} + // ─── Props ──────────────────────────────────────────────────────────────────── interface MintParametersProps { @@ -143,6 +197,7 @@ export function MintParameters({ }: MintParametersProps) { const modelIds = Object.keys(threadData.models ?? {}); const isConfigured = modelIds.length > 0; + const flowSettings = useFlowSettings(modelIds.filter((id) => threadData.models[id]?.isFlow)); // Shared with the wizard rail. Note it also requires an execution summary: a // model with no adjustable parameters would otherwise read as done before the @@ -163,11 +218,11 @@ export function MintParameters({ if (!param.accepted_values.includes(v)) { return `Accepted values: ${param.accepted_values.join(', ')}`; } - } else if (param.type === 'int') { + } else if (param.type === 'int' || param.type === 'integer') { const n = parseInt(v, 10); if (param.min != null && n < parseInt(param.min, 10)) return `Min is ${param.min}`; if (param.max != null && n > parseInt(param.max, 10)) return `Max is ${param.max}`; - } else if (param.type === 'float') { + } else if (param.type === 'float' || param.type === 'number') { const n = parseFloat(v); if (param.min != null && n < parseFloat(param.min)) return `Min is ${param.min}`; if (param.max != null && n > parseFloat(param.max)) return `Max is ${param.max}`; @@ -176,15 +231,60 @@ export function MintParameters({ return null; } + // ─ Which of a model's parameters are fixed, hidden, or the runner's to set ────── + // A flow's author may fix a setting (it shows as read-only) or hide it (it does not + // show). The adapter refuses a runner's value for either, so a value bound earlier for + // one that has since been fixed or hidden is dropped on save rather than sent. + function partitionParameters(mid: string, model: ThreadExecutionData['models'][string]) { + const rows = userParameters(model).sort((a, b) => { + if (a.position != null && b.position != null) return a.position - b.position; + return (a.name ?? '').localeCompare(b.name ?? ''); + }); + if (!model.isFlow) { + return { + fixed: rows.filter((p) => !!p.value), + adjustable: rows.filter((p) => !p.value), + withheld: [] as ModelParameter[], + }; + } + const viewOf = (p: ModelParameter) => flowSettingView(p, flowSettings[mid]); + const hidden = rows.filter((p) => viewOf(p).visibility === 'hidden'); + const fixed = rows.filter((p) => !hidden.includes(p) && viewOf(p).fixed); + return { + fixed, + adjustable: rows.filter((p) => !hidden.includes(p) && !fixed.includes(p)), + withheld: [...hidden, ...fixed], + }; + } + // ─ Parse values from the form for a parameter ───────────────────────────── - function getParamValues(modelId: string, param: ModelParameter, isFlow = false): string[] { + function getParamValues( + modelId: string, + param: ModelParameter, + isFlow = false, + flowDefault = '', + ): string[] { const form = formRefs.current[modelId]; if (!form) return []; - const el = form.elements.namedItem(param.id ?? '') as HTMLInputElement | null; + const el = form.elements.namedItem(param.id ?? '') as + | HTMLInputElement + | HTMLSelectElement + | null; + if (el instanceof HTMLSelectElement && el.multiple) { + // A model parameter with accepted values: every selected value is a run. + return Array.from(el.selectedOptions).map((option) => option.value); + } + if (isFlow) { + // A flow's setting is one value: a comma belongs to the value (a title, a + // list the flow parses itself), it does not start a sweep. A value left at the + // flow's default is not bound: the run then uses the default as the author's, + // which the runner accepts before it starts. + const checkbox = el instanceof HTMLInputElement && el.type === 'checkbox'; + const text = checkbox ? String(el.checked) : (el?.value ?? '').trim(); + if (checkbox && !el.checked && flowDefault === '') return []; + return text && text !== flowDefault ? [text] : []; + } const raw = el?.value ?? param.default ?? ''; - // A flow's setting is one value: a comma belongs to the value (a title, a - // list the flow parses itself), it does not start a sweep. - if (isFlow) return raw.trim() ? [raw.trim()] : []; return raw .split(/\s*,\s*/) .map((s) => s.trim()) @@ -255,8 +355,9 @@ export function MintParameters({ for (const mid of modelIds) { const model = threadData.models[mid]!; - const adjustable = userParameters(model).filter((p) => !p.value); + const { adjustable, withheld } = partitionParameters(mid, model); const bindings = newEnsembles[mid]?.bindings ?? {}; + for (const p of withheld) delete bindings[p.id ?? '']; const adapterPlans = threadData.adapter_plans?.[mid] ?? []; const adapterParameters = new Map(); for (const plan of adapterPlans) { @@ -312,7 +413,12 @@ export function MintParameters({ // If not in edit mode and already bound, keep existing if (!editMode && current && current.length > 0) continue; - const vals = getParamValues(mid, param, model.isFlow); + const vals = getParamValues( + mid, + param, + model.isFlow, + model.isFlow ? flowSettingView(param, flowSettings[mid]).defaultText : '', + ); const err = validateValues(param, vals); if (err) { newErrors[`${mid}::${param.id}`] = err; @@ -426,19 +532,16 @@ export function MintParameters({ const model = threadData.models[mid]!; const ensemble = threadData.model_ensembles[mid] ?? { id: '', bindings: {} }; - const fixedParams = userParameters(model) - .filter((p) => !!p.value) - .sort((a, b) => { - if (a.position != null && b.position != null) return a.position - b.position; - return (a.name ?? '').localeCompare(b.name ?? ''); - }); - - const adjustableParams = userParameters(model) - .filter((p) => !p.value) - .sort((a, b) => { - if (a.position != null && b.position != null) return a.position - b.position; - return (a.name ?? '').localeCompare(b.name ?? ''); - }); + const { fixed: fixedParams, adjustable: adjustableParams } = partitionParameters( + mid, + model, + ); + const flowView = (p: ModelParameter) => flowSettingView(p, flowSettings[mid]); + // The flow's author may keep rarely changed settings out of the way. + const advancedParams = model.isFlow + ? adjustableParams.filter((p) => flowView(p).visibility === 'advanced') + : []; + const shownParams = adjustableParams.filter((p) => !advancedParams.includes(p)); const adapterPlans = threadData.adapter_plans?.[mid] ?? []; const adapterParams = new Map< @@ -454,6 +557,108 @@ export function MintParameters({ } } + const renderRow = (p: ModelParameter) => { + const bindings = ensemble.bindings[p.id ?? ''] ?? []; + const displayValue = bindings.join(', '); + const isRegionGeoJson = p.default === '__region_geojson'; + const errKey = `${mid}::${p.id}`; + const view = model.isFlow ? flowView(p) : null; + // A model parameter with accepted values is picked from them. Picking + // several is several runs, as comma separated values are in the text box. + const accepted = + !model.isFlow && p.accepted_values?.length ? p.accepted_values : null; + const min = view ? view.details.minimum : p.min; + const max = view ? view.details.maximum : p.max; + const selected = accepted + ? (bindings.length > 0 + ? bindings + : (p.default ?? '').split(/\s*,\s*/).filter(Boolean) + ).filter((value) => accepted.includes(value)) + : []; + + return ( + + +
+ {view + ? settingTitle(p.name ?? '', view.details) + : (p.name ?? '').replace(/_/g, ' ')} +
+ {(view?.details.description ?? p.description) && ( +
+ {view?.details.description ?? p.description} +
+ )} + {(min != null || max != null) && ( +
+ {min != null && max != null + ? `Range: ${min} – ${max}.` + : min != null + ? `Min: ${min}.` + : `Max: ${max}.`} + {p.default && ` Default: ${p.default}`} +
+ )} + + + {!editMode ? ( + {displayValue || view?.defaultText || '—'} + ) : isRegionGeoJson ? ( + Region GeoJSON + ) : ( +
+ {accepted ? ( + <> + +
+ Hold Ctrl or Cmd to pick more than one: each value is a run. +
+ + ) : view ? ( + + ) : ( + + )} + {errors[errKey] && ( +
+ {errors[errKey]} +
+ )} +
+ )} + + + ); + }; + return (
  • @@ -490,14 +695,20 @@ export function MintParameters({
    - {(p.name ?? '').replace(/_/g, ' ')} + {model.isFlow + ? settingTitle(p.name ?? '', flowView(p).details) + : (p.name ?? '').replace(/_/g, ' ')}
    {p.description && (
    {p.description}
    )} - {p.default === '__region_geojson' ? 'Region GeoJSON' : p.value} + {p.default === '__region_geojson' + ? 'Region GeoJSON' + : model.isFlow + ? flowView(p).fixedText + : p.value} ))} @@ -534,64 +745,18 @@ export function MintParameters({ Values - - {adjustableParams.map((p) => { - const bindings = ensemble.bindings[p.id ?? ''] ?? []; - const displayValue = bindings.join(', '); - const isRegionGeoJson = p.default === '__region_geojson'; - const errKey = `${mid}::${p.id}`; - - return ( - - -
    - {(p.name ?? '').replace(/_/g, ' ')} -
    - {p.description && ( -
    {p.description}
    - )} - {(p.min != null || p.max != null) && ( -
    - {p.min != null && p.max != null - ? `Range: ${p.min} – ${p.max}.` - : p.min != null - ? `Min: ${p.min}.` - : `Max: ${p.max}.`} - {p.default && ` Default: ${p.default}`} -
    - )} - - - {!editMode ? ( - {displayValue || '—'} - ) : isRegionGeoJson ? ( - Region GeoJSON - ) : ( -
    - - {errors[errKey] && ( -
    - {errors[errKey]} -
    - )} -
    - )} - - - ); - })} - + {shownParams.map(renderRow)} + {advancedParams.length > 0 && ( +
    + + Advanced settings ({advancedParams.length}) + + + {advancedParams.map(renderRow)} +
    +
    + )}

  • ) : ( diff --git a/ui-react/src/pages/modeling/thread/__tests__/MintParameters.test.tsx b/ui-react/src/pages/modeling/thread/__tests__/MintParameters.test.tsx index 78d1a612..24825140 100644 --- a/ui-react/src/pages/modeling/thread/__tests__/MintParameters.test.tsx +++ b/ui-react/src/pages/modeling/thread/__tests__/MintParameters.test.tsx @@ -1,7 +1,7 @@ /** * Tests for MintParameters — parameter sweep configuration step. */ -import { describe, expect, it, vi } from 'vitest'; +import { afterEach, describe, expect, it, vi } from 'vitest'; import { screen, fireEvent, waitFor } from '@testing-library/react'; import type { ReactNode } from 'react'; import { renderWithProviders } from '@/test/utils/render'; @@ -604,3 +604,246 @@ describe('MintParameters', () => { }); }); }); + +describe('the settings of a flow', () => { + const MODE = { + name: 'match_mode', + parameter_id: 'p-mode', + visibility: 'shown', + title: 'How terms are counted', + description: 'The counting rule.', + type: 'string', + default: 'auto', + choices: [ + { value: 'auto', title: 'Automatic', description: 'Words and phrases.' }, + { value: 'longest', title: 'Longest match', description: 'No double counting.' }, + ], + }; + const FILES = { + name: 'max_files', + title: 'Most files', + parameter_id: 'p-files', + visibility: 'advanced', + type: 'integer', + minimum: 1, + maximum: 500, + default: 200, + }; + const SECRET = { + name: 'internal', + parameter_id: 'p-internal', + visibility: 'hidden', + default: 'x', + }; + const PINNED = { + name: 'grounding', + parameter_id: 'p-pinned', + visibility: 'shown', + fixed: true, + default: 'keyword', + }; + const row = (id: string, name: string, extra = {}) => ({ id, name, type: 'string', ...extra }); + + const flowData = (bindings: Record = {}): ThreadExecutionData => ({ + ...mockThreadDataUnconfigured, + models: { + 'model-1': { + ...mockThreadDataUnconfigured.models['model-1']!, + isFlow: true, + input_parameters: [ + row('p-mode', 'match_mode', { default: 'auto' }), + row('p-files', 'max_files', { type: 'integer', default: '200' }), + row('p-internal', 'internal', { default: 'x' }), + row('p-pinned', 'grounding', { default: 'keyword' }), + row('p-plain', 'title'), + ], + }, + }, + model_ensembles: { 'model-1': { id: 'ens-1', bindings } }, + }); + + const open = async ( + data = flowData(), + settings: unknown[] = [MODE, FILES, SECRET, PINNED], + ready = 'How terms are counted', + ) => { + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue({ ok: true, json: async () => ({ settings, thread_bound: [] }) }), + ); + const onSave = vi.fn().mockResolvedValue(undefined); + renderWithProviders( + , + ); + // A flow whose step was saved opens read-only, as a finished step does. + fireEvent.click(await screen.findByTestId('edit-parameters-btn')); + // The form shows first; the settings answer follows and gives the titles. + await screen.findByText(ready); + return onSave; + }; + const saved = async (onSave: ReturnType) => { + fireEvent.click(screen.getByTestId('parameters-save-btn')); + await waitFor(() => expect(onSave).toHaveBeenCalled()); + return (onSave.mock.calls[0]![0] as Record }>)[ + 'model-1' + ]!.bindings; + }; + + afterEach(() => vi.unstubAllGlobals()); + + it('shows the title, the explanation and a dropdown filled with the default', async () => { + await open(); + expect(screen.getByText('The counting rule.')).toBeInTheDocument(); + const select = screen.getByTestId('param-input-p-mode') as HTMLSelectElement; + expect(select.tagName).toBe('SELECT'); + expect(select.value).toBe('auto'); + expect(screen.getByTestId('param-input-p-mode-explanation')).toHaveTextContent( + 'Words and phrases.', + ); + fireEvent.change(select, { target: { value: 'longest' } }); + expect(screen.getByTestId('param-input-p-mode-explanation')).toHaveTextContent( + 'No double counting.', + ); + }); + + it('keeps advanced settings in a collapsed section, with a number box and its bounds', async () => { + await open(); + const advanced = screen.getByTestId('advanced-settings-model-1') as HTMLDetailsElement; + expect(advanced.open).toBe(false); + expect(advanced).toHaveTextContent('Advanced settings'); + expect(advanced).toContainElement(screen.getByTestId('param-input-p-files')); + expect(screen.getByTestId('param-input-p-files')).toHaveAttribute('type', 'number'); + expect(screen.getByTestId('param-input-p-files')).toHaveAttribute('max', '500'); + expect(screen.getByTestId('param-input-p-mode').closest('details')).toBeNull(); + }); + + it('does not show a hidden setting, and lists a fixed one read-only', async () => { + await open(); + expect(screen.queryByTestId('param-input-p-internal')).not.toBeInTheDocument(); + expect(screen.queryByText('internal')).not.toBeInTheDocument(); + expect(screen.queryByTestId('param-input-p-pinned')).not.toBeInTheDocument(); + expect(screen.getByText(/expert modeler has selected/i)).toBeInTheDocument(); + expect(screen.getByText('grounding')).toBeInTheDocument(); + expect(screen.getByText('keyword')).toBeInTheDocument(); + }); + + it('binds only what the runner changed from the default, and a plain setting as typed', async () => { + const onSave = await open(); + fireEvent.change(screen.getByTestId('param-input-p-mode'), { target: { value: 'longest' } }); + fireEvent.change(screen.getByTestId('param-input-p-plain'), { target: { value: 'A, B' } }); + const bindings = await saved(onSave); + expect(bindings['p-mode']).toEqual(['longest']); + expect(bindings['p-plain']).toEqual(['A, B']); + // Left at the default: not a value the runner sent, so the flow's default is still + // listed for acceptance when the run starts. + expect(bindings['p-files']).toEqual([]); + }); + + it('drops a value bound earlier for a setting that is now hidden or fixed', async () => { + const onSave = await open( + flowData({ 'p-internal': ['y'], 'p-pinned': ['z'], 'p-mode': ['auto'] }), + ); + const bindings = await saved(onSave); + expect(bindings['p-internal']).toBeUndefined(); + expect(bindings['p-pinned']).toBeUndefined(); + }); + + it('refuses a number outside the limits the piece gave', async () => { + const data = flowData(); + data.models['model-1']!.input_parameters = [ + row('p-files', 'max_files', { type: 'integer', min: '1', max: '500', default: '200' }), + ]; + const onSave = await open(data, [FILES], 'Most files'); + fireEvent.change(screen.getByTestId('param-input-p-files'), { target: { value: '900' } }); + fireEvent.click(screen.getByTestId('parameters-save-btn')); + expect(await screen.findByTestId('param-error-p-files')).toHaveTextContent('Max is 500'); + expect(onSave).not.toHaveBeenCalled(); + }); + + it('still shows a dropdown from the flows parameter rows when the settings cannot be read', async () => { + vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, json: async () => ({}) })); + const data = flowData(); + data.models['model-1']!.input_parameters = [ + row('p-mode', 'match_mode', { default: 'auto', accepted_values: ['auto', 'longest'] }), + ]; + renderWithProviders( + , + ); + fireEvent.click(screen.getByTestId('edit-parameters-btn')); + const select = screen.getByTestId('param-input-p-mode') as HTMLSelectElement; + expect(select.tagName).toBe('SELECT'); + expect(select.value).toBe('auto'); + expect(screen.getByText('match mode')).toBeInTheDocument(); + }); +}); + +describe('a model parameter with accepted values', () => { + const dataWith = (bindings: Record = {}): ThreadExecutionData => ({ + ...mockThreadDataUnconfigured, + models: { + 'model-1': { + ...mockThreadDataUnconfigured.models['model-1']!, + input_parameters: [ + { + id: 'param-s', + name: 'scheme', + type: 'string', + accepted_values: ['upstream', 'central', 'tvd'], + default: 'central', + }, + { id: 'param-t', name: 'timestep', type: 'int' }, + ], + }, + }, + model_ensembles: { 'model-1': { id: 'ens-1', bindings } }, + }); + const render_ = (bindings?: Record) => { + const onSave = vi.fn().mockResolvedValue(undefined); + renderWithProviders( + , + ); + return onSave; + }; + + it('is a multi-select with the default selected, and plain parameters stay text boxes', () => { + render_(); + const select = screen.getByTestId('param-input-param-s') as HTMLSelectElement; + expect(select.multiple).toBe(true); + expect(Array.from(select.selectedOptions).map((o) => o.value)).toEqual(['central']); + expect((screen.getByTestId('param-input-param-t') as HTMLInputElement).type).toBe('text'); + }); + + it('makes several selected values several runs', async () => { + const onSave = render_(); + const select = screen.getByTestId('param-input-param-s') as HTMLSelectElement; + for (const option of Array.from(select.options)) { + option.selected = option.value !== 'central'; + } + fireEvent.click(screen.getByTestId('parameters-save-btn')); + await waitFor(() => expect(onSave).toHaveBeenCalled()); + const bindings = ( + onSave.mock.calls[0]![0] as Record }> + )['model-1']!.bindings; + expect(bindings['param-s']).toEqual(['upstream', 'tvd']); + const summary = onSave.mock.calls[0]![1] as Record; + expect(summary['model-1']!.total_runs).toBe(2); + }); + + it('preselects the values already chosen instead of the default', () => { + render_({ 'param-s': ['tvd', 'upstream'] }); + const select = screen.getByTestId('param-input-param-s') as HTMLSelectElement; + expect(Array.from(select.selectedOptions).map((o) => o.value)).toEqual(['upstream', 'tvd']); + }); +}); From aa2fc72b8e8a9d2fb83350bdb730b8cbdeb5afe9 Mon Sep 17 00:00:00 2001 From: Will Mobley Date: Fri, 20 Nov 2026 13:51:34 -0600 Subject: [PATCH 7/8] Spec: record implementation deviations for flow setting schemas --- .../design/2026-11-20-flow-setting-schemas.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/design/2026-11-20-flow-setting-schemas.md b/docs/design/2026-11-20-flow-setting-schemas.md index 828bc684..a135d960 100644 --- a/docs/design/2026-11-20-flow-setting-schemas.md +++ b/docs/design/2026-11-20-flow-setting-schemas.md @@ -321,6 +321,36 @@ The old pieces stay registered, so rolling back means pointing the flows back at - 2026-11-20: visibility is stored in a new `modelcatalog_configuration_flow.settings_json` column. Rejected: `parameter_type`, which is already used for other meanings, and step `settings_json`, because one setting can span several steps. +- 2026-11-20 (user): the `openai_compatible` choice of `embedding_kind` and `chat_kind` is + titled "Tejas". The stored value is unchanged, because the library reads it. + +### Implementation deviations (2026-11-20, monorepo commits 9994104, 3f9a750, f22c7a3; library 98bd2dd, 760c3ff) + +- **The run form reads the catalog parameter rows, not adapter plans,** because a flow is planned + only at Run. A new adapter route, `GET /flows/{id}/settings`, is relayed by the catalog API like + `/availability`. It returns per setting the title, choices, bounds, advanced flag, resolved + default, fixed flag and visibility, plus the thread-filled names. The form merges it onto the + rows. With the adapter down, the rows alone still give dropdowns, numbers and defaults. One + resolver, `flow_settings.resolve`, serves plan, submit and this route. +- **The parameter rows are mirrored by the catalog API's `POST /flows` (`buildRows`), not the + UI.** This keeps one writer. +- **A pre-filled value equal to the flow default is not saved as a runner binding.** Fixed or + hidden values already bound in a thread are dropped on save. +- **Thread-filled settings (for example dates) are exempt from the runner-value refusal, not + from the flow check.** An author who hides one must give it a value. +- **Hidden wins over fixed in the UI:** a hidden fixed setting is not listed read-only. +- **Error codes:** + - `FLOW_SETTING_REFUSED` (422 at submit) + - `FLOW_SETTING_HIDDEN_WITHOUT_VALUE`, `FLOW_SETTING_FIXED_WITHOUT_VALUE` and + `FLOW_SETTING_INVALID` (flow check) + - `FLOW_SETTINGS_UNAVAILABLE` (502 from the relay) +- **Migration:** `1771300000047_configuration_flow_settings`. +- **Open:** draft-lexicon `grounding=semantic` and map-and-project `mapping_method=embedding` + cannot run, because the adapter makes every declared secret required (`step_secrets.py`, no + optional flag). Declaring `model_server` on map-and-project would force a credential on keyword + runs. Proposed: separate embedding variants of the two pieces (awaiting the user). +- **Unverified:** Hasura applying the migration; the `text[]` literal written for + `has_accepted_values`; anything live. ## User feedback / decisions From 499b4c3cfcf8bfce55e0c5be00b482ad8ef7d16f Mon Sep 17 00:00:00 2001 From: Will Mobley Date: Fri, 20 Nov 2026 13:59:52 -0600 Subject: [PATCH 8/8] Flow settings review fixes: guard credential-like names, thread values, 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. --- .../design/2026-11-20-flow-setting-schemas.md | 28 +++ model-catalog-api/src/__tests__/flows.test.ts | 14 ++ model-catalog-api/src/flows.ts | 6 +- svo-adapter-service/app/flow_graph.py | 49 ++++- svo-adapter-service/app/flow_settings.py | 31 ++++ svo-adapter-service/app/main.py | 17 +- svo-adapter-service/app/models.py | 3 + svo-adapter-service/docs/api.md | 19 +- .../tests/test_flow_settings.py | 173 ++++++++++++++++++ .../docs/docs/data-scientist/build-a-flow.md | 2 + ui-react/src/components/flows/StepCard.tsx | 6 + .../__tests__/FlowAuthoringForm.test.tsx | 13 ++ .../src/lib/__tests__/flow-authoring.test.ts | 8 + ui-react/src/lib/flow-authoring.ts | 6 + .../pages/modeling/thread/MintParameters.tsx | 20 +- .../__tests__/FlowSettingsDialog.test.tsx | 20 ++ .../thread/__tests__/MintParameters.test.tsx | 36 ++++ 17 files changed, 432 insertions(+), 19 deletions(-) diff --git a/docs/design/2026-11-20-flow-setting-schemas.md b/docs/design/2026-11-20-flow-setting-schemas.md index a135d960..443aea06 100644 --- a/docs/design/2026-11-20-flow-setting-schemas.md +++ b/docs/design/2026-11-20-flow-setting-schemas.md @@ -310,6 +310,34 @@ The old pieces stay registered, so rolling back means pointing the flows back at 2. Should `output_uri` stay hidden on every flow? DYNAMO sets it today. **[unverified]** whether a runner ever needs to change it. +## Implementation deviations + +Recorded 2026-11-20, after review. + +- The catalog API (`model-catalog-api/src/flows.ts`) writes `settings_json` and mirrors the + defaults, fixed values, choices and bounds onto the parameter rows; the UI sends the step + settings and the flow `settings` only. The run form reads settings through a new + `GET /flows/{id}/settings` (adapter, relayed by the catalog API), and falls back to the + parameter rows. +- A value left at the flow default on the run form is not bound, so the default is still + listed for acceptance. Every author value is listed in that dialog whatever its visibility. +- New codes: `FLOW_SETTING_REFUSED` (submit), `FLOW_SETTING_HIDDEN_WITHOUT_VALUE`, + `FLOW_SETTING_FIXED_WITHOUT_VALUE`, `FLOW_SETTING_INVALID`, `FLOW_SETTING_LOOKS_SECRET`, + `FLOW_THREAD_BINDING_FIXED`, `FLOW_SETTING_CONFLICT` (check), `FLOW_SETTINGS_UNAVAILABLE` + (catalog relay). +- Hidden is not secret. The check refuses values for credential-like setting names. +- **Thread-bound settings (review item 4).** Chosen: refuse at author time. A setting the + thread fills in (a date) that is also fixed or hidden is a check problem + (`FLOW_THREAD_BINDING_FIXED`), at save (the catalog sends `thread_settings`, and the form + sends it to the live check) and at plan. The runtime exemption for thread-bound names stays + only as a safety net for a flow saved before the check, compared through aliases. Reason: a + fixed or hidden setting then never depends on who supplies the thread's value, and the EM's + own thread values need no special case. +- Pieces that share a setting name must agree on type, choices and bounds + (`FLOW_SETTING_CONFLICT`); titles and explanations may differ. +- A model multi-select keeps a bound or default value that is not an accepted value, flagged + "not an accepted value", so the existing validation names it instead of the save losing it. + ## Decisions - 2026-11-20: Per-choice explanations go in the piece's JSON Schema (`oneOf`), not in a new diff --git a/model-catalog-api/src/__tests__/flows.test.ts b/model-catalog-api/src/__tests__/flows.test.ts index ef83822a..7621c133 100644 --- a/model-catalog-api/src/__tests__/flows.test.ts +++ b/model-catalog-api/src/__tests__/flows.test.ts @@ -176,8 +176,22 @@ describe('the catalog rows for a flow', () => { expect(() => planRegistration({ ...BODY(), settings } as any)).toThrow(FlowError) }) + it('mirrors the pieces default into the fixed value when the author gave none', () => { + const body = { ...BODY(), settings: { start: { fixed: true } } } + const built = buildRows(body, planRegistration(body), PIECES, 'alice') + const [start] = built.configuration.parameters.data.map((p: any) => p.parameter.data) + expect(start.label).toBe('start') + expect([start.has_fixed_value, start.has_default_value]).toEqual(['2024-01-01', '2024-01-01']) + }) + + it('tells the check which settings the thread fills in', () => { + expect(planRegistration(BODY()).check.thread_settings).toEqual(['start']) + expect(planRegistration({ ...BODY(), thread_bindings: {} }).check.thread_settings).toEqual([]) + }) + it('writes a Postgres text array literal', () => { expect(toPgTextArray(['a', 'b c'])).toBe('{"a","b c"}') + expect(toPgTextArray(['a', '', ' '])).toBe('{"a"}') }) it('describes a data output from the piece and passes a value output through', () => { diff --git a/model-catalog-api/src/flows.ts b/model-catalog-api/src/flows.ts index 336ee050..83167622 100644 --- a/model-catalog-api/src/flows.ts +++ b/model-catalog-api/src/flows.ts @@ -139,7 +139,7 @@ const VISIBILITIES = ['shown', 'advanced', 'hidden'] /** A Postgres text-array literal: Hasura reads a `text[]` column from one, not from a list. */ export function toPgTextArray(values: string[]): string { - return `{${values.map((value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`).join(',')}}` + return `{${values.filter((value) => value.trim() !== '').map((value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`).join(',')}}` } /** The flow's own choices about each setting, `{name: {visibility, fixed}}`. The @@ -235,6 +235,10 @@ export function planRegistration(body: Json): FlowRegistration { steps: checkedSteps, outputs: checkedOutputs, settings: settingRules(body.settings), + // The settings the thread fills in, so the check can refuse one that is also fixed or hidden. + thread_settings: Object.values(object(body.thread_bindings, 'thread_bindings')) + .flatMap((target) => (target && typeof target === 'object' && typeof (target as Json).setting === 'string' + ? [(target as Json).setting as string] : [])), }, } } diff --git a/svo-adapter-service/app/flow_graph.py b/svo-adapter-service/app/flow_graph.py index 6c03f211..d0365a37 100644 --- a/svo-adapter-service/app/flow_graph.py +++ b/svo-adapter-service/app/flow_graph.py @@ -373,7 +373,7 @@ def _check(flow: dict[str, Any], refused_settings: Iterable[str]) -> Checked: result.depends_on[position] = sorted(after) wired_by_position[position] = wired_settings - _check_settings(flow, by_position, wired_by_position, problems) + _check_settings(flow, by_position, wired_by_position, problems, refused) _check_outputs(flow, by_position, result) _check_pause(flow, by_position, result) _check_thread_bindings(flow, flow_inputs, flow_parameters, problems) @@ -385,12 +385,42 @@ def _check_settings( by_position: dict[int, dict[str, Any]], wired_by_position: dict[int, set[str]], problems: list[Problem], + refused: set[str], ) -> None: - """The author's decisions about settings: they must name settings of the flow's - pieces, and a setting that is hidden or fixed must still have a value to run on.""" + """The author's decisions about settings, and what the pieces say about them. + + - a setting may not be described two ways by the pieces that share its name; + - no credential-like setting may have a value, since a flow's settings are readable + even when hidden; + - decisions must name settings of the flow's pieces; + - a setting that is hidden or fixed must still have a value to run on, and must not + be one the thread fills in (a runner cannot change what a thread fills in either). + """ rules = flow.get("settings") pieces = {position: step["piece"] for position, step in by_position.items() if isinstance(step.get("piece"), dict)} + + seen: dict[str, tuple[int, tuple[Any, ...]]] = {} + for position in sorted(pieces): + properties = (pieces[position].get("parameters_schema_json") or {}).get("properties") or {} + for name in sorted(properties): + key = flow_settings.description_key(properties[name]) + first = seen.setdefault(name, (position, key)) + if first[1] != key: + problems.append(Problem( + "FLOW_SETTING_CONFLICT", + f"{name} has different choices or limits in step {first[0]} and step {position}, " + "but a setting with one name is one setting of the flow", position)) + for position in sorted(by_position): + values = by_position[position].get("settings") + for name in sorted(values if isinstance(values, dict) else {}, key=str): + if flow_settings.looks_secret(name) and str(name).lower() not in refused: + problems.append(Problem( + "FLOW_SETTING_LOOKS_SECRET", + f"{name} looks like a credential. A flow's settings can be read by anyone who can " + "read the flow, even a hidden one: use a stored credential the piece declares instead", + position)) + known = {name for piece in pieces.values() for name in piece_arguments(piece)} shape = flow_settings.rules_problems(rules, known) for message in shape: @@ -404,14 +434,23 @@ def _check_settings( for name in flow_settings.hidden_without_value(rules, pieces[position], given, wired): problems.append(Problem( "FLOW_SETTING_HIDDEN_WITHOUT_VALUE", - f"{name} is hidden from the runner but the piece needs it and nothing gives it a value: " - "set a value or a default, or show it", position)) + f"The setting {name} (step {position}) is hidden from the runner, but the piece needs it " + "and nothing gives it a value: set a value or a default, or show it", position)) + thread_bound = flow_settings.comparable( + [*flow_settings.thread_bound_names(flow.get("thread_bindings")), + *(n for n in flow.get("thread_settings") or [] if isinstance(n, str))]) for name in sorted(n for n in rules if flow_settings.is_fixed(rules, n)): has_value = name in given or any( flow_settings.piece_default(piece, name) is not None for piece in pieces.values()) if not has_value: problems.append(Problem( "FLOW_SETTING_FIXED_WITHOUT_VALUE", f"{name} is fixed but has no value to fix it to")) + for name in sorted(rules): + if ((flow_settings.is_fixed(rules, name) or flow_settings.visibility_of(rules, name) == "hidden") + and flow_settings.comparable([name]) & thread_bound): + problems.append(Problem( + "FLOW_THREAD_BINDING_FIXED", + f"{name} is filled in by the thread (a date), so it cannot also be fixed or hidden")) def _check_outputs(flow: dict[str, Any], by_position: dict[int, dict[str, Any]], result: Checked) -> None: diff --git a/svo-adapter-service/app/flow_settings.py b/svo-adapter-service/app/flow_settings.py index b157f98d..38e12a6e 100644 --- a/svo-adapter-service/app/flow_settings.py +++ b/svo-adapter-service/app/flow_settings.py @@ -20,13 +20,44 @@ """ from __future__ import annotations +import re from typing import Any, Iterable +from .etl_contract import accepted_aliases, canonical_key + VISIBILITIES = ("shown", "advanced", "hidden") # Between the flow's parameter ids and the setting names: ``{configuration}_setting_{name}``. PARAMETER_MARKER = "_setting_" +# A setting whose name says it carries a credential. A flow's settings are readable by +# anyone who can read the flow, hidden ones included ("hidden" is not "secret"), so an +# author may not give such a setting a value: a piece declares a stored credential instead. +_LOOKS_SECRET = re.compile(r"token|secret|password|api_?key|authorization|credential", re.IGNORECASE) + + +def looks_secret(name: Any) -> bool: + return isinstance(name, str) and _LOOKS_SECRET.search(name) is not None + + +def comparable(names: Iterable[Any]) -> set[str]: + """Names as compared for what a runner may not send: trimmed, lower case, and every + form the adapter treats as the same argument (its aliases and canonical key).""" + found: set[str] = set() + for name in accepted_aliases(str(item) for item in names): + found.add(name.strip().lower()) + found.add(str(canonical_key(name)).strip().lower()) + return found + + +def description_key(prop: Any) -> tuple[Any, ...]: + """What two pieces must agree on when they share a setting by name: its type, its + choices (by value) and its bounds. Titles and explanations may differ.""" + described = describe(prop) + return (described.get("type"), tuple(str(c["value"]) for c in described.get("choices", [])), + described.get("minimum"), described.get("maximum")) + + _PASSED_ON = ("type", "default", "description", "title", "minimum", "maximum") diff --git a/svo-adapter-service/app/main.py b/svo-adapter-service/app/main.py index 3486da52..57947ebf 100755 --- a/svo-adapter-service/app/main.py +++ b/svo-adapter-service/app/main.py @@ -2653,9 +2653,13 @@ def _fixed_flow_args(plan_json: dict[str, Any], args: dict[str, Any]) -> list[st # adapter's own setting, never a value from the request. fixed.update({"execution_id", "source_uri", "tapis_token", "flow_staging_uri", "tapis_base_url"}) sent = normalize_args(_wrap_args(args or {})) + # Compared trimmed and without case, so a variant spelling is refused as well. (The + # run itself reads arguments by exact name, so a variant would be unknown anyway.) + fixed_names = flow_settings.comparable(fixed) # What the adapter hands a step bound to a secret: the run, where to fetch, and # each step's own fetch credential. - return sorted(name for name in sent if name in fixed or step_secrets.is_managed_argument(str(name))) + return sorted(name for name in sent + if flow_settings.comparable([name]) & fixed_names or step_secrets.is_managed_argument(str(name))) def _refused_flow_setting_args(plan_json: dict[str, Any], args: dict[str, Any]) -> dict[str, list[str]]: @@ -2665,15 +2669,17 @@ def _refused_flow_setting_args(plan_json: dict[str, Any], args: dict[str, Any]) runner's choice and pass, even when the author hid them.""" if not isinstance(plan_json.get("flow"), dict): return {} - sent = set(normalize_args(_wrap_args(args or {}))) - thread_bound = flow_settings.thread_bound_names((plan_json["flow"]).get("thread_bindings")) + sent = flow_settings.comparable(normalize_args(_wrap_args(args or {}))) + thread_bound = flow_settings.comparable( + flow_settings.thread_bound_names((plan_json["flow"]).get("thread_bindings"))) refused: dict[str, list[str]] = {} for reason, applies in (("fixed", lambda p: p.get("fixed") is True), ("hidden", lambda p: p.get("visibility") == "hidden")): names = sorted( str(parameter["name"]) for parameter in plan_json.get("parameters") or [] - if parameter.get("name") and parameter["name"] not in thread_bound and applies(parameter) - and sent & accepted_aliases([str(parameter["name"])])) + if parameter.get("name") and applies(parameter) + and not flow_settings.comparable([parameter["name"]]) & thread_bound + and flow_settings.comparable([parameter["name"]]) & sent) if names: refused[reason] = names return refused @@ -2877,6 +2883,7 @@ async def check_flow(body: FlowCheckIn, authorization: str | None = Header(None) "outputs": body.outputs, "thread_bindings": body.thread_bindings, "settings": body.settings, + "thread_settings": body.thread_settings, }, refused_settings=_refused_flow_settings()) secret_problems = [ problem for step in body.steps if step.etl_process_id in pieces diff --git a/svo-adapter-service/app/models.py b/svo-adapter-service/app/models.py index 7ae31b58..88969b3a 100755 --- a/svo-adapter-service/app/models.py +++ b/svo-adapter-service/app/models.py @@ -111,6 +111,9 @@ class FlowCheckIn(BaseModel): thread_bindings: dict[str, Any] = Field(default_factory=dict) # What the author decided about each setting: {name: {"visibility", "fixed"}}. settings: dict[str, Any] = Field(default_factory=dict) + # Settings the thread fills in (the dates), by name, when the bindings cannot name + # flow parameters yet (a flow that is not saved). + thread_settings: list[str] = Field(default_factory=list, max_length=64) class FlowProposeIn(BaseModel): diff --git a/svo-adapter-service/docs/api.md b/svo-adapter-service/docs/api.md index 39cc06e5..1b227d24 100644 --- a/svo-adapter-service/docs/api.md +++ b/svo-adapter-service/docs/api.md @@ -168,9 +168,20 @@ The author's choices are kept on the flow as `settings_json` (`{"": {"visibility": "...", "fixed": true}}`) and sent to `POST /flows/check` as `settings`. The check adds `FLOW_SETTING_INVALID` (a malformed choice, or a setting no piece has), `FLOW_SETTING_HIDDEN_WITHOUT_VALUE` (hidden, required by the piece, and nothing gives it a -value) and `FLOW_SETTING_FIXED_WITHOUT_VALUE` (fixed to nothing). `setting_details` in the check's +value), `FLOW_SETTING_FIXED_WITHOUT_VALUE` (fixed to nothing), `FLOW_SETTING_LOOKS_SECRET`, +`FLOW_THREAD_BINDING_FIXED` and `FLOW_SETTING_CONFLICT`. `setting_details` in the check's piece summary carries the same description keys as the settings route. +**Hidden means not shown, not secret.** A hidden setting is left off the run form, but its +value is stored with the flow and can be read by anyone who can read the flow, and the run +dialog lists it before the runner accepts. So the check refuses (`FLOW_SETTING_LOOKS_SECRET`) +any value, default or fixed, for a setting whose name contains `token`, `secret`, `password`, +`api_key`/`apikey`, `authorization` or `credential` (any letter case): a piece declares a +stored credential instead. A setting the thread fills in (the dates) cannot also be fixed or +hidden (`FLOW_THREAD_BINDING_FIXED`; the check body's `thread_settings` names them when the +flow is not saved yet). Pieces that share a setting name must agree on its type, choices and +limits (`FLOW_SETTING_CONFLICT`). + **`POST /plans/flow`** plans a stored flow: `{"flow_id": "", "inputs": {"": ""}}`. The response is a plan like any other, to submit with `/workflows/submit`. @@ -363,8 +374,10 @@ used only when the submitter says so. `execution_id`, `source_uri`, `flow_staging_uri` or `tapis_token`. Plan again to change a dataset. - `POST /workflows/submit` refuses a flow plan with 422 `FLOW_SETTING_REFUSED` when `args` holds a value for a setting the author fixed or hid (`fixed` and `hidden` list which). The - form hides them, and this refusal means the API cannot be used around it. The dates a thread - fills in are not refused, even when hidden. + form hides them, and this refusal means the API cannot be used around it. Names are compared + trimmed, without case and through the adapter's aliases, so a variant spelling is refused too + (the run reads arguments by exact name, so a variant would be an unknown parameter anyway). + Settings the thread fills in are not refused; the check keeps those from being fixed or hidden. **What a flow's author cannot do.** diff --git a/svo-adapter-service/tests/test_flow_settings.py b/svo-adapter-service/tests/test_flow_settings.py index 9672b9f3..ff986d30 100644 --- a/svo-adapter-service/tests/test_flow_settings.py +++ b/svo-adapter-service/tests/test_flow_settings.py @@ -32,6 +32,7 @@ MAX_FILES = {"type": "integer", "title": "Most files", "minimum": 1, "maximum": 500, "default": 200, "x-advanced": True} COLOUR = {"type": "string", "enum": ["red", "green"]} +COLOR_URL = {"type": "string"} @pytest.fixture(autouse=True) @@ -295,3 +296,175 @@ def test_the_run_form_settings_of_a_configuration_that_is_not_a_flow_are_refused stored_flow(register("score", {"a": {"type": "string"}}), monkeypatch) response = client.get("/flows/a-model/settings", headers=AUTH) assert response.status_code == 422 and response.json()["detail"]["code"] == "FLOW_NOT_FOUND" + + +# --- what a runner may not send, however it is spelled ------------------------------- + +@pytest.mark.parametrize("args", [ + {"MATCH_MODE": "longest_match"}, + {" match_mode ": "longest_match"}, + {"Match_Mode": {"value": "longest_match"}}, + {"match_mode": {"value": "longest_match"}}, +]) +def test_a_fixed_setting_is_refused_whatever_the_case_spacing_or_wrapping(monkeypatch, args): + piece = register("score", {"match_mode": MATCH_MODE}) + stored_flow(piece, monkeypatch, settings={"match_mode": {"fixed": True}}) + plan_id = plan().json()["plan_id"] + refused = submit(plan_id, args=args) + assert refused.status_code == 422 and refused.json()["detail"]["code"] == "FLOW_SETTING_REFUSED" + + +def test_the_managed_arguments_are_refused_whatever_the_case(monkeypatch): + piece = register("score", {"match_mode": MATCH_MODE}) + stored_flow(piece, monkeypatch) + plan_id = plan().json()["plan_id"] + for name in ("SOURCE_URI", " source_uri", "Execution_Id"): + refused = submit(plan_id, args={name: "x"}) + assert refused.status_code == 422 and refused.json()["detail"]["code"] == "FLOW_ARGUMENT_FIXED", name + + +def test_a_variant_spelling_is_not_a_way_round_because_the_run_reads_exact_names(monkeypatch): + # Refused above on purpose; and were it not, the plan's own argument check is exact. + piece = register("score", {"match_mode": MATCH_MODE}) + stored_flow(piece, monkeypatch) + plan_json = plan().json()["plan_json"] + with pytest.raises(Exception) as unknown: + main_module._validate_plan_args(plan_json, {"MATCH_MODE": "x"}, "tok") + assert "UNKNOWN_PARAMETERS" in str(unknown.value.detail) + + +def test_an_aliased_name_is_compared_as_the_same_setting(): + plan_json = { + "flow": {"thread_bindings": {"start_date": {"parameter": "cfg-1_setting_gma_boundary_uri"}}}, + "parameters": [{"name": "geometry_source_uri", "visibility": "hidden"}, + {"name": "other", "visibility": "hidden"}, + {"name": "pinned", "fixed": True}]} + refused = main_module._refused_flow_setting_args( + plan_json, {"location_file_uri": "x", "OTHER": "y", " Pinned": "z"}) + # The thread fills in the aliased name; the others are refused. + assert refused == {"fixed": ["pinned"], "hidden": ["other"]} + assert main_module._refused_flow_setting_args(plan_json, {"geometry_source_uri": "x"}) == {} + + +def test_every_author_value_is_listed_for_acceptance_whatever_its_visibility(monkeypatch): + piece = register("score", {"match_mode": MATCH_MODE, "colour": COLOR_URL}) + stored_flow(piece, monkeypatch, settings={"colour": {"visibility": "hidden", "fixed": True}, + "match_mode": {"visibility": "advanced"}}, + step_settings={"colour": "https://elsewhere.example/x.json", "match_mode": "longest_match"}) + plan_json = plan().json()["plan_json"] + gate = main_module._unaccepted_flow_settings(plan_json, {}) + assert gate["defaults"] == {"colour": "https://elsewhere.example/x.json", "match_mode": "longest_match"} + refused = submit(plan().json()["plan_id"], accept_flow_settings=False, dry_run=False) + assert refused.json()["detail"]["code"] == "FLOW_SETTINGS_NOT_ACCEPTED" + assert "colour" in refused.json()["detail"]["defaults"] + + +def test_a_fixed_value_reaches_the_run_when_the_runner_sends_nothing(monkeypatch): + piece = register("score", {"match_mode": MATCH_MODE}) + stored_flow(piece, monkeypatch, settings={"match_mode": {"fixed": True, "visibility": "hidden"}}, + step_settings={"match_mode": "longest_match"}) + body = plan().json() + used = main_module._validate_plan_args(body["plan_json"], {}, "tok", require_required=False) + assert used["match_mode"] == {"value": "longest_match"} + from app import tapis + pipeline = tapis.generate_tapis_workflow({"id": body["plan_id"], "plan_json": body["plan_json"]}) + assert pipeline["params"]["match_mode"]["default"] == "longest_match" + + +# --- the check: credentials, thread values, conflicts, messages ---------------------- + +@pytest.mark.parametrize("name", ["service_token_url", "My_Password_Hint", "ApiKeyName", "api_key", "AUTHORIZATION_note", + "credentials_file"]) +def test_a_credential_like_setting_may_not_be_given_a_value(name): + piece = register("score", {name: {"type": "string"}}) + refused = check(piece, None, {name: "abc"}) + assert refused["ok"] is False + assert [p["code"] for p in refused["problems"]] == ["FLOW_SETTING_LOOKS_SECRET"] + assert refused["problems"][0]["step"] == 1 and "stored credential" in refused["problems"][0]["message"] + # Without a value there is nothing to leak: the runner may be asked for it. + assert check(piece)["ok"] is True + + +def test_a_setting_the_thread_fills_in_cannot_also_be_fixed_or_hidden(): + piece = register("score", {"start": {"type": "string", "default": "2020"}}) + body = {"thread_settings": ["Start"]} + for rule in ({"fixed": True}, {"visibility": "hidden"}): + result = client.post("/flows/check", headers=AUTH, json={ + "inputs": [{"id": "in:corpus", "contract": {"standard_variable_uri": V + "corpus"}}], + "steps": [{"position": 1, "etl_process_id": piece, "settings": {"start": "2021"}, + "wires": [{"to": {"input": 1}, "from": {"flow_input": "in:corpus"}}]}], + "settings": {"start": rule}, **body}).json() + assert [p["code"] for p in result["problems"]] == ["FLOW_THREAD_BINDING_FIXED"] + shown = client.post("/flows/check", headers=AUTH, json={ + "inputs": [{"id": "in:corpus", "contract": {"standard_variable_uri": V + "corpus"}}], + "steps": [{"position": 1, "etl_process_id": piece, "settings": {}, + "wires": [{"to": {"input": 1}, "from": {"flow_input": "in:corpus"}}]}], + "settings": {"start": {"visibility": "advanced"}}, **body}).json() + assert shown["ok"] is True + + +def test_a_stored_flow_whose_thread_binding_names_a_fixed_setting_is_refused_at_plan(monkeypatch): + piece = register("score", {"start": {"type": "string", "default": "2020"}}) + stored_flow(piece, monkeypatch, settings={"start": {"fixed": True}}, + step_settings={"start": "2021"}) + flow = main_module._load_flow # the stored stand-in + import asyncio + stored = asyncio.run(flow(None, "cfg-1")) + stored["thread_bindings"] = {"start_date": {"parameter": "cfg-1_setting_start"}} + response = plan() + assert response.status_code == 422 + assert "FLOW_THREAD_BINDING_FIXED" in str(response.json()["detail"]["problems"]) + + +def test_two_pieces_may_not_describe_one_setting_two_ways(): + a = register("a", {"mode": {"type": "string", "enum": ["x", "y"]}}) + b = register("b", {"mode": {"type": "string", "enum": ["x", "z"]}}) + c = register("c", {"mode": {"type": "string", "enum": ["y", "x"][::-1], "title": "Other title"}}) + wires = [{"to": {"input": 1}, "from": {"flow_input": "in:corpus"}}] + steps = lambda *ids: [{"position": i + 1, "etl_process_id": p, "settings": {}, "wires": wires} # noqa: E731 + for i, p in enumerate(ids)] + inputs = [{"id": "in:corpus", "contract": {"standard_variable_uri": V + "corpus"}}] + clash = client.post("/flows/check", headers=AUTH, json={"inputs": inputs, "steps": steps(a, b)}).json() + assert [(p["code"], p["step"]) for p in clash["problems"]] == [("FLOW_SETTING_CONFLICT", 2)] + assert "step 1 and step 2" in clash["problems"][0]["message"] + same = client.post("/flows/check", headers=AUTH, json={"inputs": inputs, "steps": steps(a, c)}).json() + assert same["ok"] is True # titles and explanations may differ; choices and limits may not + + +def test_the_hidden_message_names_the_setting_and_the_step(): + piece = register("score", {"mode": {"type": "string"}}, required=["mode"]) + problem = check(piece, {"mode": {"visibility": "hidden"}})["problems"][0] + assert "mode" in problem["message"] and "step 1" in problem["message"] and problem["step"] == 1 + + +def test_a_hidden_setting_linked_from_an_earlier_step_has_a_value(): + first = client.post("/transform-specs", json={ + "name": "resolve", "method": "tapis_function", "transform_type": "unit_convert", + "contracts": [{"role": "output", "standard_variable_uri": V + "archive"}], + "parameters_schema_json": {"properties": {}, "value_outputs": [{"name": "manifest_name"}]}}).json()["id"] + second = client.post("/transform-specs", json={ + "name": "publish", "method": "tapis_function", "transform_type": "unit_convert", + "contracts": [{"role": "input", "standard_variable_uri": V + "archive"}], + "parameters_schema_json": {"properties": {"manifest_name": {"type": "string"}}, + "required": ["manifest_name"]}, + "env_from_args": {"TAPIS_TOKEN": "tapis_token", "MANIFEST_NAME": "manifest_name"}}).json()["id"] + result = client.post("/flows/check", headers=AUTH, json={ + "steps": [ + {"position": 1, "etl_process_id": first, "settings": {}, "wires": []}, + {"position": 2, "etl_process_id": second, "settings": {}, "wires": [ + {"to": {"input": 1}, "from": {"step": 1, "output": 1}}, + {"to": {"setting": "manifest_name"}, "from": {"step": 1, "value": "manifest_name"}}]}], + "settings": {"manifest_name": {"visibility": "hidden"}}}).json() + assert result["ok"] is True, result["problems"] + + +def test_a_decision_about_a_setting_only_a_removed_piece_had_is_refused(): + piece = register("score", {"mode": {"type": "string"}}) + result = client.post("/flows/check", headers=AUTH, json={ + "inputs": [{"id": "in:corpus", "contract": {"standard_variable_uri": V + "corpus"}}], + "steps": [ + {"position": 1, "etl_process_id": piece, "settings": {}, + "wires": [{"to": {"input": 1}, "from": {"flow_input": "in:corpus"}}]}, + {"position": 2, "etl_process_id": "no-such-piece", "settings": {}, "wires": []}], + "settings": {"gone": {"visibility": "hidden"}}}).json() + assert "FLOW_SETTING_INVALID" in [p["code"] for p in result["problems"]] diff --git a/ui-react/docs/docs/data-scientist/build-a-flow.md b/ui-react/docs/docs/data-scientist/build-a-flow.md index 9d89cb8f..d3439570 100644 --- a/ui-react/docs/docs/data-scientist/build-a-flow.md +++ b/ui-react/docs/docs/data-scientist/build-a-flow.md @@ -90,6 +90,8 @@ The form has these parts, in order. - **Default or Fixed.** With *Default: a runner can change it*, the person who runs the flow sees your value and may change it. With *Fixed: a runner cannot change it*, they see the value but cannot change it, and a run that tries to change it is refused. - **Who sees it.** *Shown* puts it in the main list. *Advanced settings* puts it in a collapsed section of the run form. The piece may suggest this for a rarely changed argument, and you can override it. *Hidden from runners* keeps it off the run form entirely: the run uses your fixed value, else your default, else the piece's default. If a piece requires a hidden setting and nothing gives it a value, the check says so and the flow cannot be saved. + **Hidden means not shown, not secret.** Anyone who can read the flow can read a hidden value, and the run dialog lists every value you chose before a runner accepts it. The check therefore refuses a value for a setting whose name looks like a credential (it contains token, secret, password, api key, authorization or credential). Use a stored credential instead. A setting the thread fills in, such as a date, cannot also be fixed or hidden. If two steps' pieces describe a shared setting with different choices or limits, the check asks you to resolve it. + A setting that is linked to an earlier step's output cannot also have a default, and its value cannot be edited here. A setting name used by more than one step is one setting of the flow, so the choices apply to all of them. 5. **Outputs**. Add the outputs the flow reports, with **Add output**. 6. **What the thread fills in**. The settings the flow takes from the thread. A value that is fixed here is shown to the person who runs the flow. Which inputs take a collection is set on each input above. diff --git a/ui-react/src/components/flows/StepCard.tsx b/ui-react/src/components/flows/StepCard.tsx index a24ade9b..8621b0af 100644 --- a/ui-react/src/components/flows/StepCard.tsx +++ b/ui-react/src/components/flows/StepCard.tsx @@ -278,6 +278,12 @@ export function StepCard(props: StepCardProps) { + {shown === 'hidden' && ( + + Hidden means not shown, not secret: anyone who can read this flow can see + the value. Use a stored credential for anything private. + + )} )}
    diff --git a/ui-react/src/components/flows/__tests__/FlowAuthoringForm.test.tsx b/ui-react/src/components/flows/__tests__/FlowAuthoringForm.test.tsx index ea1427c8..b613f7d7 100644 --- a/ui-react/src/components/flows/__tests__/FlowAuthoringForm.test.tsx +++ b/ui-react/src/components/flows/__tests__/FlowAuthoringForm.test.tsx @@ -334,6 +334,19 @@ describe('FlowAuthoringForm', () => { expect(check.body.settings).toEqual({ match_mode: { fixed: true, visibility: 'hidden' } }); }); + it('says that hidden is not secret, once a setting is hidden', async () => { + fakeServer(); + const user = userEvent.setup(); + render({ initial: counting() }); + const step = await screen.findByTestId('flow-form-step-1'); + expect(within(step).queryByText(/not shown, not secret/)).not.toBeInTheDocument(); + await user.selectOptions( + await within(step).findByLabelText('Who sees How terms are counted'), + 'hidden', + ); + expect(within(step).getByText(/not shown, not secret/)).toBeInTheDocument(); + }); + it('sends no decisions when the author made none', async () => { fakeServer(); render({ initial: counting() }); diff --git a/ui-react/src/lib/__tests__/flow-authoring.test.ts b/ui-react/src/lib/__tests__/flow-authoring.test.ts index a83d8e3d..25164fc4 100644 --- a/ui-react/src/lib/__tests__/flow-authoring.test.ts +++ b/ui-react/src/lib/__tests__/flow-authoring.test.ts @@ -321,6 +321,14 @@ describe('what the author decides about a setting', () => { }); }); + it('tells the check which settings the thread fills in', () => { + const draft: FlowDraft = { + ...emptyDraft(), + bindings: { ...emptyDraft().bindings, start_date: 'setting:begin', region: 'input:corpus' }, + }; + expect(buildCheckBody(draft).thread_settings).toEqual(['begin']); + }); + it('is read back from a stored flow, ignoring what it cannot read', () => { const base: StoredFlowSource = { configuration: { label: 'F', inputs: [], outputs: [], parameters: [] }, diff --git a/ui-react/src/lib/flow-authoring.ts b/ui-react/src/lib/flow-authoring.ts index 3439ef6b..272ffae9 100644 --- a/ui-react/src/lib/flow-authoring.ts +++ b/ui-react/src/lib/flow-authoring.ts @@ -185,6 +185,12 @@ export function buildCheckBody(draft: FlowDraft, known?: ReadonlySet) { outputs: draft.outputs.map((output) => outputJson(output, false)), thread_bindings: bindings, settings: settingRulesJson(draft, known), + // The settings the thread fills in: the check refuses one that is also fixed or hidden. + thread_settings: BINDING_ROLES.flatMap((role) => + draft.bindings[role].startsWith('setting:') + ? [draft.bindings[role].slice('setting:'.length)] + : [], + ), }; } diff --git a/ui-react/src/pages/modeling/thread/MintParameters.tsx b/ui-react/src/pages/modeling/thread/MintParameters.tsx index 0100e95f..015464c3 100644 --- a/ui-react/src/pages/modeling/thread/MintParameters.tsx +++ b/ui-react/src/pages/modeling/thread/MintParameters.tsx @@ -569,11 +569,16 @@ export function MintParameters({ !model.isFlow && p.accepted_values?.length ? p.accepted_values : null; const min = view ? view.details.minimum : p.min; const max = view ? view.details.maximum : p.max; + // What is chosen already, or the default. A value the list does not hold + // (an old binding, say) stays visible and selected, flagged, so the + // validation names it instead of the save quietly losing it. const selected = accepted - ? (bindings.length > 0 - ? bindings - : (p.default ?? '').split(/\s*,\s*/).filter(Boolean) - ).filter((value) => accepted.includes(value)) + ? bindings.length > 0 + ? bindings + : (p.default ?? '').split(/\s*,\s*/).filter(Boolean) + : []; + const notAccepted = accepted + ? [...new Set(selected.filter((value) => !accepted.includes(value)))] : []; return ( @@ -614,7 +619,7 @@ export function MintParameters({ name={p.id ?? ''} data-testid={`param-input-${p.id}`} defaultValue={selected} - size={Math.min(accepted.length, 6)} + size={Math.min(accepted.length + notAccepted.length, 6)} className="w-full rounded border bg-background px-2 py-1 text-xs focus:outline-none focus:ring-1 focus:ring-blue-400" > {accepted.map((value) => ( @@ -622,6 +627,11 @@ export function MintParameters({ {value} ))} + {notAccepted.map((value) => ( + + ))}
    Hold Ctrl or Cmd to pick more than one: each value is a run. diff --git a/ui-react/src/pages/modeling/thread/__tests__/FlowSettingsDialog.test.tsx b/ui-react/src/pages/modeling/thread/__tests__/FlowSettingsDialog.test.tsx index 087d8269..17cbf772 100644 --- a/ui-react/src/pages/modeling/thread/__tests__/FlowSettingsDialog.test.tsx +++ b/ui-react/src/pages/modeling/thread/__tests__/FlowSettingsDialog.test.tsx @@ -20,6 +20,26 @@ describe('FlowSettingsDialog', () => { ); }); + it('lists every value the author chose, hidden and fixed ones and web addresses too', () => { + // The plan lists the author's values whatever the form shows, so the runner reads + // each one before accepting. Nothing here is filtered by visibility. + open({ + settings: { + defaults: { + taxonomy_uri: 'https://elsewhere.example/taxonomy.json', + chat_kind: 'openai_compatible', + max_files: 5, + }, + links: [], + }, + }); + const defaults = screen.getByTestId('flow-settings-defaults'); + expect(defaults).toHaveTextContent('taxonomy uri: https://elsewhere.example/taxonomy.json'); + expect(defaults).toHaveTextContent('chat kind: openai_compatible'); + expect(defaults).toHaveTextContent('max files: 5'); + expect(screen.getByRole('button', { name: 'Accept and run' })).toBeDisabled(); + }); + it('writes a linked setting with the step names, never as JSON', () => { open({ settings: { diff --git a/ui-react/src/pages/modeling/thread/__tests__/MintParameters.test.tsx b/ui-react/src/pages/modeling/thread/__tests__/MintParameters.test.tsx index 24825140..6cbba0c6 100644 --- a/ui-react/src/pages/modeling/thread/__tests__/MintParameters.test.tsx +++ b/ui-react/src/pages/modeling/thread/__tests__/MintParameters.test.tsx @@ -760,6 +760,29 @@ describe('the settings of a flow', () => { expect(onSave).not.toHaveBeenCalled(); }); + it('still lists a fixed setting read-only from its row when the settings cannot be read', async () => { + vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, json: async () => ({}) })); + const data = flowData(); + data.models['model-1']!.input_parameters = [ + row('p-pinned', 'grounding', { default: 'keyword', value: 'keyword' }), + row('p-plain', 'title'), + ]; + renderWithProviders( + , + ); + fireEvent.click(screen.getByTestId('edit-parameters-btn')); + expect(screen.getByText(/expert modeler has selected/i)).toBeInTheDocument(); + expect(screen.getByText('keyword')).toBeInTheDocument(); + expect(screen.queryByTestId('param-input-p-pinned')).not.toBeInTheDocument(); + expect(screen.getByTestId('param-input-p-plain')).toBeInTheDocument(); + }); + it('still shows a dropdown from the flows parameter rows when the settings cannot be read', async () => { vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, json: async () => ({}) })); const data = flowData(); @@ -846,4 +869,17 @@ describe('a model parameter with accepted values', () => { const select = screen.getByTestId('param-input-param-s') as HTMLSelectElement; expect(Array.from(select.selectedOptions).map((o) => o.value)).toEqual(['upstream', 'tvd']); }); + + it('keeps a bound value the list does not hold, flagged, and says so on save', async () => { + // An old model saved comma separated values: one of them is not an accepted value. + const onSave = render_({ 'param-s': ['central', 'upwind'] }); + const select = screen.getByTestId('param-input-param-s') as HTMLSelectElement; + expect( + screen.getByRole('option', { name: 'upwind (not an accepted value)' }), + ).toBeInTheDocument(); + expect(Array.from(select.selectedOptions).map((o) => o.value)).toEqual(['central', 'upwind']); + fireEvent.click(screen.getByTestId('parameters-save-btn')); + expect(await screen.findByTestId('param-error-param-s')).toHaveTextContent('Accepted values'); + expect(onSave).not.toHaveBeenCalled(); + }); });