@ghchinoy/litflow 0.2.7 → 0.3.0

package/src/breadboard/engine/file-system/partial-persistent-backend.ts

@@ -0,0 +1,109 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  FileSystemPath,
+  FileSystemQueryResult,
+  FileSystemWriteResult,
+  LLMContent,
+  Outcome,
+  PersistentBackend,
+} from "@breadboard-ai/types";
+import { err } from "@breadboard-ai/utils";
+
+export { PartialPersistentBackend };
+
+class PartialPersistentBackend implements PersistentBackend {
+  constructor(private readonly backend: Partial<PersistentBackend>) {}
+
+  async query(
+    graphUrl: string,
+    path: FileSystemPath
+  ): Promise<FileSystemQueryResult> {
+    const result = this.backend.query?.(graphUrl, path);
+    if (!result) {
+      return err(`Method "query" not implemented`);
+    }
+    return result;
+  }
+
+  async read(
+    graphUrl: string,
+    path: FileSystemPath,
+    inflate: boolean
+  ): Promise<Outcome<LLMContent[]>> {
+    const result = this.backend.read?.(graphUrl, path, inflate);
+    if (!result) {
+      return err(`Method "read" not implemented`);
+    }
+    return result;
+  }
+
+  async write(
+    graphUrl: string,
+    path: FileSystemPath,
+    data: LLMContent[]
+  ): Promise<FileSystemWriteResult> {
+    const result = this.backend.write?.(graphUrl, path, data);
+    if (!result) {
+      return err(`Method "write" not implemented`);
+    }
+    return result;
+  }
+
+  async append(
+    graphUrl: string,
+    path: FileSystemPath,
+    data: LLMContent[]
+  ): Promise<FileSystemWriteResult> {
+    const result = this.backend.append?.(graphUrl, path, data);
+    if (!result) {
+      return err(`Method "append" not implemented`);
+    }
+    return result;
+  }
+
+  async delete(
+    graphUrl: string,
+    path: FileSystemPath,
+    all: boolean
+  ): Promise<FileSystemWriteResult> {
+    const result = this.backend.delete?.(graphUrl, path, all);
+    if (!result) {
+      return err(`Method "delete" not implemented`);
+    }
+    return result;
+  }
+
+  async copy(
+    graphUrl: string,
+    source: FileSystemPath,
+    destination: FileSystemPath
+  ): Promise<FileSystemWriteResult> {
+    const result = this.backend.copy?.(graphUrl, source, destination);
+    if (!result) {
+      return err(`Method "copy" not implemented`);
+    }
+    return result;
+  }
+
+  async move(
+    graphUrl: string,
+    source: FileSystemPath,
+    destination: FileSystemPath
+  ): Promise<FileSystemWriteResult> {
+    const result = this.backend.move?.(graphUrl, source, destination);
+    if (!result) {
+      return err(`Method "move" not implemented`);
+    }
+    return result;
+  }
+
+  async onEndRun(): Promise<void> {
+    return this.backend.onEndRun?.();
+  }
+}

package/src/breadboard/engine/file-system/path.ts

