@exellix/graph-composer 2.0.0

package/functions/graph-composer/prompts/shared/request-context.md

@@ -0,0 +1,12 @@
+## Request payload (always read)
+
+- **`intent.description`**: The user’s goal or question for this call. For `explain` and `suggestConceptObjective`, treat it as the angle of emphasis (e.g. “focus on data flow”, “explain branching”) when it adds detail beyond the graph alone. It may contain a **graph concept story** (marker line `# graphConcept story` plus structured `key: value` lines and multiline `|` blocks); the raw text remains authoritative alongside any structured companion field.
+- **`graphConceptFromStory`**: When present on `create`, `modify`, or `reviewConcept` requests (server-parsed from `intent.description`), this object includes **`parsed`**: a JSON object with fields such as `graphType`, `primaryIntentType`, `primaryIntentStatement`, `expectedInput`, `coreTasks` (array of task objects merged from `coreTasks.N.*` keys), `outputDescription`, `persistenceNotes`, etc. Treat **`parsed` plus `intent.description`** together as the product-level spec for the graph (or the expected spec when reviewing). Follow the action-specific instructions when this field appears.
+- **`intent.focusNodeIds`**: When set on `modify` or `explain`, prioritize those nodes (and their edges); still keep the rest consistent or summarized as required by the action.
+- **`constraints`**: Honor `maxNodes`, `requireFinalizer`, `allowConditionalEdges`, and any `executionMemorySchema` hints from the request when building or changing graphs.
+- **`skillMode`**: Governs whether you may introduce new `skillKey` values (see the skill-mode section appended after the catalogs).
+- **`analysisContext`**: When present on `suggestConceptObjective`, treat it as **structured analysis** (execution order, per-node IO, issues, layers, etc.). Prefer it over re-deriving the same facts from scratch when it is consistent with `existingGraph`.
+- **`catalogCandidates`**: When present on `suggestCatalogResolution` / `suggestCatalogCreations`, extra managed-catalog rows from the host (e.g. **Catalox** via `loadCatalogCandidatesFromCatalox`): `aiSkills`, `utilitySkills`, `scopingMaps`, `narrixTemplates`. These extend the inline `aiSkills` / `utilitySkills` arrays for matching.
+- **`catalogMatchHints`**: When present, a server-injected object with optional `skills`, `scoping`, `narrix` entries from `matchLists` pre-pass. Treat as **non-authoritative hints**; reconcile with `existingGraph` and produce your own final recommendations.
+- **`suggestScopingNeedMatch`**: Requires non-empty **`catalogCandidates.scopingMaps`**. **`intent.description`** is the data need. **`existingGraph`** optional.
+- **`scopingNeedMatchHints`**: When present, server-injected `matchLists` result for need → scoping map candidates. **Hints only**; you produce the final `hasSuitableMatch` / `recommended` / `gaps`.

package/functions/graph-composer/prompts/shared/skill-selection.md

@@ -0,0 +1,6 @@
+## Skill selection guidelines
+- Prefer local/deterministic skills for rule evaluation, data lookup, payload assembly, and persistence.
+- Use AI-backed skills for inference, classification, summarization, open-ended analysis, and any task requiring judgment.
+- Never use an AI-backed skill for something a local skill can handle deterministically.
+- When writing `taskVariable.question` for an AI skill, be specific: state what data the skill will receive, what it should analyze, and what shape of answer is expected.
+- Each node should do one thing. If a step requires both data reading and inference, use two nodes.

package/functions/graph-composer/prompts/shared/structural-validation.md

