@ghchinoy/litflow 0.2.7 → 0.3.0

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

@@ -0,0 +1,338 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  CapabilitiesManagerImpl,
+  invokeDescriber,
+  invokeGraph,
+  invokeMainDescriber,
+} from "../../runtime/legacy.js";
+import type {
+  GraphDescriber,
+  GraphIdentifier,
+  InputValues,
+  InspectableNode,
+  ModuleIdentifier,
+  MutableGraph,
+  NodeDescriberContext,
+  NodeDescriberResult,
+  NodeTypeIdentifier,
+  Outcome,
+  Schema,
+} from "@breadboard-ai/types";
+import {
+  combineSchemas,
+  emptyDescriberResult,
+  err,
+  filterEmptyValues,
+  ok,
+  removeProperty,
+} from "@breadboard-ai/utils";
+import { getModuleId, isModule } from "../utils.js";
+import { ExportsDescriber } from "./exports-describer.js";
+import { GraphDescriptorHandle } from "./graph-descriptor-handle.js";
+import { describeInput, describeOutput } from "./schemas.js";
+
+export { GraphDescriberManager };
+
+/**
+ * Contains all machinery that allows
+ * describing a node or a graph
+ */
+class GraphDescriberManager implements GraphDescriber {
+  private readonly exports: ExportsDescriber;
+
+  private constructor(
+    public readonly handle: GraphDescriptorHandle,
+    public readonly mutable: MutableGraph
+  ) {
+    this.exports = new ExportsDescriber(mutable, (graphId, mutable) => {
+      if (isModule(graphId)) {
+        return new ModuleDescriber(mutable, getModuleId(graphId));
+      }
+      return GraphDescriberManager.create(graphId, mutable);
+    });
+  }
+
+  #nodesByType(type: NodeTypeIdentifier): InspectableNode[] {
+    return this.mutable.nodes.byType(type, this.handle.graphId);
+  }
+
+  async #describeWithStaticAnalysis(): Promise<NodeDescriberResult> {
+    const inputSchemas = (
+      await Promise.all(
+        this.#nodesByType("input")
+          .filter((n) => n.isEntry())
+          .map((input) =>
+            describeInput({
+              inputs: input.configuration(),
+              incoming: input.incoming(),
+              outgoing: input.outgoing(),
+              asType: true,
+            })
+          )
+      )
+    ).map((result) => result.outputSchema);
+
+    const outputSchemas = (
+      await Promise.all(
+        this.#nodesByType("output")
+          .filter((n) => n.isExit())
+          .map((output) =>
+            describeOutput({
+              inputs: output.configuration(),
+              incoming: output.incoming(),
+              outgoing: output.outgoing(),
+              asType: true,
+            })
+          )
+      )
+    )
+      .map((result) =>
+        result.inputSchema.behavior?.includes("bubble")
+          ? null
+          : result.inputSchema
+      )
+      .filter(Boolean) as Schema[];
+
+    const inputSchema = combineSchemas(inputSchemas, (result, schema) => {
+      if (schema.additionalProperties !== false) {
+        result.additionalProperties = true;
+      } else if (!("additionalProperties" in result)) {
+        result.additionalProperties = false;
+      }
+    });
+    const outputSchema = removeProperty(
+      combineSchemas(outputSchemas),
+      "schema"
+    );
+
+    const adjustedResults = this.#presumeContextInOut({
+      inputSchema,
+      outputSchema,
+    });
+    // Do not add export describers when we are in a subgraph.
+    if (this.handle.graphId) return adjustedResults;
+
+    return this.exports.transform(adjustedResults);
+  }
+
+  /**
+   * This is a bit hacky, but it gets the job done.
+   * This function tweaks the result to look like a context in / context out
+   * in cases when the graph being described is a subgraph and the
+   * static analysis yielded nothing.
+   *
+   * Additionally, we scan for parameters in the graph and add them as schema
+   * parameters.
+   *
+   * We use this logic to allow subgraphs that are "custom tools" to
+   * participate as normal steps in the graph.
+   */
+  #presumeContextInOut(result: NodeDescriberResult): NodeDescriberResult {
+    const { inputSchema, outputSchema } = result;
+    if (
+      !inputSchema.properties &&
+      !outputSchema.properties &&
+      this.handle.graphId
+    ) {
+      return filterEmptyValues({
+        ...result,
+        inputSchema: {
+          properties: {
+            context: {
+              type: "array",
+              items: { type: "object", behavior: ["llm-content"] },
+            },
+          },
+        },
+        outputSchema: {
+          properties: {
+            context: {
+              type: "array",
+              items: { type: "object", behavior: ["llm-content"] },
+            },
+          },
+        },
+      });
+    }
+    return result;
+  }
+
+  async #tryDescribingWithCustomDescriber(
+    inputs: InputValues,
+    context?: NodeDescriberContext
+  ): Promise<Outcome<NodeDescriberResult>> {
+    const customDescriber =
+      this.handle.graph().metadata?.describer ||
+      (this.handle.graph().main
+        ? `module:${this.handle.graph().main}`
+        : undefined);
+    if (!customDescriber) {
+      return err("Unable to find custom describer");
+    }
+    // invoke graph
+    try {
+      const { sandbox } = this.mutable.store;
+      if (sandbox && customDescriber.startsWith("module:")) {
+        const { inputSchema, outputSchema } =
+          await this.#describeWithStaticAnalysis();
+
+        const moduleId = customDescriber.slice("module:".length);
+
+        let result;
+        if (this.handle.main() === moduleId) {
+          result = await invokeMainDescriber(
+            context || {},
+            this.mutable,
+            this.mutable.graph,
+            inputs,
+            inputSchema,
+            outputSchema,
+            new CapabilitiesManagerImpl(context),
+            context?.asType || false
+          );
+        } else {
+          result = await invokeDescriber(
+            context || {},
+            moduleId,
+            this.mutable,
+            this.mutable.graph,
+            inputs,
+            inputSchema,
+            outputSchema,
+            new CapabilitiesManagerImpl(context),
+            context?.asType || false
+          );
+        }
+        if (result) {
+          return result;
+        }
+        if (result === false) {
+          return err("Custom describer could not provide results.");
+        }
+      }
+      const base = this.handle.url();
+
+      const loader = this.mutable.store.loader;
+
+      // try loading the describer graph.
+      const loadResult = await loader.load(customDescriber, {
+        base,
+        board: this.handle.graph(),
+        outerGraph: this.handle.graph(),
+      });
+      if (!loadResult.success) {
+        const error = `Could not load custom describer graph ${customDescriber}: ${loadResult.error}`;
+        console.warn(error);
+        return err(error);
+      }
+      const { inputSchema: $inputSchema, outputSchema: $outputSchema } =
+        await this.#describeWithStaticAnalysis();
+      // Remove the artifacts of the describer from the input/output schemas.
+      // TODO: The right fix here is for static describer to not include
+      // describer outputs.
+      // delete $outputSchema.properties?.inputSchema;
+      // delete $outputSchema.properties?.outputSchema;
+      const result = (await invokeGraph(
+        loadResult,
+        { ...inputs, $inputSchema, $outputSchema },
+        {
+          base,
+          kits: [...this.mutable.store.kits],
+          loader,
+        }
+      )) as NodeDescriberResult;
+      if ("$error" in result) {
+        const message = `Error while invoking graph's custom describer`;
+        console.warn(message, result.$error);
+        return err(`${message}: ${JSON.stringify(result.$error)}`);
+      }
+      if (!result.inputSchema || !result.outputSchema) {
+        const message = `Custom describer did not return input/output schemas`;
+        console.warn(message, result);
+        return err(`${message}: ${JSON.stringify(result)}`);
+      }
+      return result;
+    } catch (e) {
+      const message = `Error while invoking graph's custom describer`;
+      console.warn(message, e);
+      return err(`${message}: ${JSON.stringify(e)}`);
+    }
+  }
+
+  async describe(
+    inputs?: InputValues,
+    _inputSchema?: Schema,
+    _outputSchema?: Schema,
+    context?: NodeDescriberContext
+  ): Promise<NodeDescriberResult> {
+    const result = await this.#tryDescribingWithCustomDescriber(
+      inputs || {},
+      context
+    );
+    if (ok(result)) {
+      return result;
+    }
+    const staticResult = await this.#describeWithStaticAnalysis();
+    const graph = this.handle.graph();
+    const metadata: Omit<NodeDescriberResult, "inputSchema" | "outputSchema"> =
+      filterEmptyValues({
+        title: graph.title,
+        description: graph.description,
+        metadata: filterEmptyValues({
+          icon: graph.metadata?.icon,
+          help: graph.metadata?.help,
+          tags: graph.metadata?.tags,
+        }),
+      });
+    return {
+      ...metadata,
+      ...staticResult,
+    };
+  }
+
+  static create(
+    graphId: GraphIdentifier,
+    cache: MutableGraph
+  ): Outcome<GraphDescriberManager> {
+    const handle = GraphDescriptorHandle.create(cache.graph, graphId);
+    if (!handle.success) {
+      return err(handle.error);
+    }
+    return new GraphDescriberManager(handle.result, cache);
+  }
+}
+
+class ModuleDescriber implements GraphDescriber {
+  constructor(
+    public readonly mutable: MutableGraph,
+    public readonly moduleId: ModuleIdentifier
+  ) {}
+
+  async describe(
+    inputs?: InputValues,
+    inputSchema?: Schema,
+    outputSchema?: Schema,
+    context?: NodeDescriberContext
+  ): Promise<NodeDescriberResult> {
+    const result = await invokeDescriber(
+      context || {},
+      this.moduleId,
+      this.mutable,
+      this.mutable.graph,
+      inputs || {},
+      inputSchema,
+      outputSchema,
+      new CapabilitiesManagerImpl(context),
+      context?.asType || false
+    );
+    if (!result) return emptyDescriberResult();
+
+    return result;
+  }
+}

