Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
ca59c90
Upload page: Use in a thread starts guided model setup with the datas…
wmobley Nov 20, 2026
b90ef9b
Framing boundary picker: readable names, grouped, searchable, familie…
wmobley Nov 20, 2026
023bcc7
Outcome picker shows titled, unrepeated options; Models step ranks ou…
wmobley Nov 20, 2026
38c0b29
Rank upload variable suggestions by which inputs take the files
wmobley Nov 20, 2026
058891a
Design spec: flow settings with choices, explanations and author defa…
wmobley Nov 20, 2026
fc5634e
Spec: hidden settings, model dropdowns, visibility column, traced def…
wmobley Nov 20, 2026
b4456f9
Spec approved: flow setting schemas
wmobley Nov 20, 2026
9994104
Flow settings: author choices column, adapter resolution and refusals
wmobley Nov 20, 2026
3f9a750
Flow builder: describe settings by their piece, and let the author fi…
wmobley Nov 20, 2026
f22c7a3
Thread run form: titles, dropdowns, advanced and hidden settings, mod…
wmobley Nov 20, 2026
aa2fc72
Spec: record implementation deviations for flow setting schemas
wmobley Nov 20, 2026
499b4c3
Flow settings review fixes: guard credential-like names, thread value…
wmobley Nov 20, 2026
5a7cb38
Merge remote-tracking branch 'origin/feat/flow-setting-schemas' into …
wmobley Nov 20, 2026
f0b37e2
Merge remote-tracking branch 'origin/feat/upload-starts-guided-setup'…
wmobley Nov 20, 2026
8d491fb
Merge remote-tracking branch 'origin/fix/ui-upload-suggestion-ranking…
wmobley Nov 20, 2026
7dae6e9
Merge remote-tracking branch 'origin/fix/ui-outcome-picker-and-flow-r…
wmobley Nov 20, 2026
5750bba
Merge remote-tracking branch 'origin/fix/ui-boundary-picker' into fea…
wmobley Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
390 changes: 390 additions & 0 deletions docs/design/2026-11-20-flow-setting-schemas.md

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions graphql_engine/metadata/tables.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -5126,15 +5126,15 @@
- _not: {thread_models: {}}
- _not: {executions: {}}
- {_exists: {_table: {name: modelcatalog_admin, schema: public}, _where: {username: {_eq: X-Hasura-User-Id}}}}
columns: [configuration_id, outputs_json, thread_bindings_json]
columns: [configuration_id, outputs_json, thread_bindings_json, settings_json]
select_permissions:
- role: anonymous
permission:
columns: [configuration_id, outputs_json, thread_bindings_json, created_at]
columns: [configuration_id, outputs_json, thread_bindings_json, settings_json, created_at]
filter: {}
- role: user
permission:
columns: [configuration_id, outputs_json, thread_bindings_json, created_at]
columns: [configuration_id, outputs_json, thread_bindings_json, settings_json, created_at]
filter: {}
# No update: a flow's graph does not change in place. Plans are built from it and a
# changed flow is a new configuration. Deleting it removes its steps (ON DELETE CASCADE)
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
ALTER TABLE modelcatalog_configuration_flow
DROP CONSTRAINT IF EXISTS configuration_flow_settings_is_object,
DROP COLUMN IF EXISTS settings_json;
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
-- Flow-level choices the author makes about each setting, by setting name:
-- {"match_mode": {"visibility": "shown"}, "output_uri": {"visibility": "hidden", "fixed": true}}
-- visibility is shown, advanced or hidden. Values stay in each step's settings_json and
-- are mirrored onto the flow's parameter rows. It sits on the flow, not on a step,
-- because one setting name used by several steps is one flow parameter.
ALTER TABLE modelcatalog_configuration_flow
ADD COLUMN settings_json JSONB NOT NULL DEFAULT '{}'::jsonb,
ADD CONSTRAINT configuration_flow_settings_is_object CHECK (jsonb_typeof(settings_json) = 'object');
48 changes: 48 additions & 0 deletions model-catalog-api/openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -8054,6 +8054,22 @@ paths:
maxItems: 64
items:
type: string
settings:
type: object
description: >-
What the author decided about each setting, by setting name. Values
stay in each step's `settings`. A setting that is `hidden`, and that
its piece requires, needs a value or a default (`FLOW_SETTING_HIDDEN_WITHOUT_VALUE`).
A `fixed` setting is written to the flow parameter's fixed value, and a
runner's value for a fixed or hidden setting is refused when the flow is run.
additionalProperties:
type: object
properties:
visibility:
type: string
enum: [shown, advanced, hidden]
fixed:
type: boolean
responses:
"201":
description: Flow registered. Returns the ids of the software, version, configuration, inputs and settings.
Expand Down Expand Up @@ -8108,6 +8124,38 @@ paths:
summary: Which steps of a flow the caller can run
tags:
- ModelConfiguration
/flows/{id}/settings:
get:
operationId: custom_flows_id_settings_get
description: >-
A stored flow's settings as a runner meets them: each piece's description of the
setting (title, explanation, type, choices with their own explanations, bounds),
the value a run starts from, whether the author fixed it, and whether it is
shown, advanced or hidden. The SVO adapter answers with the caller's own token.
The flow id may be the full configuration id (URL-encoded) or the short id after
the catalog prefix.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The flow's settings, and the names of those the thread fills in itself.
"401":
description: Missing or invalid bearer token.
"422":
description: No such flow (`FLOW_NOT_FOUND`).
"502":
description: The SVO adapter could not be reached or refused the request.
"503":
description: This deployment has no SVO adapter configured.
security:
- BearerAuth: []
summary: The settings of a flow, as a runner sees them
tags:
- ModelConfiguration
/regions/categories:
post:
operationId: custom_regions_categories_post
Expand Down
99 changes: 99 additions & 0 deletions model-catalog-api/src/__tests__/flows.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,13 @@ vi.mock('../hasura/client.js', () => ({
import {
custom_flows_post,
custom_flows_id_availability_get,
custom_flows_id_settings_get,
warnIfAdapterSecretMissing,
planRegistration,
buildRows,
registrationMutation,
usernameFromBearer,
toPgTextArray,
FlowError,
} from '../flows.js'

Expand Down Expand Up @@ -129,6 +131,69 @@ describe('the catalog rows for a flow', () => {
])
})

it('mirrors the pieces description of a setting and the authors fixed value onto the row', () => {
const body = {
...BODY(),
settings: { top_n: { visibility: 'advanced', fixed: true }, start: { visibility: 'hidden' } },
}
const pieces = {
...PIECES,
'p:score': {
...PIECES['p:score'],
setting_details: {
top_n: { type: 'integer', default: 10, minimum: 1, maximum: 50, choices: [{ value: 5 }, { value: 'a"b' }] },
start: {},
},
},
}
const built = buildRows(body, planRegistration(body), pieces, 'alice')
const [start, top] = built.configuration.parameters.data.map((p: any) => p.parameter.data)
expect([top.has_fixed_value, top.has_default_value]).toEqual(['25', '25'])
expect([top.has_minimum_accepted_value, top.has_maximum_accepted_value]).toEqual(['1', '50'])
expect(top.has_accepted_values).toBe('{"5","a\\"b"}')
expect([start.has_fixed_value, start.has_accepted_values, start.has_minimum_accepted_value]).toEqual([null, null, null])
expect(built.flow.settings_json).toEqual(body.settings)
})

it('writes an empty settings object and no fixed value when the author chose nothing', () => {
const built = rows()
expect(built.flow.settings_json).toEqual({})
expect(built.configuration.parameters.data.every((p: any) => p.parameter.data.has_fixed_value === null)).toBe(true)
})

it('sends the authors settings to the adapter check', () => {
const body = { ...BODY(), settings: { top_n: { visibility: 'hidden' } } }
expect(planRegistration(body).check.settings).toEqual({ top_n: { visibility: 'hidden' } })
expect(planRegistration(BODY()).check.settings).toEqual({})
})

it.each([
[{ top_n: { visibility: 'secret' } }],
[{ top_n: { fixed: 'yes' } }],
[{ top_n: { colour: 1 } }],
[{ top_n: 'hidden' }],
])('refuses settings that are not a visibility and a fixed flag', (settings) => {
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', () => {
const { configuration, flow } = rows()
const output = configuration.outputs.data[0].output.data
Expand Down Expand Up @@ -442,6 +507,40 @@ describe('GET /flows/{id}/availability', () => {
})
})

describe('GET /flows/{id}/settings', () => {
const makeSettingsReq = (id: string, authorization: string | undefined = ALICE) =>
({ params: { id }, headers: { authorization }, log: { error: vi.fn() } })

it('asks the adapter for the flow settings as the caller', async () => {
const answer = { flow_id: C, settings: [{ name: 'match_mode', visibility: 'shown' }], thread_bound: [] }
const fetchMock = adapterAnswers(answer)
const reply = makeReply()
await custom_flows_id_settings_get(makeSettingsReq('dictionary'), reply)
expect([reply._status, reply._body]).toEqual([200, answer])
const [url, request] = fetchMock.mock.calls[0]
expect(url).toBe(`https://adapter.example/flows/${encodeURIComponent(C)}/settings`)
expect(request.headers.Authorization).toBe(ALICE)
})

it('needs a signed-in caller, passes on a missing flow, and names its own unavailable code', async () => {
let fetchMock = adapterAnswers({})
let reply = makeReply()
await custom_flows_id_settings_get(makeSettingsReq('dictionary', ''), reply)
expect(reply._status).toBe(401)
expect(fetchMock).not.toHaveBeenCalled()

adapterAnswers({ detail: { code: 'FLOW_NOT_FOUND' } }, 422)
reply = makeReply()
await custom_flows_id_settings_get(makeSettingsReq('dictionary'), reply)
expect([reply._status, reply._body.code]).toEqual([422, 'FLOW_NOT_FOUND'])

fetchMock = adapterAnswers({}, 500)
reply = makeReply()
await custom_flows_id_settings_get(makeSettingsReq('dictionary'), reply)
expect([reply._status, reply._body.code]).toEqual([502, 'FLOW_SETTINGS_UNAVAILABLE'])
})
})

describe('the startup warning for a missing service secret', () => {
it('warns once, naming the setting and no value, only when an adapter is set without it', () => {
const log = { warn: vi.fn() }
Expand Down
3 changes: 2 additions & 1 deletion model-catalog-api/src/custom-handlers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ import {
custom_regions_import_post,
} from './region-import.js';
import { custom_regions_categories_post } from './region-category.js';
import { custom_flows_post, custom_flows_id_availability_get } from './flows.js';
import { custom_flows_post, custom_flows_id_availability_get, custom_flows_id_settings_get } from './flows.js';

/**
* Resolve an incoming {id} path/query value to a full resource URI.
Expand Down Expand Up @@ -899,5 +899,6 @@ export const customHandlers: Record<
custom_regions_categories_post,
custom_flows_post,
custom_flows_id_availability_get,
custom_flows_id_settings_get,
user_login_post,
};
Loading
Loading