RFC: Node configuration redesign — unify services.json sections, freeze getServiceSchemas

[stepmikhaylov]

Status: Proposal · rev 3 — feedback welcome
Scope: reformat services.json in place · all sections · Python nodeConfig · simplify services.cpp
Backward-compat contract: getServiceSchemas output stays byte-identical

One node config field is defined in four places today that quietly drift apart. This proposal reformats services.json in place — field definitions and the config structure separated into fields{} + config[], with presets and conditionals folded into a single recursive enum field type — and simplifies the parser, while getServiceSchemas keeps emitting the legacy schema so no external component changes.

What changed since rev 2. rev 2 proposed an ordered fields[] array plus a separate presets block and a when predicate. rev 3 replaces those with (a) a reusable fields{} definition map + a config[] structure whose items reference / inline / inherits a field, and (b) an enum field type whose values each carry their own nested config — one recursive construct that subsumes presets, the profile selector, conditionals, and per-profile storage. Everything else in rev 2 (freeze getServiceSchemas, kill getNodeConfig, the phase plan) stands.

Contents

1. The problem
2. Principles & scope
3. The new services.json
4. Field model, modes & types
5. Runtime: IInstance.nodeConfig
6. Engine: input new, output legacy
7. UI & external components
8. The compatibility boundary
9. Decisions taken
10. Implementation plan
11. Risks & mitigations
12. Open questions

---

1. The problem

The pieces downstream are clean. The pain is concentrated in authoring and in the Python that reads config — and it comes from one thing: the same field is declared, and defaulted, in several unconnected places.

A node's configuration is spread across four sources of truth, and the runtime and the UI don't even read the same one:

Concern	Declared in	Read by
Field schema + UI hints	fields{} — dotted names, flat global pool, private-over-global merge	C++ → UI (RJSF), docs generator
Layout / which section a field shows in	shape[] — sections referencing field names by string	C++ → UI
Runtime default values	preconfig.profiles[…]	Config.getNodeConfig → Python
Fallback default	hardcoded config.get('x', DEFAULT)	Python only — 138 files

So fields[].default (what the UI and docs show) and preconfig.profiles[…] (what the node actually receives) are separate declarations that silently diverge, and the node then hardcodes a third fallback. Change a default in one place and the other two lie.

Two further structural costs: fields live in a flat global pool resolved by dotted-name magic (vector.apikey, llm.cloud.apikey) with private-over-global merge, and the same field is duplicated across sections — the filesystem source, for instance, declares a whole parallel Pipe.include / Pipe.exclude set beside its include / exclude just to appear in both the Source and Pipe forms.

On the Python side, every node opens with the same plumbing — resolve through Config.getNodeConfig (packages/ai/src/ai/common/config.py), then read each value with a hardcoded fallback. It's called across 138 files; the base class already wraps it behind a property carrying a literal # TODO: this global/object config stuff needs refactoring at rocketlib/filters.py:613.

2. Principles & scope

• Same file, new shape. No new node.json. Each services.json is refactored in place to the new schema.
• All sections, one model. Pipe, Source, Target, Transform (and the Export mode) all move to a single ordered config[] structure. Section membership becomes a per-entry modes tag, replacing the shape array.
• Define once, place many. A field's schema is declared once — inline in config[] for a one-off field, or in the shared fields{} pool for a reused one — and referenced (or specialized via inherits) where it is placed. That one declaration produces the resolved runtime value, the form, and the docs row.
• Compat at the output. services.cpp is adapted to parse the new format; the public getServiceSchemas keeps emitting today's compiled schema byte-for-byte, so every external consumer — the UI, the overlay product, provider combos — is unaffected. Backward-compat moves from "don't touch the files" to "don't change the output."
• Simplify for OSS. With one clean input model, the parser sheds the global-pool, shape-indirection, and per-section-duplication machinery.
• Kill getNodeConfig. Python reads values through a declarative nodeConfig; the resolver and hardcoded fallbacks go away.

3. The new services.json

Identity and registration keep the top-level keys they already have. What changes: fields{} + shape[] + preconfig collapse into a reusable fields{} definition map plus an ordered config[] structure, and the profile / preset / conditional idiom collapses into an enum field type.

fields{} (definitions) vs config[] (structure)

