@exellix/graph-composer 2.0.0

package/functions/graph-composer/meta.json

@@ -0,0 +1,607 @@
+{
+  "id": "graph-composer",
+  "status": "draft",
+  "version": "1.0.0",
+  "scoreGate": 0.85,
+  "$defs": {
+    "GraphConceptEntityBindings": {
+      "type": "object",
+      "description": "Lane 1 — xmemory entity collections the graph is about (Intent Map v3)",
+      "properties": {
+        "coreEntityCollectionId": { "type": "string" },
+        "supportingEntityCollectionIds": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "targetEntityCollectionId": { "type": "string" }
+      }
+    },
+    "GraphConceptRequirementsPatch": {
+      "type": "object",
+      "description": "Partial requirements for one coreTask (reviewConcept patch); consumers deep-merge",
+      "properties": {
+        "skill": {
+          "type": "object",
+          "properties": {
+            "skillKey": { "type": "string" },
+            "isLocal": { "type": "boolean" }
+          }
+        },
+        "catalogBinding": { "type": "object" },
+        "strategies": {
+          "type": "object",
+          "description": "PRE/POST ai-task strategy catalog ids",
+          "properties": {
+            "pre": { "type": "array", "items": { "type": "string" } },
+            "post": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "narrix": { "type": "object" },
+        "memoryIO": {
+          "type": "object",
+          "properties": {
+            "reads": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "writes": { "type": "string" },
+            "jobContextMappings": { "type": "object" }
+          }
+        }
+      }
+    },
+    "GraphConceptCoreTaskPatchItem": {
+      "type": "object",
+      "description": "Partial coreTask aligned by index with metadata.graphConcept.coreTasks",
+      "properties": {
+        "taskType": {
+          "enum": ["question", "decision", "action", "objective"],
+          "description": "Sketch step intent type"
+        },
+        "statement": { "type": "string" },
+        "details": { "type": "string" },
+        "sourceFamilyHints": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "planningRunsAfterTaskIndex": {
+          "type": "integer",
+          "minimum": -1,
+          "description": "0-based core task index this follows, or -1 after start; omit for auto"
+        },
+        "stepInputs": {
+          "description": "v3 string path hints or legacy object",
+          "anyOf": [{ "type": "string" }, { "type": "object" }]
+        },
+        "subTasks": {
+          "type": "array",
+          "items": { "type": "object" }
+        },
+        "requirements": {
+          "$ref": "#/$defs/GraphConceptRequirementsPatch"
+        },
+        "webScoping": { "type": "object" },
+        "synthesis": { "type": "object" }
+      }
+    },
+    "RequirementOptionCandidate": {
+      "type": "object",
+      "description": "One ranked option for a requirement field (value and/or rationale)",
+      "properties": {
+        "value": { "type": "string" },
+        "rationale": { "type": "string" },
+        "source": { "type": "string" }
+      }
+    },
+    "RequirementOptionEntry": {
+      "type": "object",
+      "description": "Ambiguous requirement field: candidates and whether a new catalog artifact is needed",
+      "required": ["taskIndex", "field", "candidates", "needsNewArtifact"],
+      "properties": {
+        "taskIndex": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "field": { "type": "string" },
+        "candidates": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/RequirementOptionCandidate" }
+        },
+        "needsNewArtifact": { "type": "boolean" }
+      }
+    },
+    "GraphConceptPatch": {
+      "type": "object",
+      "description": "Merge into graph.metadata.graphConcept (suggestConceptObjective primary fields; reviewConcept may add coreTasks and extended strings)",
+      "properties": {
+        "primaryIntentType": {
+          "enum": ["question", "decision", "action", "objective"],
+          "description": "L1 intent classification for the whole graph"
+        },
+        "primaryIntentStatement": {
+          "type": "string",
+          "description": "One or two product-facing sentences: overall goal"
+        },
+        "businessObjective": { "type": "string" },
+        "primaryOutcome": { "type": "string" },
+        "graphType": { "type": "string" },
+        "expectedInput": { "type": "string" },
+        "outputDescription": { "type": "string" },
+        "persistenceNotes": { "type": "string" },
+        "notes": { "type": "string" },
+        "targetEntityType": { "type": "string" },
+        "decisionType": { "type": "string" },
+        "conceptStatus": {
+          "enum": [
+            "not-started",
+            "generated-draft",
+            "user-refined",
+            "complete"
+          ],
+          "description": "Intent Map v3 concept lifecycle"
+        },
+        "entityBindings": {
+          "$ref": "#/$defs/GraphConceptEntityBindings"
+        },
+        "coreTasks": {
+          "type": "array",
+          "description": "Index-aligned partial core tasks (reviewConcept)",
+          "items": {
+            "anyOf": [
+              { "type": "null" },
+              { "$ref": "#/$defs/GraphConceptCoreTaskPatchItem" }
+            ]
+          }
+        }
+      }
+    },
+    "SkillDescriptor": {
+      "type": "object",
+      "required": ["skillKey", "description"],
+      "properties": {
+        "skillKey": { "type": "string" },
+        "description": { "type": "string" },
+        "isLocal": { "type": "boolean", "default": false },
+        "inputSchema": { "type": "object" },
+        "outputSchema": { "type": "object" },
+        "tags": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "ScopingMapCandidate": {
+      "type": "object",
+      "description": "Scoping map or question-id row from MetaDB or host",
+      "properties": {
+        "scopingMapId": { "type": "string" },
+        "questionId": { "type": "string" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "tags": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "NarrixTemplateCandidate": {
+      "type": "object",
+      "description": "Narrix / discovery-definition template candidate",
+      "properties": {
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "datasetId": { "type": "string" },
+        "layer": { "type": "string" },
+        "narrativeTypeIds": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "enableWebScope": { "type": "boolean" },
+        "tags": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "CatalogCandidates": {
+      "type": "object",
+      "description": "Optional managed-catalog rows; merged with aiSkills/utilitySkills for suggestCatalog*; scopingMaps required for suggestScopingNeedMatch",
+      "properties": {
+        "aiSkills": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SkillDescriptor" }
+        },
+        "utilitySkills": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SkillDescriptor" }
+        },
+        "scopingMaps": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ScopingMapCandidate" }
+        },
+        "narrixTemplates": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/NarrixTemplateCandidate" }
+        }
+      }
+    }
+  },
+  "io": {
+    "input": {
+      "type": "object",
+      "required": ["intent"],
+      "properties": {
+        "intent": {
+          "type": "object",
+          "required": ["action", "description"],
+          "properties": {
+            "action": {
+              "enum": [
+                "create",
+                "modify",
+                "explain",
+                "suggestConceptObjective",
+                "suggestCatalogResolution",
+                "suggestCatalogCreations",
+                "suggestScopingNeedMatch",
+                "suggestScopingMapCreation",
+                "reviewConcept"
+              ]
+            },
+            "description": {
+              "type": "string",
+              "description": "User goal, or a graph concept story: optional marker line `# graphConcept story` plus `key: value` lines and multiline `|` blocks for whole-graph create/modify."
+            },
+            "focusNodeIds": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "For modify/explain — limit scope to these nodes"
+            },
+            "onlyIfEmpty": {
+              "type": "array",
+              "items": {
+                "enum": [
+                  "primaryIntentType",
+                  "primaryIntentStatement",
+                  "businessObjective",
+                  "primaryOutcome"
+                ]
+              },
+              "description": "For suggestConceptObjective — skip patch keys when metadata.graphConcept already has a value"
+            }
+          }
+        },
+        "existingGraph": {
+          "description": "Required for modify, explain, suggestConceptObjective, suggestCatalogResolution, suggestCatalogCreations, reviewConcept. Optional for suggestScopingNeedMatch (context) and suggestScopingMapCreation (alignment).",
+          "type": "object"
+        },
+        "analysisContext": {
+          "type": "object",
+          "description": "Optional graph analysis output (execution order, IO, issues, …). Strongly recommended for suggestConceptObjective, reviewConcept, and suggestCatalog*."
+        },
+        "skillMode": {
+          "enum": ["locked", "extensible"],
+          "default": "locked"
+        },
+        "aiSkills": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SkillDescriptor" },
+          "description": "AI-backed skills (call ai-tasks)"
+        },
+        "utilitySkills": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SkillDescriptor" },
+          "description": "Local/deterministic skills (runtime-intercepted)"
+        },
+        "catalogCandidates": {
+          "$ref": "#/$defs/CatalogCandidates",
+          "description": "Extra catalog rows from worox-graph MetaDB list APIs (or fixtures) for suggestCatalog* and suggestScoping*"
+        },
+        "catalogMatchHints": {
+          "type": "object",
+          "description": "Injected by runGraphWorker when matchLists assist runs; do not set from clients"
+        },
+        "scopingNeedMatchHints": {
+          "type": "object",
+          "description": "Injected by runGraphWorker for suggestScopingNeedMatch matchLists assist; do not set from clients"
+        },
+        "graphConceptFromStory": {
+          "type": "object",
+          "description": "Injected by graph-composer on create/modify/reviewConcept when intent.description matches a graph concept story. Clients normally omit.",
+          "properties": {
+            "parsed": {
+              "type": "object",
+              "description": "Normalized fields (e.g. graphType, primaryIntentStatement, expectedInput, coreTasks array)."
+            }
+          }
+        },
+        "constraints": {
+          "type": "object",
+          "properties": {
+            "maxNodes": { "type": "integer" },
+            "requireFinalizer": { "type": "boolean", "default": true },
+            "allowConditionalEdges": { "type": "boolean", "default": true },
+            "executionMemorySchema": {
+              "type": "object",
+              "description": "Known execution-memory shape to guide outputMapping paths"
+            }
+          }
+        }
+      }
+    },
+    "output": {
+      "type": "object",
+      "required": ["action"],
+      "properties": {
+        "action": {
+          "enum": [
+            "create",
+            "modify",
+            "explain",
+            "suggestConceptObjective",
+            "suggestCatalogResolution",
+            "suggestCatalogCreations",
+            "suggestScopingNeedMatch",
+            "suggestScopingMapCreation",
+            "reviewConcept"
+          ]
+        },
+        "graph": {
+          "type": "object",
+          "description": "Full graph JSON (create) or patched graph JSON (modify). Absent for explain."
+        },
+        "changelog": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "enum": [
+                  "added_node",
+                  "removed_node",
+                  "modified_node",
+                  "added_edge",
+                  "removed_edge",
+                  "modified_edge",
+                  "changed_variable",
+                  "changed_finalizer"
+                ]
+              },
+              "nodeId": { "type": "string" },
+              "summary": { "type": "string" }
+            }
+          },
+          "description": "Present for create and modify"
+        },
+        "explanation": {
+          "type": "object",
+          "properties": {
+            "summary": { "type": "string" },
+            "executionOrder": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Topological node-id sequence (with branching noted)"
+            },
+            "nodeDescriptions": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "nodeId": { "type": "string" },
+                  "role": { "type": "string" },
+                  "reads": { "type": "array", "items": { "type": "string" } },
+                  "writes": { "type": "array", "items": { "type": "string" } }
+                }
+              }
+            },
+            "dataFlow": {
+              "type": "string",
+              "description": "Prose description of how data moves through execution memory"
+            },
+            "conditionalPaths": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "fromNodeId": { "type": "string" },
+                  "branches": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "toNodeId": { "type": "string" },
+                        "condition": { "type": "string" }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "description": "Present for explain"
+        },
+        "graphConceptPatch": {
+          "$ref": "#/$defs/GraphConceptPatch",
+          "description": "Present for suggestConceptObjective; optional for reviewConcept — merge into metadata.graphConcept"
+        },
+        "verdict": {
+          "type": "object",
+          "description": "Present for reviewConcept",
+          "required": ["coherent", "summary"],
+          "properties": {
+            "coherent": { "type": "boolean" },
+            "summary": { "type": "string" }
+          }
+        },
+        "findings": {
+          "type": "array",
+          "description": "Present for reviewConcept — categorized review findings",
+          "items": {
+            "type": "object",
+            "required": ["category", "severity", "summary"],
+            "properties": {
+              "category": { "type": "string" },
+              "severity": { "type": "string" },
+              "summary": { "type": "string" },
+              "taskIndex": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Zero-based index into metadata.graphConcept.coreTasks"
+              },
+              "nodeIds": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "suggestedChange": { "type": "string" },
+              "proposal": {
+                "type": "object",
+                "description": "Optional structured catalog / gap payload (e.g. category catalog)"
+              }
+            }
+          }
+        },
+        "requirementOptions": {
+          "type": "array",
+          "description": "Optional for reviewConcept — ranked candidates per requirement field when inference is ambiguous",
+          "items": { "$ref": "#/$defs/RequirementOptionEntry" }
+        },
+        "suggestedConceptPatch": {
+          "$ref": "#/$defs/GraphConceptPatch",
+          "description": "Optional for reviewConcept — partial patch for metadata.graphConcept (same shape as graphConceptPatch; prefer one key)"
+        },
+        "catalogProposals": {
+          "type": "array",
+          "description": "Optional for reviewConcept — structured catalog-gap proposals when bindings are missing",
+          "items": { "type": "object" }
+        },
+        "suggestedCatalogArtifacts": {
+          "type": "array",
+          "description": "Optional alias for catalogProposals (normalized to catalogProposals before validation)",
+          "items": { "type": "object" }
+        },
+        "skillResolution": {
+          "type": "array",
+          "description": "Present for suggestCatalogResolution",
+          "items": {
+            "type": "object",
+            "required": ["nodeId", "skillKey"],
+            "properties": {
+              "nodeId": { "type": "string" },
+              "skillKey": { "type": "string" },
+              "isLocal": { "type": "boolean" },
+              "confidence": { "type": "string" },
+              "rationale": { "type": "string" }
+            }
+          }
+        },
+        "scopingResolution": {
+          "type": "array",
+          "description": "Present for suggestCatalogResolution",
+          "items": { "type": "object" }
+        },
+        "narrixResolution": {
+          "type": "array",
+          "description": "Present for suggestCatalogResolution",
+          "items": { "type": "object" }
+        },
+        "gaps": {
+          "type": "array",
+          "description": "Present for suggestCatalogResolution — missing catalog coverage",
+          "items": {
+            "type": "object",
+            "required": ["kind", "summary"],
+            "properties": {
+              "kind": { "type": "string" },
+              "summary": { "type": "string" },
+              "suggestedRequestedId": { "type": "string" }
+            }
+          }
+        },
+        "catalogRequestProposals": {
+          "type": "array",
+          "description": "Present for suggestCatalogCreations — merge into graph.metadata.catalogRequests after MetaDB CRUD",
+          "items": {
+            "type": "object",
+            "required": ["catalogType", "requestedId"],
+            "properties": {
+              "catalogType": { "type": "string" },
+              "requestedId": { "type": "string" },
+              "status": { "type": "string" },
+              "reason": { "type": "string" },
+              "title": { "type": "string" },
+              "purpose": { "type": "string" },
+              "datasetId": { "type": "string" },
+              "layer": { "type": "string" },
+              "narrativeTypeIds": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "enableWebScope": { "type": "boolean" }
+            }
+          }
+        },
+        "newSkillDescriptors": {
+          "type": "array",
+          "description": "Optional for suggestCatalogCreations",
+          "items": { "$ref": "#/$defs/SkillDescriptor" }
+        },
+        "hasSuitableMatch": {
+          "type": "boolean",
+          "description": "Present for suggestScopingNeedMatch"
+        },
+        "recommended": {
+          "description": "Present for suggestScopingNeedMatch — object with scopingMapId and/or questionId when hasSuitableMatch; null otherwise",
+          "oneOf": [{ "type": "object" }, { "type": "null" }]
+        },
+        "alternatives": {
+          "type": "array",
+          "description": "Optional runners-up for suggestScopingNeedMatch",
+          "items": { "type": "object" }
+        },
+        "scopingMapProposal": {
+          "type": "object",
+          "description": "Present for suggestScopingMapCreation",
+          "required": [
+            "suggestedScopingMapId",
+            "title",
+            "purpose"
+          ],
+          "properties": {
+            "suggestedScopingMapId": { "type": "string" },
+            "title": { "type": "string" },
+            "purpose": { "type": "string" },
+            "questionTitle": { "type": "string" },
+            "asks": { "type": "string" },
+            "entityIdPath": { "type": "string" },
+            "expectedFieldPaths": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "rationale": {
+          "type": "string",
+          "description": "Optional note for UI/logs (suggest* and catalog actions)"
+        },
+        "requiredSkills": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "skillKey",
+              "description",
+              "expectedInputSchema",
+              "expectedOutputSchema"
+            ],
+            "properties": {
+              "skillKey": { "type": "string" },
+              "description": { "type": "string" },
+              "expectedInputSchema": { "type": "object" },
+              "expectedOutputSchema": { "type": "object" },
+              "rationale": { "type": "string" }
+            }
+          },
+          "description": "Only present when skillMode=extensible and the LLM needed skills not in the provided lists"
+        },
+        "warnings": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Structural warnings: orphan nodes, missing edges, unmapped outputs, etc."
+        }
+      }
+    }
+  }
+}

