@x12i/graphenix-executable-profile-format

@x12i/graphenix-executable-profile-format

Phase model profiles for graph-level metadata.modelConfig and per-node taskConfiguration.modelConfig overrides.

Legacy import may still read metadata.extensions["graphenix.executable/v1"] — promote to metadata.modelConfig before persist (authoringGraphToEngineDocument).

profileChoice encoding (persistable authoring): { "kind": "profileChoice", "key": "pro/default" } — bare strings are rejected on persist.

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.modelConfig (cases + triplet) — canonical 2.1.0 persist path
• Legacy import metadata.extensions["graphenix.executable/v1"].modelConfig (extension validation only)
• 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.1.0",
  "id": "graph:example",
  "graph": {
    "nodes": [],
    "edges": [],
    "inputs": [],
    "outputs": [],
    "metadata": {
      "modelConfig": {
        "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