• fields{} — a map (key = name) of reusable field definitions, as today (a local pool, resolved over the shared global pool).
• config[] — the ordered configuration structure. Each item is either:
  • a string — a reference to a field defined in fields{} (local, then global), or
  • an object — a new inline field, or an extension of a defined field via "inherits": "<name>" plus overrides.

Resolution unwinds bottom-up, most-specific wins: the config[] item's own definition (inline / inherits overrides), then local fields{}, then global fields{}.

The simplest node — prompt — today versus target:

Before — three blocks:

"fields": {
  "instructions": {
    "type": "array", "title": "Instructions",
    "items": { "type": "string" } }
},
"shape": [
  { "section": "Pipe", "properties": ["instructions"] }
],
"preconfig": {
  "default": "default",
  "profiles": { "default": {
    "instructions": ["Please…"]   // 2nd default
  } }
}

After — one structure entry, defined inline (a one-off field needs no fields{} entry):

"config": [
  {
    "name": "instructions",
    "type": "string[]",
    "label": "Instructions",
    "help": "Added before the LLM",
    "default": ["Please…"]   // the only default
    // no "modes" → applies to every section
  }
]

Ordered array, position is order

config[] is an array; array position is the display order — the ordering that shape[].properties used to encode implicitly. A field reused across nodes is declared once in fields{} and pulled in by name.

Sections become modes

A config[] entry's modes lists the sections it appears in: "modes": "Source" or "modes": ["Target", "Export"]. Omit it and the entry applies to every mode. This both shares a field across sections (one entry, several modes) and specializes it where sections genuinely differ (two entries, same name, disjoint modes) — which is how the old cross-section duplication is resolved:

Before — parallel field sets + shape:

"fields": {
  "include":      { /* Source copy */ },
  "Pipe.include": { /* Pipe copy */ }
},
"shape": [
  { "section": "Source", "properties": ["include", "estimation"] },
  { "section": "Pipe",   "properties": ["Pipe.include"] }
]

After — one definition, placed with tags:

"fields": {
  "include": { "type": "row[]", … }        // defined once
},
"config": [
  { "inherits": "include", "modes": ["Source", "Pipe"] },   // shared
  { "name": "estimation", "type": "group",
    "modes": "Source", … }                                  // Source only
]

Full structure (an LLM node with presets)

The model selector is an enum field: each value is a model, its title is the dropdown label, and its config pins that model's metadata (and, for custom, reveals the editable fields). No separate presets block.

// nodes/src/nodes/llm_anthropic/services.json
{
  // ── identity / registration — top-level keys unchanged ──
  "title": "Anthropic", "protocol": "llm_anthropic://",
  "classType": ["llm"], "capabilities": ["invoke"],
  "register": "filter", "node": "python", "path": "nodes.llm_anthropic",
  "icon": "anthropic.svg", "tile": ["Model: ${config.model}"],
  "lanes": { "questions": ["answers"] },
  "invoke": { "llm": { "description": "Ask the model" } },

  // ── fields: reusable definitions ──
  "fields": {
    "apikey":           { "type": "secret", "label": "API Key", "required": true },
    "model":            { "type": "string", "label": "Model" },
    "modelTotalTokens": { "type": "int",    "label": "Context tokens", "default": 200000 },
    "temperature":      { "type": "number", "label": "Temperature", "default": 0.7,
                          "min": 0, "max": 1, "advanced": true }
  },

  // ── config: ordered structure, ONE source of truth ──
  "config": [
    "apikey",
    {
      "name": "model", "type": "enum", "label": "Model",
      "default": "claude-sonnet-4-6",
      "values": {
        "claude-sonnet-4-6": { "title": "Claude Sonnet 4.6",
          "config": [ { "inherits": "modelTotalTokens", "default": 1000000 } ] },
        "custom":            { "title": "Custom",
          "config": [ "model", "modelTotalTokens" ] }
      }
    },
    "temperature"
  ],

  "test": { /* co-located, semantics unchanged */ }
}

4. Field model, modes & types

Every field definition is { type, … }; every config[] placement is a string ref, an inline field ({ name, type, … }), or an inherits extension ({ inherits, …overrides }), optionally carrying modes. The type vocabulary folds today's type + format + secure + ui.widget + enum sprawl into a small closed set.

The field envelope

• name — the runtime key (was the object key / last dotted segment).
• modes — section membership; string or array; omit = all. Replaces shape/section.
• type, label, help, default, required, min/max, readonly, hidden, advanced.

The enum type

enum carries a values map — each key is a stored value, each entry a { title, config? }:

