@exellix/graph-composer 2.0.0

package/dist/graphComposerAgent.js

@@ -0,0 +1,175 @@
+import { runJsonCompletion, isAiJsonError, } from "@x12i/funcx/functions";
+import { GRAPH_COMPOSER_ACTION_REGISTRY, getActionDefinitionByToolName, } from "./graphComposerActions.js";
+import { DEFAULT_UTILITY_SKILLS } from "./defaultUtilitySkills.js";
+import { readGraphComposerPromptFile } from "./packDir.js";
+import { runGraphWorker, getGraphComposerLlmClient, } from "./runGraphComposer.js";
+const PATCH_KEY_ENUM = [
+    "primaryIntentType",
+    "primaryIntentStatement",
+    "businessObjective",
+    "primaryOutcome",
+];
+function orchestratorStepSchema() {
+    const toolEnum = GRAPH_COMPOSER_ACTION_REGISTRY.map((d) => d.toolName);
+    return {
+        oneOf: [
+            {
+                type: "object",
+                required: ["kind", "summary"],
+                additionalProperties: false,
+                properties: {
+                    kind: { const: "finish" },
+                    summary: { type: "string", minLength: 1 },
+                },
+            },
+            {
+                type: "object",
+                required: ["kind", "tool", "arguments"],
+                additionalProperties: false,
+                properties: {
+                    kind: { const: "call_tool" },
+                    tool: { type: "string", enum: [...toolEnum] },
+                    arguments: {
+                        type: "object",
+                        required: ["intentDescription"],
+                        additionalProperties: false,
+                        properties: {
+                            intentDescription: { type: "string", minLength: 1 },
+                            focusNodeIds: {
+                                type: "array",
+                                items: { type: "string" },
+                            },
+                            onlyIfEmpty: {
+                                type: "array",
+                                items: { type: "string", enum: [...PATCH_KEY_ENUM] },
+                            },
+                        },
+                    },
+                },
+            },
+        ],
+    };
+}
+function toolCatalogText() {
+    return GRAPH_COMPOSER_ACTION_REGISTRY.map((d) => `- \`${d.toolName}\` → worker action \`${d.action}\`: ${d.toolDescription}`).join("\n");
+}
+function buildWorkerInput(action, args, ctx) {
+    const intent = {
+        action,
+        description: args.intentDescription,
+    };
+    if (args.focusNodeIds?.length) {
+        intent.focusNodeIds = [...args.focusNodeIds];
+    }
+    if (action === "suggestConceptObjective" && args.onlyIfEmpty?.length) {
+        intent.onlyIfEmpty = [...args.onlyIfEmpty];
+    }
+    return {
+        intent,
+        existingGraph: ctx.existingGraph,
+        analysisContext: ctx.analysisContext,
+        skillMode: ctx.skillMode,
+        aiSkills: ctx.aiSkills,
+        utilitySkills: ctx.utilitySkills,
+        constraints: ctx.constraints,
+        catalogCandidates: ctx.catalogCandidates,
+    };
+}
+function normalizeAgentInput(input) {
+    const skillMode = input.skillMode ?? "locked";
+    const aiSkills = input.aiSkills ?? [];
+    const utilitySkills = input.utilitySkills === undefined
+        ? [...DEFAULT_UTILITY_SKILLS]
+        : input.utilitySkills;
+    return {
+        ...input,
+        skillMode,
+        aiSkills,
+        utilitySkills,
+        catalogCandidates: input.catalogCandidates,
+    };
+}
+/**
+ * Orchestrator: chooses registered graph workers via structured JSON steps (`runJsonCompletion`),
+ * then runs each selection with `runGraphWorker` (same prompts as direct `runGraphComposer`).
+ */
+export async function runGraphComposerAgent(input, options = {}) {
+    const client = getGraphComposerLlmClient(options);
+    const normalized = normalizeAgentInput(input);
+    const maxSteps = options.maxOrchestratorSteps ?? 8;
+    const system = readGraphComposerPromptFile("orchestrator-system.md");
+    const schema = orchestratorStepSchema();
+    const ctxPayload = {
+        existingGraph: normalized.existingGraph,
+        analysisContext: normalized.analysisContext,
+        skillMode: normalized.skillMode,
+        aiSkills: normalized.aiSkills,
+        utilitySkills: normalized.utilitySkills,
+        constraints: normalized.constraints,
+        catalogCandidates: normalized.catalogCandidates,
+    };
+    const steps = [];
+    let transcript = "";
+    let lastResult = null;
+    for (let i = 0; i < maxSteps; i++) {
+        const instruction = [
+            "## User goal",
+            normalized.goal.trim(),
+            "",
+            "## Context (JSON)",
+            JSON.stringify(ctxPayload),
+            "",
+            "## Registered tools",
+            toolCatalogText(),
+            "",
+            "## Response schema",
+            "Return a single JSON object matching exactly one branch of:",
+            '- `{ "kind": "finish", "summary": "<what was achieved or why you stop>" }`',
+            '- `{ "kind": "call_tool", "tool": "<tool name>", "arguments": { "intentDescription": "...", "focusNodeIds"?: string[], "onlyIfEmpty"?: string[] } }`',
+            "",
+            "## Prior tool results",
+            transcript.trim() ? transcript : "(none yet)",
+        ].join("\n");
+        const r = await runJsonCompletion({
+            instruction,
+            options: {
+                system,
+                client,
+                schema,
+                model: options.model,
+                temperature: options.temperature ?? 0.2,
+                maxTokens: options.maxTokens ?? 2048,
+                timeoutMs: options.askTimeoutMs,
+            },
+        });
+        if (isAiJsonError(r)) {
+            throw new Error(`Orchestrator step failed: ${r.message} (after ${i} step(s))`);
+        }
+        const step = r.parsed;
+        if (!step || typeof step !== "object") {
+            throw new Error("Orchestrator returned empty parsed step");
+        }
+        if (step.kind === "finish") {
+            return {
+                orchestration: { summary: step.summary, steps },
+                result: lastResult,
+            };
+        }
+        const def = getActionDefinitionByToolName(step.tool);
+        if (!def) {
+            throw new Error(`Unknown tool "${step.tool}"`);
+        }
+        const workerInput = buildWorkerInput(def.action, step.arguments, ctxPayload);
+        lastResult = await runGraphWorker(workerInput, options);
+        steps.push({
+            kind: "call_tool",
+            tool: step.tool,
+            action: def.action,
+        });
+        const preview = typeof lastResult === "object" && lastResult !== null
+            ? JSON.stringify(lastResult)
+            : String(lastResult);
+        transcript += `\n---\nTool ${step.tool} (${def.action}) returned:\n${preview.slice(0, 12_000)}${preview.length > 12_000 ? "\n…(truncated)" : ""}\n`;
+    }
+    throw new Error(`runGraphComposerAgent exceeded maxOrchestratorSteps (${maxSteps})`);
+}