@@ -0,0 +1,125 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  FileSystemPath,
+  FileSystemReadWritePath,
+  Outcome,
+} from "@breadboard-ai/types";
+import { err, ok } from "@breadboard-ai/utils";
+
+export { Path };
+
+const PATH_SEPARATOR = "/";
+
+type RootDirSpec = {
+  name: string;
+  writable: boolean;
+  /**
+   * Set to true when the files in this directory are persisted across the
+   * lifetime of the FileSystem instance. In other words, they aren't part
+   * of FileSystem's in-memory store.
+   */
+  persistent: boolean;
+  /**
+   * Set to true when the files in this directory come from mounted sources.
+   * These files might not actually be files, but rather file-shaped objects
+   * that the system supplies.
+   */
+  mounted: boolean;
+};
+
+const ROOT_DIRS: readonly RootDirSpec[] = [
+  { name: "local", writable: true, persistent: true, mounted: false },
+  { name: "mnt", writable: true, persistent: false, mounted: true },
+  { name: "session", writable: true, persistent: false, mounted: false },
+  { name: "run", writable: true, persistent: false, mounted: false },
+  { name: "tmp", writable: true, persistent: false, mounted: false },
+  { name: "env", writable: false, persistent: false, mounted: false },
+  { name: "assets", writable: false, persistent: false, mounted: false },
+] as const;
+
+export function writablePathFromString(
+  s: string
+): Outcome<FileSystemReadWritePath> {
+  const path = Path.create(s as FileSystemPath);
+  if (!ok(path)) return path;
+  if (!path.writable) {
+    return err(`Path "${s}" is not writable`);
+  }
+  return s as FileSystemReadWritePath;
+}
+
+class Path {
+  static roots = new Set(ROOT_DIRS.map((item) => item.name));
+  static writableRoots = new Set(
+    ROOT_DIRS.filter((item) => item.writable).map((item) => item.name)
+  );
+  static persistentRoots = new Set(
+    ROOT_DIRS.filter((item) => item.persistent).map((item) => item.name)
+  );
+  static mountedRoots = new Set(
+    ROOT_DIRS.filter((item) => item.mounted).map((item) => item.name)
+  );
+
+  readonly writable: boolean;
+  readonly persistent: boolean;
+  readonly mounted: boolean;
+
+  constructor(
+    public readonly root: string,
+    public readonly path: string[],
+    public readonly dir: boolean
+  ) {
+    this.writable = Path.writableRoots.has(this.root);
+    this.persistent = Path.persistentRoots.has(this.root);
+    this.mounted = Path.mountedRoots.has(this.root);
+  }
+
+  static createRoots(): Path[] {
+    return ROOT_DIRS.map((item) => {
+      return new Path(item.name, [], true);
+    });
+  }
+
+  static create(path: FileSystemPath): Outcome<Path> {
+    const components = path.split(PATH_SEPARATOR);
+    const [leading, root, ...rest] = components;
+    const isDir = rest.at(-1)?.length === 0;
+
+    const validationResult = validate();
+    if (!ok(validationResult)) {
+      return validationResult;
+    }
+    return new Path(root, isDir ? rest.slice(0, -1) : rest, isDir);
+
+    function validate(): Outcome<void> {
+      if (leading.length !== 0)
+        return {
+          $error: `Invalid path "${path}": all paths must start with a slash`,
+        };
+      if (!Path.roots.has(root))
+        return {
+          $error: `Invalid path "${path}": unknown root directory`,
+        };
+      if (rest.length === 0)
+        return {
+          $error: `Invalid path "${path}": when pointing at a root directory, add a slash`,
+        };
+      for (const [i, fragment] of rest.entries()) {
+        if (fragment.length === 0) {
+          // Only last fragment can be empty (trailing slash)
+          if (i !== rest.length - 1) {
+            return {
+              $error: `Invalid path "${path}": paths may not contain empty fragments`,
+            };
+          }
+        }
+      }
+    }
+  }
+}

package/src/breadboard/engine/file-system/persistent-file.ts

