UDIChatConfig

Defined in: chat/src/app/UDIChatConfig.ts:32

Public configuration surface for the UDIChat root component. Extracted from UDIChat.tsx so that validateConfig and other app-layer utilities can import the type without reaching into the component module.

Properties

apiBaseUrl

apiBaseUrl: string

Defined in: chat/src/app/UDIChatConfig.ts:33

authToken?

optional authToken?: string

Defined in: chat/src/app/UDIChatConfig.ts:51

className?

optional className?: string

Defined in: chat/src/app/UDIChatConfig.ts:262

cohort?

optional cohort?: object

Defined in: chat/src/app/UDIChatConfig.ts:243

The subject to report the filtered cohort of: a table of the data package (entity, e.g. 'patient') and the fields that identify its rows (fields, default: the table’s primaryKey). With UDIChatConfig.onCohortChange, every change to the filters — chat, chart and host alike, on any table that reaches this one — reports the rows of entity that pass them all.

entity

entity: string

fields?

optional fields?: string[]

dataFieldDomains?

optional dataFieldDomains?: DataFieldDomain[]

Defined in: chat/src/app/UDIChatConfig.ts:48

Pre-computed field domains. When provided with dataPackage, skips CSV loading for domain computation.

dataPackage?

optional dataPackage?: DataPackage

Defined in: chat/src/app/UDIChatConfig.ts:46

Provide a DataPackage object directly instead of fetching from a URL. Takes precedence over dataPackagePath.

dataPackagePath?

optional dataPackagePath?: string

Defined in: chat/src/app/UDIChatConfig.ts:44

URL to fetch a datapackage_udi.json from. Ignored when dataPackage is provided.

downloadActions?

optional downloadActions?: readonly DownloadAction[]

Defined in: chat/src/app/UDIChatConfig.ts:70

Extra items to append to the Download Data dropdown. Each action’s onClick receives a DownloadActionContext snapshot of the current filters and per-source rows, so consumers can export, route, or post-process that data in consumer-specific ways. Rendered after the built-in “Download Raw Data” and “Download Manifest” items, separated by a divider.

downloadButtonLabel?

optional downloadButtonLabel?: string

Defined in: chat/src/app/UDIChatConfig.ts:76

Override the visible label on the Download dropdown trigger. Defaults to “Download Data”. Useful when consumers want product-specific wording (e.g. “Export”, “Download Cohort”).

entityIcons?

optional entityIcons?: EntityIconMap

Defined in: chat/src/app/UDIChatConfig.ts:84

Map from entity name (as it appears in the data package resources[].name) to an icon component. Merged on top of the built-in icons (donors, samples, datasets, …) with consumer entries winning, so you can supply icons for additional entities or override the defaults. Any component that accepts a className prop works — lucide-react icons are typical.

fetchOptions?

optional fetchOptions?: RequestInit

Defined in: chat/src/app/UDIChatConfig.ts:50

Custom fetch options (e.g. headers, credentials) forwarded to all data-loading fetch calls.

filterMode?

optional filterMode?: FilterMode

Defined in: chat/src/app/UDIChatConfig.ts:234

How UDIChatConfig.filters meet the filters made in the chat and on charts.

'separate' (default) — each host filter is its own chip, read-only to the agent, and applies on top of any chat or chart filter on the same column.
'shared' — a host filter on a single field becomes that column’s filter, the one chat and charts write too: one chip, and whoever edits it last (the host, the agent, a chart click) sets it. UDIChatConfig.onFiltersChange reports it as col:<entity>.<field> with the origin of that last edit, so a host can mirror chart clicks and chat requests by matching dataSourceKey and field. Dropping a host entry removes the filter only while the host was still its last editor. Filters on several fields stay separate.

filters?

optional filters?: UDIFilter[]

Defined in: chat/src/app/UDIChatConfig.ts:210

