@exellix/graph-composer 2.0.0

package/dist/catalogMatchAssist.d.ts

@@ -0,0 +1,20 @@
+import type { Client } from "@x12i/funcx";
+import type { LlmMode } from "@x12i/funcx/functions";
+import type { GraphComposerInput, SkillDescriptor } from "./types.js";
+export type CatalogMatchAssistOptions = {
+    client: Client;
+    mode?: LlmMode;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+};
+/**
+ * When `catalogCandidates` is set and lists are non-empty, runs `matchLists` per dimension
+ * and returns a compact object to inject into the worker prompt as `catalogMatchHints`.
+ */
+export declare function buildCatalogMatchHints(input: GraphComposerInput & {
+    skillMode: "locked" | "extensible";
+    aiSkills: SkillDescriptor[];
+    utilitySkills: SkillDescriptor[];
+}, opts: CatalogMatchAssistOptions): Promise<Record<string, unknown> | undefined>;
+//# sourceMappingURL=catalogMatchAssist.d.ts.map

package/dist/catalogMatchAssist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogMatchAssist.d.ts","sourceRoot":"","sources":["../src/catalogMatchAssist.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAEV,kBAAkB,EAGlB,eAAe,EAChB,MAAM,YAAY,CAAC;AAgKpB,MAAM,MAAM,yBAAyB,GAAG;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,kBAAkB,GAAG;IAC1B,SAAS,EAAE,QAAQ,GAAG,YAAY,CAAC;IACnC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,aAAa,EAAE,eAAe,EAAE,CAAC;CAClC,EACD,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAqF9C"}

package/dist/catalogMatchAssist.js