package/src/breadboard/engine/inspector/graph/graph-descriptor-handle.ts

@@ -0,0 +1,73 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { isImperativeGraph, toDeclarativeGraph } from "@breadboard-ai/utils";
+import type {
+  GraphDescriptor,
+  GraphIdentifier,
+  ModuleIdentifier,
+  Result,
+} from "@breadboard-ai/types";
+
+export { GraphDescriptorHandle };
+
+class GraphDescriptorHandle {
+  #graph: GraphDescriptor;
+  #imperativeMain: ModuleIdentifier | undefined;
+  #url: URL | undefined;
+
+  private constructor(
+    graph: GraphDescriptor,
+    public readonly graphId: GraphIdentifier
+  ) {
+    if (isImperativeGraph(graph)) {
+      const { main } = graph;
+      graph = toDeclarativeGraph(graph);
+      this.#imperativeMain = main;
+    }
+    this.#graph = graph;
+    this.#url = maybeURL(graph.url);
+  }
+
+  main() {
+    return this.#imperativeMain;
+  }
+
+  url() {
+    return this.#url;
+  }
+
+  outerGraph() {
+    return this.#graph;
+  }
+
+  graph() {
+    return this.graphId ? this.#graph.graphs![this.graphId]! : this.#graph;
+  }
+
+  static create(
+    graph: GraphDescriptor,
+    graphId: GraphIdentifier
+  ): Result<GraphDescriptorHandle> {
+    if (graphId && !graph.graphs?.[graphId]) {
+      return {
+        success: false,
+        error: `Unable to create a valid GraphDEscriptorHandle: subgraph "${graphId}" is not in the graph.`,
+      };
+    }
+    return { success: true, result: new GraphDescriptorHandle(graph, graphId) };
+  }
+}
+
+function maybeURL(url?: string): URL | undefined {
+  url = url || "";
+  try {
+    return new URL(url);
+  } catch {
+    return undefined;
+  }
+}

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

