@ghchinoy/litflow 0.2.8 → 0.3.0

package/src/breadboard/engine/inspector/graph/node-type-describer-manager.ts

@@ -0,0 +1,122 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  DescribeResultTypeCacheArgs,
+  GraphDescriptor,
+  MutableGraphStore,
+  NodeDescriberContext,
+  NodeDescriberFunction,
+  NodeDescriberResult,
+  NodeHandler,
+  NodeTypeIdentifier,
+} from "@breadboard-ai/types";
+import { createLoader } from "../../loader/index.js";
+import { SENTINEL_BASE_URL } from "../../loader/loader.js";
+import { getHandler } from "../../runtime/legacy.js";
+import { contextFromMutableGraphStore } from "../graph-store.js";
+import { UpdateEvent } from "./event.js";
+import { emptyResult, NodeDescriberManager } from "./node-describer-manager.js";
+import { describeInput, describeOutput } from "./schemas.js";
+import {
+  assetsFromGraphDescriptor,
+  envFromGraphDescriptor,
+} from "../../../data/file-system.js";
+
+export { NodeTypeDescriberManager };
+
+const PLACEHOLDER_ID = crypto.randomUUID();
+
+const TYPE_DESCRIPTOR_GRAPH_URL = SENTINEL_BASE_URL.href;
+
+class NodeTypeDescriberManager implements DescribeResultTypeCacheArgs {
+  constructor(public readonly store: MutableGraphStore) {}
+
+  initial(): NodeDescriberResult {
+    return emptyResult();
+  }
+
+  updated(): void {
+    this.store.dispatchEvent(
+      new UpdateEvent(PLACEHOLDER_ID, "", "", [], false)
+    );
+  }
+
+  latest(type: NodeTypeIdentifier): Promise<NodeDescriberResult> {
+    return this.getLatestDescription(type);
+  }
+
+  async getLatestDescription(type: NodeTypeIdentifier) {
+    // The schema of an input or an output is defined by their
+    // configuration schema or their incoming/outgoing edges.
+    if (type === "input") {
+      return describeInput({});
+    }
+    if (type === "output") {
+      return describeOutput({});
+    }
+
+    const kits = [...this.store.kits];
+    const describer = await this.#getDescriber(type);
+    const asWired = NodeDescriberManager.asWired();
+    if (!describer) {
+      return asWired;
+    }
+    const loader = this.store.loader || createLoader();
+    // When describing types, we provide a weird empty graph with a special URL
+    // because we're not actually inside of any graph, and that is ok.
+    const outerGraph: GraphDescriptor = {
+      nodes: [],
+      edges: [],
+      url: TYPE_DESCRIPTOR_GRAPH_URL,
+    };
+    const context: NodeDescriberContext = {
+      outerGraph,
+      loader,
+      kits,
+      sandbox: this.store.sandbox,
+      graphStore: this.store,
+      fileSystem: this.store.fileSystem.createRunFileSystem({
+        graphUrl: TYPE_DESCRIPTOR_GRAPH_URL,
+        env: envFromGraphDescriptor(this.store.fileSystem.env()),
+        assets: assetsFromGraphDescriptor(),
+      }),
+      wires: { incoming: {}, outgoing: {} },
+      asType: true,
+      flags: this.store.flags,
+    };
+    try {
+      return describer(
+        undefined,
+        asWired.inputSchema,
+        asWired.outputSchema,
+        context
+      );
+    } catch (e) {
+      console.warn(`Error describing node type ${type}`, e);
+      return asWired;
+    }
+  }
+
+  async #getDescriber(
+    type: NodeTypeIdentifier
+  ): Promise<NodeDescriberFunction | undefined> {
+    let handler: NodeHandler | undefined;
+    try {
+      handler = await getHandler(
+        type,
+        contextFromMutableGraphStore(this.store)
+      );
+    } catch (e) {
+      console.warn(`Error getting describer for node type ${type}`, e);
+    }
+    if (!handler || !("describe" in handler) || !handler.describe) {
+      return undefined;
+    }
+    return handler.describe;
+  }
+}

package/src/breadboard/engine/inspector/graph/node.ts