package/functions/graph-composer/prompts/README.md

@@ -0,0 +1,46 @@
+# graph-composer prompts & templates
+
+All **editable** instruction text and judge rules for this function pack live here. Runtime code loads these files from the published `functions/graph-composer/` tree.
+
+## Per-action workers
+
+Each **`intent.action`** maps to one **worker prompt file** plus optional **shared** fragments (see [`src/graphComposerActions.ts`](../../../src/graphComposerActions.ts) — the action registry is the source of truth).
+
+| Path | Role |
+|------|------|
+| `shared/request-context.md` | How to read `intent`, `constraints`, `analysisContext`, etc. |
+| `shared/graph-format.md` | worox-graph JSON shapes, execution memory, edges, finalizer |
+| `shared/skill-selection.md` | How to pick catalog skills |
+| `shared/structural-validation.md` | Checks before returning a graph (create/modify) |
+| `action-create.md` | Worker for `create` only |
+| `action-modify.md` | Worker for `modify` only |
+| `action-explain.md` | Worker for `explain` only |
+| `action-suggest-concept-objective.md` | Worker for `suggestConceptObjective` only |
+| `action-review-concept.md` | Worker for `reviewConcept` only (concept review, no graph JSON) |
+| `orchestrator-system.md` | System prompt for `runGraphComposerAgent` (tool loop) |
+
+## Appended for every worker
+
+| File | Role |
+|------|------|
+| `skill-mode-locked.md` | Appended when `skillMode` is `locked`. |
+| `skill-mode-extensible.md` | Appended when `skillMode` is `extensible`. |
+| `skill-catalog-ai-header.md` | Heading before injected AI skill list. |
+| `skill-catalog-utility-header.md` | Heading before utility (local) skill list. |
+| `judge-rules.md` | Human-readable doc; **weighted rules** for aifunctions-js (function-pack LLM call) live in the first fenced JSON block. |
+| `default-utility-skills.json` | Default utility catalog when the request omits `utilitySkills`. |
+
+Pack root (sibling of this folder) still holds `meta.json` and `test-cases.json`.
+
+Legacy rules fallbacks: root-level `rules.json` or `rules` — see `loadRules` in `src/runGraphComposer.ts`.
+
+---
+
+## Adding a new graph action
+
+1. **`src/types.ts`**: Extend `GraphComposerIntent["action"]` with the new literal.
+2. **`src/graphComposerActions.ts`**: Add a registry row (`action`, `promptFile`, `sharedIncludes`, `requiresExistingGraph`, `toolName`, `toolDescription`, `validateOutput`).
+3. **`functions/graph-composer/prompts/`**: Add `action-<kebab>.md` (path must match `promptFile`) and any new `shared/*.md` fragments.
+4. **`functions/graph-composer/meta.json`**: Extend `io.input` / `io.output` enums and shapes.
+5. **Tests**: Unit coverage for composition + validation; add or extend a live smoke test when the action is LLM-backed.
+6. **`npm run verify:local`**: Must stay green (required files are derived from the registry).