@@ -0,0 +1,111 @@
+// @ts-nocheck
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describerResultToNodeHandlerMetadata,
+  getGraphHandlerFromMutableGraph,
+} from "../../runtime/legacy.js";
+import type {
+  InspectableNodePorts,
+  InspectableNodeType,
+  MutableGraph,
+  NodeConfiguration,
+  NodeDescriberResult,
+  NodeDescriberWires,
+  NodeHandler,
+  NodeHandlerMetadata,
+  NodeHandlerObject,
+} from "@breadboard-ai/types";
+import { portsFromHandler } from "./ports.js";
+
+export { GraphNodeType };
+
+class GraphNodeType implements InspectableNodeType {
+  #type: string;
+  #metadata: NodeHandlerMetadata | null = null;
+  #handlerPromise: Promise<NodeHandlerObject | undefined> | null = null;
+  #mutable: MutableGraph;
+
+  constructor(type: string, mutable: MutableGraph) {
+    this.#type = type;
+    this.#mutable = mutable;
+    this.#handlerPromise = getGraphHandlerFromMutableGraph(type, mutable);
+  }
+
+  #extractExamples(
+    describeResult: NodeDescriberResult
+  ): NodeConfiguration | undefined {
+    const example = describeResult.inputSchema.examples?.at(0);
+    if (!example) return;
+    try {
+      return JSON.parse(example) as NodeConfiguration;
+    } catch {
+      // eat the error.
+    }
+  }
+
+  async #readMetadata() {
+    const handler = await this.#handlerPromise;
+    const describeResult = await handler?.describe?.(
+      undefined,
+      undefined,
+      undefined,
+      {
+        graphStore: this.#mutable.store,
+        outerGraph: this.#mutable.graph,
+        kits: [...this.#mutable.store.kits],
+        wires: {} as NodeDescriberWires,
+        fileSystem: this.#mutable.store.fileSystem,
+      }
+    );
+    if (
+      describeResult &&
+      describeResult.metadata &&
+      Object.keys(describeResult.metadata).length > 0
+    ) {
+      const example = this.#extractExamples(describeResult);
+      return {
+        ...describeResult.metadata,
+        example,
+        title: describeResult.title,
+        description: describeResult.description,
+      };
+    }
+    if (handler && "metadata" in handler && handler.metadata) {
+      return handler.metadata;
+    }
+    return {
+      title: shortUrlTitle(this.#type),
+    };
+  }
+
+  currentMetadata(): NodeHandlerMetadata {
+    const { current, updating } = this.#mutable.store.types.get(this.#type);
+    const result = describerResultToNodeHandlerMetadata(current, updating);
+    return result;
+  }
+
+  async metadata(): Promise<NodeHandlerMetadata> {
+    this.#metadata ??= await this.#readMetadata();
+    return this.#metadata;
+  }
+
+  type() {
+    return this.#type;
+  }
+
+  async ports(): Promise<InspectableNodePorts> {
+    const handler = await this.#handlerPromise;
+    return portsFromHandler(this.#type, handler as NodeHandler);
+  }
+}
+
+function shortUrlTitle(url: string) {
+  const urlObj = new URL(url);
+  const path = urlObj.pathname.split("/").pop();
+  return path || urlObj.host;
+}