@@ -0,0 +1,203 @@
+import { matchLists } from "@x12i/funcx/functions";
+function mergeBySkillKey(a, b) {
+    if (!b?.length)
+        return [...a];
+    const seen = new Set(a.map((s) => s.skillKey));
+    const out = [...a];
+    for (const s of b) {
+        if (!seen.has(s.skillKey)) {
+            seen.add(s.skillKey);
+            out.push(s);
+        }
+    }
+    return out;
+}
+function taskNodesFromGraph(graph) {
+    const g = graph;
+    const nodes = g.nodes;
+    if (!Array.isArray(nodes))
+        return [];
+    return nodes.filter((n) => n !== null && typeof n === "object" && !Array.isArray(n) && n.type === "task");
+}
+function nodeSkillSummary(node) {
+    const id = typeof node.id === "string" ? node.id : "(no-id)";
+    const skillKey = typeof node.skillKey === "string" ? node.skillKey : undefined;
+    const meta = node.metadata !== null &&
+        node.metadata !== undefined &&
+        typeof node.metadata === "object" &&
+        !Array.isArray(node.metadata)
+        ? node.metadata
+        : undefined;
+    const gr = meta?.graphReadability !== null &&
+        meta?.graphReadability !== undefined &&
+        typeof meta.graphReadability === "object" &&
+        !Array.isArray(meta.graphReadability)
+        ? meta.graphReadability
+        : undefined;
+    const title = typeof gr?.title === "string" ? gr.title : undefined;
+    const asks = typeof gr?.asks === "string" ? gr.asks : undefined;
+    const kind = typeof gr?.kind === "string" ? gr.kind : undefined;
+    return {
+        nodeId: id,
+        currentSkillKey: skillKey,
+        title,
+        asks,
+        graphReadabilityKind: kind,
+    };
+}
+function scopingNodeSummary(node) {
+    const meta = node.metadata !== null &&
+        node.metadata !== undefined &&
+        typeof node.metadata === "object" &&
+        !Array.isArray(node.metadata)
+        ? node.metadata
+        : undefined;
+    const skillKey = typeof node.skillKey === "string" ? node.skillKey : undefined;
+    const usesScoped = skillKey === "scoped-data-reader" ||
+        skillKey === "scoped-answer-writer" ||
+        typeof meta?.scopingMapId === "string" ||
+        typeof meta?.questionId === "string";
+    if (!usesScoped)
+        return null;
+    const id = typeof node.id === "string" ? node.id : "(no-id)";
+    const gr = meta?.graphReadability !== null &&
+        meta?.graphReadability !== undefined &&
+        typeof meta.graphReadability === "object" &&
+        !Array.isArray(meta.graphReadability)
+        ? meta.graphReadability
+        : undefined;
+    return {
+        nodeId: id,
+        skillKey,
+        title: typeof gr?.title === "string" ? gr.title : undefined,
+        asks: typeof gr?.asks === "string" ? gr.asks : undefined,
+        scopingMapId: typeof meta?.scopingMapId === "string" ? meta.scopingMapId : undefined,
+        questionId: typeof meta?.questionId === "string" ? meta.questionId : undefined,
+        entityIdPath: typeof meta?.entityIdPath === "string" ? meta.entityIdPath : undefined,
+    };
+}
+function narrixNodeSummary(node) {
+    const meta = node.metadata !== null &&
+        node.metadata !== undefined &&
+        typeof node.metadata === "object" &&
+        !Array.isArray(node.metadata)
+        ? node.metadata
+        : undefined;
+    if (!meta?.narrix)
+        return null;
+    const narrix = meta.narrix;
+    if (narrix === null ||
+        typeof narrix !== "object" ||
+        Array.isArray(narrix)) {
+        return null;
+    }
+    const n = narrix;
+    const id = typeof node.id === "string" ? node.id : "(no-id)";
+    const skillKey = typeof node.skillKey === "string" ? node.skillKey : undefined;
+    return {
+        nodeId: id,
+        skillKey,
+        narrix: {
+            datasetId: n.datasetId,
+            layer: n.layer,
+            enableWebScope: n.enableWebScope,
+            narrativeTypeIds: n.narrativeTypeIds,
+        },
+    };
+}
+function skillCatalogItems(skills) {
+    return skills.map((s) => ({
+        skillKey: s.skillKey,
+        description: s.description,
+        isLocal: s.isLocal ?? false,
+        tags: s.tags ?? [],
+    }));
+}
+function scopingCatalogItems(maps) {
+    return maps.map((m) => ({
+        scopingMapId: m.scopingMapId,
+        questionId: m.questionId,
+        title: m.title,
+        description: m.description,
+        tags: m.tags ?? [],
+    }));
+}
+function narrixCatalogItems(templates) {
+    return templates.map((t) => ({
+        id: t.id,
+        title: t.title,
+        description: t.description,
+        datasetId: t.datasetId,
+        layer: t.layer,
+        narrativeTypeIds: t.narrativeTypeIds ?? [],
+        enableWebScope: t.enableWebScope ?? false,
+        tags: t.tags ?? [],
+    }));
+}
+/**
+ * When `catalogCandidates` is set and lists are non-empty, runs `matchLists` per dimension
+ * and returns a compact object to inject into the worker prompt as `catalogMatchHints`.
+ */
+export async function buildCatalogMatchHints(input, opts) {
+    const cc = input.catalogCandidates;
+    if (!cc ||
+        (input.intent.action !== "suggestCatalogResolution" &&
+            input.intent.action !== "suggestCatalogCreations")) {
+        return undefined;
+    }
+    const existingGraph = input.existingGraph;
+    if (existingGraph === undefined ||
+        existingGraph === null ||
+        typeof existingGraph !== "object") {
+        return undefined;
+    }
+    const hints = {};
+    const { client, mode, model } = opts;
+    const aiMerged = mergeBySkillKey(input.aiSkills, cc.aiSkills);
+    const utilMerged = mergeBySkillKey(input.utilitySkills, cc.utilitySkills);
+    const allSkills = [...utilMerged, ...aiMerged];
+    const taskNodes = taskNodesFromGraph(existingGraph);
+    const nodeSummaries = taskNodes.map(nodeSkillSummary);
+    if (nodeSummaries.length > 0 && allSkills.length > 0) {
+        const r = await matchLists({
+            list1: nodeSummaries,
+            list2: skillCatalogItems(allSkills),
+            guidance: "Match each graph task node to the single best catalog skillKey by operational role (data read, rules, LLM, scoped IO, assembly). Prefer local/utility skills for deterministic work. Use reason briefly.",
+            mode,
+            client,
+            model,
+        }, { rules: [] });
+        hints.skills = { matches: r.matches, unmatched: r.unmatched };
+    }
+    const scopingNodes = taskNodes
+        .map(scopingNodeSummary)
+        .filter((x) => x !== null);
+    const scopingMaps = cc.scopingMaps ?? [];
+    if (scopingNodes.length > 0 && scopingMaps.length > 0) {
+        const r = await matchLists({
+            list1: scopingNodes,
+            list2: scopingCatalogItems(scopingMaps),
+            guidance: "Match each scoped-data or scoping-related node to the best scopingMapId or questionId candidate by what the node reads/asks and entity scope. reason briefly.",
+            mode,
+            client,
+            model,
+        }, { rules: [] });
+        hints.scoping = { matches: r.matches, unmatched: r.unmatched };
+    }
+    const narrixNodes = taskNodes
+        .map(narrixNodeSummary)
+        .filter((x) => x !== null);
+    const narrixTemplates = cc.narrixTemplates ?? [];
+    if (narrixNodes.length > 0 && narrixTemplates.length > 0) {
+        const r = await matchLists({
+            list1: narrixNodes,
+            list2: narrixCatalogItems(narrixTemplates),
+            guidance: "Match each node that has metadata.narrix to the best narrix template candidate (layer, datasetId, narrativeTypeIds, web scope). reason briefly.",
+            mode,
+            client,
+            model,
+        }, { rules: [] });
+        hints.narrix = { matches: r.matches, unmatched: r.unmatched };
+    }
+    return Object.keys(hints).length > 0 ? hints : undefined;
+}

