@ghchinoy/litflow 0.2.8 → 0.3.0

package/src/breadboard/engine/inspector/graph/describe-type-cache.ts

@@ -0,0 +1,48 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  DescribeResultTypeCacheArgs,
+  InspectableDescriberResultCacheEntry,
+  InspectableDescriberResultTypeCache,
+  NodeDescriberResult,
+  NodeTypeIdentifier,
+} from "@breadboard-ai/types";
+import { SnapshotUpdater } from "@breadboard-ai/utils";
+
+export { DescribeResultTypeCache };
+
+type MapItem = SnapshotUpdater<NodeDescriberResult>;
+
+class DescribeResultTypeCache implements InspectableDescriberResultTypeCache {
+  #map = new Map<NodeTypeIdentifier, MapItem>();
+
+  constructor(public readonly args: DescribeResultTypeCacheArgs) {}
+
+  get(type: NodeTypeIdentifier): InspectableDescriberResultCacheEntry {
+    let result = this.#map.get(type);
+    if (result) {
+      return result.snapshot();
+    }
+    result = new SnapshotUpdater({
+      initial: () => this.args.initial(),
+      latest: () => this.args.latest(type),
+      updated: () => this.args.updated(type),
+    });
+    this.#map.set(type, result);
+    return result.snapshot();
+  }
+
+  update(affectedTypes: NodeTypeIdentifier[]): void {
+    for (const type of affectedTypes) {
+      this.#map.delete(type);
+    }
+  }
+  clear(): void {
+    this.#map.clear();
+  }
+}

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

