@x12i/graphenix-executable-profile-format

Phase model profiles for metadata.extensions["graphenix.executable/v1"] — graph and node-level AI model case configuration.

Validates profileChoice keys, model config cases, node override slices, and extension-only mode (does not reject sibling task-node fields).

Canonical vocabulary: GLOSSARY.md §4 — Phase model profiles.
When phase model profile terms change, update this README and GLOSSARY.md together.

Phase model profiles (separate from utility strategies)

| Slot | Run phase | Meaning | | ---- | --------- | ------- | | preActionModel | prePhase | AI profile for PRE-phase utility work | | skillModel | mainPhase | AI profile for skill / MAIN execution | | postActionModel | postPhase | AI profile for POST-phase utility work |

Banned shorthand: “PRE model” → use PRE-phase model profile (preActionModel).

| Layer | Package | Question | | ----- | ------- | -------- | | Phase utility strategy | @x12i/graphenix-task-node-format | What utility runs (aiTaskStrategies.pre, …) | | Phase model profile | this package | Which AI profile runs each phase |

Do not conflate aiTaskStrategies.pre: "synthesis" (PRE-phase utility strategy key) with aiTaskProfile.inputSynthesis (skill input synthesis profile — @x12i/graphenix-task-node-format).

Graph extension and per-node override

Validators in this package cover:

• Graph-level metadata.extensions["graphenix.executable/v1"].modelConfig (cases + triplet)
• Node-level taskConfiguration.modelConfig override slices (preActionModel, skillModel, postActionModel on the task node)

Node overrides are executable profile semantics even when stored on the task node — not task-node body validation. validateNodeModelConfigSlice() and validateExecutableProfileExtension() both enforce §4; neither validates utility strategies (§2) or skill input synthesis profile (§3).

Examples (JSON)

Graph-level phase model profiles (required triplet per case)

{
  "formatVersion": "2.0.0",
  "id": "graph:example",
  "graph": {
    "nodes": [],
    "edges": [],
    "inputs": [],
    "outputs": [],
    "metadata": {
      "extensions": {
        "graphenix.executable/v1": {
          "profileVersion": "1.0.0",
          "modelConfig": {
            "version": "graph-model-config/v1",
            "cases": [
              {
                "id": "default",
                "modelConfig": {
                  "preActionModel": { "kind": "profileChoice", "key": "cheap/default" },
                  "skillModel": { "kind": "profileChoice", "key": "vol/default" },
                  "postActionModel": { "kind": "profileChoice", "key": "cheap/default" }
                }
              },
              {
                "id": "simulate",
                "when": { "path": "runtime.mode", "op": "eq", "value": "simulate" },
                "modelConfig": {
                  "preActionModel": { "kind": "profileChoice", "key": "cheap/default" },
                  "skillModel": { "kind": "profileChoice", "key": "sum/default" },
                  "postActionModel": { "kind": "profileChoice", "key": "cheap/default" }
                }
              }
            ],
            "fallbackPolicy": {
              "enabled": true,
              "allowedTriggers": ["nodeSlotMissing"],
              "maxAttemptsPerSlot": 1
            }
          }
        }
      }
    }
  }
}

Node-level override (partial MAIN-phase model profile)

"parameters": {
  "profile": "graphenix.task-node/v1",
  "nodeType": "task",
  "skillKey": "professional-answer",
  "taskConfiguration": {
    "executionStrategies": [],
    "aiTaskStrategies": { "pre": "synthesis" },
    "modelConfig": {
      "inherit": true,
      "cases": [{
        "id": "high-risk-input",
        "when": { "path": "runtime.input.riskLevel", "op": "eq", "value": "high" },
        "modelConfig": {
          "skillModel": { "kind": "profileChoice", "key": "deep/openai_deep" }
        }
      }]
    }
  }
}

Same node also carries phase utility strategies (aiTaskStrategies) — validated by task-node-format, not this package.

Rejected legacy shape (do not author)

"preActionModel": "cheap"

Use { "kind": "profileChoice", "key": "cheap/default" } instead.

Install

npm install @x12i/graphenix-executable-profile-format @x12i/graphenix-core

@x12i/ai-profiles is installed automatically for profileChoice key validation.

Key exports

| API | Purpose | | --- | ------- | | validateExecutableProfileExtension(doc, options?) | Validate graphenix.executable/v1 extension | | validateNodeModelConfigSlice(nodeId, params, options?) | Node taskConfiguration.modelConfig only | | validateAuthoringGraphModelConfig(modelConfig) | Graph-level cases + triplet | | preservesSiblingTaskNodeFields(parameters) | Assert extension validation ignores task body | | validateAiModelSelection, isKnownProfileChoice | Profile choice validation |

extensionOnly mode (default): validates model config semantics only — does not strip or reject taskVariable, inputsConfig, aiTaskStrategies, etc.

Extension namespace

graph.metadata.extensions["graphenix.executable/v1"]
  └─ modelConfig
       └─ cases[]
            └─ modelConfig: { preActionModel, skillModel, postActionModel }

Missing slots on node override inherit from the selected graph case (same-slot fallback only). See Examples (JSON) above.

Related

| Doc / package | Role | | ------------- | ---- | | GLOSSARY.md | Full phase + strategy + model vocabulary | | @x12i/graphenix-task-node-format | Phase utility strategies (design) | | @x12i/graphenix-plan-format | Resolved slots on compiled plan | | @x12i/graphenix-authoring-format | Composes authoring + task-node + profile validation |