• title — the option label (replaces enumNames and the *>preconfig.profiles.*.title projection).
• config — optional nested config[] revealed when the value is selected, stored under a subtree keyed by the value. Omit it for a plain select; use it for a preset bundle / conditional reveal / per-profile subtree — they are all the same construct.

Today	New	Meaning
fields object + shape[]	fields{} defs + config[] (ref / inline / inherits) + per-entry modes	reusable definitions, ordered structure, section membership inline
type:"string" / + format:"textarea"	string / text	single- / multi-line
type:"number" / "integer"	number / int	numeric, with min/max
type:"boolean"	bool	toggle
secure:true + ApiKey/password widget	secret	masked, encrypted, never dropped on change
format:"url" / "data-url"	url / file	validated URL · file upload
type:"array" items:string / object	string[] · row[] of a group	list · repeatable sub-form
type:"object" + properties	group with a nested config[]	nested object
enum:[[v,label]] + enumNames	enum + values:{ value:{ title } }	select
combo:"llm"	type:"provider", of:"llm"	pick a node of a classType + its config
conditional:[{value,properties}]	enum value's nested config[]	reveal-on-select (recursive)
optional:false	required:true	inverted; optional by default
object:"<profile>" + preconfig	enum field with per-value config	the whole model-selector idiom, no separate block
dotted global pool (vector.apikey)	fields{} def + string ref, resolved local → global	no implicit namespace
ui.chip	— dropped —	no live consumer found

Conditionals become a reveal. Today a conditional compiles to JSON-Schema dependencies → oneOf — the source of much nesting. In the new model a value simply lists the fields it reveals in its own config[], and a nested selector nests its own config, so chained conditions fall out of the recursion. The parser still expands this to the legacy oneOf on output (§6); the runtime uses it so a hidden field never leaks a value. (A lightweight boolean show-if — a bool that reveals fields without being a full enum — is UI-only and deferred; see §12.)

5. Runtime: IInstance.nodeConfig

A typed, resolved view of the node's config, populated from the declaration. Declaring a field is all it takes to read it — no resolver call, no fallback literal. Scope: the Python pipe nodes (the Source/Target endpoints are C++-native).

Before:

# IGlobal.beginGlobal
self.config = Config.getNodeConfig(
    self.glb.logicalType, self.glb.connConfig)
# IInstance
cfg = self.IGlobal.config
model = cfg.get('model', 'claude-…')   # 3rd default

After:

# no getNodeConfig, no IGlobal plumbing, no hardcoded fallback
model  = self.nodeConfig.model             # str
tokens = self.nodeConfig.modelTotalTokens  # int, coerced