Filters set by the embedding page. Each shows as a chip in the Filters bar and filters every chart, like a chat filter; the user can adjust, clear or remove it there. Entries are matched by id and applied again only when that entry changes, so re-rendering with the same array never undoes the user’s edits; dropping an entry deletes its filter. Entries whose origin is 'chat' or 'chart' are ignored, so feeding UDIChatConfig.onFiltersChange’s output straight back is safe.

fontScale?

optional fontScale?: number

Defined in: chat/src/app/UDIChatConfig.ts:141

Multiplier on every text size, charts and tables included: 1 is the stock size, 2 doubles it. Clamped to 1–2. When set, it overrides the viewer’s own Text size setting and hides that slider, so the host decides — e.g. a presentation mode, or a read-only embed, which has no slider to reach. Omit it to leave text size to the viewer.

initialSession?

optional initialSession?: unknown

Defined in: chat/src/app/UDIChatConfig.ts:192

A session export to seed the dashboard (and the conversation behind it) with — the JSON written by the dashboard’s Session → Export session action, in the SessionExport shape.

Typed unknown so a consumer can pass JSON.parse(file) straight through: the value is run past parseSessionExport, and a malformed one throws from validateConfig into the surrounding ErrorBoundary rather than failing quietly. Applied once, after the data package has loaded (the cards need its field lists to become interactive).

issueReporting?

optional issueReporting?: boolean

Defined in: chat/src/app/UDIChatConfig.ts:261

Let users report a problem to the development team: a Report an issue item in the Session menu, a button on the crash screen, and an offer from the agent when the user asks to report something or says a result is wrong. A report sends the user’s note and their session export to POST /v1/yac/issue_report, which records it in the agent’s LangFuse. Off by default; switch it on only against an agent with LangFuse configured (without it the agent refuses reports, and never offers one).

mascot?

optional mascot?: ReactNode

Defined in: chat/src/app/UDIChatConfig.ts:93

Controls the mascot rendered on the empty-dashboard splash:

undefined (prop omitted): the default YAC mascot image is rendered.
null: the mascot is hidden entirely.
any other ReactNode: the provided node is rendered in place of the mascot.

The speech-bubble prompt above the mascot is not affected by this prop.

model?

optional model?: string

Defined in: chat/src/app/UDIChatConfig.ts:61

LLM model id to run the request on. Applied only when the user supplies their own OpenAI key (requireApiKey, or a key entered in the UI): the server honors a requested model only alongside an X-OpenAI-Key, so that whoever pays for the tokens picks the model. Without a caller key the server’s own GPT_MODEL_NAME applies and this value is not sent.

onCohortChange?

optional onCohortChange?: (cohort) => void

Defined in: chat/src/app/UDIChatConfig.ts:251

Called with the cohort UDIChatConfig.cohort asks for, once the filters settle: the key fields of every passing row, or null while no filter reaches the entity, so the host need not handle a list of every subject. Unlike row-level results, the list is not capped in server-side data mode.

Parameters

cohort

UDICohort | null

Returns

void

onEvent?

optional onEvent?: TrackerFn

Defined in: chat/src/app/UDIChatConfig.ts:112

Optional analytics callback. When provided, UDIChat emits events for key user actions (messages sent, responses received, rebuffs, API key changes, visualization pin/close, conversation reset, downloads).

Callbacks carry metadata only — never raw message content or OpenAI key material — and thrown errors are swallowed so an analytics failure never breaks the chat. See the “Analytics events” section of the README for the full event catalog and the properties each one emits.

onFiltersChange?

optional onFiltersChange?: (filters) => void

Defined in: chat/src/app/UDIChatConfig.ts:217

Called with every filter in place whenever one changes — chat, chart and host filters alike, each tagged with its origin. A filter with no values ([]) is cleared: still shown, filtering nothing. Removed filters are left out.

Parameters

filters

UDIFilter[]

Returns

void

onReadOnlyChange?

optional onReadOnlyChange?: (readOnly) => void

Defined in: chat/src/app/UDIChatConfig.ts:173

Called with false when the user presses Explore Data — not when UDIChatConfig.readOnly changes. Passing it makes the mode controlled: the button no longer leaves read-only by itself, and the host does so by setting readOnly — free to move the chat into more room, and to animate that, in the same update.