@@ -0,0 +1,149 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  GraphIdentifier,
+  InputValues,
+  InspectableEdge,
+  InspectableNode,
+  InspectableNodePorts,
+  InspectableNodeType,
+  MutableGraph,
+  NodeConfiguration,
+  NodeDescriberResult,
+  NodeDescriptor,
+  NodeMetadata,
+  OutputValues,
+} from "@breadboard-ai/types";
+import { GraphQueries } from "./graph-queries.js";
+import { describerResultToPorts } from "./ports.js";
+
+export class Node implements InspectableNode {
+  descriptor: NodeDescriptor;
+  #graph: MutableGraph;
+  #graphId: GraphIdentifier;
+  #deleted = false;
+
+  constructor(
+    descriptor: NodeDescriptor,
+    graph: MutableGraph,
+    graphId: GraphIdentifier
+  ) {
+    this.descriptor = descriptor;
+    this.#graph = graph;
+    this.#graphId = graphId;
+  }
+
+  title(): string {
+    return this.descriptor.metadata?.title || this.descriptor.id;
+  }
+
+  description(): string {
+    return this.descriptor.metadata?.description || this.title();
+  }
+
+  incoming(): InspectableEdge[] {
+    return new GraphQueries(this.#graph, this.#graphId).incoming(
+      this.descriptor.id
+    );
+  }
+
+  outgoing(): InspectableEdge[] {
+    return new GraphQueries(this.#graph, this.#graphId).outgoing(
+      this.descriptor.id
+    );
+  }
+
+  isEntry(): boolean {
+    return this.incoming().length === 0;
+  }
+
+  isExit(): boolean {
+    return this.outgoing().length === 0;
+  }
+
+  isStart(): boolean {
+    return new GraphQueries(this.#graph, this.#graphId).isStart(
+      this.descriptor.id
+    );
+  }
+
+  type(): InspectableNodeType {
+    const type = new GraphQueries(this.#graph, this.#graphId).typeForNode(
+      this.descriptor.id
+    );
+    if (!type) {
+      throw new Error(
+        `Possible integrity error: node ${this.descriptor.id} does not have a type`
+      );
+    }
+    return type;
+  }
+
+  configuration(): NodeConfiguration {
+    return this.descriptor.configuration || {};
+  }
+
+  metadata(): NodeMetadata {
+    return this.descriptor.metadata || {};
+  }
+
+  async describe(): Promise<NodeDescriberResult> {
+    const describeEntry = this.#graph.describe.get(
+      this.descriptor.id,
+      this.#graphId
+    );
+    return describeEntry.latest;
+  }
+
+  currentDescribe(): NodeDescriberResult {
+    const describeEntry = this.#graph.describe.get(
+      this.descriptor.id,
+      this.#graphId
+    );
+    return describeEntry.current;
+  }
+
+  currentPorts(
+    inputValues?: InputValues,
+    outputValues?: OutputValues
+  ): InspectableNodePorts {
+    const snapshot = this.#graph.describe.get(
+      this.descriptor.id,
+      this.#graphId
+    );
+    return describerResultToPorts(
+      this,
+      snapshot.current,
+      snapshot.updating,
+      inputValues,
+      outputValues
+    );
+  }
+
+  async ports(
+    inputValues?: InputValues,
+    outputValues?: OutputValues
+  ): Promise<InspectableNodePorts> {
+    const described = await this.describe();
+    return describerResultToPorts(
+      this,
+      described,
+      false,
+      inputValues,
+      outputValues
+    );
+  }
+
+  setDeleted() {
+    this.#deleted = true;
+  }
+
+  deleted() {
+    return this.#deleted;
+  }
+}

package/src/breadboard/engine/inspector/graph/port-cache.ts

@@ -0,0 +1,80 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  GraphIdentifier,
+  InspectableNodePorts,
+  InspectablePortList,
+  NodeIdentifier,
+  NodePortChanges,
+} from "@breadboard-ai/types";
+
+export { PortCache };
+
+type NodePortMap = Map<NodeIdentifier, InspectableNodePorts>;
+
+type PortsUpdate = {
+  updated: InspectableNodePorts;
+  changes: NodePortChanges;
+};
+
+class PortCache {
+  #map: Map<GraphIdentifier, NodePortMap> = new Map();
+
+  reconcilePorts(
+    incoming: InspectableNodePorts,
+    existing?: InspectableNodePorts
+  ): PortsUpdate {
+    if (!existing) {
+      return this.createNewSnapshot(incoming);
+    }
+    throw new Error("Not implemented");
+  }
+
+  createNewSnapshot(incoming: InspectableNodePorts): PortsUpdate {
+    return {
+      updated: incoming,
+      changes: {
+        input: toUpdates(incoming.inputs),
+        output: toUpdates(incoming.outputs),
+        side: toUpdates(incoming.side),
+      },
+    };
+
+    function toUpdates(ports: InspectablePortList) {
+      return {
+        fixedChanged: ports.fixed,
+        deleted: [],
+        added: ports.ports,
+        updated: [],
+      };
+    }
+  }
+
+  current(
+    graphId: GraphIdentifier,
+    nodeId: NodeIdentifier
+  ): InspectableNodePorts | undefined {
+    return this.#map.get(graphId)?.get(nodeId);
+  }
+
+  getChanges(
+    graphId: GraphIdentifier,
+    nodeId: NodeIdentifier,
+    ports: InspectableNodePorts
+  ): NodePortChanges {
+    let graphPorts = this.#map.get(graphId);
+    if (!graphPorts) {
+      graphPorts = new Map();
+      this.#map.set(graphId, graphPorts);
+    }
+    const nodePorts = graphPorts.get(nodeId);
+    const { updated, changes } = this.reconcilePorts(ports, nodePorts);
+    graphPorts.set(nodeId, updated);
+    return changes;
+  }
+}