package/dist/cataloxCatalogBridge.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Load {@link CatalogCandidates} from Catalox (`listCatalogItems`, or optional
+ * {@link CataloxCatalogBridgeOptions.aiItemMatch}: pool rows via Catalox, then rank by relevance with **funcx** `rank` — no Catalox search API).
+ * Hosts construct {@link Catalox} via `createCatalox`
+ * from `@x12i/catalox/embedder` and pass `CataloxContext` (with **@x12i/catalox** ≥ 3.4.6,
+ * `appId` may be omitted for catalog-id-first flows when your deployment allows it).
+ *
+ * **Catalog IDs are caller-supplied** — this package does not hardcode your
+ * Firestore `catalogId` strings. Use {@link CataloxCatalogBridgeCatalogIds} to
+ * map your Catalox catalogs into the four `CatalogCandidates` slices (see
+ * `docs/catalog-metadb-end-state-contract.md` for a reference mapping table).
+ */
+import type { Catalox } from "@x12i/catalox/embedder";
+import type { CataloxContext, CatalogQueryOptions, UnifiedCatalogItem } from "@x12i/catalox/embedder";
+import type { Client } from "@x12i/funcx";
+import type { LlmMode } from "@x12i/funcx/functions";
+import type { CatalogCandidates, NarrixTemplateCandidate, ScopingMapCandidate, SkillDescriptor } from "./types.js";
+/**
+ * Which Catalox `catalogId` to read for each optional fetch. Several keys
+ * merge into the same `CatalogCandidates` slice (e.g. pre/post strategy catalogs
+ * both become `aiSkills`).
+ */
+export type CataloxCatalogBridgeCatalogIds = {
+    /** e.g. `ai-skills` → {@link CatalogCandidates.aiSkills} */
+    aiSkills?: string;
+    /** e.g. `ai-tasks-strategies-pre` → merged into `aiSkills` after `aiSkills`. */
+    aiTasksStrategiesPre?: string;
+    /** e.g. `ai-tasks-strategies-post` → merged into `aiSkills` after pre. */
+    aiTasksStrategiesPost?: string;
+    /**
+     * Synthesis **mode** catalog (PRE-style rows) → merged into `aiSkills` after post.
+     * Node `metadata.aiTaskProfile.inputSynthesis.catalogId` should match this id when using that catalog.
+     */
+    inputSynthesisModes?: string;
+    utilitySkills?: string;
+    /** Legacy single scoping catalog; merged first into `scopingMaps`. */
+    scopingMaps?: string;
+    /** e.g. `xmemory.scopingQuestions` → merged into `scopingMaps`. */
+    xmemoryScopingQuestions?: string;
+    /** e.g. `xmemory.entity-collections` → merged into `scopingMaps`. */
+    xmemoryEntityCollections?: string;
+    narrixTemplates?: string;
+    /** Alias for Catalox catalog id `narratives` (same slice as `narrixTemplates`). */
+    narratives?: string;
+};
+export type CataloxCatalogBridgeListOptions = Partial<Record<keyof CataloxCatalogBridgeCatalogIds, CatalogQueryOptions | undefined>>;
+/**
+ * Semantic narrowing: Catalox supplies a **candidate pool** (`listCatalogItems` with `poolLimit`),
+ * then **@x12i/funcx** `rank` scores items against `query`. Catalox search APIs are not used.
+ *
+ * `temperature`, `maxTokens`, and `timeoutMs` are reserved for future funcx wiring; `rank` currently uses its defaults.
+ */
+export type CataloxCatalogBridgeAiItemMatch = {
+    query: string;
+    maxResultsPerSlice?: number;
+    /** Drop ranked rows below this score (0–1). If every row fails, the slice is empty. */
+    minScore?: number;
+    /** Max rows pulled from Catalox before ranking (default 200). */
+    poolLimit?: number;
+    mode?: LlmMode;
+    /** Required: OpenRouter-backed funcx client (same as graph-composer workers). */
+    client: Client;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+};
+/**
+ * Optional **per-bridge-key** Catalox context for multi-app deployments: each
+ * `catalogId` may be bound under a different `appId` than your default service app.
+ * When omitted for a key, the **base** `context` passed to {@link loadCatalogCandidatesFromCatalox} is used.
+ */
+export type CataloxCatalogBridgeContextByKey = Partial<Record<keyof CataloxCatalogBridgeCatalogIds, CataloxContext>>;
+export type CataloxCatalogBridgeOptions = {
+    catalogIds: CataloxCatalogBridgeCatalogIds;
+    listOptions?: CataloxCatalogBridgeListOptions;
+    /** When set, lists a capped pool per catalog, then ranks with funcx using {@link CataloxCatalogBridgeAiItemMatch.query}. */
+    aiItemMatch?: CataloxCatalogBridgeAiItemMatch;
+    /**
+     * Pin `CataloxContext` per bridge fetch (e.g. `aiSkills` under the `ai-skills` app,
+     * PRE/POST under `ai-tasks`). See `docs/catalox-multi-app-context.md`.
+     */
+    contextByBridgeKey?: CataloxCatalogBridgeContextByKey;
+};
+/**
+ * Map a Catalox row to {@link SkillDescriptor} (AI or utility catalog).
+ * Reads `data.skillKey` / `data.key` / `itemId`, then description from `data.description`, subtitle, or title.
+ */
+export declare function unifiedCatalogItemToSkillDescriptor(item: UnifiedCatalogItem): SkillDescriptor;
+/**
+ * Map a Catalox row to {@link ScopingMapCandidate} (expects `data` fields aligned with your descriptor).
+ */
+export declare function unifiedCatalogItemToScopingMapCandidate(item: UnifiedCatalogItem): ScopingMapCandidate;
+/**
+ * Map a Catalox row to {@link NarrixTemplateCandidate}.
+ */
+export declare function unifiedCatalogItemToNarrixTemplateCandidate(item: UnifiedCatalogItem): NarrixTemplateCandidate;
+/**
+ * Fetches configured Catalox catalogs and returns a {@link CatalogCandidates} object
+ * suitable for `GraphComposerInput.catalogCandidates`.
+ */
+export declare function loadCatalogCandidatesFromCatalox(catalox: Catalox, context: CataloxContext, options: CataloxCatalogBridgeOptions): Promise<CatalogCandidates>;
+//# sourceMappingURL=cataloxCatalogBridge.d.ts.map