Parameters

readOnly

boolean

Returns

void

palette?

optional palette?: UDIPalette

Defined in: chat/src/app/UDIChatConfig.ts:120

Default color palette applied to every chart and table. Sets the categorical colors, ordinal colors, single mark color, and the continuous (numeric) color ramp. The ramp may be a Vega scheme name, an array of colors, or an interpolator function (t: number) => string for numeric scales. A spec-level per-encoding range still overrides it.

readOnly?

optional readOnly?: ReadOnlyOption

Defined in: chat/src/app/UDIChatConfig.ts:165

Read-only mode: the chat pane and the dashboard’s top bar (counts, grid settings, session import/export, Download Data) are hidden, as is every editing control on the cards — drag, resize, rename, close, field tweak. What stays is the charts and what reads them: brushing and cross-filtering, the filter chips, the chart/table toggle and the info tooltips.

true — a floating Explore Data button leaves read-only and opens the chat (see UDIChatConfig.onReadOnlyChange).
'locked' — the same, with no way out for the user. For hosts embedding the dashboard that do not want their users chatting at all.

A change to this prop switches the mode, so the host can move between an inline read-only dashboard and a full chat — say, in a modal — and back, with charts, filters, brushes and the conversation intact. That needs the same mounted UDIChat throughout: restyle its container rather than rendering it somewhere else (a portal-based dialog remounts it).

With the chat hidden there is nothing to build a dashboard from, so a read-only embed almost always wants UDIChatConfig.initialSession too. See also the UDIDashboard component, which is UDIChat with this set.

recordUrl?

optional recordUrl?: RecordUrlFn

Defined in: chat/src/app/UDIChatConfig.ts:133

Links individual records out to their own pages. Called with a row of a chart or table and its entity (the spec’s first source); return that record’s URL, or nothing for a row with no page. Tables gain a leading ↗ column, and a plain click on a point opens the record (a modifier click still picks). Aggregated rows carry no record id, so an aggregate gets no links. Only http(s) URLs are followed; relative ones resolve against the host page.

Independently of this prop, a table cell whose value is an http(s) URL is always a link.

refitOnReadOnlyChange?

optional refitOnReadOnlyChange?: boolean

Defined in: chat/src/app/UDIChatConfig.ts:180

Whether the dashboard re-derives its column count for its new width when read-only mode changes either way: narrower when the chat pane appears, wider when it goes. Default true. Pass false to keep the count — an UDIChatConfig.initialSession’s, say — and let the cards stretch.

remotePackage?

optional remotePackage?: string

Defined in: chat/src/app/UDIChatConfig.ts:42

Name of a server-side data package (configured on the agent server’s query backends). When set, the chat fetches introspected metadata from GET /v1/yac/metadata and routes all data queries through POST /v1/yac/query — no CSVs are loaded into the browser, and cross-filtering becomes non-interactive (commit on mouse-up with a loading overlay). Takes precedence over dataPackage/dataPackagePath.

requireApiKey?

optional requireApiKey?: boolean

Defined in: chat/src/app/UDIChatConfig.ts:53

If true, prompt the user to enter an OpenAI API key before chatting.

savedSessionsKey?

optional savedSessionsKey?: string

Defined in: chat/src/app/UDIChatConfig.ts:200

Turns on “Saved in browser” in the dashboard’s Session menu: the user can save the current session under a name, and load or delete the sessions saved under this key. They live in this origin’s localStorage, and a session only makes sense against the data package it was built on, so use one key per package. Unset, the menu offers file export/import only.

splashMessages?

optional splashMessages?: readonly string[]

Defined in: chat/src/app/UDIChatConfig.ts:101

Override the randomised prompts shown in the speech bubble above the mascot on the empty-dashboard splash.

undefined (prop omitted): use the built-in defaults.
A non-empty array: pick one of the provided messages at random.
An empty array ([]): hide the speech bubble entirely.

style?

optional style?: CSSProperties

Defined in: chat/src/app/UDIChatConfig.ts:263