@@ -0,0 +1,118 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  Edge as EdgeDescriptor,
+  GraphDescriptor,
+  GraphIdentifier,
+  InspectableEdge,
+  InspectableEdgeCache,
+} from "@breadboard-ai/types";
+import { Edge, unfixUpStarEdge } from "./edge.js";
+
+type EdgeFactory = (
+  edge: EdgeDescriptor,
+  graphId: GraphIdentifier
+) => InspectableEdge;
+
+export class EdgeCache implements InspectableEdgeCache {
+  #factory: EdgeFactory;
+  #map: Map<GraphIdentifier, Map<EdgeDescriptor, InspectableEdge>> = new Map();
+
+  constructor(factory: EdgeFactory) {
+    this.#factory = factory;
+  }
+
+  rebuild(graph: GraphDescriptor) {
+    // Initialize the edge map from the graph. This is only done once, and all
+    // following updates are performed incrementally.
+    const mainGraphEdges = new Map(
+      graph.edges.map((edge) => [edge, this.#factory(edge, "")])
+    );
+    this.#map.set("", mainGraphEdges);
+    Object.entries(graph.graphs || {}).forEach(([graphId, graph]) => {
+      const subGraphEdges = new Map(
+        graph.edges.map((edge) => [edge, this.#factory(edge, graphId)])
+      );
+      this.#map.set(graphId, subGraphEdges);
+    });
+  }
+
+  get(
+    edge: EdgeDescriptor,
+    graphId: GraphIdentifier
+  ): InspectableEdge | undefined {
+    return this.#map.get(graphId)?.get(edge);
+  }
+
+  getOrCreate(edge: EdgeDescriptor, graphId: GraphIdentifier): InspectableEdge {
+    let result = this.get(edge, graphId);
+    if (result) {
+      return result;
+    }
+    result = this.#factory(edge, graphId);
+    this.add(edge, graphId);
+    return result;
+  }
+
+  add(edge: EdgeDescriptor, graphId: GraphIdentifier) {
+    console.assert(
+      !this.#map.get(graphId)?.has(edge),
+      "Edge already exists when adding."
+    );
+    let graphEdges = this.#map.get(graphId);
+    if (!graphEdges) {
+      graphEdges = new Map();
+      this.#map.set(graphId, graphEdges);
+    }
+    graphEdges.set(edge, this.#factory(edge, graphId));
+  }
+
+  remove(edge: EdgeDescriptor, graphId: GraphIdentifier) {
+    console.assert(
+      this.#map.get(graphId)?.has(edge),
+      "Edge not found when removing."
+    );
+    const inspectableEdge = this.#map.get(graphId)?.get(edge);
+    this.#map.get(graphId)?.delete(edge);
+    (inspectableEdge as Edge)?.setDeleted();
+  }
+
+  has(edge: EdgeDescriptor, graphId: GraphIdentifier): boolean {
+    return !!this.#map.get(graphId)?.has(edge);
+  }
+
+  hasByValue(edge: EdgeDescriptor, graphId: GraphIdentifier): boolean {
+    edge = unfixUpStarEdge(edge);
+    const edges = this.edges(graphId);
+    return !!edges.find((e) => {
+      return (
+        e.from.descriptor.id === edge.from &&
+        e.to.descriptor.id === edge.to &&
+        e.out === edge.out &&
+        e.in === edge.in
+      );
+    });
+  }
+
+  edges(graphId: GraphIdentifier): InspectableEdge[] {
+    return Array.from(this.#map.get(graphId)?.values() || []);
+  }
+
+  addSubgraphEdges(subgraph: GraphDescriptor, graphId: GraphIdentifier): void {
+    subgraph.edges.map((edge) => {
+      this.add(edge, graphId);
+    });
+  }
+
+  removeSubgraphEdges(graphId: GraphIdentifier): void {
+    this.#map.get(graphId)?.forEach((inspectableEdge) => {
+      (inspectableEdge as Edge).setDeleted();
+    });
+    this.#map.delete(graphId);
+  }
+}

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

@@ -0,0 +1,133 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  Edge as EdgeDescriptor,
+  EdgeMetadata,
+  GraphIdentifier,
+  InspectableEdge,
+  InspectablePort,
+  MutableGraph,
+} from "@breadboard-ai/types";
+import { InspectableEdgeType } from "@breadboard-ai/types";
+export { Edge };
+
+/**
+ * This helper is necessary because both "*" and "" are valid representations
+ * of a wildcard edge tail. This function ensures that the edge is always
+ * consistent.
+ * @param edge -- the edge to fix up
+ * @returns
+ */
+export const fixUpStarEdge = (edge: EdgeDescriptor): EdgeDescriptor => {
+  if (edge.out === "*") {
+    return { ...edge, in: "" };
+  }
+  return edge;
+};
+
+/**
+ * This is inverse of the helper above, necessary when working with
+ * instances of `InspectableEdge` directly, since they will show "*" on both
+ * sides of the edge.
+ * @param edge -- the edge to un-fix up
+ * @returns
+ */
+export const unfixUpStarEdge = (edge: EdgeDescriptor): EdgeDescriptor => {
+  if (edge.out === "*") {
+    return { ...edge, in: "*" };
+  }
+  return edge;
+};
+
+export const fixupConstantEdge = (edge: EdgeDescriptor): EdgeDescriptor => {
+  const { constant, ...rest } = edge;
+  if (constant === false) {
+    return rest;
+  }
+  return edge;
+};
+
+class Edge implements InspectableEdge {
+  #mutable: MutableGraph | null;
+  #edge: EdgeDescriptor;
+  #graphId: GraphIdentifier;
+
+  constructor(
+    mutable: MutableGraph,
+    edge: EdgeDescriptor,
+    graphId: GraphIdentifier
+  ) {
+    this.#mutable = mutable;
+    this.#edge = edge;
+    this.#graphId = graphId;
+  }
+
+  raw(): EdgeDescriptor {
+    return this.#edge;
+  }
+
+  get from() {
+    if (!this.#mutable) {
+      throw new Error(
+        `Unable to access "from": this edge was deleted and is no longer part of the graph`
+      );
+    }
+    const from = this.#mutable.nodes.get(this.#edge.from, this.#graphId);
+    console.assert(from, "From node not found when getting from.");
+    return from!;
+  }
+
+  get out() {
+    return this.#edge.out as string;
+  }
+
+  get to() {
+    if (!this.#mutable) {
+      throw new Error(
+        `Unable to access "to": this edge was deleted and is no longer part of the graph`
+      );
+    }
+    const to = this.#mutable.nodes.get(this.#edge.to, this.#graphId);
+    console.assert(to, "To node not found when getting to.");
+    return to!;
+  }
+
+  get in() {
+    const edgein = this.#edge.out === "*" ? "*" : this.#edge.in;
+    return edgein as string;
+  }
+
+  get type() {
+    if (this.#edge.out === "*") return InspectableEdgeType.Star;
+    if (this.#edge.out === "") return InspectableEdgeType.Control;
+    if (this.#edge.constant) return InspectableEdgeType.Constant;
+    return InspectableEdgeType.Ordinary;
+  }
+
+  metadata(): EdgeMetadata | undefined {
+    return this.#edge.metadata;
+  }
+
+  async outPort(): Promise<InspectablePort> {
+    const ports = await this.from.ports();
+    return ports.outputs.ports.find((port) => port.name === this.out)!;
+  }
+
+  async inPort(): Promise<InspectablePort> {
+    const ports = await this.to.ports();
+    return ports.inputs.ports.find((port) => port.name === this.in)!;
+  }
+
+  setDeleted() {
+    this.#mutable = null;
+  }
+
+  deleted(): boolean {
+    return !this.#mutable;
+  }
+}

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

@@ -0,0 +1,35 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  GraphIdentifier,
+  GraphStoreUpdateEvent,
+  MainGraphIdentifier,
+  NodeIdentifier,
+} from "@breadboard-ai/types";
+
+export { UpdateEvent };
+
+const eventInit = {
+  bubbles: true,
+  cancelable: true,
+  composed: true,
+};
+
+class UpdateEvent extends Event implements GraphStoreUpdateEvent {
+  static eventName = "update";
+
+  constructor(
+    public readonly mainGraphId: MainGraphIdentifier,
+    public readonly graphId: GraphIdentifier,
+    public readonly nodeId: NodeIdentifier,
+    public readonly affectedGraphs: MainGraphIdentifier[],
+    public readonly topologyChange: boolean
+  ) {
+    super(UpdateEvent.eventName, { ...eventInit });
+  }
+}

package/src/breadboard/engine/inspector/graph/exports-describer.ts

@@ -0,0 +1,45 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  GraphDescriberFactory,
+  MutableGraph,
+  NodeDescriberExport,
+  NodeDescriberResult,
+} from "@breadboard-ai/types";
+import { ok } from "@breadboard-ai/utils";
+
+export { ExportsDescriber };
+
+class ExportsDescriber {
+  constructor(
+    private readonly mutable: MutableGraph,
+    private readonly describerFactory: GraphDescriberFactory
+  ) {}
+
+  async transform(result: NodeDescriberResult): Promise<NodeDescriberResult> {
+    const { exports } = this.mutable.graph;
+    if (!exports) return result;
+
+    const entries = Object.fromEntries(
+      (
+        await Promise.all(
+          exports.map(async (id) => {
+            const describer = this.describerFactory(id, this.mutable);
+            if (!ok(describer)) return null;
+
+            const result = await describer.describe();
+            const url = `${this.mutable.graph.url}${id}`;
+            return [url, result];
+          })
+        )
+      ).filter((item) => item !== null) as [string, NodeDescriberExport][]
+    );
+
+    return { ...result, exports: entries };
+  }
+}

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

@@ -0,0 +1,54 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  GraphDescriptor,
+  GraphIdentifier,
+  InspectableGraph,
+  InspectableGraphCache,
+  InspectableSubgraphs,
+} from "@breadboard-ai/types";
+
+export { GraphCache };
+
+type GraphFactory = (graphId: GraphIdentifier) => InspectableGraph;
+
+class GraphCache implements InspectableGraphCache {
+  #factory: GraphFactory;
+  #graphs: Map<GraphIdentifier, InspectableGraph> = new Map();
+
+  constructor(factory: GraphFactory) {
+    this.#factory = factory;
+  }
+
+  rebuild(graph: GraphDescriptor) {
+    this.#graphs = new Map(
+      Object.keys(graph.graphs || []).map((id) => [id, this.#factory(id)])
+    );
+    this.#graphs.set("", this.#factory(""));
+  }
+
+  get(id: GraphIdentifier): InspectableGraph | undefined {
+    return this.#graphs.get(id);
+  }
+
+  add(id: GraphIdentifier): void {
+    this.#graphs.set(id, this.#factory(id));
+  }
+
+  graphs(): InspectableSubgraphs {
+    return Object.fromEntries([...this.#graphs.entries()].filter(([id]) => id));
+  }
+
+  remove(id: GraphIdentifier): void {
+    this.#graphs.delete(id);
+  }
+
+  clear(): void {
+    this.#graphs.clear();
+  }
+}