@@ -0,0 +1,66 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  FileSystemFile,
+  FileSystemPath,
+  FileSystemQueryEntry,
+  FileSystemReadResult,
+  FileSystemWriteResult,
+  LLMContent,
+  Outcome,
+  PersistentBackend,
+} from "@breadboard-ai/types";
+import { ok } from "@breadboard-ai/utils";
+import { noStreams, readFromStart } from "./utils.js";
+
+export { PersistentFile };
+
+class PersistentFile implements FileSystemFile {
+  constructor(
+    public readonly graphUrl: string,
+    public readonly path: FileSystemPath,
+    public readonly backend: PersistentBackend
+  ) {}
+
+  async read(
+    inflate: boolean,
+    start: number = 0
+  ): Promise<FileSystemReadResult> {
+    const reading = await this.backend.read(this.graphUrl, this.path, inflate);
+    if (!ok(reading)) {
+      return reading;
+    }
+    return readFromStart(this.path, reading, start);
+  }
+
+  async append(
+    data: LLMContent[],
+    done: boolean,
+    receipt?: boolean
+  ): Promise<FileSystemWriteResult> {
+    const checkForStreams = noStreams(done, receipt);
+    if (!ok(checkForStreams)) {
+      return checkForStreams;
+    }
+    return this.backend.append(this.graphUrl, this.path, data);
+  }
+
+  copy(): Outcome<FileSystemFile> {
+    throw new Error("Method not implemented.");
+  }
+
+  queryEntry(_path: FileSystemPath): FileSystemQueryEntry {
+    throw new Error("Method not implemented.");
+  }
+
+  delete(): Promise<FileSystemWriteResult> {
+    throw new Error("Method not implemented.");
+  }
+
+  data: LLMContent[] = [];
+}

package/src/breadboard/engine/file-system/readable-stream-file.ts

@@ -0,0 +1,61 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  FileSystemFile,
+  FileSystemPath,
+  FileSystemQueryEntry,
+  FileSystemReadResult,
+  FileSystemWriteResult,
+  LLMContent,
+  Outcome,
+} from "@breadboard-ai/types";
+import { err } from "@breadboard-ai/utils";
+
+export { ReadableStreamFile };
+
+class ReadableStreamFile implements FileSystemFile {
+  readonly data: LLMContent[] = [];
+
+  constructor(public readonly stream: ReadableStream<LLMContent>) {}
+
+  async read(_inflate: boolean, start?: number): Promise<FileSystemReadResult> {
+    if (start !== undefined && start !== 0) {
+      return err(`Reading partial streams is not supported.`);
+    }
+
+    const reader = this.stream.getReader();
+    try {
+      const { value, done } = await reader.read();
+      return { data: value ? [value] : [], done };
+    } catch (e) {
+      const error = e as Error;
+      if (error.name === "AbortError") {
+        return err(`Run stopped`);
+      }
+      return err(`Unable to read stream: ${(e as Error).message}`);
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  async append(): Promise<Outcome<void>> {
+    return err(`Can't write to a read-only stream`);
+  }
+
+  copy(): Outcome<FileSystemFile> {
+    return err(`Copying read-only streams is not supported`);
+  }
+
+  queryEntry(path: FileSystemPath): FileSystemQueryEntry {
+    return { path, length: 0, stream: true };
+  }
+
+  async delete(): Promise<FileSystemWriteResult> {
+    this.stream.cancel().catch(() => {});
+  }
+}

package/src/breadboard/engine/file-system/stub-file-system.ts

@@ -0,0 +1,47 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  FileSystem,
+  FileSystemEntry,
+  FileSystemQueryResult,
+  FileSystemReadResult,
+  FileSystemWriteResult,
+  Outcome,
+} from "@breadboard-ai/types";
+
+export { StubFileSystem };
+
+class StubFileSystem implements FileSystem {
+  query(): Promise<FileSystemQueryResult> {
+    throw new Error("Attempting to use stubbed-out file system.");
+  }
+  read(): Promise<FileSystemReadResult> {
+    throw new Error("Attempting to use stubbed-out file system.");
+  }
+  write(): Promise<FileSystemWriteResult> {
+    throw new Error("Attempting to use stubbed-out file system.");
+  }
+  addStream(): Promise<Outcome<void>> {
+    throw new Error("Attempting to use stubbed-out file system.");
+  }
+  close(): Promise<void> {
+    throw new Error("Attempting to use stubbed-out file system.");
+  }
+  updateRunFileSystem(): FileSystem {
+    throw new Error("Attempting to use stubbed-out file system.");
+  }
+  createRunFileSystem(): FileSystem {
+    throw new Error("Attempting to use stubbed-out file system.");
+  }
+  createModuleFileSystem(): FileSystem {
+    throw new Error("Attempting to use stubbed-out file system.");
+  }
+  env(): FileSystemEntry[] {
+    throw new Error("Attempting to use stubbed-out file system.");
+  }
+}

package/src/breadboard/engine/file-system/utils.ts

@@ -0,0 +1,40 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  FileSystemPath,
+  FileSystemReadResult,
+  FileSystemWriteResult,
+  LLMContent,
+} from "@breadboard-ai/types";
+import { err } from "@breadboard-ai/utils";
+
+export { noStreams, readFromStart };
+
+function readFromStart(
+  path: FileSystemPath,
+  data: LLMContent[] | undefined,
+  start: number
+): FileSystemReadResult {
+  if (!data) {
+    return err(`File at "${path}" is empty`);
+  }
+
+  if (start >= data.length) {
+    return err(`Length of file is lesser than start "${start}"`);
+  }
+  return {
+    data: data.slice(start),
+    last: data.length - 1,
+  };
+}
+
+function noStreams(done: boolean, receipt?: boolean): FileSystemWriteResult {
+  if (done || receipt) {
+    return err("Can't close the file that isn't a stream");
+  }
+}

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

