@ghchinoy/litflow 0.2.8 → 0.3.0

package/src/breadboard/engine/runtime/static/types.ts

@@ -0,0 +1,77 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { NodeIdentifier, Outcome } from "@breadboard-ai/types";
+
+/**
+ * Very WIP, sketching out reactive Model + Controller
+ * that replaces the current HarnessRunner
+ */
+export type OrchestrationController = {
+  /**
+   * Run the graph from start to finish or the next breakpoint.
+   * Always restarts, resetting current state.
+   * Promise resolves when the run completes.
+   */
+  run(): Promise<Outcome<void>>;
+  /**
+   * Run all incomplete stages to finish or the next breakpoint.
+   * Promise resolves when the run completes.
+   */
+  continue(): Promise<Outcome<void>>;
+  /**
+   * Invoke the next "ready" node in the orchestration.
+   * Promise resolves when the node invocation completes.
+   * If the node reports failure, this is not an error that affects outcome.
+   */
+  stepThroughNode(): Promise<Outcome<void>>;
+  /**
+   * Step through the next incomplete stage in the orchestration.
+   * Promise resolves when the stage completes.
+   */
+  stepThroughStage(): Promise<Outcome<void>>;
+  /**
+   * Provides a way to manage breakpoints.
+   */
+  breakpoints: BreakpointsController;
+};
+
+export type BreakpointsController = {
+  /**
+   * All current breakpoints.
+   */
+  readonly breakpoints: ReadonlyMap<NodeIdentifier, Breakpoint>;
+  /**
+   * Creates a breakpoint. Can be called multiple times on the same node.
+   * @param node - the node at which to set the breakpoint
+   */
+  create(node: NodeIdentifier): void;
+  /**
+   * Removes a breakpoint. Can be called multiple times on the same node.
+   * @param node - the node at which to remove the breakpoint
+   */
+  delete(node: NodeIdentifier): void;
+  /**
+   * Clears all breakpoints.
+   */
+  clear(): void;
+};
+
+export type Breakpoint = {
+  /**
+   * The node at which the breakpoint is set.
+   */
+  readonly id: NodeIdentifier;
+  /**
+   * Disables the breakpoint.
+   */
+  disable(): void;
+  /**
+   * Enables the breakpoint.
+   */
+  enable(): void;
+};

package/src/breadboard/engine/runtime/traversal/index.ts

@@ -0,0 +1,58 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  Edge,
+  InputValues,
+  NodeDescriptor,
+  NodeIdentifier,
+} from "@breadboard-ai/types";
+
+const requiredInputsFromEdges = (edges: Edge[]): string[] => {
+  return [
+    ...new Set(
+      edges
+        .filter((edge: Edge) => !!edge.in && !edge.optional)
+        .map((edge: Edge) => edge.in || "")
+    ),
+  ];
+};
+
+/**
+ * This class holds important parts of the graph traversal algorithm.
+ */
+export class Traversal {
+  /**
+   * Computes the missing inputs for a node. A missing input is an input that is
+   * required by the node, but is not (yet) available in the current state.
+   * @param heads All the edges that point to the node.
+   * @param inputs The input values that will be passed to the node
+   * @param current The node that is being visited.
+   * @returns Array of missing input names.
+   */
+  static computeMissingInputs(
+    heads: Edge[],
+    inputs: InputValues,
+    current: NodeDescriptor,
+    start?: NodeIdentifier
+  ): string[] {
+    const isStartNode = current.id === start;
+    const requiredInputs: string[] = isStartNode
+      ? []
+      : requiredInputsFromEdges(heads);
+    const inputsWithConfiguration = new Set();
+    Object.keys(inputs).forEach((key) => inputsWithConfiguration.add(key));
+    if (current.configuration) {
+      Object.keys(current.configuration).forEach((key) =>
+        inputsWithConfiguration.add(key)
+      );
+    }
+    return requiredInputs.filter(
+      (input) => !inputsWithConfiguration.has(input)
+    );
+  }
+}

package/src/breadboard/engine/runtime/traversal/iterator.ts