package/src/breadboard/engine/inspector/graph/ports.ts

@@ -0,0 +1,292 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  BehaviorSchema,
+  InputValues,
+  InspectableEdge,
+  InspectableNode,
+  InspectableNodePorts,
+  InspectablePort,
+  InspectablePortList,
+  InspectablePortType,
+  NodeConfiguration,
+  NodeDescriberResult,
+  NodeHandler,
+  NodeTypeIdentifier,
+  OutputValues,
+  Schema,
+} from "@breadboard-ai/types";
+import { PortStatus } from "@breadboard-ai/types";
+import { DEFAULT_SCHEMA, EdgeType } from "./schemas.js";
+
+export { describerResultToPorts };
+
+const title = (schema: Schema, key: string) => {
+  return schema.properties?.[key]?.title || key;
+};
+
+const computePortStatus = (
+  wired: boolean,
+  expected: boolean,
+  required: boolean,
+  wiredContainsStar: boolean
+): PortStatus => {
+  if (wired) {
+    if (expected) return PortStatus.Connected;
+    return wiredContainsStar ? PortStatus.Indeterminate : PortStatus.Dangling;
+  }
+  if (required) {
+    return wiredContainsStar ? PortStatus.Indeterminate : PortStatus.Missing;
+  }
+  return PortStatus.Ready;
+};
+
+export const collectPorts = (
+  type: EdgeType,
+  edges: InspectableEdge[],
+  schema: Schema,
+  addErrorPort: boolean,
+  allowRequired: boolean,
+  values?: NodeConfiguration
+) => {
+  let wiredContainsStar = false;
+  // Get the list of all ports wired to this node.
+  const wiredPortNames = edges.map((edge) => {
+    if (edge.out === "*") {
+      wiredContainsStar = true;
+      return "*";
+    }
+    return type === EdgeType.In ? edge.in : edge.out;
+  });
+  schema ??= {};
+  const fixed = schema.additionalProperties === false;
+  const schemaPortNames = Object.keys(schema.properties || {});
+  if (addErrorPort) {
+    // Even if not specified in the schema, all non-built-in nodes always have
+    // an optional `$error` port.
+    schemaPortNames.push("$error");
+  }
+  const schemaContainsStar = schemaPortNames.includes("*");
+  const requiredPortNames = schema.required || [];
+  const valuePortNames = Object.keys(values || {});
+  const portNames = [
+    ...new Set([
+      ...wiredPortNames,
+      ...schemaPortNames,
+      ...valuePortNames,
+      "*", // Always include the star port.
+      "", // Always include the control port.
+    ]),
+  ];
+  portNames.sort();
+  return portNames
+    .map((port) => {
+      const star = port === "*" || port === "";
+      const configured = valuePortNames.includes(port);
+      const wired = wiredPortNames.includes(port);
+      const expected = schemaPortNames.includes(port) || star;
+      const required = requiredPortNames.includes(port);
+      const portSchema = schema.properties?.[port] || DEFAULT_SCHEMA;
+      const kind = computeKind(type, portSchema);
+      if (portSchema.behavior?.includes("deprecated") && !wired) return null;
+      return {
+        name: port,
+        title: title(schema, port),
+        configured,
+        value: values?.[port],
+        star,
+        get edges() {
+          if (!wired) return [];
+          return edges.filter((edge) => {
+            if (edge.out === "*" && star) return true;
+            return type === EdgeType.In ? edge.in === port : edge.out === port;
+          });
+        },
+        status: computePortStatus(
+          wired || configured,
+          !fixed || expected || schemaContainsStar,
+          allowRequired && required,
+          wiredContainsStar
+        ),
+        schema: portSchema,
+        type: new PortType(portSchema),
+        kind,
+      } satisfies InspectablePort;
+    })
+    .filter(Boolean) as InspectablePort[];
+};
+
+function computeKind(
+  type: EdgeType,
+  portSchema: Schema
+): "input" | "output" | "side" {
+  const behaviors: BehaviorSchema[] =
+    (portSchema.type === "array"
+      ? behaviorFromArray(portSchema.items)
+      : portSchema.behavior) || [];
+  if (type === EdgeType.Out) return "output";
+  const match: Set<BehaviorSchema> = new Set(["config", "board", "side"]);
+  let count = 0;
+  behaviors.forEach((behavior) => {
+    if (match.has(behavior)) ++count;
+  });
+  if (count == 3) return "side";
+  return "input";
+}
+
+function behaviorFromArray(
+  items: Schema | Schema[] | undefined
+): BehaviorSchema[] {
+  if (!items) return [];
+  if (Array.isArray(items)) {
+    return items.flatMap((item) => item.behavior || []) || [];
+  }
+  return items.behavior || [];
+}
+
+export class PortType implements InspectablePortType {
+  constructor(public schema: Schema) {}
+
+  hasBehavior(behavior: BehaviorSchema): boolean {
+    return !!this.schema.behavior?.includes(behavior);
+  }
+}
+
+const collectPortsForType = (
+  schema: Schema,
+  kind: "input" | "output"
+): InspectablePort[] => {
+  const portNames = Object.keys(schema.properties || {});
+  const requiredPortNames = schema.required || [];
+  portNames.sort();
+  return portNames.map((port) => {
+    const portSchema: Schema = schema.properties?.[port] || DEFAULT_SCHEMA;
+    return {
+      name: port,
+      title: title(schema, port),
+      configured: false,
+      star: false,
+      edges: [],
+      value: null,
+      status: computePortStatus(
+        false,
+        true,
+        requiredPortNames.includes(port),
+        false
+      ),
+      schema: portSchema,
+      type: new PortType(portSchema),
+      kind,
+    } satisfies InspectablePort;
+  });
+};
+
+/**
+ * CAUTION: Side-effectey. Will remove side-wire ports from `inputs`.
+ */
+function filterSidePorts(inputs: InspectablePortList) {
+  const sidePorts: InspectablePort[] = [];
+  const inputPorts = inputs.ports.filter((port) => {
+    if (port.kind === "side") {
+      sidePorts.push(port);
+      return false;
+    }
+    return true;
+  });
+  inputs.ports = inputPorts;
+  return sidePorts;
+}
+
+function describerResultToPorts(
+  node: InspectableNode,
+  described: NodeDescriberResult,
+  updating: boolean,
+  inputValues?: InputValues,
+  outputValues?: OutputValues
+): InspectableNodePorts {
+  const incoming = node.incoming();
+  const outgoing = node.outgoing();
+  const inputs: InspectablePortList = {
+    fixed: described.inputSchema?.additionalProperties === false,
+    behavior: described.inputSchema.behavior,
+    ports: collectPorts(
+      EdgeType.In,
+      incoming,
+      described.inputSchema,
+      false,
+      true,
+      { ...node.configuration(), ...inputValues }
+    ),
+  };
+  const side: InspectablePortList = {
+    fixed: true,
+    ports: filterSidePorts(inputs),
+  };
+  const addErrorPort =
+    node.descriptor.type !== "input" && node.descriptor.type !== "output";
+  const outputs: InspectablePortList = {
+    fixed: described.outputSchema?.additionalProperties === false,
+    ports: collectPorts(
+      EdgeType.Out,
+      outgoing,
+      described.outputSchema,
+      addErrorPort,
+      false,
+      outputValues
+    ),
+  };
+  return { inputs, outputs, side, updating };
+}
+
+const emptyPorts = (): InspectableNodePorts => ({
+  inputs: {
+    ports: [],
+    fixed: false,
+  },
+  outputs: {
+    ports: [],
+    fixed: false,
+  },
+  side: {
+    ports: [],
+    fixed: true,
+  },
+  updating: false,
+});
+
+export const portsFromHandler = async (
+  type: NodeTypeIdentifier,
+  handler: NodeHandler | undefined
+): Promise<InspectableNodePorts> => {
+  if (!handler || typeof handler === "function" || !handler.describe) {
+    return emptyPorts();
+  }
+  try {
+    const described = await handler.describe();
+    const inputs = {
+      fixed: described.inputSchema.additionalProperties === false,
+      ports: collectPortsForType(described.inputSchema, "input"),
+    };
+    const side = {
+      fixed: true,
+      ports: filterSidePorts(inputs),
+    };
+    return {
+      inputs,
+      outputs: {
+        fixed: described.outputSchema.additionalProperties === false,
+        ports: collectPortsForType(described.outputSchema, "output"),
+      },
+      side,
+      updating: false,
+    };
+  } catch (e) {
+    console.warn(`Error describing node type ${type}:`, e);
+    return emptyPorts();
+  }
+};