package/dist/cataloxCatalogBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cataloxCatalogBridge.d.ts","sourceRoot":"","sources":["../src/cataloxCatalogBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EACV,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,qEAAqE;IACrE,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,OAAO,CACnD,MAAM,CAAC,MAAM,8BAA8B,EAAE,mBAAmB,GAAG,SAAS,CAAC,CAC9E,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gCAAgC,GAAG,OAAO,CACpD,MAAM,CAAC,MAAM,8BAA8B,EAAE,cAAc,CAAC,CAC7D,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,UAAU,EAAE,8BAA8B,CAAC;IAC3C,WAAW,CAAC,EAAE,+BAA+B,CAAC;IAC9C,4HAA4H;IAC5H,WAAW,CAAC,EAAE,+BAA+B,CAAC;IAC9C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,gCAAgC,CAAC;CACvD,CAAC;AA2FF;;;GAGG;AACH,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,kBAAkB,GACvB,eAAe,CAwBjB;AAED;;GAEG;AACH,wBAAgB,uCAAuC,CACrD,IAAI,EAAE,kBAAkB,GACvB,mBAAmB,CASrB;AAED;;GAEG;AACH,wBAAgB,2CAA2C,CACzD,IAAI,EAAE,kBAAkB,GACvB,uBAAuB,CAYzB;AA2CD;;;GAGG;AACH,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAyF5B"}