@@ -0,0 +1,124 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  Edge,
+  ErrorCapability,
+  GraphRepresentation,
+  TraversalResult,
+} from "@breadboard-ai/types";
+import { Traversal } from "./index.js";
+import { MachineResult } from "./result.js";
+
+export class TraversalMachineIterator
+  implements AsyncIterator<TraversalResult>
+{
+  graph: GraphRepresentation;
+  #current: TraversalResult;
+
+  constructor(graph: GraphRepresentation, result: TraversalResult) {
+    this.graph = graph;
+    this.#current = result;
+  }
+
+  async next(): Promise<IteratorResult<TraversalResult>> {
+    // If there are no missing inputs, let's consume the outputs
+    if (!this.#current.skip) {
+      const { inputs, descriptor } = this.#current;
+      let { outputs, newOpportunities } = this.#current;
+
+      // Mark inputs as used, i.e. shift inputs queues.
+      this.#current.state.useInputs(descriptor.id, this.#current.inputs);
+
+      if (outputs && outputs.$error) {
+        const $error = (
+          typeof outputs.$error === "string"
+            ? { error: new Error(outputs.$error) }
+            : outputs.$error
+        ) as ErrorCapability;
+        outputs.$error = {
+          descriptor,
+          ...($error as object),
+          ...("metadata" in outputs ? { metadata: outputs.metadata } : {}),
+          inputs: { ...inputs, ...$error.inputs },
+        };
+        newOpportunities = newOpportunities.filter(
+          (edge) => edge.out === "$error"
+        );
+      }
+
+      outputs ??= {};
+
+      // Process outputs.
+      this.#current.opportunities.push(...newOpportunities);
+      this.#current.state.wireOutputs(newOpportunities, outputs);
+
+      if (outputs.$error) {
+        if (newOpportunities.length === 0) {
+          // If the node threw an exception and it wasn't routed via $error,
+          // throw it again. This will cause the traversal to stop.
+          throw new Error(
+            "Uncaught exception in node handler. Catch by wiring up the $error output.",
+            {
+              cause: outputs.$error,
+            }
+          );
+        } else {
+          console.warn(
+            "Error in node handler, passing to the wired $error output.",
+            outputs.$error,
+            newOpportunities
+          );
+        }
+      }
+    }
+
+    // If there are no more opportunities and none are pending, we're done.
+    if (this.#current.opportunities.length === 0)
+      return { done: true, value: null };
+
+    // Now, we're ready to start the next iteration.
+
+    // Otherwise, let's pop the next opportunity from the queue.
+    const opportunity = this.#current.opportunities.shift() as Edge;
+
+    const { heads, nodes, tails } = this.graph;
+
+    const toNode = opportunity.to;
+    const currentDescriptor = nodes.get(toNode);
+    if (!currentDescriptor) throw new Error(`No node found for id "${toNode}"`);
+
+    const incomingEdges = heads.get(toNode) || [];
+    const inputs = this.#current.state.getAvailableInputs(toNode);
+
+    const missingInputs = Traversal.computeMissingInputs(
+      incomingEdges,
+      inputs,
+      currentDescriptor,
+      this.graph.start
+    );
+
+    const newOpportunities = tails.get(toNode) || [];
+    // Pour configuration values into inputs. These are effectively like
+    // constants.
+    const inputsWithConfiguration = {
+      ...currentDescriptor.configuration,
+      ...inputs,
+    };
+
+    this.#current = new MachineResult(
+      currentDescriptor,
+      inputsWithConfiguration,
+      missingInputs,
+      opportunity,
+      this.#current.opportunities,
+      newOpportunities,
+      this.#current.state
+    );
+    return { done: false, value: this.#current };
+  }
+}

package/src/breadboard/engine/runtime/traversal/machine.ts

@@ -0,0 +1,58 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  GraphDescriptor,
+  TraversalResult,
+  NodeIdentifier,
+  GraphRepresentation,
+} from "@breadboard-ai/types";
+import { TraversalMachineIterator } from "./iterator.js";
+import { MachineResult } from "./result.js";
+import { MachineEdgeState } from "./state.js";
+import { GraphRepresentationImpl } from "./representation.js";
+
+export class TraversalMachine implements AsyncIterable<TraversalResult> {
+  graph: GraphRepresentation;
+  previousResult?: TraversalResult;
+
+  constructor(
+    descriptor: GraphDescriptor,
+    result?: TraversalResult,
+    start?: NodeIdentifier
+  ) {
+    this.graph = new GraphRepresentationImpl(descriptor, start);
+    this.previousResult = result;
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<TraversalResult> {
+    return this.start();
+  }
+
+  start(): TraversalMachineIterator {
+    if (this.previousResult)
+      return new TraversalMachineIterator(this.graph, this.previousResult);
+
+    const { entries } = this.graph;
+    if (entries.length === 0) throw new Error("No entry node found in graph.");
+    // Create fake edges to represent entry points.
+    const opportunities = entries.map((entry) => ({
+      from: "$entry",
+      to: entry,
+    }));
+    const entryResult = new MachineResult(
+      { id: "$empty", type: "$empty" },
+      {},
+      [],
+      { from: "$entry", to: entries[0] },
+      opportunities,
+      [],
+      new MachineEdgeState()
+    );
+    return new TraversalMachineIterator(this.graph, entryResult);
+  }
+}

package/src/breadboard/engine/runtime/traversal/representation.ts

@@ -0,0 +1,115 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  Edge,
+  GraphDescriptor,
+  GraphRepresentation,
+  NodeDescriptor,
+  NodeIdentifier,
+} from "@breadboard-ai/types";
+
+export class GraphRepresentationImpl implements GraphRepresentation {
+  start?: NodeIdentifier;
+  /**
+   * Tails: a map of all outgoing edges, keyed by node id.
+   */
+  tails: Map<NodeIdentifier, Edge[]> = new Map();
+
+  /**
+   * Heads: a map of all incoming edges, keyed by node id.
+   */
+  heads: Map<NodeIdentifier, Edge[]> = new Map();
+
+  /**
+   * Nodes: a map of all nodes, keyed by node id.
+   */
+  nodes: Map<NodeIdentifier, NodeDescriptor> = new Map();
+
+  /**
+   * Entries: a list of all nodes that have no incoming edges.
+   */
+  entries: NodeIdentifier[] = [];
+
+  #notInHeads(id: NodeIdentifier) {
+    return !this.heads.has(id) || this.heads.get(id)?.length === 0;
+  }
+
+  #notInTails(id: NodeIdentifier) {
+    return !this.tails.has(id) || this.tails.get(id)?.length === 0;
+  }
+
+  #findEntries(): NodeIdentifier[] {
+    const entries = Array.from(this.nodes.keys()).filter((node) =>
+      this.#notInHeads(node)
+    );
+    // If entries is empty, return empty array
+    if (entries.length === 0) return [];
+
+    // Now, let's separate out all standalone steps and see if maybe we only
+    // have standalone nodes.
+    const standalone: NodeIdentifier[] = [];
+    const connected: NodeIdentifier[] = [];
+    let onlyStandalone = true;
+    entries.forEach((node) => {
+      if (this.#notInTails(node)) {
+        standalone.push(node);
+      } else {
+        onlyStandalone = false;
+        connected.push(node);
+      }
+    });
+
+    // If there are no standalone nodes, return all entries as usual.
+    if (standalone.length === 0) return entries;
+
+    // First, let's see if we can find the starting one
+    const start = standalone.find(
+      (node) => this.nodes.get(node)!.metadata?.start
+    );
+    // If there's a standalone start node, let's return.
+    if (start) return [start];
+
+    if (onlyStandalone) {
+      // This is the situation when we have a bunch of random nodes in graph
+      // and they are not connected, and there's no designated start node.
+
+      // Just return the first standalone node.
+      return [standalone.at(0)!];
+    } else {
+      // If there are both standalone and connected nodes, we just ignore
+      // all standalone nodes.
+      return connected;
+    }
+  }
+
+  constructor(descriptor: GraphDescriptor, start?: NodeIdentifier) {
+    if (start) {
+      this.start = start;
+    }
+    this.tails = descriptor.edges.reduce((acc, edge) => {
+      const from = edge.from;
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      acc.has(from) ? acc.get(from)?.push(edge) : acc.set(from, [edge]);
+      return acc;
+    }, new Map());
+
+    this.heads = descriptor.edges.reduce((acc, edge) => {
+      const to = edge.to;
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      acc.has(to) ? acc.get(to)?.push(edge) : acc.set(to, [edge]);
+      return acc;
+    }, new Map());
+
+    this.nodes = descriptor.nodes.reduce((acc, node) => {
+      acc.set(node.id, node);
+      return acc;
+    }, new Map());
+
+    this.entries = this.#findEntries();
+  }
+}