@@ -0,0 +1,19 @@
+## Structural validation rules
+Before returning any graph (create/modify only), verify:
+1. Every edge references existing node ids in `from` and `to`.
+2. Every `executionMemoryPath` in `inputsConfig` or `jobContextMapping` traces to `input.*`, `inputs.*`, or an upstream `executionMapping.path`.
+3. Dynamic task variables use `taskVariable` only. Put `question`, literals, and `$path` refs (`jobVariables.*`, `taskVariables.*`, or legacy `variables.*`) under `taskVariable`; do not place them under `inputsConfig` or deprecated `inputs`.
+4. Every conditional edge's `when.path` traces to a written execution-memory path.
+5. The finalizer's `config.items` reference existing node ids.
+6. No cycles exist.
+7. If `requireFinalizer` is true, at least one finalizer node exists.
+8. If `maxNodes` is set, the total node count does not exceed it.
+9. All `skillKey` values exist in the provided catalog (unless extensible mode is active).
+10. For every **AI task** node, include **`taskConfiguration.aiTaskProfile.preStrategyKey`** and **`postStrategyKey`** (non-empty strings matching deployment PRE/POST strategy catalog row ids). Omit only on local/utility skills.
+11. When **`taskConfiguration.aiTaskProfile.webScoping.enabled`** is `true`, include a non-empty **`webScoping.questions`** array. Do not set `questions` when `enabled` is `false`.
+12. When **`inputSynthesis.enabled`** is `true`, set non-empty **`inputSynthesis.catalogId`**, **`strategyKey`**, **`outputKey`**, **`sources`** (memory paths), and **`destination`** (`job`, `task`, or `execution`). Do not add manual PRE `synthesized-context` steps when profile synthesis is enabled.
+13. Do not author deprecated task-node **`inputs`** or **`outputMapping`** — use **`inputsConfig`** and **`executionMapping`**.
+14. **Narrix** belongs under **`taskConfiguration.narrix`** (`datasetId`, `layer`, `narrativeTypeIds` when needed). Author web questions only under **`taskConfiguration.aiTaskProfile.webScoping`**, not on `narrix`.
+15. **`metadata`** is for planning fields (`graphReadability`, `catalogBinding`, …) only.
+16. Optional **`metadata.catalogBinding`** / **`metadata.catalogRequests`** per product catalog planning.
+17. New graphs should include root **`response`** with `shape` selectors; legacy `metadata.graphResponse` is non-canonical.

package/functions/graph-composer/prompts/skill-catalog-ai-header.md

@@ -0,0 +1,3 @@
+## Available AI skills (call ai-tasks; isLocal: false)
+
+Use **exactly** the `skillKey` strings below when selecting an AI-backed step. Read each skill’s description and schemas to match intent. Prefer an AI skill only when the work needs judgment, language, or unstructured reasoning—otherwise use a utility skill if one fits.

package/functions/graph-composer/prompts/skill-catalog-utility-header.md

@@ -0,0 +1,3 @@
+## Available Utility skills (runtime-local; isLocal: true)
+
+Use **exactly** the `skillKey` strings below for deterministic work (rules, reads/writes, assembly, routing). Prefer these over AI skills whenever the job can be specified as a fixed procedure.

package/functions/graph-composer/prompts/skill-mode-extensible.md

@@ -0,0 +1,7 @@
+## Skill mode: EXTENSIBLE
+
+- Use skills from the **Available AI skills** and **Available Utility skills** lists whenever a reasonable match exists (exact `skillKey` strings).
+- If a step **requires** a capability that no listed skill provides, you may introduce a **new** `skillKey` on that node.
+- For **every** new `skillKey` you use anywhere in the graph, you **must** include one **`requiredSkills`** array entry in the output with **all** of:
+  - `skillKey`, `description`, `expectedInputSchema`, `expectedOutputSchema`, and `rationale` (why no existing skill sufficed).
+- Keep `expectedInputSchema` / `expectedOutputSchema` as concrete JSON Schema–style objects (at least `type`, `properties`, and `required` where applicable) so operators can implement the skill.

package/functions/graph-composer/prompts/skill-mode-locked.md

@@ -0,0 +1,7 @@
+## Skill mode: LOCKED
+
+- You may **only** use `skillKey` values that appear in the **Available AI skills** and **Available Utility skills** sections above (exact string match).
+- If a step is needed but **no listed skill** can reasonably perform it, **do not** invent a `skillKey`. Instead:
+  - Prefer restructuring the graph to approximate the goal with allowed skills, **or**
+  - Omit that step and add a **`warnings`** entry describing the catalog gap and what skill would be needed.
+- Never output a node whose `skillKey` is absent from the provided catalogs.

package/functions/graph-composer/test-cases.json