package/dist/cataloxCatalogBridge.js

@@ -0,0 +1,222 @@
+import { rank } from "@x12i/funcx/functions";
+function resolveBridgeContext(bridgeKey, baseContext, options) {
+    const pin = options.contextByBridgeKey?.[bridgeKey];
+    return pin ?? baseContext;
+}
+function pickStr(v) {
+    return typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+}
+function pickStrArray(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = v.filter((x) => typeof x === "string" && x.trim().length > 0);
+    return out.length > 0 ? out : undefined;
+}
+function pickBool(v) {
+    return typeof v === "boolean" ? v : undefined;
+}
+const DEFAULT_AI_POOL_LIMIT = 200;
+function compactUnifiedItemForRank(item) {
+    const d = item.data ?? {};
+    return {
+        itemId: String(item.itemId),
+        title: item.title,
+        subtitle: item.subtitle,
+        skillKey: pickStr(d.skillKey) ?? pickStr(d.key),
+        description: pickStr(d.description),
+        id: pickStr(d.id),
+        scopingMapId: pickStr(d.scopingMapId) ?? pickStr(d.scoping_map_id),
+        questionId: pickStr(d.questionId) ?? pickStr(d.question_id),
+        datasetId: pickStr(d.datasetId) ?? pickStr(d.dataset_id),
+        layer: pickStr(d.layer),
+        tags: pickStrArray(d.tags),
+    };
+}
+async function rankCatalogPoolWithFuncx(pool, ai) {
+    if (pool.length === 0)
+        return [];
+    const payloads = pool.map((it) => compactUnifiedItemForRank(it));
+    const ranked = await rank({
+        items: payloads,
+        query: ai.query,
+        mode: ai.mode ?? "normal",
+        client: ai.client,
+        model: ai.model,
+    }, { rules: [] });
+    const byId = new Map(pool.map((it) => [String(it.itemId), it]));
+    const raw = ranked.rankedItems;
+    if (!Array.isArray(raw))
+        return [];
+    const scored = raw
+        .map((row) => {
+        const payload = row?.item;
+        const id = payload && typeof payload.itemId === "string" ? payload.itemId : undefined;
+        const score = typeof row?.score === "number" ? row.score : 0;
+        return id !== undefined ? { id, score } : null;
+    })
+        .filter((x) => x !== null)
+        .sort((a, b) => b.score - a.score);
+    const maxN = ai.maxResultsPerSlice ?? 50;
+    const min = ai.minScore;
+    const out = [];
+    const seen = new Set();
+    for (const row of scored) {
+        if (out.length >= maxN)
+            break;
+        if (min !== undefined && row.score < min)
+            continue;
+        const full = byId.get(row.id);
+        if (full && !seen.has(row.id)) {
+            seen.add(row.id);
+            out.push(full);
+        }
+    }
+    return out;
+}
+/**
+ * Map a Catalox row to {@link SkillDescriptor} (AI or utility catalog).
+ * Reads `data.skillKey` / `data.key` / `itemId`, then description from `data.description`, subtitle, or title.
+ */
+export function unifiedCatalogItemToSkillDescriptor(item) {
+    const d = item.data ?? {};
+    const skillKey = pickStr(d.skillKey) ??
+        pickStr(d.key) ??
+        pickStr(d.id) ??
+        String(item.itemId);
+    const description = pickStr(d.description) ??
+        item.subtitle ??
+        item.title ??
+        skillKey;
+    const isLocal = pickBool(d.isLocal);
+    const tags = pickStrArray(d.tags);
+    const out = { skillKey, description };
+    if (isLocal !== undefined)
+        out.isLocal = isLocal;
+    if (tags !== undefined)
+        out.tags = tags;
+    if (typeof d.inputSchema === "object" && d.inputSchema !== null && !Array.isArray(d.inputSchema)) {
+        out.inputSchema = d.inputSchema;
+    }
+    if (typeof d.outputSchema === "object" && d.outputSchema !== null && !Array.isArray(d.outputSchema)) {
+        out.outputSchema = d.outputSchema;
+    }
+    return out;
+}
+/**
+ * Map a Catalox row to {@link ScopingMapCandidate} (expects `data` fields aligned with your descriptor).
+ */
+export function unifiedCatalogItemToScopingMapCandidate(item) {
+    const d = item.data ?? {};
+    return {
+        scopingMapId: pickStr(d.scopingMapId) ?? pickStr(d.scoping_map_id),
+        questionId: pickStr(d.questionId) ?? pickStr(d.question_id),
+        title: item.title ?? pickStr(d.title),
+        description: pickStr(d.description) ?? item.subtitle,
+        tags: pickStrArray(d.tags),
+    };
+}
+/**
+ * Map a Catalox row to {@link NarrixTemplateCandidate}.
+ */
+export function unifiedCatalogItemToNarrixTemplateCandidate(item) {
+    const d = item.data ?? {};
+    return {
+        id: pickStr(d.id) ?? String(item.itemId),
+        title: item.title ?? pickStr(d.title),
+        description: pickStr(d.description) ?? item.subtitle,
+        datasetId: pickStr(d.datasetId) ?? pickStr(d.dataset_id),
+        layer: pickStr(d.layer),
+        narrativeTypeIds: pickStrArray(d.narrativeTypeIds) ?? pickStrArray(d.narrative_type_ids),
+        enableWebScope: pickBool(d.enableWebScope) ?? pickBool(d.enable_web_scope),
+        tags: pickStrArray(d.tags),
+    };
+}
+async function listItemsForCatalog(catalox, context, catalogId, listOptions, ai) {
+    if (ai !== undefined) {
+        const poolLimit = ai.poolLimit ?? listOptions?.limit ?? DEFAULT_AI_POOL_LIMIT;
+        const poolOpts = {
+            ...listOptions,
+            limit: poolLimit,
+        };
+        const list = await catalox.listCatalogItems(context, catalogId, poolOpts);
+        if (list.listOutcome === "mapping_blocked") {
+            const msg = (list.issues ?? [])
+                .map((i) => i.message ?? String(i))
+                .join("; ");
+            throw new Error(`Catalox listCatalogItems mapping_blocked for catalog "${catalogId}" (AI pool)${msg ? `: ${msg}` : ""}`);
+        }
+        return rankCatalogPoolWithFuncx(list.items, ai);
+    }
+    const list = await catalox.listCatalogItems(context, catalogId, listOptions);
+    if (list.listOutcome === "mapping_blocked") {
+        const msg = (list.issues ?? [])
+            .map((i) => i.message ?? String(i))
+            .join("; ");
+        throw new Error(`Catalox listCatalogItems mapping_blocked for catalog "${catalogId}"${msg ? `: ${msg}` : ""}`);
+    }
+    return list.items;
+}
+function nonemptyCatalogId(id) {
+    return id !== undefined && id !== "";
+}
+/**
+ * Fetches configured Catalox catalogs and returns a {@link CatalogCandidates} object
+ * suitable for `GraphComposerInput.catalogCandidates`.
+ */
+export async function loadCatalogCandidatesFromCatalox(catalox, context, options) {
+    const { catalogIds, listOptions, aiItemMatch } = options;
+    const out = {};
+    const aiSkillCatalogs = [
+        "aiSkills",
+        "aiTasksStrategiesPre",
+        "aiTasksStrategiesPost",
+        "inputSynthesisModes",
+    ];
+    const skillRows = [];
+    for (const key of aiSkillCatalogs) {
+        const id = catalogIds[key];
+        if (!nonemptyCatalogId(id))
+            continue;
+        const items = await listItemsForCatalog(catalox, resolveBridgeContext(key, context, options), id, listOptions?.[key], aiItemMatch);
+        skillRows.push(...items.map((i) => unifiedCatalogItemToSkillDescriptor(i)));
+    }
+    if (skillRows.length > 0) {
+        out.aiSkills = skillRows;
+    }
+    if (nonemptyCatalogId(catalogIds.utilitySkills)) {
+        const key = "utilitySkills";
+        const items = await listItemsForCatalog(catalox, resolveBridgeContext(key, context, options), catalogIds.utilitySkills, listOptions?.utilitySkills, aiItemMatch);
+        out.utilitySkills = items.map((i) => unifiedCatalogItemToSkillDescriptor(i));
+    }
+    const scopingCatalogs = [
+        "scopingMaps",
+        "xmemoryScopingQuestions",
+        "xmemoryEntityCollections",
+    ];
+    const scopingRows = [];
+    for (const key of scopingCatalogs) {
+        const id = catalogIds[key];
+        if (!nonemptyCatalogId(id))
+            continue;
+        const items = await listItemsForCatalog(catalox, resolveBridgeContext(key, context, options), id, listOptions?.[key], aiItemMatch);
+        scopingRows.push(...items.map((i) => unifiedCatalogItemToScopingMapCandidate(i)));
+    }
+    if (scopingRows.length > 0) {
+        out.scopingMaps = scopingRows;
+    }
+    const narrixParts = [];
+    if (nonemptyCatalogId(catalogIds.narrixTemplates)) {
+        const key = "narrixTemplates";
+        const items = await listItemsForCatalog(catalox, resolveBridgeContext(key, context, options), catalogIds.narrixTemplates, listOptions?.narrixTemplates, aiItemMatch);
+        narrixParts.push(items.map((i) => unifiedCatalogItemToNarrixTemplateCandidate(i)));
+    }
+    if (nonemptyCatalogId(catalogIds.narratives)) {
+        const key = "narratives";
+        const items = await listItemsForCatalog(catalox, resolveBridgeContext(key, context, options), catalogIds.narratives, listOptions?.narratives, aiItemMatch);
+        narrixParts.push(items.map((i) => unifiedCatalogItemToNarrixTemplateCandidate(i)));
+    }
+    if (narrixParts.length > 0) {
+        out.narrixTemplates = narrixParts.flat();
+    }
+    return out;
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * CLI: runs one graph-composer case against OpenRouter.
+ * - Positional args `network-vuln` / `network-vuln-intent` are **demo smoke** entrypoints (bundled sample graph), not the core library API.
+ * - Prefer constructing `GraphComposerInput` in application code or using `test-cases.json` ids for fixtures.
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runGraphComposer } from "./runGraphComposer.js";
+import { inputExplainNetworkVulnSubnet, inputSuggestConceptObjectiveNetworkVulnSubnet, } from "./exampleInputs.js";
+const repoRoot = path.join(fileURLToPath(new URL("..", import.meta.url)));
+const testCasesPath = path.join(repoRoot, "functions", "graph-composer", "test-cases.json");
+function loadTestCase(id) {
+    const raw = readFileSync(testCasesPath, "utf-8");
+    const cases = JSON.parse(raw);
+    const found = cases.find((c) => c.id === id);
+    if (!found) {
+        const ids = cases.map((c) => c.id).join(", ");
+        throw new Error(`Unknown test case "${id}". Known: ${ids}`);
+    }
+    return found.input;
+}
+const arg = process.argv[2] ?? process.env.GRAPH_COMPOSER_TEST_CASE ?? "explain-basic";
+const input = arg === "network-vuln"
+    ? inputExplainNetworkVulnSubnet()
+    : arg === "network-vuln-intent"
+        ? inputSuggestConceptObjectiveNetworkVulnSubnet()
+        : loadTestCase(arg);
+const result = await runGraphComposer(input, arg === "network-vuln"
+    ? {
+        askTimeoutMs: 180_000,
+        connectTimeoutMs: 60_000,
+        maxTokens: 16384,
+    }
+    : arg === "network-vuln-intent"
+        ? {
+            askTimeoutMs: 180_000,
+            connectTimeoutMs: 60_000,
+            maxTokens: 8192,
+        }
+        : { askTimeoutMs: 180_000, connectTimeoutMs: 60_000 });
+console.log(JSON.stringify(result, null, 2));