package/src/breadboard/engine/runtime/traversal/result.ts

@@ -0,0 +1,72 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  Edge,
+  QueuedNodeValuesState,
+  InputValues,
+  NodeDescriptor,
+  OutputValues,
+  TraversalResult,
+} from "@breadboard-ai/types";
+import { MachineEdgeState } from "./state.js";
+
+export class MachineResult implements TraversalResult {
+  descriptor: NodeDescriptor;
+  inputs: InputValues;
+  missingInputs: string[];
+  current: Edge;
+  opportunities: Edge[];
+  newOpportunities: Edge[];
+  state: QueuedNodeValuesState;
+  outputs?: OutputValues;
+  partialOutputs?: OutputValues;
+
+  constructor(
+    descriptor: NodeDescriptor,
+    inputs: InputValues,
+    missingInputs: string[],
+    currentOpportunity: Edge,
+    opportunities: Edge[],
+    newOpportunities: Edge[],
+    state: QueuedNodeValuesState,
+    partialOutputs?: OutputValues
+  ) {
+    this.descriptor = descriptor;
+    this.inputs = inputs;
+    this.missingInputs = missingInputs;
+    this.current = currentOpportunity;
+    this.opportunities = opportunities;
+    this.newOpportunities = newOpportunities;
+    this.state = state;
+    this.partialOutputs = partialOutputs;
+  }
+
+  /**
+   * `true` if the machine decided that the node should be skipped, rather than
+   * visited.
+   */
+  get skip(): boolean {
+    return this.missingInputs.length > 0;
+  }
+
+  static fromObject(o: TraversalResult): MachineResult {
+    const edgeState = new MachineEdgeState();
+    edgeState.constants = o.state.constants;
+    edgeState.state = o.state.state;
+    return new MachineResult(
+      o.descriptor,
+      o.inputs,
+      o.missingInputs,
+      o.current,
+      o.opportunities,
+      o.newOpportunities,
+      edgeState,
+      o.partialOutputs
+    );
+  }
+}

