@nodetool-ai/node-sdk 0.7.0-rc.23 → 0.8.2

package/dist/content-card.js

@@ -0,0 +1,68 @@
+/**
+ * Which output types render as a content card.
+ *
+ * A node whose primary output is one of these has something to *show* — an
+ * image, a video, an audio waveform, a 3D model, or text. The editor renders
+ * those with `ContentCardBody` (a preview-forward body) instead of the generic
+ * input/output layout, driven by `body: "content_card"` in the node metadata.
+ *
+ * Provider packs derive the flag from their manifest rather than declaring it
+ * per node, so a new model added to a manifest gets the right body for free.
+ * Keep this list in sync with `getContentCardVariant` in
+ * `web/src/components/node_types/contentCardRegistry.ts`, which maps the same
+ * types onto the concrete preview variant.
+ */
+const CONTENT_CARD_OUTPUT_TYPES = new Set([
+    "image",
+    "image_mask",
+    "mask",
+    "video",
+    "audio",
+    "model_3d",
+    "asset_3d",
+    "str",
+    "text"
+]);
+/** True when a node with this primary output type should render a content card. */
+export function isContentCardOutputType(outputType) {
+    return outputType !== undefined && CONTENT_CARD_OUTPUT_TYPES.has(outputType);
+}
+/**
+ * Type of the output slot the editor previews — the one `getNodeMetadata`
+ * puts at `outputs[0]`, so the resolution order matches it: an explicit
+ * `metadataOutputTypes` map wins over `outputTypes`.
+ */
+export function primaryDeclaredOutputType(nodeClass) {
+    const declared = nodeClass.metadataOutputTypes ?? nodeClass.outputTypes ?? {};
+    return Object.values(declared)[0];
+}
+/**
+ * Stamp `body = "content_card"` on a generated node class whose primary output
+ * is displayable. A class that already declares its own `body` keeps it —
+ * per-node overrides win (e.g. the "small" voice-picker bodies).
+ *
+ * Call after the class's output types are defined.
+ */
+export function applyContentCardBody(nodeClass) {
+    if (nodeClass.body !== undefined) {
+        return;
+    }
+    if (!isContentCardOutputType(primaryDeclaredOutputType(nodeClass))) {
+        return;
+    }
+    Object.defineProperty(nodeClass, "body", {
+        value: "content_card",
+        configurable: true
+    });
+}
+/**
+ * List form of {@link applyContentCardBody}, for hand-written node packs that
+ * export a node array. Returns `classes` so it can wrap the array literal.
+ */
+export function tagContentCardBodies(classes) {
+    for (const cls of classes) {
+        applyContentCardBody(cls);
+    }
+    return classes;
+}
+//# sourceMappingURL=content-card.js.map

package/dist/content-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-card.js","sourceRoot":"","sources":["../src/content-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,yBAAyB,GAAwB,IAAI,GAAG,CAAC;IAC7D,OAAO;IACP,YAAY;IACZ,MAAM;IACN,OAAO;IACP,OAAO;IACP,UAAU;IACV,UAAU;IACV,KAAK;IACL,MAAM;CACP,CAAC,CAAC;AAWH,mFAAmF;AACnF,MAAM,UAAU,uBAAuB,CACrC,UAA8B;IAE9B,OAAO,UAAU,KAAK,SAAS,IAAI,yBAAyB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAC/E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,SAA4B;IAE5B,MAAM,QAAQ,GAAG,SAAS,CAAC,mBAAmB,IAAI,SAAS,CAAC,WAAW,IAAI,EAAE,CAAC;IAC9E,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAA4B;IAC/D,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO;IACT,CAAC;IACD,IAAI,CAAC,uBAAuB,CAAC,yBAAyB,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;QACnE,OAAO;IACT,CAAC;IACD,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE;QACvC,KAAK,EAAE,cAAc;QACrB,YAAY,EAAE,IAAI;KACnB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAU;IAEV,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,oBAAoB,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/correlation-validation.d.ts