package/dist/composeInstructions.d.ts

@@ -0,0 +1,11 @@
+import type { SkillDescriptor } from "./types.js";
+import type { GraphComposerAction } from "./graphComposerActions.js";
+/** Loaded from `functions/graph-composer/prompts/skill-mode-locked.md`. */
+export declare const LOCKED_GATE_TEXT: string;
+/** Loaded from `functions/graph-composer/prompts/skill-mode-extensible.md`. */
+export declare const EXTENSIBLE_GATE_TEXT: string;
+export declare function formatSkillList(catalogSectionHeader: string, skills: SkillDescriptor[]): string;
+export declare function composeInstructions(baseInstructions: string, aiSkills: SkillDescriptor[], utilitySkills: SkillDescriptor[], skillMode: "locked" | "extensible"): string;
+/** Per-action worker system prompt: shared fragments + action file + catalogs + skill mode. */
+export declare function composeWorkerInstructions(action: GraphComposerAction, aiSkills: SkillDescriptor[], utilitySkills: SkillDescriptor[], skillMode: "locked" | "extensible"): string;
+//# sourceMappingURL=composeInstructions.d.ts.map

package/dist/composeInstructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composeInstructions.d.ts","sourceRoot":"","sources":["../src/composeInstructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGrE,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,QAE5B,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AAgBF,wBAAgB,eAAe,CAC7B,oBAAoB,EAAE,MAAM,EAC5B,MAAM,EAAE,eAAe,EAAE,GACxB,MAAM,CAaR;AAED,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,eAAe,EAAE,EAC3B,aAAa,EAAE,eAAe,EAAE,EAChC,SAAS,EAAE,QAAQ,GAAG,YAAY,GACjC,MAAM,CASR;AAED,+FAA+F;AAC/F,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,eAAe,EAAE,EAC3B,aAAa,EAAE,eAAe,EAAE,EAChC,SAAS,EAAE,QAAQ,GAAG,YAAY,GACjC,MAAM,CAOR"}