package/src/breadboard/engine/runtime/traversal/state.ts

@@ -0,0 +1,115 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  Edge,
+  QueuedNodeValuesState,
+  NodeIdentifier,
+  InputValues,
+  OutputValues,
+  NodeValue,
+  NodeValuesQueuesMap,
+} from "@breadboard-ai/types";
+
+export class MachineEdgeState implements QueuedNodeValuesState {
+  state: NodeValuesQueuesMap = new Map();
+  constants: NodeValuesQueuesMap = new Map();
+
+  #queueOutput(
+    map: NodeValuesQueuesMap,
+    node: NodeIdentifier,
+    key: string,
+    value: NodeValue
+  ) {
+    let queuesMap = map.get(node);
+    if (!queuesMap) {
+      queuesMap = new Map();
+      map.set(node, queuesMap);
+    }
+    let queue = queuesMap.get(key);
+    if (!queue) {
+      queue = [];
+      queuesMap.set(key, queue);
+    }
+    queue.push(value);
+  }
+
+  /**
+   * Processes outputs by wiring them to the destinations according
+   * to the supplied edges. Assumes that the outputs were generated by
+   * the from node.
+   *
+   * @param opportunites {Edge[]} Edges to process
+   * @param outputs {OutputValues} Outputs to wire
+   */
+  wireOutputs(opportunites: Edge[], outputs: OutputValues): void {
+    // Verify that all edges are from the same node.
+    if (
+      opportunites.filter(
+        (opportunity) => opportunity.from != opportunites[0].from
+      ).length !== 0
+    )
+      throw new Error("All opportunities must be from the same node");
+
+    opportunites.forEach((opportunity) => {
+      const to = opportunity.to;
+      const out = opportunity.out;
+      const queuesMap = opportunity.constant ? this.constants : this.state;
+      if (!out) return;
+      if (out === "*") {
+        for (const key in outputs) {
+          const output = outputs[key];
+          if (output != null && output != undefined)
+            this.#queueOutput(queuesMap, to, key, output);
+        }
+      } else if (opportunity.in) {
+        const output = outputs[out];
+        // TODO: Check and document why we don't allow that
+        if (output != null && output != undefined)
+          this.#queueOutput(queuesMap, to, opportunity.in, output);
+      }
+    });
+  }
+
+  /**
+   * Returns the available inputs for a given node.
+   *
+   * @param nodeId {NodeIdentifier} The node to get the inputs for.
+   * @returns {InputValues} The available inputs.
+   */
+  getAvailableInputs(nodeId: NodeIdentifier): InputValues {
+    const result: InputValues = {};
+
+    for (const queuesMap of [
+      this.constants.get(nodeId), // Constants are overwritten by state.
+      this.state.get(nodeId),
+    ]) {
+      if (!queuesMap) continue;
+      for (const [key, queue] of queuesMap.entries()) {
+        if (queue.length === 0) continue;
+        result[key] = queue[0];
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Shifts inputs from the queues. Leaves constants as is.
+   *
+   * @param nodeId {NodeIdentifier} The node to shift the inputs for.
+   * @param inputs {InputValues} The inputs that are used.
+   */
+  useInputs(nodeId: NodeIdentifier, inputs: InputValues): void {
+    const queuesMap = this.state.get(nodeId);
+    if (!queuesMap) return;
+    for (const key in inputs) {
+      const queue = queuesMap.get(key);
+      if (!queue) continue;
+      queue.shift();
+    }
+  }
+}