Added to the rocketlib base classes (rocketlib/filters.py) on IInstanceBase and IGlobalBase (~93 of today's call sites live in IGlobal.py). The value is resolved by overlaying four layers, highest priority last:

#	Layer	Source
1	Field default	services.json · field definition (fields{} / inline)
2	Selected enum value's config	services.json · the chosen enum value's config (defaults + revealed fields)
3	Saved node config	.pipe · connConfig
4	Per-object parameters	currentObject.parameters[pipeType.id]

non-null wins · nested groups merge recursively · cached per object, cleared in close()

This preserves the exact layering getNodeConfig + the params property implement today, including per-object overrides and the flat / nested-under-profile connConfig shapes in saved pipelines. Field declarations are read from the same services.json the engine parses (via getServiceDefinition, now returning the new-format raw definition).

Cross-provider resolution. ~11 nodes (autopipe, vectorizer, chroma, qdrant, pinecone, …) resolve another node's config when nested as a sub-provider (getMultiProviderConfig). A module helper resolveConfig(logicalType, connConfig) — the declaration-driven successor to getNodeConfig — handles that; Config.getNodeConfig remains a thin deprecated shim over it until those sites migrate.

6. Engine: input new, output legacy

This is the load-bearing idea (from rev 2). services.cpp learns the new format on the way in and keeps emitting the current compiled schema on the way out — so the simplification is internal and invisible to everything downstream.

flowchart LR
  A["services.json (new)<br/>fields{} + config[] + enum values"] --> B["services.cpp (simplified)<br/>resolve config[] refs/inherits<br/>group by modes<br/>enum values → selector + oneOf + per-value subtree/defaults"]
  B --> C["getServiceSchemas (legacy · frozen)<br/>serviceSchema[section] = {schema, ui}"]
  C --> D["UI (RJSF)"]
  C --> E["Overlay product"]
  C --> F["Provider combos (processCombo)"]

Loading

What the parser sheds (the OSS-simplification win): the flat global-field pool's dotted-name resolution magic, the shape-to-fields indirection, and the per-section field duplication. What it keeps is a single compile step from the clean config[] to the legacy per-section {schema, ui}: resolving refs/inherits against fields{}, grouping by modes, and materializing each enum value's config into the profile-selector enum + the oneOf reveal + injected defaults the current schema carries. Complexity moves from the input model to a single, testable emitter.

Contract — getServiceSchemas is the frozen surface. The compiled catalog served over WebSocket rrext_services (port 5565) under VERSION = 1 is asserted byte-identical before and after (§10, Phase 0). getServiceDefinition (the raw, Python-facing definition) does change to the new shape — its only readers are our own nodes, updated in step.

7. UI & external components

Supersedes rev 1. rev 1 chose a native loader with a new UI renderer that dropped RJSF. rev 2/3 make that unnecessary: because getServiceSchemas output is frozen, the UI, the overlay product, and the combo machinery all keep working with zero changes. RJSF stays. A new renderer becomes an optional, fully decoupled follow-up rather than part of this refactor.

Nothing in shared-ui/…/NodeConfigPanel.tsx, the rrext_services transport, the TS/Python client types, or the RJSF widget layer changes. The UI still reads service.Pipe.{schema, ui}; edited values still persist 1:1 into the .pipe config object; every saved pipeline still loads. That is the entire point of freezing the output.

8. The compatibility boundary

The guarantee is relocated: not "these files are off-limits" but "this output never changes."

Surface	Disposition
getServiceSchemas output (WS 5565)	Frozen. Byte-identical; VERSION stays 1. This is what the overlay product and UI consume.
Source / Target / Transform sections	Reformatted in place like every other section (via modes), but compile to the same schema. Endpoints stay C++-native.
Persisted .pipe config shape	Unchanged. Enum-value subtrees keep the config.<value>.<key> layout; resolver keeps the flat and nested-under-profile read paths.
ConfigureService.cpp (mode → section)	Unchanged; still selects by source/target/export/transform mode.
Model-sync tool (tools/sync_models/…/merger.py)	Retargeted to write the model enum's values instead of preconfig.profiles — same data, new location.
getServiceDefinition (raw, Python-facing)	Changes to new shape; internal readers updated in step.

Must confirm — what the overlay actually consumes. This all holds if the overlay product consumes getServiceSchemas output and does not ship its own raw legacy services.json into this engine. If it does ship raw files, services.cpp must either retain a legacy input reader (less simplification) or those files migrate too. This is the one fact to nail down before Phase 1 — see §12.

9. Decisions taken

• Reformat in place, freeze the output. Same services.json, new schema, all sections; services.cpp adapted and simplified; getServiceSchemas unchanged.
• Definitions vs structure. fields{} holds reusable field definitions; config[] is the ordered structure that references (string), inlines, or inherits-and-overrides them. Resolution unwinds bottom-up: config[] item → local fields{} → global fields{}. The shared global pool is kept (this settles rev 2's §12 "shared fields" question).
• Presets = an enum field, no separate block. The profile + conditional + object + preconfig idiom collapses into one enum field type whose values each carry a title and an optional nested config — which is simultaneously the preset bundle, the selector, the conditional reveal, and the per-profile subtree. LLM nodes keep dozens of model values maintained by the sync tool.
• Migration = convert-and-verify sweep. Because the output is byte-verifiable, a deterministic converter + a parity harness make a mechanical sweep safer and simpler than maintaining dual-format parsing. The tree converts in reviewed batches, each gated on identical getServiceSchemas output, and services.cpp carries one format — not two — as soon as the sweep completes.

10. Implementation plan

Six phases. The parity harness in Phase 0 is the spine — every later phase is gated on identical getServiceSchemas output and identical resolved config.

Phase 0 — Spec, converter & parity harness

Make correctness mechanically checkable before touching the engine.

• Write the new-format spec + meta-schema (fields{}, config[], the enum/values construct, inherits resolution).
• Build a deterministic converter: legacy services.json → new format.
• Capture a baseline of getServiceSchemas output for all 145 files; build a harness asserting new-format output is byte-identical, and that resolved config matches for real .pipe fixtures.
• Exit: converter runs clean on all files; baseline captured; harness green against legacy.

Phase 1 — Parser: read new, emit legacy · C++

Teach services.cpp the new format while freezing its output.

• Resolve config[] refs/inherits against fields{}; group by mode; materialize enum values → selector + oneOf + per-value subtree/defaults.
• Delete the global-pool dotted-merge / shape-indirection machinery once unreferenced.
• Run against converter output; gate on the byte-identical harness.
• Exit: converted fixtures produce byte-identical getServiceSchemas; parser LoC down.

Phase 2 — Convert the tree · C++ · JSON

Move all 145 files to the new format.

• Run the converter in reviewed batches (Pipe families, then endpoints/Transform).
• Each batch gated on identical output; hand-review same-name-different-modes splits and enum-value materialization.
• log any file the converter can't handle for manual follow-up — no silent skips.
• Exit: whole tree new-format; harness green; legacy input reader removable.

Phase 3 — Runtime: nodeConfig · Python

Kill getNodeConfig across 138 files.

• Implement the declaration-driven resolver, resolveConfig(), and IInstance/IGlobal.nodeConfig in rocketlib.
• Reduce Config.getNodeConfig to a shim; convert node code to self.nodeConfig.*.
• Gate on resolved-config parity fixtures from Phase 0.
• Exit: nodes read via nodeConfig; node tests green; shim only behind provider-nesting sites.

Phase 4 — Docs generator

Keep the co-located schema tables truthful.

• Point nodes/scripts/gen-node-tables.mjs at the new fields{} + config[].
• Verify with builder docs:build per the co-located-docs rule.
• Exit: generated tables regenerate cleanly; docs build passes.

Phase 5 — Final simplification

Remove the last of the legacy machinery.

• Drop the legacy input reader (pending the §12 overlay answer) and the preconfig / dotted-pool code paths.
• Remove Config.getNodeConfig once provider-nesting sites are on resolveConfig.
• Update the services.cpp test + client types.
• Exit: one input format, one config path, output still frozen.

11. Risks & mitigations

• Output drift. Any divergence in getServiceSchemas breaks the overlay silently. Mitigation: the byte-identical harness (Phase 0) is a hard gate on every phase; VERSION only bumps if we deliberately change the surface.
• Overlay ships raw files. If the external product ships legacy services.json into this engine, dropping legacy input parsing breaks it. Mitigation: confirm before Phase 1 (§12); if so, keep a thin legacy reader instead of removing it in Phase 5.
• Lossy conversion. Cross-section field differences and the preset idiom are the tricky conversions. Mitigation: converter emits same-name-different-modes splits and enum-value bundles explicitly; every file is output-diffed, and unconvertible cases are logged, not skipped.
• getServiceDefinition readers. A handful of nodes read raw shape/preconfig via getServiceDefinition. Mitigation: inventory them in Phase 0; update in step with the format (they're all in-repo).

12. Open questions

• Overlay consumption (blocking). Does the external product consume only getServiceSchemas output, or does it also ship raw legacy services.json files this engine must parse? This decides whether Phase 5 removes legacy input parsing entirely.
• Boolean-conditional reveal. A bool that shows/hides fields without being a full enum — model it as a degenerate enum (values:{true:{config},false:{config}}) or add a small when back for that case only? Deferred; UI-only, no effect on code-side config access.
• Same-name split ergonomics. When a field genuinely differs by section, two config[] entries sharing a name with disjoint modes (proposed) — or per-mode overrides inside one entry (e.g. "overrides": { "Pipe": { "help": "…" } })?
• Provider-composition nodes (autopipe, vectorizer): model the nested {provider, <provider>:{…}} as a first-class provider field type now, or keep them on the shim longest?

---

Grounded in: packages/ai/src/ai/common/config.py · rocketlib/filters.py · engLib/store/services/services.cpp · engLib/store/python/bindings.cpp · shared-ui/…/NodeConfigPanel.tsx · nodes/scripts/gen-node-tables.mjs. Corpus: 145 config files · sections Pipe 132 / Transform 11 / Source 2 / Target 2 (+ nested parameters, estimation) · 138 getNodeConfig sites.

[github-actions[bot]]

🤖 Internal: Discord sync marker

Auto-managed by the Discord notification workflow. Stores the linked Discord message ID and forum thread ID. Do not edit or delete.

[asclearuc]

@stepmikhaylov - LGTM !