@@ -0,0 +1,19 @@
+import type { InputMode, OutputCorrelation } from "@nodetool-ai/protocol";
+export interface CorrelationValidationIssue {
+    nodeType: string;
+    handle?: string;
+    message: string;
+}
+export declare class CorrelationMetadataError extends Error {
+    readonly issues: readonly CorrelationValidationIssue[];
+    constructor(issues: readonly CorrelationValidationIssue[]);
+}
+/**
+ * Descriptor-level validation of `output_correlation` per docs/correlation-design.md §3.
+ *
+ * Only checks rules that depend solely on the node metadata. Graph-topology rules
+ * (multi-edge list source scopes, strict-prefix invocation scope, Zip constraints)
+ * belong to the static-correlation analyzer added in PR 3.
+ */
+export declare function validateOutputCorrelation(nodeType: string, inputMode: InputMode | undefined, outputCorrelation: Record<string, OutputCorrelation> | undefined, declaredOutputs: readonly string[]): CorrelationValidationIssue[];
+//# sourceMappingURL=correlation-validation.d.ts.map

package/dist/correlation-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation-validation.d.ts","sourceRoot":"","sources":["../src/correlation-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,MAAM,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAEvD,YAAY,MAAM,EAAE,SAAS,0BAA0B,EAAE,EAexD;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,SAAS,EAChE,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC,0BAA0B,EAAE,CAmF9B"}

package/dist/correlation-validation.js