package/dist/graphComposerOutputValidation.d.ts

@@ -0,0 +1,23 @@
+import type { GraphComposerInput } from "./types.js";
+/** Passed to output validators when the worker request is available (e.g. `utilitySkills` for protocol checks). */
+export type OutputValidationContext = {
+    input?: GraphComposerInput;
+};
+export type OutputValidator = (out: Record<string, unknown>, ctx?: OutputValidationContext) => void;
+export declare function validateExplainOutput(out: Record<string, unknown>, _ctx?: OutputValidationContext): void;
+export declare function validateReviewConceptOutput(out: Record<string, unknown>, _ctx?: OutputValidationContext): void;
+/**
+ * When `existingGraph.metadata.graphConcept.coreTasks` has length N > 0, any
+ * `graphConceptPatch` / `suggestedConceptPatch` must include `coreTasks` with
+ * the same length (index-aligned). Call after `validateReviewConceptOutput`.
+ */
+export declare function validateReviewConceptOutputAgainstInput(out: Record<string, unknown>, input: {
+    existingGraph?: unknown;
+}): void;
+export declare function validateSuggestConceptOutput(out: Record<string, unknown>, _ctx?: OutputValidationContext): void;
+export declare function validateCreateModifyOutput(out: Record<string, unknown>, ctx?: OutputValidationContext): void;
+export declare function validateSuggestCatalogResolutionOutput(out: Record<string, unknown>, _ctx?: OutputValidationContext): void;
+export declare function validateSuggestCatalogCreationsOutput(out: Record<string, unknown>, _ctx?: OutputValidationContext): void;
+export declare function validateSuggestScopingNeedMatchOutput(out: Record<string, unknown>, _ctx?: OutputValidationContext): void;
+export declare function validateSuggestScopingMapCreationOutput(out: Record<string, unknown>, _ctx?: OutputValidationContext): void;
+//# sourceMappingURL=graphComposerOutputValidation.d.ts.map

package/dist/graphComposerOutputValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphComposerOutputValidation.d.ts","sourceRoot":"","sources":["../src/graphComposerOutputValidation.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAwB,MAAM,YAAY,CAAC;AAE3E,mHAAmH;AACnH,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,CAAC,EAAE,uBAAuB,KAC1B,IAAI,CAAC;AAuBV,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,IAAI,CAIN;AAmYD,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,IAAI,CAwGN;AAED;;;;GAIG;AACH,wBAAgB,uCAAuC,CACrD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,KAAK,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,IAAI,CAqCN;AAuBD,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,IAAI,CAmBN;AAsBD,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,CAAC,EAAE,uBAAuB,GAC5B,IAAI,CAwBN;AAmBD,wBAAgB,sCAAsC,CACpD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,IAAI,CAkDN;AAED,wBAAgB,qCAAqC,CACnD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,IAAI,CAiCN;AAUD,wBAAgB,qCAAqC,CACnD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,IAAI,CAwDN;AAED,wBAAgB,uCAAuC,CACrD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,IAAI,CAwDN"}