@@ -0,0 +1,162 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  InputValues,
+  InspectableEdge,
+  InspectableNode,
+  InspectableNodePorts,
+  InspectableNodeType,
+  InspectablePortList,
+  NodeConfiguration,
+  NodeDescriberResult,
+  NodeDescriptor,
+  NodeMetadata,
+  OutputValues,
+} from "@breadboard-ai/types";
+import { filterBySchema } from "@breadboard-ai/utils";
+import { collectPorts } from "./ports.js";
+import { EdgeType, describeInput } from "./schemas.js";
+
+/**
+ * This is a special kind of an `InspectableNode`, representing a bubbled
+ * node instance. Its key difference is that, when it's type = input,
+ * it will narrow down the ports and values to only the ones that bubbled up.
+ * For instance, the actual input node might have four parameters, but
+ * only one of them bubbled up. This node will make sure that it looks as if
+ * it only has that one parameter.
+ */
+export class BubbledInspectableNode implements InspectableNode {
+  descriptor: NodeDescriptor;
+  #actual: InspectableNode;
+
+  constructor(actual: InspectableNode) {
+    const descriptor = actual.descriptor;
+    if (descriptor.type !== "input" && descriptor.type !== "output") {
+      throw new Error(
+        "BubbledInspectableNode can only be an input or an output"
+      );
+    }
+    this.#actual = actual;
+    this.descriptor = descriptor;
+  }
+
+  title(): string {
+    return this.#actual.title();
+  }
+
+  description(): string {
+    return this.#actual.description();
+  }
+
+  incoming(): InspectableEdge[] {
+    return this.#actual.incoming();
+  }
+
+  outgoing(): InspectableEdge[] {
+    return this.#actual.outgoing();
+  }
+
+  isEntry(): boolean {
+    return this.#actual.isEntry();
+  }
+
+  isExit(): boolean {
+    return this.#actual.isExit();
+  }
+
+  isStart(): boolean {
+    return this.#actual.isStart();
+  }
+
+  type(): InspectableNodeType {
+    return this.#actual.type();
+  }
+
+  configuration(): NodeConfiguration {
+    return this.#actual.configuration();
+  }
+
+  metadata(): NodeMetadata {
+    return this.#actual.metadata();
+  }
+
+  async describe(): Promise<NodeDescriberResult> {
+    if (this.descriptor.type === "input") {
+      return describeInput({ inputs: this.#actual.configuration() });
+    }
+    return this.#actual.describe();
+  }
+
+  currentDescribe(): NodeDescriberResult {
+    if (this.descriptor.type === "input") {
+      return describeInput({ inputs: this.#actual.configuration() });
+    }
+
+    return this.#actual.currentDescribe();
+  }
+
+  #portsForInput(inputValues?: InputValues, outputValues?: OutputValues) {
+    const described = describeInput({ inputs: inputValues });
+
+    const bubbledValues = filterBySchema(
+      outputValues || {},
+      described.outputSchema
+    );
+    const inputs: InspectablePortList = {
+      fixed: described.inputSchema.additionalProperties === false,
+      ports: collectPorts(
+        EdgeType.In,
+        this.incoming(),
+        described.inputSchema,
+        false,
+        true,
+        inputValues
+      ),
+    };
+    const outputs: InspectablePortList = {
+      fixed: described.outputSchema.additionalProperties === false,
+      ports: collectPorts(
+        EdgeType.Out,
+        [],
+        described.outputSchema,
+        false,
+        false,
+        bubbledValues
+      ),
+    };
+    const side: InspectablePortList = {
+      fixed: true,
+      ports: [],
+    };
+    return { inputs, outputs, side, updating: false };
+  }
+
+  async ports(
+    inputValues?: InputValues | undefined,
+    outputValues?: OutputValues | undefined
+  ): Promise<InspectableNodePorts> {
+    if (this.descriptor.type === "input") {
+      return this.#portsForInput(inputValues, outputValues);
+    }
+    return this.#actual.ports(inputValues, outputValues || undefined);
+  }
+
+  currentPorts(
+    inputValues?: InputValues,
+    outputValues?: OutputValues
+  ): InspectableNodePorts {
+    if (this.descriptor.type === "input") {
+      return this.#portsForInput(inputValues, outputValues);
+    }
+    return this.#actual.currentPorts(inputValues, outputValues);
+  }
+
+  deleted(): boolean {
+    return this.#actual.deleted();
+  }
+}

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

@@ -0,0 +1,78 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  AffectedNode,
+  DescribeResultCacheArgs,
+  GraphIdentifier,
+  InspectableDescriberResultCache,
+  InspectableDescriberResultCacheEntry,
+  NodeDescriberResult,
+  NodeIdentifier,
+} from "@breadboard-ai/types";
+import {
+  hash,
+  SnapshotUpdater,
+  SnapshotUpdaterArgs,
+} from "@breadboard-ai/utils";
+
+export { DescribeResultCache };
+
+type MapItem = SnapshotUpdater<NodeDescriberResult>;
+
+class DescribeResultCache implements InspectableDescriberResultCache {
+  #map = new Map<number, MapItem>();
+
+  constructor(public readonly args: DescribeResultCacheArgs) {}
+
+  #createSnapshotArgs(graphId: GraphIdentifier, nodeId: NodeIdentifier) {
+    return {
+      initial: () => this.args.initial(graphId, nodeId),
+      latest: () => this.args.latest(graphId, nodeId),
+      willUpdate: (previous, current) =>
+        this.args.willUpdate(previous, current),
+      updated: () => {
+        this.args.updated(graphId, nodeId);
+      },
+    } as SnapshotUpdaterArgs<NodeDescriberResult>;
+  }
+
+  get(
+    id: NodeIdentifier,
+    graphId: GraphIdentifier
+  ): InspectableDescriberResultCacheEntry {
+    const hash = computeHash({ id, graphId });
+    let result = this.#map.get(hash);
+    if (result) {
+      return result.snapshot();
+    }
+    result = new SnapshotUpdater(this.#createSnapshotArgs(graphId, id));
+    this.#map.set(hash, result);
+    return result.snapshot();
+  }
+
+  update(affectedNodes: AffectedNode[]) {
+    affectedNodes.forEach((affected) => {
+      const hash = computeHash(affected);
+      this.#map.get(hash)?.refresh();
+    });
+  }
+
+  clear(visualOnly: boolean, affectedNodes: AffectedNode[]) {
+    if (visualOnly) {
+      return;
+    }
+    affectedNodes.forEach((node) => {
+      const hash = computeHash(node);
+      this.#map.delete(hash);
+    });
+  }
+}
+
+function computeHash(node: AffectedNode): number {
+  return hash(node);
+}