From ca59c90b1de8169e6c09691ab5e9ca92e57b2003 Mon Sep 17 00:00:00 2001 From: Will Mobley Date: Fri, 20 Nov 2026 12:59:43 -0600 Subject: [PATCH 01/12] Upload page: Use in a thread starts guided model setup with the dataset and recommended models The wizard shows models that take the uploaded variable first, close matches as a second tier, and prefills the question, period and region (editable). --- ui-react/src/lib/datasets/upload-preview.ts | 33 ++++++++ .../src/pages/datasets/DatasetUploadPage.tsx | 21 +++++- .../__tests__/DatasetUploadPage.test.tsx | 29 ++++++- .../src/pages/modeling/GuidedModelSetup.tsx | 75 +++++++++++++++++-- .../__tests__/GuidedModelSetup.test.tsx | 65 ++++++++++++++++ 5 files changed, 211 insertions(+), 12 deletions(-) diff --git a/ui-react/src/lib/datasets/upload-preview.ts b/ui-react/src/lib/datasets/upload-preview.ts index ace22e0b..283a91b1 100644 --- a/ui-react/src/lib/datasets/upload-preview.ts +++ b/ui-react/src/lib/datasets/upload-preview.ts @@ -103,3 +103,36 @@ export function closeConsumers( } return found; } + +export interface GuidedSetupLinkInput { + datasetId: string; + variable: { label: string } | null; + exact: UploadConsumer[]; + close: CloseConsumer[]; + title: string; + startDate: string; + endDate: string; + /** Only set when the user picked a catalog region; a drawn box is derived from the dataset instead. */ + regionId?: string; +} + +/** + * The guided model setup URL for a just-uploaded dataset. The exact consumers + * travel as `modelIds` (recommended), the close matches as `closeModelIds`, and + * `modelNames` maps ids to readable names. Nothing here confirms anything: the + * wizard still asks the user to frame the question. + */ +export function guidedSetupLink(input: GuidedSetupLinkInput): string { + const params = new URLSearchParams({ datasetId: input.datasetId }); + if (input.exact.length) params.set('modelIds', input.exact.map((c) => c.id).join(',')); + if (input.close.length) params.set('closeModelIds', input.close.map((c) => c.id).join(',')); + const names: Record = {}; + for (const c of [...input.exact, ...input.close]) names[c.id] = c.name; + if (Object.keys(names).length) params.set('modelNames', JSON.stringify(names)); + if (input.variable) params.set('variable', input.variable.label); + if (input.title.trim()) params.set('goal', input.title.trim()); + if (input.startDate) params.set('startDate', input.startDate); + if (input.endDate) params.set('endDate', input.endDate); + if (input.regionId) params.set('regionId', input.regionId); + return `/modeling/problem-statements/start?${params.toString()}`; +} diff --git a/ui-react/src/pages/datasets/DatasetUploadPage.tsx b/ui-react/src/pages/datasets/DatasetUploadPage.tsx index 4c2a8bc7..5ed8dfc7 100644 --- a/ui-react/src/pages/datasets/DatasetUploadPage.tsx +++ b/ui-react/src/pages/datasets/DatasetUploadPage.tsx @@ -35,7 +35,11 @@ import { } from '@/lib/ckan-upload'; import { useDebouncedValue } from '@/hooks/useDebouncedValue'; import { useSemanticSearch, useSimilarVariables } from '@/hooks/useSemanticSearch'; -import { closeConsumers, consumersOfVariable } from '@/lib/datasets/upload-preview'; +import { + closeConsumers, + consumersOfVariable, + guidedSetupLink, +} from '@/lib/datasets/upload-preview'; import { unionBoundingBox, type BoundingBox } from '@/lib/geo/bbox'; import { standardVariableName } from '@/lib/standard-variable-display'; import { useAuth } from '@/lib/auth/useAuth'; @@ -304,7 +308,20 @@ export function DatasetUploadPage() { + ) : ( + + )} + choose(option)} + > + + {option.label} + + + {isExpanded && + option.parts?.map((part) => ( +
+ choose(part)}> + + {part.label} + +
+ ))} + + ); + }; + + const ungrouped = visible.filter((option) => !option.group); + + return ( + { + setOpen(next); + if (!next) setQuery(''); + }} + > + + + + + + + + No matching boundaries. + {query.trim() === '' && ( + + choose(null)}> + + All boundaries + + + )} + {ungrouped.length > 0 && {ungrouped.map(renderOption)}} + {groups.map((group) => ( + + {visible.filter((option) => option.group === group).map(renderOption)} + + ))} + + + + + ); +} diff --git a/ui-react/src/pages/modeling/thread/SpatialScopeMap.tsx b/ui-react/src/pages/modeling/thread/SpatialScopeMap.tsx index c35cc070..70cf3b5d 100644 --- a/ui-react/src/pages/modeling/thread/SpatialScopeMap.tsx +++ b/ui-react/src/pages/modeling/thread/SpatialScopeMap.tsx @@ -8,8 +8,17 @@ import 'leaflet/dist/leaflet.css'; import { parseGeometry } from '@/pages/regions/regionUtils'; import { LIST_REGISTERED_BOUNDARY_REGIONS } from '@/graphql/queries/regions'; import { fetchSpatialLayers, spatialLayersAvailable } from '@/lib/spatial-layers'; +import { + boundaryGroups, + buildLayerOptions, + buildRegionOptions, + findBoundaryOption, + type BoundaryLabelConfig, + type BoundaryOption, +} from '@/lib/spatial-boundaries'; +import { BoundaryCombobox } from './BoundaryCombobox'; -interface SpatialLayerCatalogEntry { +interface SpatialLayerCatalogEntry extends BoundaryLabelConfig { id: string; label: string; uri: string; @@ -85,6 +94,9 @@ type RegisteredBoundaryRegionsData = { // pulling the much larger administrative level datasets into every map. const REGISTERED_BOUNDARY_CATEGORY_IDS = ['hydrology']; +/** Sentinel for the category select's "All categories" entry. */ +const ALL_CATEGORIES = '__all__'; + /** Cartographic preview of the spatial scope carried by the problem statement. */ export function SpatialScopeMap({ geometries = [], @@ -103,6 +115,7 @@ export function SpatialScopeMap({ const [selectedLayerId, setSelectedLayerId] = useState(''); const [layerFeatures, setLayerFeatures] = useState([]); const [selectedFeatureValue, setSelectedFeatureValue] = useState(''); + const [categoryChoice, setCategoryChoice] = useState(''); const [layerLoading, setLayerLoading] = useState(false); const [layerError, setLayerError] = useState(null); @@ -187,42 +200,49 @@ export function SpatialScopeMap({ const activeFilterField = filterField?.trim() || selectedLayer?.default_filter_field; - const featureOptions = useMemo(() => { + const isRegionLayer = selectedLayer?.source_type === 'mint-regions'; + const allOptions = useMemo(() => { if (!activeFilterField) return []; - const options = layerFeatures.flatMap((feature) => { - const rawValue = feature.properties?.[activeFilterField]; - if (rawValue == null || String(rawValue).trim() === '') return []; - const value = String(rawValue); - const name = - feature.properties?.GMAName ?? - feature.properties?.GMA_Name ?? - feature.properties?.GMA_NAME ?? - feature.properties?.Name ?? - feature.properties?.name ?? - feature.properties?.region_name ?? - feature.properties?.label ?? - ''; - return [ - { - value, - label: name ? `${value} — ${String(name)}` : value, - }, - ]; - }); - return options - .filter( - (option, index) => - options.findIndex((candidate) => candidate.value === option.value) === index, - ) - .sort((left, right) => left.label.localeCompare(right.label, undefined, { numeric: true })); - }, [activeFilterField, layerFeatures]); + return isRegionLayer + ? buildRegionOptions(layerFeatures, activeFilterField) + : buildLayerOptions(layerFeatures, activeFilterField, selectedLayer); + }, [activeFilterField, isRegionLayer, layerFeatures, selectedLayer]); + + // Registered regions span several categories. Show one at a time, starting + // with the saved selection's category, so the map is not a pile of overlaps. + const categories = useMemo(() => boundaryGroups(allOptions), [allOptions]); + const savedOption = findBoundaryOption( + allOptions, + selectedFeatureValue || filterValue?.trim() || '', + ); + const activeCategory = + categories.length > 1 && categoryChoice !== ALL_CATEGORIES + ? categories.includes(categoryChoice) + ? categoryChoice + : (savedOption?.group ?? categories[0] ?? '') + : ''; + const featureOptions = useMemo( + () => (activeCategory ? allOptions.filter((o) => o.group === activeCategory) : allOptions), + [activeCategory, allOptions], + ); + const visibleFeatures = useMemo( + () => + activeCategory + ? layerFeatures.filter((f) => f.properties?.category_name === activeCategory) + : layerFeatures, + [activeCategory, layerFeatures], + ); + const selectedOption = findBoundaryOption(allOptions, selectedFeatureValue); + const selectedValues = useMemo(() => new Set(selectedOption?.values ?? []), [selectedOption]); + const isSelectedFeature = (feature: GeoJSON.Feature) => + selectedValues.has(String(feature.properties?.[activeFilterField ?? ''])); useEffect(() => { const nextValue = filterValue?.trim() ?? ''; setSelectedFeatureValue( - nextValue && featureOptions.some((option) => option.value === nextValue) ? nextValue : '', + nextValue && findBoundaryOption(allOptions, nextValue) ? nextValue : '', ); - }, [featureOptions, filterValue]); + }, [allOptions, filterValue]); useEffect(() => { if (!selectedLayer) { @@ -249,6 +269,8 @@ export function SpatialScopeMap({ // (for example GMAnum=12) for ETL arguments. region_id: region.id.split('__').pop() ?? region.id, region_name: region.name, + category_id: region.category_id, + category_name: region.region_category?.name ?? region.category_id, }, geometry: parsed, } as GeoJSON.Feature, @@ -318,20 +340,20 @@ export function SpatialScopeMap({ () => ({ type: 'FeatureCollection', features: [ - ...layerFeatures.map((feature) => ({ + ...visibleFeatures.map((feature) => ({ ...feature, properties: { ...(feature.properties ?? {}), catalogLayer: true, selectedBoundary: - Boolean(selectedFeatureValue) && - String(feature.properties?.[activeFilterField ?? '']) === selectedFeatureValue, + selectedValues.size > 0 && + selectedValues.has(String(feature.properties?.[activeFilterField ?? ''])), }, })), ...selectedScopeFeatures, ], }), - [activeFilterField, layerFeatures, selectedFeatureValue, selectedScopeFeatures], + [activeFilterField, selectedValues, selectedScopeFeatures, visibleFeatures], ); const sourceIsCustom = Boolean( @@ -341,11 +363,8 @@ export function SpatialScopeMap({ ), ); const activeLayerLabel = sourceIsCustom ? 'Custom geometry source' : selectedLayer?.label; - const focusedFeatures = selectedFeatureValue - ? layerFeatures.filter( - (feature) => String(feature.properties?.[activeFilterField ?? '']) === selectedFeatureValue, - ) - : []; + const focusedFeatures = selectedFeatureValue ? visibleFeatures.filter(isSelectedFeature) : []; + const hasSelection = selectedValues.size > 0; const style = (feature?: GeoJSON.Feature): PathOptions => feature?.properties?.selectedBoundary @@ -363,12 +382,15 @@ export function SpatialScopeMap({ fillOpacity: 0, interactive: false, } - : { - color: '#1d4ed8', - weight: 1.5, - fillColor: '#3b82f6', - fillOpacity: 0.12, - }; + : hasSelection + ? // Everything but the selection is faint, so the choice stands out. + { color: '#94a3b8', weight: 1, fillColor: '#94a3b8', fillOpacity: 0.04 } + : { + color: '#1d4ed8', + weight: 1.5, + fillColor: '#3b82f6', + fillOpacity: 0.08, + }; return (
@@ -386,6 +408,7 @@ export function SpatialScopeMap({ const nextId = event.target.value; setSelectedLayerId(nextId); setSelectedFeatureValue(''); + setCategoryChoice(''); const nextLayer = layers.find((layer) => layer.id === nextId); if (nextLayer) onLayerSelect?.(nextLayer); }} @@ -397,41 +420,50 @@ export function SpatialScopeMap({ ))} - {featureOptions.length > 0 && ( + {categories.length > 1 && ( )} + {allOptions.length > 0 && ( +
+ Boundary + { + setSelectedFeatureValue(option?.value ?? ''); + if (!option || !activeFilterField) return; + onFeatureSelect?.({ + filterField: activeFilterField, + filterValue: option.value, + label: option.label, + layer: selectedLayer, + geometry: boundaryGeometry(layerFeatures, activeFilterField, option), + }); + }} + /> +
+ )}
)}
@@ -457,7 +489,7 @@ export function SpatialScopeMap({ const option = featureValue == null ? undefined - : featureOptions.find((item) => item.value === String(featureValue)); + : findBoundaryOption(allOptions, String(featureValue)); const scopeName = option?.label ?? (featureValue == null ? activeLayerLabel : String(featureValue)); if (scopeName && (!isStoredScope || layerFeatures.length === 0)) { @@ -470,7 +502,7 @@ export function SpatialScopeMap({ ) { layer.on('click', () => { const value = String(feature.properties?.[activeFilterField]); - const option = featureOptions.find((item) => item.value === value); + const option = findBoundaryOption(allOptions, value); setSelectedFeatureValue(value); onFeatureSelect?.({ filterField: activeFilterField, @@ -497,7 +529,7 @@ export function SpatialScopeMap({
{activeLayerLabel ?? 'Stored region geometry'} - {scopeId ? ` · ${label ?? scopeId}` : ''} + {scopeId && label ? ` · ${label}` : ''} {layerLoading ? 'Loading layer…' : (layerError ?? 'OpenStreetMap base map')}
@@ -505,6 +537,20 @@ export function SpatialScopeMap({ ); } +/** The geometry a boundary option stands for: one feature's, or the union of a family's parts. */ +function boundaryGeometry( + features: GeoJSON.Feature[], + filterField: string, + option: BoundaryOption, +): GeoJSON.Geometry | undefined { + const values = new Set(option.values); + const geometries = features + .filter((feature) => values.has(String(feature.properties?.[filterField]))) + .flatMap((feature) => (feature.geometry ? [feature.geometry] : [])); + if (geometries.length <= 1) return geometries[0]; + return { type: 'GeometryCollection', geometries }; +} + function spatialLayerQueryUrl(uri: string): string | null { try { const url = new URL(uri); 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..e6b87469 100644 --- a/ui-react/src/pages/modeling/thread/__tests__/MintParameters.test.tsx +++ b/ui-react/src/pages/modeling/thread/__tests__/MintParameters.test.tsx @@ -205,14 +205,10 @@ describe('MintParameters', () => { expect( screen.getByRole('option', { name: 'TWDB Statewide GMA Boundaries' }), ).toBeInTheDocument(); - await waitFor(() => { - expect(screen.getByRole('option', { name: '8 — Gulf Coast' })).toBeInTheDocument(); - expect( - Array.from( - screen.getByLabelText('Spatial boundary feature').querySelectorAll('option'), - ).map((option) => option.textContent), - ).toEqual(['All boundaries', '2 — Central High Plains', '8 — Gulf Coast']); - }); + const picker = await screen.findByRole('combobox', { name: 'Spatial boundary feature' }); + fireEvent.click(picker); + expect(await screen.findByText('2 — Central High Plains')).toBeInTheDocument(); + expect(screen.getByText('8 — Gulf Coast')).toBeInTheDocument(); // The layers come from the Ensemble Manager; the browser does not call the adapter. expect(fetchMock).toHaveBeenCalledWith( 'http://em/v1/spatial/layers', @@ -326,7 +322,9 @@ describe('MintParameters', () => { fireEvent.change(screen.getByLabelText('Spatial boundary layer'), { target: { value: 'mint_registered_ground_water_availability_models' }, }); - expect(await screen.findByRole('option', { name: 'gams_12 — GMA 12' })).toBeInTheDocument(); + fireEvent.click(await screen.findByRole('combobox', { name: 'Spatial boundary feature' })); + expect(await screen.findByText('GMA 12')).toBeInTheDocument(); + expect(screen.queryByText(/gams_12/)).not.toBeInTheDocument(); vi.unstubAllGlobals(); Reflect.deleteProperty(window, '__MINT_CONFIG__'); diff --git a/ui-react/src/pages/modeling/thread/__tests__/SpatialScopeMap.test.tsx b/ui-react/src/pages/modeling/thread/__tests__/SpatialScopeMap.test.tsx new file mode 100644 index 00000000..4b33a008 --- /dev/null +++ b/ui-react/src/pages/modeling/thread/__tests__/SpatialScopeMap.test.tsx @@ -0,0 +1,156 @@ +import { fireEvent, screen, within } from '@testing-library/react'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import { LIST_REGISTERED_BOUNDARY_REGIONS } from '@/graphql/queries/regions'; +import { renderWithProviders } from '@/test/utils/render'; +import { SpatialScopeMap } from '../SpatialScopeMap'; + +// jsdom has no SVG renderer for Leaflet vectors; the picker is what is under test. +vi.mock('react-leaflet', () => ({ + MapContainer: ({ children }: { children?: React.ReactNode }) =>
{children}
, + TileLayer: () => null, + GeoJSON: () => null, + useMap: () => ({ fitBounds: () => undefined }), +})); + +const square = (x: number) => ({ + type: 'Polygon', + coordinates: [ + [ + [x, 29], + [x + 1, 29], + [x + 1, 30], + [x, 30], + [x, 29], + ], + ], +}); + +const region = (id: string, name: string, categoryId: string, categoryName: string, x: number) => ({ + id: `mint__${id}`, + name, + category_id: categoryId, + region_category: { id: categoryId, name: categoryName }, + geometries: [{ geometry: square(x) }], +}); + +const REGIONS = [ + region('0B4wIEBZthkf9gclJk1F', 'SEYMOUR_3', 'hydrology', 'Hydrology', -100), + region('1ap0Inly6Lq3jYZgDDKy', 'TRINITY_53', 'hydrology', 'Hydrology', -99), + region('2ap0Inly6Lq3jYZgDDKy', 'TRINITY_2', 'hydrology', 'Hydrology', -98), + region('3wKEpR6sL8AtkDM8hXAo', 'Alwero', 'hydrology', 'Hydrology', -97), +]; + +function mount(props: Parameters[0] = {}) { + return renderWithProviders(, { + apolloMocks: [ + { + request: { + query: LIST_REGISTERED_BOUNDARY_REGIONS, + variables: { categoryIds: ['hydrology'] }, + }, + result: { data: { region: REGIONS } }, + }, + ], + }); +} + +async function openPicker() { + fireEvent.click(await screen.findByRole('combobox', { name: 'Spatial boundary feature' })); +} + +describe('SpatialScopeMap boundary picker', () => { + beforeEach(() => { + window.__MINT_CONFIG__ = { + HASURA_ENDPOINT: 'http://hasura/graphql', + AUTH_SERVER: '', + AUTH_CLIENT_ID: '', + AUTH_REALM: '', + AUTH_PROVIDER: 'keycloak', + ENSEMBLE_MANAGER_API: 'http://em/v1', + }; + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue({ ok: true, json: async () => ({ layers: [] }) }), + ); + }); + + afterEach(() => { + vi.unstubAllGlobals(); + Reflect.deleteProperty(window, '__MINT_CONFIG__'); + }); + + it('shows region names sorted, with no ids, and one entry for a numbered family', async () => { + mount(); + await openPicker(); + const labels = within(await screen.findByRole('listbox')) + .getAllByRole('option') + .map((option) => option.textContent); + expect(labels).toEqual(['All boundaries', 'Alwero', 'Seymour 3', 'Trinity (2 parts)']); + expect(document.body.textContent).not.toMatch(/0B4wIEBZthkf9gclJk1F|1ap0Inly6Lq3jYZgDDKy/); + }); + + it('groups the options under their category', async () => { + mount(); + await openPicker(); + expect(await screen.findByText('Hydrology')).toBeInTheDocument(); + }); + + it('selects the whole family, and lets the user expand to one part', async () => { + const onFeatureSelect = vi.fn(); + mount({ onFeatureSelect }); + await openPicker(); + fireEvent.click(await screen.findByText('Trinity (2 parts)')); + expect(onFeatureSelect).toHaveBeenCalledTimes(1); + const whole = onFeatureSelect.mock.calls[0]?.[0]; + expect(whole.label).toBe('Trinity (2 parts)'); + expect(whole.filterField).toBe('region_id'); + expect(whole.filterValue.split(',').sort()).toEqual([ + '1ap0Inly6Lq3jYZgDDKy', + '2ap0Inly6Lq3jYZgDDKy', + ]); + expect(whole.geometry.type).toBe('GeometryCollection'); + expect(whole.geometry.geometries).toHaveLength(2); + + await openPicker(); + fireEvent.click(screen.getByRole('button', { name: 'Expand Trinity (2 parts)' })); + fireEvent.click(await screen.findByText('Trinity 53')); + expect(onFeatureSelect).toHaveBeenCalledTimes(2); + expect(onFeatureSelect.mock.calls[1]?.[0].filterValue).toBe('1ap0Inly6Lq3jYZgDDKy'); + expect(onFeatureSelect.mock.calls[1]?.[0].geometry.type).toBe('Polygon'); + }); + + it('filters as the user types', async () => { + mount(); + await openPicker(); + fireEvent.change(await screen.findByPlaceholderText('Search boundaries...'), { + target: { value: 'sey' }, + }); + const labels = within(screen.getByRole('listbox')) + .getAllByRole('option') + .map((option) => option.textContent); + expect(labels).toEqual(['Seymour 3']); + }); + + it('still shows a saved region by its readable name', async () => { + mount({ + scopeId: 'a-region-hash-id', + label: 'Texas Panhandle', + geometries: [square(-101)], + }); + const picker = await screen.findByRole('combobox', { name: 'Spatial boundary feature' }); + expect(picker).toHaveTextContent('Texas Panhandle'); + expect(document.body.textContent).not.toContain('a-region-hash-id'); + }); + + it('shows a saved boundary selection by name', async () => { + mount({ + filterField: 'region_id', + filterValue: '3wKEpR6sL8AtkDM8hXAo', + label: 'Alwero', + scopeId: '3wKEpR6sL8AtkDM8hXAo', + }); + const picker = await screen.findByRole('combobox', { name: 'Spatial boundary feature' }); + await vi.waitFor(() => expect(picker).toHaveTextContent('Alwero')); + }); +}); diff --git a/ui-react/src/pages/modeling/thread/wizard/FramingStep.tsx b/ui-react/src/pages/modeling/thread/wizard/FramingStep.tsx index 7a906519..2bc0791b 100644 --- a/ui-react/src/pages/modeling/thread/wizard/FramingStep.tsx +++ b/ui-react/src/pages/modeling/thread/wizard/FramingStep.tsx @@ -155,7 +155,7 @@ export function FramingStep({ geometries={(thread.region?.geometries ?? []) .map((geometry) => geometry.geometry) .filter(Boolean)} - label={spatialSelection?.feature?.label ?? thread.region?.name ?? regionId} + label={spatialSelection?.feature?.label ?? thread.region?.name} scopeId={spatialSelection?.feature?.filterValue ?? regionId} sourceUri={spatialSelection?.layer?.source_uri ?? spatialSelection?.layer?.uri} filterField={spatialSelection?.feature?.filterField} From 023bcc70ca8c1b30a4425894107ac956abc92311 Mon Sep 17 00:00:00 2001 From: Will Mobley Date: Fri, 20 Nov 2026 13:11:06 -0600 Subject: [PATCH 03/12] Outcome picker shows titled, unrepeated options; Models step ranks outcome producers first The picker led each option with its description and listed the same variable under its catalog id and its adapter URI. Options now lead with the humanized label, show the description as secondary text, and drop repeats by id and, across merged sources, by label. The Models step only filtered, in tree order, and matched a flow's output by id alone. Rows that declare the outcome (by id or name) now sort first, then rows reachable by a transform, each with a reason; a search keeps an exact match the semantic index does not carry. --- .../autocomplete-comboboxes.test.tsx | 4 +- .../autocomplete/StandardVariableCombobox.tsx | 56 +++--- .../StandardVariableCombobox.create.test.tsx | 2 +- .../StandardVariableCombobox.options.test.tsx | 144 +++++++++++++++ .../StandardVariableCombobox.scope.test.tsx | 60 +++---- ...tandardVariableCombobox.unlabeled.test.tsx | 4 +- .../useScopedStandardVariables.ts | 15 +- ui-react/src/lib/standard-variable-display.ts | 41 +++++ .../modeling/thread/wizard/ModelsStep.tsx | 101 +++++++++-- .../ModelsStepOutcomeRanking.test.tsx | 169 ++++++++++++++++++ 10 files changed, 513 insertions(+), 83 deletions(-) create mode 100644 ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.options.test.tsx create mode 100644 ui-react/src/pages/modeling/thread/wizard/__tests__/ModelsStepOutcomeRanking.test.tsx diff --git a/ui-react/src/__tests__/autocomplete-comboboxes.test.tsx b/ui-react/src/__tests__/autocomplete-comboboxes.test.tsx index d4704309..a55a31d5 100644 --- a/ui-react/src/__tests__/autocomplete-comboboxes.test.tsx +++ b/ui-react/src/__tests__/autocomplete-comboboxes.test.tsx @@ -88,7 +88,7 @@ describe('StandardVariableCombobox', () => { expect(screen.getByRole('combobox')).not.toBeDisabled(); }); - it('shows selected human-readable description when a value is provided', async () => { + it('shows the humanized title when a value is provided', async () => { const selected = { id: 'https://w3id.org/okn/i/mint/sv1', label: 'Precipitation', @@ -99,7 +99,7 @@ describe('StandardVariableCombobox', () => { }); // Wait for loading to complete await waitFor(() => { - expect(screen.getByText('Amount of precipitation')).toBeInTheDocument(); + expect(screen.getByRole('combobox')).toHaveTextContent('Precipitation'); }); }); diff --git a/ui-react/src/components/autocomplete/StandardVariableCombobox.tsx b/ui-react/src/components/autocomplete/StandardVariableCombobox.tsx index 65a491b7..de5d7e27 100644 --- a/ui-react/src/components/autocomplete/StandardVariableCombobox.tsx +++ b/ui-react/src/components/autocomplete/StandardVariableCombobox.tsx @@ -16,11 +16,11 @@ import * as React from 'react'; import { Check, ChevronsUpDown, Plus } from 'lucide-react'; import { cn } from '@/lib/utils'; -import { humanizeStandardVariable } from '@/lib/standard-variable-grammar'; import { + dedupeStandardVariables, isUnlabeledStandardVariable, standardVariableDescription, - standardVariableName, + standardVariableTitle, } from '@/lib/standard-variable-display'; import { useSemanticSearch } from '@/hooks/useSemanticSearch'; import { Button } from '@/components/ui/button'; @@ -127,16 +127,27 @@ export function StandardVariableCombobox({ const options = narrowed && !showAll ? scoped : all; const semanticSearch = useSemanticSearch(search, { target: 'svo', limit: 50 }); - const semanticOptions = React.useMemo( - () => - semanticSearch.results?.map((result) => ({ + const knownById = React.useMemo( + () => new Map([...all, ...scoped].map((o) => [o.id, o])), + [all, scoped], + ); + const semanticOptions = React.useMemo(() => { + if (!semanticSearch.results) return null; + // The service can answer with an empty label (or only a description) for a + // row the catalog names; take the catalog's label so the option has a title. + const mapped = semanticSearch.results.map((result) => { + const known = knownById.get(result.id); + return { id: result.id, - label: result.label ?? '', - description: result.description ?? null, + label: result.label?.trim() || known?.label || '', + description: result.description ?? known?.description ?? null, models: Array.isArray(result.models) ? result.models : [], - })) ?? null, - [semanticSearch.results], - ); + }; + }); + // One row per id, and one per label: the service can return the same + // variable under a catalog id and under an adapter URI. + return dedupeStandardVariables(mapped, { byLabel: true }); + }, [semanticSearch.results, knownById]); /** * Semantic results are ranked over the whole catalog, so the scope has to be @@ -160,7 +171,7 @@ export function StandardVariableCombobox({ * a control that reads as empty. */ const visibleOptions = React.useMemo(() => { - const listed = rankedOptions ?? options; + const listed = dedupeStandardVariables(rankedOptions ?? options); const base = requireLabel ? listed.filter((o) => !isUnlabeledStandardVariable(o)) : listed; // Semantic search results already have a query-specific ranking. Apply the // task/goal ranking only to the unfiltered catalog list. @@ -196,15 +207,7 @@ export function StandardVariableCombobox({ [value, visibleOptions, all, onChange], ); - const triggerLabel = !value - ? placeholder - : (standardVariableDescription(value) ?? - (isUnlabeledStandardVariable(value) - ? standardVariableName(value) - : (() => { - const { phenomenon, property } = humanizeStandardVariable(value.label); - return phenomenon ? `${phenomenon} — ${property}` : property; - })())); + const triggerLabel = !value ? placeholder : standardVariableTitle(value); return ( <> @@ -270,21 +273,12 @@ export function StandardVariableCombobox({ )} />
+ {standardVariableTitle(sv)} {standardVariableDescription(sv) && ( - + {standardVariableDescription(sv)} )} - - {standardVariableName(sv)} - {!!sv.models?.length && ( {sv.models diff --git a/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.create.test.tsx b/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.create.test.tsx index 4b7bcb59..185b4853 100644 --- a/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.create.test.tsx +++ b/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.create.test.tsx @@ -94,7 +94,7 @@ describe('StandardVariableCombobox create', () => { description: null, }), ); - expect(screen.getByRole('combobox')).toHaveTextContent(/zzz_new/i); + expect(screen.getByRole('combobox')).toHaveTextContent(/zzz new/i); }); it('does not offer create unless asked to', async () => { diff --git a/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.options.test.tsx b/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.options.test.tsx new file mode 100644 index 00000000..8f0139eb --- /dev/null +++ b/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.options.test.tsx @@ -0,0 +1,144 @@ +/** + * Every option leads with a readable title (the humanized label), shows its + * description as smaller secondary text, and is listed once. + */ +import { MockedProvider } from '@apollo/client/testing'; +import { render, screen, waitFor } from '@testing-library/react'; +import userEvent from '@testing-library/user-event'; +import { beforeEach, describe, expect, it, vi } from 'vitest'; + +import { StandardVariableCombobox } from '@/components/autocomplete/StandardVariableCombobox'; +import { IndicatorAdapterInferenceDocument } from '@/components/autocomplete/useScopedStandardVariables'; +import { + GetIndicatorVariableOptionsDocument, + PrefetchReferenceDataDocument, +} from '@/graphql/generated/graphql'; + +const semantic = vi.hoisted(() => ({ + results: null as Array<{ + id: string; + label?: string | null; + description?: string | null; + }> | null, +})); +vi.mock('@/hooks/useSemanticSearch', () => ({ + useSemanticSearch: (query: string) => ({ + results: query.trim() ? semantic.results : null, + loading: false, + error: null, + }), +})); + +const sv = (id: string, label: string | null, description: string | null = null) => ({ + __typename: 'modelcatalog_standard_variable', + id, + label, + description, +}); + +const TERM_COUNT = 'https://w3id.org/okn/i/mint/document_lexicon_group__term_count'; +const DESCRIPTION = "For each document and lexicon group, how often the group's terms occur."; + +const catalogMock = { + request: { query: PrefetchReferenceDataDocument }, + result: { + data: { + modelcatalog_standard_variable: [ + sv(TERM_COUNT, 'document_lexicon_group__term_count', DESCRIPTION), + ], + modelcatalog_unit: [], + }, + }, +}; + +async function open(mocks: unknown[]) { + render( + + {}} scope="all" /> + , + ); + await userEvent.click(await screen.findByRole('combobox')); +} + +describe('StandardVariableCombobox option titles and repeats', () => { + beforeEach(() => { + semantic.results = null; + }); + + it('leads with the humanized label and keeps the description as secondary text', async () => { + await open([catalogMock]); + const title = await screen.findByText('Document lexicon group — Term count'); + expect(title).toHaveClass('font-medium'); + const description = screen.getByText(DESCRIPTION); + expect(description).toHaveClass('text-xs', 'line-clamp-1'); + expect(screen.getAllByRole('option')).toHaveLength(1); + }); + + it('gives a search hit with no label the catalog title, and lists each variable once', async () => { + // The service answers with an empty label, then again under the same id. + semantic.results = [ + { id: TERM_COUNT, label: '', description: DESCRIPTION }, + { id: TERM_COUNT, label: 'document_lexicon_group__term_count', description: null }, + ]; + await open([catalogMock]); + await userEvent.type(screen.getByPlaceholderText(/search standard variables/i), 'term'); + await waitFor(() => expect(screen.getAllByRole('option')).toHaveLength(1)); + expect(screen.getByText('Document lexicon group — Term count')).toBeInTheDocument(); + }); + + it('titles a search hit that has only an id from the id tail', async () => { + semantic.results = [{ id: 'https://w3id.org/okn/i/mint/air__daily_max_of_temperature' }]; + await open([catalogMock]); + await userEvent.type(screen.getByPlaceholderText(/search standard variables/i), 'air'); + expect(await screen.findByText('Air — Daily max of temperature')).toBeInTheDocument(); + }); + + it('lists a variable once when the catalog and an adapter contract both name it', async () => { + const ID = 'https://w3id.org/okn/i/mint/air__daily_max_of_temperature'; + const mocks = [ + { + request: { query: GetIndicatorVariableOptionsDocument }, + result: { + data: { + modelcatalog_dataset_specification_presentation: [ + { + __typename: 'modelcatalog_dataset_specification_presentation', + dataset_specification_id: 'ds', + presentation_id: 'p', + presentation: { + __typename: 'modelcatalog_variable_presentation', + id: 'p', + standard_variable: sv( + 'catalog-uuid-1', + 'air__daily_max_of_temperature', + 'Daily max', + ), + }, + }, + ], + }, + }, + }, + { + request: { query: IndicatorAdapterInferenceDocument }, + result: { + data: { + adapterTransforms: [ + { contracts: [{ role: 'output', standard_variable_uri: ID, format: null }] }, + ], + }, + }, + }, + ]; + render( + + {}} scope="indicator" /> + , + ); + await waitFor(() => expect(screen.getByRole('combobox')).toBeEnabled()); + await userEvent.click(screen.getByRole('combobox')); + expect(await screen.findByText('Air — Daily max of temperature')).toBeInTheDocument(); + expect(screen.getAllByRole('option')).toHaveLength(1); + expect(screen.getByText('Daily max')).toBeInTheDocument(); + }); +}); diff --git a/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.scope.test.tsx b/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.scope.test.tsx index 017abf45..126cdd83 100644 --- a/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.scope.test.tsx +++ b/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.scope.test.tsx @@ -310,29 +310,29 @@ describe('StandardVariableCombobox scope', () => { it('offers the whole catalog by default, so registration forms are unchanged', async () => { renderCombobox({}); await openList(); - await waitFor(() => expect(screen.getByText('drawdown')).toBeInTheDocument()); - expect(screen.getByText('100hr_dead_moisture')).toBeInTheDocument(); - expect(screen.getByText('soil__porosity')).toBeInTheDocument(); + await waitFor(() => expect(screen.getByText('Drawdown')).toBeInTheDocument()); + expect(screen.getByText('100hr dead moisture')).toBeInTheDocument(); + expect(screen.getByText('Soil — Porosity')).toBeInTheDocument(); }); it('places preferred variables before the alphabetical catalog order', async () => { renderCombobox({ preferredIds: ['sv-poro', 'sv-draw'] }); await openList(); - await waitFor(() => expect(screen.getByText('soil__porosity')).toBeInTheDocument()); + await waitFor(() => expect(screen.getByText('Soil — Porosity')).toBeInTheDocument()); const labels = screen.getAllByRole('option').map((option) => option.textContent); - expect(labels[0]).toContain('soil__porosity'); - expect(labels[1]).toContain('drawdown'); + expect(labels[0]).toContain('Soil — Porosity'); + expect(labels[1]).toContain('Drawdown'); }); it('offers only producible variables under scope="indicator"', async () => { renderCombobox({ scope: 'indicator' }); await openList(); - await waitFor(() => expect(screen.getByText('drawdown')).toBeInTheDocument()); + await waitFor(() => expect(screen.getByText('Drawdown')).toBeInTheDocument()); // Reaches no model, so it must not be offered. - expect(screen.queryByText('100hr_dead_moisture')).not.toBeInTheDocument(); + expect(screen.queryByText('100hr dead moisture')).not.toBeInTheDocument(); // An input-only variable is not an indicator either. - expect(screen.queryByText('soil__porosity')).not.toBeInTheDocument(); + expect(screen.queryByText('Soil — Porosity')).not.toBeInTheDocument(); }); it('offers SVOs produced by registered adapter transforms as outcomes', async () => { @@ -342,25 +342,25 @@ describe('StandardVariableCombobox scope', () => { , ); await openList(); - await waitFor(() => expect(screen.getByText('spring__volume_flow_rate')).toBeInTheDocument()); + await waitFor(() => expect(screen.getByText('Spring — Volume flow rate')).toBeInTheDocument()); }); it('unions inputs and parameter-adjusted variables under scope="driver"', async () => { renderCombobox({ scope: 'driver' }); await openList(); // soil__porosity arrives through inputs, drawdown through a parameter. - await waitFor(() => expect(screen.getByText('soil__porosity')).toBeInTheDocument()); - expect(screen.getByText('drawdown')).toBeInTheDocument(); - expect(screen.queryByText('100hr_dead_moisture')).not.toBeInTheDocument(); + await waitFor(() => expect(screen.getByText('Soil — Porosity')).toBeInTheDocument()); + expect(screen.getByText('Drawdown')).toBeInTheDocument(); + expect(screen.queryByText('100hr dead moisture')).not.toBeInTheDocument(); }); it('infers drivers from a selected outcome across model and ETL steps', async () => { renderCombobox({ scope: 'driver', driverOutcomeId: 'sv-draw' }); await openList(); - await waitFor(() => expect(screen.getByText('middle')).toBeInTheDocument()); - expect(screen.getByText('sv-forcing')).toBeInTheDocument(); - expect(screen.queryByText('soil__porosity')).not.toBeInTheDocument(); - expect(screen.queryByText('drawdown')).not.toBeInTheDocument(); + await waitFor(() => expect(screen.getByText('Middle')).toBeInTheDocument()); + expect(screen.getByText('Sv-forcing')).toBeInTheDocument(); + expect(screen.queryByText('Soil — Porosity')).not.toBeInTheDocument(); + expect(screen.queryByText('Drawdown')).not.toBeInTheDocument(); }); it('limits outcome inference to the selected model configurations', async () => { @@ -370,8 +370,8 @@ describe('StandardVariableCombobox scope', () => { driverConfigurationIds: ['cfg-outcome'], }); await openList(); - await waitFor(() => expect(screen.getByText('middle')).toBeInTheDocument()); - expect(screen.queryByText('air__temperature')).not.toBeInTheDocument(); + await waitFor(() => expect(screen.getByText('Middle')).toBeInTheDocument()); + expect(screen.queryByText('Air — Temperature')).not.toBeInTheDocument(); }); it('falls back to outcome-producing models when a retained model is incompatible', async () => { @@ -381,9 +381,9 @@ describe('StandardVariableCombobox scope', () => { driverConfigurationIds: ['cfg-incompatible'], }); await openList(); - await waitFor(() => expect(screen.getByText('middle')).toBeInTheDocument()); - expect(screen.getByText('air__temperature')).toBeInTheDocument(); - expect(screen.queryByText('only_incompatible')).not.toBeInTheDocument(); + await waitFor(() => expect(screen.getByText('Middle')).toBeInTheDocument()); + expect(screen.getByText('Air — Temperature')).toBeInTheDocument(); + expect(screen.queryByText('Only incompatible')).not.toBeInTheDocument(); }); it('keeps model inference when the optional adapter registry is unavailable', async () => { @@ -412,20 +412,20 @@ describe('StandardVariableCombobox scope', () => { , ); await openList(); - await waitFor(() => expect(screen.getByText('middle')).toBeInTheDocument()); - expect(screen.queryByText('air__temperature')).not.toBeInTheDocument(); - expect(screen.queryByText('soil__porosity')).not.toBeInTheDocument(); + await waitFor(() => expect(screen.getByText('Middle')).toBeInTheDocument()); + expect(screen.queryByText('Air — Temperature')).not.toBeInTheDocument(); + expect(screen.queryByText('Soil — Porosity')).not.toBeInTheDocument(); }); it('widens to the whole catalog when the escape link is clicked', async () => { renderCombobox({ scope: 'indicator', scopeLabel: 'a model produces' }); const user = await openList(); - await waitFor(() => expect(screen.getByText('drawdown')).toBeInTheDocument()); - expect(screen.queryByText('100hr_dead_moisture')).not.toBeInTheDocument(); + await waitFor(() => expect(screen.getByText('Drawdown')).toBeInTheDocument()); + expect(screen.queryByText('100hr dead moisture')).not.toBeInTheDocument(); await user.click(screen.getByRole('button', { name: /show every standard variable/i })); - await waitFor(() => expect(screen.getByText('100hr_dead_moisture')).toBeInTheDocument()); + await waitFor(() => expect(screen.getByText('100hr dead moisture')).toBeInTheDocument()); }); it('names the scope and its size in the escape link', async () => { @@ -446,9 +446,9 @@ describe('StandardVariableCombobox scope', () => { value: { id: 'sv-dead', label: '100hr_dead_moisture', description: null }, }); await openList(); - await waitFor(() => expect(screen.getByText('drawdown')).toBeInTheDocument()); + await waitFor(() => expect(screen.getByText('Drawdown')).toBeInTheDocument()); // The trigger also prints the stored label, so assert on the option row. const options = screen.getAllByRole('option').map((o) => o.textContent); - expect(options).toContain('100hr_dead_moisture'); + expect(options).toContain('100hr dead moisture'); }); }); diff --git a/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.unlabeled.test.tsx b/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.unlabeled.test.tsx index fca2d4c7..b32a6893 100644 --- a/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.unlabeled.test.tsx +++ b/ui-react/src/components/autocomplete/__tests__/StandardVariableCombobox.unlabeled.test.tsx @@ -44,14 +44,14 @@ describe('StandardVariableCombobox unlabeled rows', () => { it('shows a readable name, never the bare id', async () => { await open(); expect(await screen.findByText('…83d62379 (no label)')).toBeInTheDocument(); - expect(screen.getByText('drawdown')).toBeInTheDocument(); + expect(screen.getByText('Drawdown')).toBeInTheDocument(); expect(screen.queryByText(/Catalog ID/)).not.toBeInTheDocument(); expect(screen.queryByText(UUID)).not.toBeInTheDocument(); }); it('leaves unlabeled rows out when the caller needs a label', async () => { await open({ requireLabel: true }); - expect(await screen.findByText('drawdown')).toBeInTheDocument(); + expect(await screen.findByText('Drawdown')).toBeInTheDocument(); expect(screen.queryByText(/no label/)).not.toBeInTheDocument(); }); }); diff --git a/ui-react/src/components/autocomplete/useScopedStandardVariables.ts b/ui-react/src/components/autocomplete/useScopedStandardVariables.ts index f75f671f..8c49ef6f 100644 --- a/ui-react/src/components/autocomplete/useScopedStandardVariables.ts +++ b/ui-react/src/components/autocomplete/useScopedStandardVariables.ts @@ -46,7 +46,10 @@ import { type InferenceTransformKind, type VariableTransform, } from '@/lib/modeling/outcome-driver-inference'; -import { UNNAMED_STANDARD_VARIABLE } from '@/lib/standard-variable-display'; +import { + UNNAMED_STANDARD_VARIABLE, + standardVariableLabelKey, +} from '@/lib/standard-variable-display'; import { slugFromUri } from '@/lib/uri'; export type StandardVariableScope = 'all' | 'indicator' | 'driver'; @@ -398,7 +401,15 @@ export function useScopedStandardVariables( return { id, label: slugFromUri(id), description: null }; }), ); - return dedupe([...rows.map((r) => r.presentation.standard_variable), ...adapterOutputs]); + const catalog = dedupe(rows.map((r) => r.presentation.standard_variable)); + // An adapter contract names a variable by URI slug, and the catalog holds + // the same variable under its own id. Keep the catalog row, which carries + // the description, and add only the adapter outputs it does not already list. + const listed = new Set(catalog.map((o) => standardVariableLabelKey(o))); + return dedupe([ + ...catalog, + ...adapterOutputs.filter((o) => !listed.has(standardVariableLabelKey(o))), + ]); } if (scope === 'driver') { const inputs = driverQ.data?.inputs ?? []; diff --git a/ui-react/src/lib/standard-variable-display.ts b/ui-react/src/lib/standard-variable-display.ts index 40ec48a5..de397196 100644 --- a/ui-react/src/lib/standard-variable-display.ts +++ b/ui-react/src/lib/standard-variable-display.ts @@ -1,3 +1,5 @@ +import { humanizeStandardVariable } from '@/lib/standard-variable-grammar'; + /** * How a standard variable reads in a list. * @@ -41,3 +43,42 @@ export function standardVariableDescription(sv: VariableLike): string | null { const text = (sv.description ?? '').trim(); return text && !text.startsWith(CATALOG_ID_PREFIX) ? text : null; } + +/** + * The title an option leads with: the label, humanized ("Document lexicon group + * — Term count" from `document_lexicon_group__term_count`). A row with no label + * borrows the id's tail when that is grammar-shaped, else reads as unnamed. + */ +export function standardVariableTitle(sv: VariableLike): string { + const source = isUnlabeledStandardVariable(sv) ? idTail(sv.id) : sv.label!.trim(); + if (isUnlabeledStandardVariable(sv) && !source.includes('__')) return standardVariableName(sv); + const { phenomenon, property } = humanizeStandardVariable(source); + if (phenomenon) return `${phenomenon} — ${property}`; + // Not grammar (no `__`): the label is the whole name, so only spell out its joiners. + const spaced = property.replace(/[~_]+/g, ' ').replace(/\s+/g, ' ').trim(); + return spaced.charAt(0).toUpperCase() + spaced.slice(1); +} + +/** A key that makes two rows naming the same variable collide; null for unlabeled rows. */ +export function standardVariableLabelKey(sv: VariableLike): string | null { + return isUnlabeledStandardVariable(sv) ? null : sv.label!.trim().toLowerCase(); +} + +/** Drop repeats by id, then (for labeled rows) by label, keeping the first seen. */ +export function dedupeStandardVariables( + rows: ReadonlyArray, + { byLabel = false }: { byLabel?: boolean } = {}, +): T[] { + const ids = new Set(); + const labels = new Set(); + const kept: T[] = []; + for (const row of rows) { + if (ids.has(row.id)) continue; + const key = byLabel ? standardVariableLabelKey(row) : null; + if (key !== null && labels.has(key)) continue; + ids.add(row.id); + if (key !== null) labels.add(key); + kept.push(row); + } + return kept; +} diff --git a/ui-react/src/pages/modeling/thread/wizard/ModelsStep.tsx b/ui-react/src/pages/modeling/thread/wizard/ModelsStep.tsx index 1b614b33..2b6c0a46 100644 --- a/ui-react/src/pages/modeling/thread/wizard/ModelsStep.tsx +++ b/ui-react/src/pages/modeling/thread/wizard/ModelsStep.tsx @@ -130,6 +130,31 @@ function rowFromConfig(cfg: ModelConfigInfo | ModelSetupInfo, parent?: ModelConf }; } +type OutcomeMatch = 'produces' | 'transforms'; + +/** The part of a standard-variable id or label that names it, lower-cased. */ +function outcomeName(value: string): string { + return slugFromUri(value.trim()).toLowerCase(); +} + +/** + * True when the row declares the outcome as one of its outputs. The id is + * compared first; the name (the URI slug or the label) bridges a flow whose + * output was registered under another namespace for the same variable. + */ +function rowProducesOutcome( + row: Pick, + outcome: string, + outcomeLabel?: string | null, +): boolean { + if (row.producesIds.includes(outcome)) return true; + const names = new Set([outcomeName(outcome), outcomeLabel ? outcomeName(outcomeLabel) : '']); + names.delete(''); + return [...row.producesIds, ...row.producesLabels].some( + (value) => value && names.has(outcomeName(value)), + ); +} + function flattenToRows( data: ReturnType['data'], ): ModelRow[] { @@ -153,10 +178,15 @@ function ModelCard({ row, checked, onToggle, + outcomeMatch, + outcomeLabel, }: { row: ModelRow; checked: boolean; onToggle: (id: string, checked: boolean) => void; + /** How the row reaches the chosen outcome, when one is chosen. */ + outcomeMatch?: OutcomeMatch | null; + outcomeLabel?: string | null; }) { // Asked only for a flow, and only once per flow per session. An unanswered or // failed check leaves the card pickable: plan and submit still refuse correctly. @@ -185,6 +215,19 @@ function ModelCard({ {row.name} {row.isFlow && }
+ {outcomeMatch && outcomeLabel && ( +
+ {outcomeMatch === 'produces' + ? `Produces ${outcomeLabel}` + : `Can be transformed into ${outcomeLabel}`} +
+ )} {row.takesCollection && (
Takes a set of files as one input
)} @@ -711,9 +754,11 @@ export function ModelsStep({ const indicatorRows = useMemo( () => indicator - ? allRows.filter((r) => r.producesIds.includes(indicator) || inferredModelIds.has(r.id)) + ? allRows.filter( + (r) => rowProducesOutcome(r, indicator, indicatorLabel) || inferredModelIds.has(r.id), + ) : allRows, - [allRows, indicator, inferredModelIds], + [allRows, indicator, indicatorLabel, inferredModelIds], ); const dataFeasibleRows = useMemo(() => { if (!hasRegionGeometry || availabilityLoading || availabilityError) return indicatorRows; @@ -756,23 +801,47 @@ export function ModelsStep({ ); }, [dataFilteredRows, searchText]); - const searchedRows = useMemo(() => { + const matchedRows = useMemo(() => { if (!debouncedSearchText.trim() || !semanticSearch.results) return localSearchedRows; const rankById = new Map(semanticSearch.results.map((result, index) => [result.id, index])); + const semanticRank = (row: ModelRow) => + Math.min( + Infinity, + ...row.searchIds + .map((id) => rankById.get(id)) + .filter((rank): rank is number => rank !== undefined), + ); + // The index may not carry a row (a flow's outputs, for one), so a row the + // plain text filter finds is kept and follows the semantic hits. + const found = new Set(localSearchedRows.map((row) => row.id)); return dataFilteredRows - .map((row) => ({ - row, - rank: Math.min( - ...row.searchIds - .map((id) => rankById.get(id)) - .filter((rank): rank is number => rank !== undefined), - ), - })) - .filter((item) => Number.isFinite(item.rank)) - .sort((a, b) => a.rank - b.rank) + .map((row) => ({ row, rank: semanticRank(row) })) + .filter((item) => Number.isFinite(item.rank) || found.has(item.row.id)) + .sort((a, b) => (a.rank === b.rank ? 0 : a.rank < b.rank ? -1 : 1)) .map((item) => item.row); }, [dataFilteredRows, debouncedSearchText, localSearchedRows, semanticSearch.results]); + // Rows that declare the outcome as an output come first, models and flows + // alike, whatever the search ranked them; then the rows reachable by a + // transform. The sort is stable, so each group keeps its own order. + const outcomeMatchById = useMemo(() => { + const matches = new Map(); + if (!indicator) return matches; + for (const row of allRows) { + if (rowProducesOutcome(row, indicator, indicatorLabel)) matches.set(row.id, 'produces'); + else if (inferredModelIds.has(row.id)) matches.set(row.id, 'transforms'); + } + return matches; + }, [allRows, indicator, indicatorLabel, inferredModelIds]); + const searchedRows = useMemo(() => { + if (outcomeMatchById.size === 0) return matchedRows; + const tier = (row: ModelRow) => { + const match = outcomeMatchById.get(row.id); + return match === 'produces' ? 0 : match === 'transforms' ? 1 : 2; + }; + return [...matchedRows].sort((a, b) => tier(a) - tier(b)); + }, [matchedRows, outcomeMatchById]); + const threadRegionId = thread.region_id ?? null; const { regionRows, otherRows } = useMemo(() => { if (!threadRegionId) return { regionRows: searchedRows, otherRows: [] as ModelRow[] }; @@ -793,10 +862,10 @@ export function ModelsStep({ return allRows.filter( (row) => selected.has(row.id) && - !row.producesIds.includes(indicator) && + !rowProducesOutcome(row, indicator, indicatorLabel) && !inferredModelIds.has(row.id), ); - }, [allRows, indicator, inferredModelIds, selectedIds]); + }, [allRows, indicator, indicatorLabel, inferredModelIds, selectedIds]); const toggleModel = useCallback((id: string, checked: boolean) => { setSelectedIds((prev) => { @@ -1023,6 +1092,8 @@ export function ModelsStep({ row={row} checked={selectedIds.has(row.id)} onToggle={toggleModel} + outcomeMatch={outcomeMatchById.get(row.id) ?? null} + outcomeLabel={indicatorLabel} /> )) )} diff --git a/ui-react/src/pages/modeling/thread/wizard/__tests__/ModelsStepOutcomeRanking.test.tsx b/ui-react/src/pages/modeling/thread/wizard/__tests__/ModelsStepOutcomeRanking.test.tsx new file mode 100644 index 00000000..eac71e6f --- /dev/null +++ b/ui-react/src/pages/modeling/thread/wizard/__tests__/ModelsStepOutcomeRanking.test.tsx @@ -0,0 +1,169 @@ +/** + * Choosing an outcome ranks the rows that produce it first, flows included, + * then the rows that can be transformed into it, and says why on each card. + */ +import { beforeEach, describe, expect, it, vi } from 'vitest'; +import type { MockedResponse } from '@apollo/client/testing'; +import userEvent from '@testing-library/user-event'; +import { renderWithProviders, screen, waitFor } from '@/test/utils/render'; +import { GetModelTreeWithRegionsDocument, type Thread } from '@/graphql/generated/modeling'; +import { ModelOutcomeAdapterInferenceDocument, ModelsStep } from '../ModelsStep'; + +vi.mock('@/components/ui/use-toast', () => ({ useToast: () => ({ toast: vi.fn() }) })); +vi.mock('@/hooks/useFlowAvailability', () => ({ useFlowAvailability: () => null })); + +const semantic = vi.hoisted(() => ({ + results: null as Array<{ id: string }> | null, +})); +vi.mock('@/hooks/useSemanticSearch', () => ({ + useSemanticSearch: (query: string) => ({ + results: query.trim() ? semantic.results : null, + loading: false, + error: null, + }), +})); + +const REPORT = 'https://w3id.org/okn/i/mint/document_collection__sensemaking_report'; +const RAW = 'https://w3id.org/okn/i/mint/document_collection__raw_text'; + +function config(id: string, label: string, outId: string, outLabel: string, isFlow = false) { + return { + id, + label, + ...(isFlow ? { flow: { __typename: 'x', configuration_id: id } } : {}), + regions: [], + inputs: [], + outputs: [ + { + configuration_id: id, + output_id: `${id}-out`, + output: { + id: `${id}-out`, + label: outLabel, + has_format: null, + presentations: [ + { + dataset_specification_id: `${id}-out`, + presentation_id: `${id}-vp`, + presentation: { id: `${id}-vp`, standard_variable: { id: outId, label: outLabel } }, + }, + ], + }, + }, + ], + child_configurations: [], + }; +} + +const treeMock: MockedResponse = { + request: { query: GetModelTreeWithRegionsDocument }, + result: { + data: { + modelcatalog_software: [ + { + id: 'sw', + label: 'Sensemaking', + versions: [ + { + id: 'v', + label: '1', + configurations: [ + config('alpha', 'Alpha model', RAW, 'document_collection__raw_text'), + config('mid', 'Mid model', REPORT, 'document_collection__sensemaking_report'), + // Registered under another namespace: only the name matches. + config( + 'zeta', + 'Zeta flow', + 'https://example.org/vocab/document_collection__sensemaking_report', + 'document_collection__sensemaking_report', + true, + ), + ], + }, + ], + }, + ], + }, + }, +}; + +const adapterMock: MockedResponse = { + request: { query: ModelOutcomeAdapterInferenceDocument }, + result: { + data: { + adapterTransforms: [ + { + id: 't1', + name: 'raw-to-report', + description: null, + contracts: [ + { id: 'c1', role: 'input', standard_variable_uri: RAW, format: null, unit: null }, + { id: 'c2', role: 'output', standard_variable_uri: REPORT, format: null, unit: null }, + ], + }, + ], + }, + }, +}; + +const thread = { + __typename: 'thread', + id: 't1', + name: 'Report', + task_id: 'task1', + start_date: '2000-01-01', + end_date: '2026-01-01', + region_id: null, + driving_variable_id: null, + response_variable_id: REPORT, + response_variable: { id: REPORT, label: 'document_collection__sensemaking_report' }, + events: [], + permissions: [{ __typename: 'thread_permission', user_id: 'testuser', read: true, write: true }], + thread_models: [], +} as unknown as Thread; + +function renderStep() { + return renderWithProviders( + , + { apolloMocks: [treeMock, adapterMock] }, + ); +} + +const cardNames = () => + screen + .getAllByRole('checkbox') + .map((box) => box.getAttribute('aria-label')?.replace(/^Select /, '')); + +describe('ModelsStep outcome ranking', () => { + beforeEach(() => { + semantic.results = null; + }); + + it('puts the rows that produce the outcome first, flows included, then transforms', async () => { + renderStep(); + await screen.findByText('Zeta flow'); + // Tree order is alphabetical (Alpha, Mid, Zeta); the producers lead. + await waitFor(() => expect(cardNames()).toEqual(['Mid model', 'Zeta flow', 'Alpha model'])); + }); + + it('says why each row is listed', async () => { + renderStep(); + await screen.findByText('Zeta flow'); + await waitFor(() => expect(screen.getAllByTestId('outcome-reason')).toHaveLength(3)); + const reasons = screen.getAllByTestId('outcome-reason').map((el) => el.textContent); + expect(reasons).toEqual([ + 'Produces document_collection__sensemaking_report', + 'Produces document_collection__sensemaking_report', + 'Can be transformed into document_collection__sensemaking_report', + ]); + }); + + it('keeps exact matches ahead of semantic-only hits, and keeps a row the index lacks', async () => { + // The index ranks the transformed row first and does not carry the flow. + semantic.results = [{ id: 'alpha' }, { id: 'mid' }]; + renderStep(); + await screen.findByText('Zeta flow'); + await userEvent.type(screen.getByPlaceholderText(/filter models/i), 'e'); + await waitFor(() => expect(cardNames()).toEqual(['Mid model', 'Zeta flow', 'Alpha model'])); + }); +}); From 38c0b29181f4cbee69fc730369e743a0c639ec66 Mon Sep 17 00:00:00 2001 From: Will Mobley Date: Fri, 20 Nov 2026 13:17:26 -0600 Subject: [PATCH 04/12] Rank upload variable suggestions by which inputs take the files Text similarity alone put a flow's output variable (narrative frames) above the corpus variable for a transcript upload. Suggestions now rank first the variables a registered flow or model input accepts these files under, then those an input takes without a declared format, then format mismatches, then variables nothing takes, keeping the semantic order within each group. Each suggestion says which flows and models take it. --- .../datasets/__tests__/upload-preview.test.ts | 122 ++++++++++++++++++ ui-react/src/lib/datasets/upload-preview.ts | 68 ++++++++++ .../src/pages/datasets/DatasetUploadPage.tsx | 87 ++++++++----- 3 files changed, 246 insertions(+), 31 deletions(-) create mode 100644 ui-react/src/lib/datasets/__tests__/upload-preview.test.ts diff --git a/ui-react/src/lib/datasets/__tests__/upload-preview.test.ts b/ui-react/src/lib/datasets/__tests__/upload-preview.test.ts new file mode 100644 index 00000000..3eeb1965 --- /dev/null +++ b/ui-react/src/lib/datasets/__tests__/upload-preview.test.ts @@ -0,0 +1,122 @@ +import { describe, expect, it } from 'vitest'; +import type { GetModelTreeWithRegionsQuery, ModelConfigInfo } from '@/graphql/generated/modeling'; +import { rankSuggestionsByUse, suggestionUseText } from '@/lib/datasets/upload-preview'; + +const SV = 'https://w3id.org/okn/i/mint/'; + +function input(id: string, variable: string, format: string | null) { + return { + configuration_id: 'c', + input_id: id, + is_optional: false, + input: { + id, + label: id, + has_format: format, + presentations: [ + { + dataset_specification_id: id, + presentation_id: `${id}-p`, + presentation: { + id: `${id}-p`, + standard_variable: { id: SV + variable, label: variable }, + }, + }, + ], + }, + }; +} + +function config(id: string, inputs: ReturnType[], flow = false): ModelConfigInfo { + return { + id, + label: id, + flow: flow ? { configuration_id: id, thread_bindings_json: null } : null, + regions: [], + inputs, + outputs: [], + child_configurations: [], + } as unknown as ModelConfigInfo; +} + +const tree: GetModelTreeWithRegionsQuery = { + modelcatalog_software: [ + { + id: 's', + label: 's', + versions: [ + { + id: 'v', + label: 'v', + configurations: [ + config( + 'Dictionary flow', + [input('corpus', 'document_collection__text', 'directory')], + true, + ), + config( + 'Narrative flow', + [input('corpus2', 'document_collection__text', 'directory')], + true, + ), + config('HAND', [input('dem', 'land_surface__elevation', 'tif')]), + config('Narratives model', [input('nlp', 'corpus_nlp', null)]), + ], + }, + ], + }, + ], +}; + +// The semantic order the service returned for "RGV Transcripts — oral histories". +const hits = [ + { id: SV + 'corpus_nlp', label: 'corpus_nlp' }, + { + id: SV + 'document_collection_narrative_frame__description', + label: 'document_collection_narrative_frame__description', + }, + { id: SV + 'land_surface__elevation', label: 'land_surface__elevation' }, + { id: SV + 'document_collection__text', label: 'document_collection__text' }, +]; + +const labels = (ranked: { item: { label: string } }[]) => ranked.map((r) => r.item.label); + +describe('rankSuggestionsByUse', () => { + it('puts the variable a flow input accepts these files under first', () => { + const ranked = rankSuggestionsByUse(tree, hits, [{ name: 'transcript.json' }]); + expect(labels(ranked)).toEqual([ + 'document_collection__text', + 'corpus_nlp', + 'land_surface__elevation', + 'document_collection_narrative_frame__description', + ]); + expect(ranked.map((r) => r.fit)).toEqual([0, 1, 2, 3]); + }); + + it('keeps the semantic order among variables that fit equally', () => { + const ranked = rankSuggestionsByUse(tree, hits, []); + // No files yet: anything an input takes ranks above what nothing takes. + expect(labels(ranked)).toEqual([ + 'corpus_nlp', + 'land_surface__elevation', + 'document_collection__text', + 'document_collection_narrative_frame__description', + ]); + }); + + it('ranks nothing without the model tree but keeps every suggestion', () => { + expect(labels(rankSuggestionsByUse(undefined, hits, []))).toEqual(hits.map((h) => h.label)); + }); +}); + +describe('suggestionUseText', () => { + it('says who takes the variable and when the format is wrong', () => { + const ranked = rankSuggestionsByUse(tree, hits, [{ name: 'transcript.json' }]); + expect(ranked.map(suggestionUseText)).toEqual([ + 'Input to 2 flows', + 'Input to 1 model', + 'Input to 1 model, but not in this file format', + 'No registered flow or model takes this as an input', + ]); + }); +}); diff --git a/ui-react/src/lib/datasets/upload-preview.ts b/ui-react/src/lib/datasets/upload-preview.ts index ace22e0b..71ad08fe 100644 --- a/ui-react/src/lib/datasets/upload-preview.ts +++ b/ui-react/src/lib/datasets/upload-preview.ts @@ -76,6 +76,74 @@ export function consumersOfVariable( ); } +/** + * How useful a suggested variable is for these files, best first: + * 0 an input that declares a format takes these files, + * 1 an input takes the variable but declares no format (or no files are chosen yet), + * 2 inputs take the variable but none takes these files, + * 3 no registered flow or model takes it. + */ +export type SuggestionFit = 0 | 1 | 2 | 3; + +export interface RankedSuggestion { + item: T; + fit: SuggestionFit; + /** Flows and models with an input that takes the variable, whatever the format. */ + flows: number; + models: number; +} + +function suggestionFit(consumers: UploadConsumer[]): SuggestionFit { + if (consumers.length === 0) return 3; + if (consumers.some((c) => c.formatFits === true && (c.format ?? '').trim())) return 0; + if (consumers.some((c) => c.formatFits !== false)) return 1; + return 2; +} + +/** + * Order the semantic suggestions by whether a registered flow or model could use + * the files under that variable, keeping the semantic order within each group. + * Text similarity alone cannot tell "a corpus of transcripts" from "frames drawn + * from transcripts"; what the catalog's inputs accept can. + */ +export function rankSuggestionsByUse( + tree: GetModelTreeWithRegionsQuery | undefined, + suggestions: T[], + files: Array<{ name: string }>, +): RankedSuggestion[] { + return suggestions + .map((item, index) => { + const consumers = consumersOfVariable( + tree, + { id: item.id, label: item.label?.trim() || item.id }, + files, + ); + return { + index, + ranked: { + item, + fit: suggestionFit(consumers), + flows: consumers.filter((c) => c.kind === 'flow').length, + models: consumers.filter((c) => c.kind === 'model').length, + }, + }; + }) + .sort((a, b) => a.ranked.fit - b.ranked.fit || a.index - b.index) + .map(({ ranked }) => ranked); +} + +/** "Input to 6 flows and 1 model", or why nothing can use it. */ +export function suggestionUseText(ranked: RankedSuggestion): string { + const count = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`; + const parts = [ + ranked.flows ? count(ranked.flows, 'flow') : '', + ranked.models ? count(ranked.models, 'model') : '', + ].filter(Boolean); + if (parts.length === 0) return 'No registered flow or model takes this as an input'; + const users = parts.join(' and '); + return ranked.fit === 2 ? `Input to ${users}, but not in this file format` : `Input to ${users}`; +} + export interface CloseConsumer extends UploadConsumer { /** The close variable whose input this matched on. */ via: string; diff --git a/ui-react/src/pages/datasets/DatasetUploadPage.tsx b/ui-react/src/pages/datasets/DatasetUploadPage.tsx index 4c2a8bc7..ba476a23 100644 --- a/ui-react/src/pages/datasets/DatasetUploadPage.tsx +++ b/ui-react/src/pages/datasets/DatasetUploadPage.tsx @@ -35,7 +35,12 @@ import { } from '@/lib/ckan-upload'; import { useDebouncedValue } from '@/hooks/useDebouncedValue'; import { useSemanticSearch, useSimilarVariables } from '@/hooks/useSemanticSearch'; -import { closeConsumers, consumersOfVariable } from '@/lib/datasets/upload-preview'; +import { + closeConsumers, + consumersOfVariable, + rankSuggestionsByUse, + suggestionUseText, +} from '@/lib/datasets/upload-preview'; import { unionBoundingBox, type BoundingBox } from '@/lib/geo/bbox'; import { standardVariableName } from '@/lib/standard-variable-display'; import { useAuth } from '@/lib/auth/useAuth'; @@ -177,12 +182,21 @@ export function DatasetUploadPage() { // Standard variables suggested from what the user wrote. Never chosen for them. const aboutText = useDebouncedValue(`${title}\n${description}`.trim(), SUGGEST_DELAY_MS); const suggested = useSemanticSearch(aboutText, { target: 'svo', limit: 20, minLength: 4 }); + // Ranked by whether a registered flow or model takes these files under the + // variable, then by how close it is to the text. const suggestions = useMemo( - () => (suggested.results ?? []).filter((r) => r.label?.trim()), - [suggested.results], + () => + rankSuggestionsByUse( + tree, + (suggested.results ?? []).filter((r) => r.label?.trim()), + files, + ), + [tree, suggested.results, files], ); - const suggestionIds = useMemo(() => suggestions.map((r) => r.id), [suggestions]); - const shownSuggestions = suggestions.filter((r) => r.id !== variable?.id).slice(0, SUGGEST_SHOWN); + const suggestionIds = useMemo(() => suggestions.map((r) => r.item.id), [suggestions]); + const shownSuggestions = suggestions + .filter((r) => r.item.id !== variable?.id) + .slice(0, SUGGEST_SHOWN); const similar = useSimilarVariables(variable?.id, { limit: 5 }); const closeMatches = useMemo( @@ -532,32 +546,43 @@ export function DatasetUploadPage() {

Suggested standard variables

    - {shownSuggestions.map((s) => ( -
  • - - {s.label} - {s.description && ( - {s.description} - )} - - -
  • - ))} + {shownSuggestions.map((ranked) => { + const s = ranked.item; + return ( +
  • + + {s.label} + {s.description && ( + + {s.description} + + )} + + {suggestionUseText(ranked)} + + + +
  • + ); + })}
)} From 058891a3b4427d211976d7bc72ccbc8eb8622706 Mon Sep 17 00:00:00 2001 From: Will Mobley Date: Fri, 20 Nov 2026 13:27:52 -0600 Subject: [PATCH 05/12] 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 10/12] 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 11/12] 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 12/12] 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(); + }); });