@@ -0,0 +1,101 @@
+export class CorrelationMetadataError extends Error {
+    issues;
+    constructor(issues) {
+        const first = issues[0];
+        const summary = issues.length === 1
+            ? `${first.nodeType}: ${first.message}`
+            : `${issues.length} correlation metadata issues:\n` +
+                issues
+                    .map((i) => `  - ${i.nodeType}${i.handle ? `.${i.handle}` : ""}: ${i.message}`)
+                    .join("\n");
+        super(summary);
+        this.name = "CorrelationMetadataError";
+        this.issues = issues;
+    }
+}
+/**
+ * Descriptor-level validation of `output_correlation` per docs/correlation-design.md §3.
+ *
+ * Only checks rules that depend solely on the node metadata. Graph-topology rules
+ * (multi-edge list source scopes, strict-prefix invocation scope, Zip constraints)
+ * belong to the static-correlation analyzer added in PR 3.
+ */
+export function validateOutputCorrelation(nodeType, inputMode, outputCorrelation, declaredOutputs) {
+    if (!outputCorrelation)
+        return [];
+    const issues = [];
+    const groupSources = new Map();
+    const declaredOutputSet = new Set(declaredOutputs);
+    for (const [handle, corr] of Object.entries(outputCorrelation)) {
+        if (!corr.source) {
+            issues.push({
+                nodeType,
+                handle,
+                message: `output "${handle}" must declare an explicit source (use "__execution__" or an input handle name)`
+            });
+            continue;
+        }
+        if (corr.kind === "forward") {
+            if (corr.source === "__execution__") {
+                issues.push({
+                    nodeType,
+                    handle,
+                    message: `forward output "${handle}" cannot use source "__execution__"; specify an input handle`
+                });
+            }
+        }
+        if (corr.kind === "aggregate") {
+            if (!corr.collapse) {
+                issues.push({
+                    nodeType,
+                    handle,
+                    message: `aggregate output "${handle}" must declare a collapse spec (e.g. "innermost")`
+                });
+            }
+            if (inputMode === "buffered") {
+                issues.push({
+                    nodeType,
+                    handle,
+                    message: `aggregate output "${handle}" is not allowed on buffered nodes; set input_mode: "stream"`
+                });
+            }
+        }
+        if (corr.kind === "iteration" && corr.group) {
+            const existing = groupSources.get(corr.group);
+            if (existing !== undefined && existing !== corr.source) {
+                issues.push({
+                    nodeType,
+                    handle,
+                    message: `iteration group "${corr.group}" has conflicting sources: "${existing}" and "${corr.source}" — handles in one group must share one source`
+                });
+            }
+            else {
+                groupSources.set(corr.group, corr.source);
+            }
+        }
+        if (declaredOutputSet.size > 0 && !declaredOutputSet.has(handle)) {
+            issues.push({
+                nodeType,
+                handle,
+                message: `output_correlation references handle "${handle}" not in declared outputs`
+            });
+        }
+    }
+    // Every declared output must have a correlation entry. A node may opt out
+    // of correlation entirely by leaving output_correlation undefined; once it
+    // declares any entry it has committed to the per-output contract.
+    // Stryker disable next-line ConditionalExpression,EqualityOperator: the guard only short-circuits an empty set; the loop body is a no-op for size 0, so size > 0 vs size >= 0 vs always-true are indistinguishable (equivalent).
+    if (declaredOutputSet.size > 0) {
+        for (const handle of declaredOutputSet) {
+            if (!(handle in outputCorrelation)) {
+                issues.push({
+                    nodeType,
+                    handle,
+                    message: `declared output "${handle}" is missing a correlation entry`
+                });
+            }
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=correlation-validation.js.map

package/dist/correlation-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation-validation.js","sourceRoot":"","sources":["../src/correlation-validation.ts"],"names":[],"mappings":"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"}

package/dist/cost-estimate.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Pure pre-run cost estimation for a workflow graph.
+ *
+ * Walks the nodes, resolves per-node unit pricing attached to node metadata
+ * (`fal_unit_pricing` first, then `kie_unit_pricing`) — or, where the model
+ * catalogs publish a grid for the same endpoint, off that grid — multiplies by
+ * an expected run count, and returns a {@link WorkflowCostEstimate}. Nodes without a known
+ * price are still reported (cost 0, confidence "unknown") and counted, never
+ * hidden — the plan-before-spend view must surface uncertainty.
+ *
+ * Generic nodes (e.g. `nodetool.image.TextToImage`) carry no fixed node-type
+ * price — the model is chosen at runtime through a provider-model property such
+ * as `model`. For those, the estimator reads the selected model id from node
+ * data and prices it through the caller-supplied `getModelPrice` lookup.
+ *
+ * No I/O: callers supply a `getMetadata` lookup so this stays hermetic and
+ * usable from web, agents, and the CLI alike.
+ */
+import type { NodeCostEstimate, WorkflowCostEstimate } from "@nodetool-ai/protocol";
+import type { UnitPricing } from "./pricing-bundle.js";
+/** FAL list price as attached to `NodeMetadata.fal_unit_pricing`. */
+export interface FalUnitPricingLike extends UnitPricing {
+    endpoint_id?: string;
+    /** "live" means fetched from the provider this session — treated as exact. */
+    source?: "live" | "bundle";
+}
+/** kie.ai list price as attached to `NodeMetadata.kie_unit_pricing`. */
+export interface KieUnitPricingLike extends UnitPricing {
+    model_id?: string;
+    /** USD conversion of the credit price, when known. Preferred over credits. */
+    usd_price?: number;
+    source?: "live" | "bundle";
+}
+/** A single node property as exposed by `NodeMetadata` — only the shape read here. */
+export interface NodePropertyLike {
+    name?: string;
+    type?: {
+        type?: string;
+    } | null;
+}
+/** Minimal slice of `NodeMetadata` this estimator reads. */
+export interface NodeMetadataLike {
+    /** The node's registered display name ("Image To Video"). */
+    title?: string | null;
+    fal_unit_pricing?: FalUnitPricingLike | null;
+    kie_unit_pricing?: KieUnitPricingLike | null;
+    /** Properties, used to find a provider-model selection on generic nodes. */
+    properties?: Array<NodePropertyLike | null> | null;
+}
+/** Price for a dynamically-selected model, as returned by `getModelPrice`. */
+export interface ModelUnitPricingLike extends UnitPricing {
+    source?: "live" | "bundle";
+}
+/** A model chosen on a node via a provider-model property (e.g. `model`). */
+export interface SelectedModel {
+    id: string;
+    provider: string | null;
+}
+/**
+ * What a node states about the job it is about to run, in the vocabulary the
+ * price catalogs bill in. Every field is optional: a missing one is priced at
+ * the model's base spec and recorded as an assumption, never guessed.
+ * `extractPricingParams` (`./pricing-params.js`) reads these off node property
+ * values.
+ */
+export interface ModelPriceParams {
+    /** A resolution tier or a raw spelling of one ("720p", "1024x1024"). */
+    resolution?: string;
+    /** Output duration in seconds. */
+    seconds?: number;
+    withAudio?: boolean;
+    /** Quality tier when a provider sells several under one model id. */
+    tier?: string;
+    referenceImages?: number;
+    /** Duration of a video fed in, which some providers bill instead of output. */
+    referenceVideoSeconds?: number;
+    megapixels?: number;
+    /** Characters of text a speech job will synthesize. */
+    characters?: number;
+}
+/**
+ * A model price computed from {@link ModelPriceParams}. `unit_price` is the
+ * whole per-run figure (a per-second model comes back already multiplied by
+ * its duration), so `estimated_cost = unit_price × quantity` still composes.
+ */
+export interface ModelParamPricingLike extends ModelUnitPricingLike {
+    /** How the figure was reached: "5 s × $0.205/s at 720p". */
+    breakdown?: string;
+    /** What was filled in because the node did not state it. */
+    assumptions?: string[];
+    /** Known-missing costs — the figure is then a lower bound. */
+    warnings?: string[];
+    /** Set instead of a price when the catalog refuses to extrapolate. */
+    declined?: string;
+    /** The duration the figure was billed for, when one applied. */
+    seconds?: number;
+    /** The rung the figure was billed at, in the catalog's own spelling. */
+    resolution?: string;
+    /** The text length the figure was billed for, when one applied. */
+    characters?: number;
+    /**
+     * The figure came off a published grid row, so it moves with the resolution,
+     * duration and audio state the node states. A flat rate leaves it unset.
+     */
+    fromGrid?: boolean;
+}
+/**
+ * A price as text. Sub-cent figures get as many decimal places as they need:
+ * `String(3e-7)` is `3e-7`, and a breakdown reading "$3e-7/s" is unreadable.
+ */
+export declare const formatUsd: (usd: number) => string;
+/** Extra facts a catalog row states about its own fidelity. */
+export interface ScalarPriceOptions {
+    /** >1 means the figure is the cheapest of several published tiers. */
+    tierCount?: number;
+}
+/**
+ * Turn a catalog scalar into a per-run figure for the stated job.
+ *
+ * A per-second, per-minute or per-megapixel scalar times what the node states;
+ * a block unit times the number of blocks the duration needs. Everything else
+ * is already a per-run price, and a unit we cannot convert — one with no fixed
+ * value (credits) or a rate over something the node never states (compute
+ * seconds, training steps) — declines rather than passing off a per-unit number
+ * as the cost of a run.
+ *
+ * Every catalog scalar goes through here: the FAL/kie rows
+ * `@nodetool-ai/model-pricing` looks a selected model up in, and the same rows
+ * attached to node metadata as `fal_unit_pricing`. A 10-second clip on a
+ * $0.14/second endpoint costs $1.40 whichever of the two answered.
+ */
+export declare function priceScalarUnit(price: ModelUnitPricingLike, params?: ModelPriceParams, options?: ScalarPriceOptions): ModelParamPricingLike;
+/**
+ * A node estimate carrying the two facts the figure was reached with. They live
+ * here rather than in `NodeCostEstimate` (`@nodetool-ai/protocol`) so callers
+ * that render them — the editor's cost panel — read them off the estimate
+ * instead of parsing them back out of `breakdown` prose.
+ */
+export interface NodeCostEstimateDetail extends NodeCostEstimate {
+    /**
+     * What to call this node in a cost table: the title the user gave it, else
+     * the node's registered title, else its class name spaced out. `node_type`
+     * stays the identity — a reader who needs `nodetool.video.ImageToVideo`
+     * still has it — but a column of dotted paths reads as one repeated prefix,
+     * and the four `nodetool.agents.Agent` rows of a real graph are told apart
+     * by their titles, not their type.
+     */
+    node_title?: string;
+    /** Output duration the price was multiplied by, when one applied. */
+    seconds?: number;
+    /** Rung the price was read off ("720p", "1MP"). */
+    resolution?: string;
+}
+/**
+ * A node type's class name, spaced: `nodetool.video.ImageToVideo` → "Image To
+ * Video". The last resort behind a user title and the registered metadata
+ * title, for a node type whose metadata a caller could not supply.
+ */
+export declare function humanizeNodeType(nodeType: string): string;
+/** {@link estimateWorkflowCost}'s result, with the detailed items. */
+export interface WorkflowCostEstimateDetail extends WorkflowCostEstimate {
+    items: NodeCostEstimateDetail[];
+}
+/**
+ * Property `type.type` values whose value is a provider-backed model selection
+ * carrying a provider + model id. Kept in sync with the web `PROVIDER_MODEL_TYPES`
+ * list. Local model types (`llama_model`, `hf.*`) are excluded — they aren't
+ * priced through a provider catalog.
+ */
+export declare const PROVIDER_MODEL_TYPES: ReadonlySet<string>;
+/**
+ * The slice of node metadata {@link usesAiModel} reads. Structural on purpose:
+ * the editor's generated `NodeMetadata` and the SDK's own registry metadata are
+ * different types over the same fields, and both satisfy this.
+ */
+export interface AiModelNodeMetadataLike {
+    type?: string;
+    fal_unit_pricing?: unknown;
+    kie_unit_pricing?: unknown;
+    properties?: ReadonlyArray<{
+        type?: {
+            type?: string;
+        } | null;
+    } | null> | null;
+}
+/**
+ * Whether a node type runs on an AI model — it carries provider unit pricing
+ * (FAL, kie) or exposes a provider-backed model property. The billable-node
+ * predicate: what the cost panel lists and what a pre-run estimate walks.
+ * Plain data and utility nodes answer false.
+ */
+export declare function usesAiModel(metadata: AiModelNodeMetadataLike | undefined | null): boolean;
+/**
+ * How many outputs a node is expected to produce, from its property values.
+ * Conservative: an absent or unreadable count is one output, so an estimate
+ * never over-counts a fan-out nobody asked for.
+ */
+export declare function nodeExpectedQuantity(values: Record<string, unknown> | undefined | null): number;
+export interface CostEstimateInput {
+    nodes: Array<{
+        id: string;
+        type: string;
+        data?: Record<string, unknown>;
+    }>;
+    /** Look up metadata (which may carry fal_unit_pricing / kie_unit_pricing) for a node type. */
+    getMetadata: (nodeType: string) => NodeMetadataLike | undefined;
+    /**
+     * Optional lookup of unit pricing for a model selected on a generic node's
+     * provider-model property. Returns `null`/`undefined` when the model is
+     * unknown. Without it, generic nodes stay "unknown".
+     */
+    getModelPrice?: (model: SelectedModel, params?: ModelPriceParams) => ModelParamPricingLike | null | undefined;
+    /**
+     * Optional per-node read of what the node states about its job (duration,
+     * resolution, audio). Supplied by the caller so this stays hermetic; the
+     * result is handed to `getModelPrice`.
+     */
+    getParams?: (node: {
+        id: string;
+        type: string;
+        data?: Record<string, unknown>;
+    }) => ModelPriceParams | undefined;
+    /** Optional per-node expected run count (fan-out). Defaults to 1. */
+    quantities?: Record<string, number>;
+    /**
+     * Optional per-node display title, keyed by node id — the name the user gave
+     * the node on the canvas. Falls back to the metadata title, then to the node
+     * type's spaced class name.
+     */
+    titles?: Record<string, string>;
+    /**
+     * Explicitly identifies graph plumbing or local utility nodes known not to
+     * create a billable provider request. Excluded nodes do not become
+     * misleading unknown-cost items.
+     */
+    isKnownNonBillable?: (node: {
+        id: string;
+        type: string;
+        data?: Record<string, unknown>;
+    }) => boolean;
+    currency?: string;
+}
+export declare function estimateWorkflowCost(input: CostEstimateInput): WorkflowCostEstimateDetail;
+//# sourceMappingURL=cost-estimate.d.ts.map

package/dist/cost-estimate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-estimate.d.ts","sourceRoot":"","sources":["../src/cost-estimate.ts"],"names":[],"mappings":"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"}