@@ -0,0 +1,52 @@
+[
+  {
+    "id": "create-simple-linear",
+    "input": {
+      "intent": { "action": "create", "description": "Read a record, classify it, write the result." },
+      "skillMode": "locked",
+      "aiSkills": [
+        { "skillKey": "professional-answer", "description": "Answer a question about a record with structured output", "isLocal": false }
+      ],
+      "utilitySkills": [
+        { "skillKey": "scoped-data-reader", "description": "Read scoped data from storage", "isLocal": true },
+        { "skillKey": "scoped-answer-writer", "description": "Persist assembled answers", "isLocal": true }
+      ],
+      "constraints": { "requireFinalizer": true }
+    }
+  },
+  {
+    "id": "create-branching",
+    "input": {
+      "intent": { "action": "create", "description": "Read a record, decide if web enrichment is needed, if yes enrich then classify, if no classify directly, then finalize." },
+      "skillMode": "locked",
+      "aiSkills": [
+        { "skillKey": "professional-answer", "description": "Classify with structured output", "isLocal": false },
+        { "skillKey": "web-enrich", "description": "Enrich record with web data", "isLocal": false }
+      ],
+      "utilitySkills": [
+        { "skillKey": "scoped-data-reader", "description": "Read scoped data", "isLocal": true },
+        { "skillKey": "deterministic-rule", "description": "Evaluate ordered rules locally", "isLocal": true }
+      ],
+      "constraints": { "requireFinalizer": true, "allowConditionalEdges": true }
+    }
+  },
+  {
+    "id": "modify-add-node",
+    "input": {
+      "intent": { "action": "modify", "description": "Add an exposure-check step between classification and finalization." },
+      "existingGraph": { "id": "test.v1", "nodes": [], "edges": [] },
+      "skillMode": "extensible",
+      "aiSkills": [{ "skillKey": "professional-answer", "description": "Classify", "isLocal": false }],
+      "utilitySkills": []
+    }
+  },
+  {
+    "id": "explain-basic",
+    "input": {
+      "intent": { "action": "explain", "description": "Explain this graph." },
+      "existingGraph": { "id": "test.v1", "nodes": [], "edges": [] },
+      "aiSkills": [],
+      "utilitySkills": []
+    }
+  }
+]

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@exellix/graph-composer",
+  "version": "2.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "LLM-backed worox-graph DAG composer: create, modify, explain, suggestConceptObjective, reviewConcept, catalog resolution/creation, scoping need match and scoping map creation plans, plus optional orchestrator — OpenRouter via @x12i/funcx; catalog rows from @x12i/catalox (loadCatalogCandidatesFromCatalox)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "graph-composer": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "functions",
+    "examples",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"const fs=require('fs'),p=require('path');const s=p.join('node_modules','nx-config2','bin','nx-config2.js'),d=p.join('node_modules','@x12i','env','bin','nx-config2.js');try{if(fs.existsSync(s)&&!fs.existsSync(d))fs.copyFileSync(s,d);}catch(_){}\"",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "start": "x12i-env run --env-file .env -- node dist/cli.js",
+    "run:example": "x12i-env run --env-file .env -- tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "verify:local": "tsx src/verify-local.ts",
+    "verify:catalog-live": "x12i-env run --env-file .env -- tsx scripts/verify-catalog-live.ts",
+    "test": "npm run test:unit && npm run test:live",
+    "test:unit": "node --import tsx/esm --test --test-force-exit test/unit/explain-shape.test.ts test/unit/graph-concept-patch.test.ts test/unit/graph-concept-story-parse.test.ts test/unit/review-concept-output-validation.test.ts test/unit/review-concept-catalog-alias.test.ts test/unit/redact-for-log.test.ts test/unit/worker-instructions.test.ts test/unit/catalog-output-validation.test.ts test/unit/catalox-catalog-bridge.test.ts test/unit/ai-task-profile.test.ts test/unit/create-modify-output-validation.test.ts test/unit/task-node-task-variable.test.ts test/unit/canonical-graph-document.test.ts test/unit/graph-engine-bridge.test.ts test/unit/example-generation.test.ts",
+    "test:live": "x12i-env run --env-file .env -- node --import tsx/esm --test test/live/all.ts",
+    "pack:check": "npm pack --dry-run",
+    "suggest-smoke": "x12i-env run --env-file .env -- tsx scripts/run-suggest-concept-smoke.ts"
+  },
+  "keywords": [
+    "worox",
+    "worox-graph",
+    "dag",
+    "graph",
+    "llm",
+    "openrouter",
+    "funcx"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/woroces/graph-composer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/woroces/graph-composer/issues"
+  },
+  "homepage": "https://github.com/woroces/graph-composer#readme",
+  "peerDependencies": {
+    "@exellix/graph-engine": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@exellix/graph-engine": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@x12i/catalox": "^5.1.1",
+    "@x12i/env": "^4.0.1",
+    "@x12i/funcx": "^4.0.2",
+    "@x12i/logxer": "^4.3.5"
+  },
+  "devDependencies": {
+    "@exellix/graph-engine": "^6.0.0",
+    "@types/node": "^22.10.2",
+    "nx-config2": "^3.6.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}