Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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