package/dist/composeInstructions.js

@@ -0,0 +1,39 @@
+import { readGraphComposerPromptFile } from "./packDir.js";
+import { loadWorkerBaseMarkdown } from "./graphComposerActions.js";
+/** Loaded from `functions/graph-composer/prompts/skill-mode-locked.md`. */
+export const LOCKED_GATE_TEXT = readGraphComposerPromptFile("skill-mode-locked.md");
+/** Loaded from `functions/graph-composer/prompts/skill-mode-extensible.md`. */
+export const EXTENSIBLE_GATE_TEXT = readGraphComposerPromptFile("skill-mode-extensible.md");
+const SKILL_CATALOG_AI_HEADER = readGraphComposerPromptFile("skill-catalog-ai-header.md").trimEnd();
+const SKILL_CATALOG_UTILITY_HEADER = readGraphComposerPromptFile("skill-catalog-utility-header.md").trimEnd();
+function schemaSummary(schema) {
+    if (schema === undefined || schema === null)
+        return "see description";
+    if (typeof schema === "object")
+        return JSON.stringify(schema);
+    return String(schema);
+}
+export function formatSkillList(catalogSectionHeader, skills) {
+    const blocks = skills.map((s) => {
+        const tags = s.tags?.length ? s.tags.join(", ") : "(none)";
+        return [
+            `- \`skillKey\`: ${s.skillKey}`,
+            `  Description: ${s.description}`,
+            `  Input: ${schemaSummary(s.inputSchema)}`,
+            `  Output: ${schemaSummary(s.outputSchema)}`,
+            `  Tags: ${tags}`,
+        ].join("\n");
+    });
+    const body = blocks.length ? blocks.join("\n\n") : "(none)";
+    return `${catalogSectionHeader}\n\n${body}`;
+}
+export function composeInstructions(baseInstructions, aiSkills, utilitySkills, skillMode) {
+    const aiSection = formatSkillList(SKILL_CATALOG_AI_HEADER, aiSkills);
+    const utilSection = formatSkillList(SKILL_CATALOG_UTILITY_HEADER, utilitySkills);
+    const modeSection = skillMode === "locked" ? LOCKED_GATE_TEXT : EXTENSIBLE_GATE_TEXT;
+    return [baseInstructions, aiSection, utilSection, modeSection].join("\n\n");
+}
+/** Per-action worker system prompt: shared fragments + action file + catalogs + skill mode. */
+export function composeWorkerInstructions(action, aiSkills, utilitySkills, skillMode) {
+    return composeInstructions(loadWorkerBaseMarkdown(action), aiSkills, utilitySkills, skillMode);
+}