@google-labs/breadboard - npm Package Compare versions

Comparing version 0.2.0 to 0.3.0

dist/src/board.d.ts

@@ -6,14 +6,8 @@ /**
  */
-import type { Edge, NodeDescriptor, InputValues, GraphDescriptor, OutputValues, NodeHandler } from "@google-labs/graph-runner";
+import type { Edge, NodeDescriptor, InputValues, GraphDescriptor, OutputValues, NodeHandler, GraphMetadata } from "@google-labs/graph-runner";
 import { type Breadboard, type BreadboardSlotSpec, type Kit, type KitConstructor, type OptionalIdConfiguration, type BreadboardValidator, BreadboardNode, ReflectNodeOutputs, IncludeNodeInputs, SlotNodeInputs } from "./types.js";
 import { Node } from "./node.js";
 import { RunResult } from "./run.js";
+import { runRemote } from "./remote.js";
 /**
- * @todo Make this just take a $ref and figure out when it's a path or a URL.
- * @param path
- * @param ref
- * @returns
- */
-export declare const loadGraph: (path?: string, ref?: string) => Promise<any>;
-/**
  * This is the heart of the Breadboard library.
@@ -33,2 +27,6 @@ * Just like for hardware makers, the `Board` is the place where wiring of
     #private;
+    url?: string;
+    title?: string;
+    description?: string;
+    version?: string;
     edges: Edge[];
@@ -38,2 +36,8 @@ nodes: NodeDescriptor[];
     /**
+     *
+     * @param metadata - optional metadata for the board. Use this parameter
+     * to provide title, description, version, and URL for the board.
+     */
+    constructor(metadata?: GraphMetadata);
+    /**
      * Runs the board. This method is an async generator that
@@ -53,10 +57,13 @@ * yields the results of each stage of the run.
      *
-     * The `stop` iterator result will have the following properties:
+     * The `stop` iterator result will be a `RunResult` and provide ability
+     * to influence running of the board.
      *
-     * - `seeksInputs`: boolean - returns `true` if the board is waiting for
-     *  input values. Returns `false` if the board is providing outputs.
-     * - `inputs`: InputValues - the input values the board is waiting for. Set this property to provide input values. This property is only available when `seeksInputs` is `true`.
-     * - `inputArguments`: InputValues - any arguments that were passed to the `input` node that triggered this stage. Usually contains `message` property, which is a friendly message to the user about what input is expected. This property is only available when `seeksInputs` is `true`.
-     * - `outputs`: OutputValues - the output values the board is providing. This property is only available when `seeksInputs` is `false`.
+     * The two key use cases are providing input and receiving output.
      *
+     * If `stop.type` is `input`, the board is waiting for input values.
+     * When that is the case, use `stop.inputs` to provide input values.
+     *
+     * If `stop.type` is `output`, the board is providing output values.
+     * When that is the case, use `stop.outputs` to receive output values.
+     *
      * See [Chapter 8: Continuous runs](https://github.com/google/labs-prototypes/tree/main/seeds/breadboard/docs/tutorial#chapter-8-continuous-runs) of Breadboard tutorial for an example of how to use this method.
@@ -114,7 +121,6 @@ *
      *
-     * @param message - a friendly message to the user about what input is expected. For example, "What is the question you'd like to have answered?".
      * @param config - optional configuration for the node.
      * @returns - a `Node` object that represents the placed node.
      */
-    input<In = InputValues, Out = OutputValues>(message?: string, config?: OptionalIdConfiguration): Node<In, Out>;
+    input<In = InputValues, Out = OutputValues>(config?: OptionalIdConfiguration): Node<In, Out>;
     /**
@@ -252,8 +258,12 @@ * Places an `output` node on the board.
      *
-     * @param $ref - the URL or a file path to the board.
+     * @param url - the URL or a file path to the board.
      * @param slots - optional slots to provide to the board.
      * @returns - a new `Board` instance.
      */
-    static load($ref: string, slots?: BreadboardSlotSpec): Promise<Board>;
+    static load(url: string, options?: {
+        slotted?: BreadboardSlotSpec;
+        base?: string;
+    }): Promise<Board>;
+    static runRemote: typeof runRemote;
 }
 //# sourceMappingURL=board.d.ts.map

dist/src/board.js

@@ -9,5 +9,7 @@ /**
 import { Core } from "./core.js";
-import { InputStageResult, OutputStageResult } from "./run.js";
+import { BeforeHandlerStageResult, InputStageResult, OutputStageResult, } from "./run.js";
 import { KitLoader } from "./kit.js";
 import { IdVendor } from "./id.js";
+import { BoardLoader } from "./loader.js";
+import { runRemote } from "./remote.js";
 class ProbeEvent extends CustomEvent {
@@ -18,20 +20,2 @@ constructor(type, detail) {
 }
-/**
- * @todo Make this just take a $ref and figure out when it's a path or a URL.
- * @param path
- * @param ref
- * @returns
- */
-export const loadGraph = async (path, ref) => {
-    if (path && typeof process === "undefined")
-        throw new Error("Unable to use `path` when not running in node");
-    if (path) {
-        const { readFile } = await import("node:fs/promises");
-        return JSON.parse(await readFile(path, "utf-8"));
-    }
-    if (!ref)
-        throw new Error("To include, we need a path or a $ref");
-    const response = await fetch(ref);
-    return await response.json();
-};
 const nodeTypeVendor = new IdVendor();
@@ -65,2 +49,6 @@ class LocalKit {
 export class Board {
+    url;
+    title;
+    description;
+    version;
     edges = [];
@@ -73,2 +61,11 @@ nodes = [];
     /**
+     *
+     * @param metadata - optional metadata for the board. Use this parameter
+     * to provide title, description, version, and URL for the board.
+     */
+    constructor(metadata) {
+        const { url, title, description, version } = metadata || {};
+        Object.assign(this, { url, title, description, version });
+    }
+    /**
      * Runs the board. This method is an async generator that
@@ -88,10 +85,13 @@ * yields the results of each stage of the run.
      *
-     * The `stop` iterator result will have the following properties:
+     * The `stop` iterator result will be a `RunResult` and provide ability
+     * to influence running of the board.
      *
-     * - `seeksInputs`: boolean - returns `true` if the board is waiting for
-     *  input values. Returns `false` if the board is providing outputs.
-     * - `inputs`: InputValues - the input values the board is waiting for. Set this property to provide input values. This property is only available when `seeksInputs` is `true`.
-     * - `inputArguments`: InputValues - any arguments that were passed to the `input` node that triggered this stage. Usually contains `message` property, which is a friendly message to the user about what input is expected. This property is only available when `seeksInputs` is `true`.
-     * - `outputs`: OutputValues - the output values the board is providing. This property is only available when `seeksInputs` is `false`.
+     * The two key use cases are providing input and receiving output.
      *
+     * If `stop.type` is `input`, the board is waiting for input values.
+     * When that is the case, use `stop.inputs` to provide input values.
+     *
+     * If `stop.type` is `output`, the board is providing output values.
+     * When that is the case, use `stop.outputs` to receive output values.
+     *
      * See [Chapter 8: Continuous runs](https://github.com/google/labs-prototypes/tree/main/seeds/breadboard/docs/tutorial#chapter-8-continuous-runs) of Breadboard tutorial for an example of how to use this method.
@@ -143,2 +143,3 @@ *
             };
+            yield new BeforeHandlerStageResult(result);
             const shouldInvokeHandler = !probe ||
@@ -174,6 +175,6 @@ probe.dispatchEvent(new ProbeEvent("beforehandler", beforehandlerDetail));
         for await (const result of this.run(probe, slots)) {
-            if (result.seeksInputs) {
+            if (result.type === "input") {
                 result.inputs = inputs;
             }
-            else {
+            else if (result.type === "output") {
                 outputs = result.outputs;
@@ -222,9 +223,8 @@ // Exit once we receive the first output.
      *
-     * @param message - a friendly message to the user about what input is expected. For example, "What is the question you'd like to have answered?".
      * @param config - optional configuration for the node.
      * @returns - a `Node` object that represents the placed node.
      */
-    input(message, config = {}) {
+    input(config = {}) {
         const { $id, ...rest } = config;
-        return new Node(this, "input", { message, ...rest }, $id);
+        return new Node(this, "input", { ...rest }, $id);
     }
@@ -398,3 +398,3 @@ /**
     static async fromGraphDescriptor(graph) {
-        const breadboard = new Board();
+        const breadboard = new Board(graph);
         breadboard.edges = graph.edges;
@@ -409,15 +409,16 @@ breadboard.nodes = graph.nodes;
      *
-     * @param $ref - the URL or a file path to the board.
+     * @param url - the URL or a file path to the board.
      * @param slots - optional slots to provide to the board.
      * @returns - a new `Board` instance.
      */
-    static async load($ref, slots) {
-        const url = new URL($ref, new URL(import.meta.url));
-        const path = url.protocol === "file:" ? $ref : undefined;
-        const graph = await loadGraph(path, $ref);
+    static async load(url, options) {
+        const { base, slotted } = options || {};
+        const loader = new BoardLoader(base);
+        const graph = await loader.load(url);
         const board = await Board.fromGraphDescriptor(graph);
-        board.#slots = slots || {};
+        board.#slots = slotted || {};
         return board;
     }
+    static runRemote = runRemote;
 }
 //# sourceMappingURL=board.js.map

dist/src/core.js

@@ -31,2 +31,10 @@ /**
         const { path, $ref, graph, slotted, parent, ...args } = inputs;
+        // Add the current graph's URL as the url of the slotted graph,
+        // if there isn't an URL already.
+        const slottedWithUrls = {};
+        if (slotted) {
+            for (const key in slotted) {
+                slottedWithUrls[key] = { url: this.#graph.url, ...slotted[key] };
+            }
+        }
         // TODO: Please fix the $ref/path mess.
@@ -36,3 +44,6 @@ const source = path || $ref || "";
             ? await Board.fromGraphDescriptor(graph)
-            : await Board.load(source, slotted);
+            : await Board.load(source, {
+                slotted: slottedWithUrls,
+                base: this.#graph.url,
+            });
         for (const validator of this.#validators)
@@ -39,0 +50,0 @@ board.addValidator(validator.getSubgraphValidator(parent, Object.keys(args)));

dist/src/index.d.ts

@@ -11,3 +11,3 @@ /**
 export { RunResult } from "./run.js";
-export type { ProbeEvent, Kit, NodeFactory, BreadboardValidator, BreadboardValidatorMetadata, BreadboardSlotSpec, BreadboardNode, OptionalIdConfiguration, } from "./types.js";
+export type { ProbeEvent, Kit, NodeFactory, BreadboardValidator, BreadboardValidatorMetadata, BreadboardSlotSpec, BreadboardNode, OptionalIdConfiguration, RunResultType, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

dist/src/run.d.ts

@@ -7,3 +7,3 @@ /**
 import { type InputValues, type NodeDescriptor, type OutputValues, type TraversalResult } from "@google-labs/graph-runner";
-import type { BreadbordRunResult as BreadboardRunResult } from "./types.js";
+import type { BreadboardRunResult, RunResultType } from "./types.js";
 export declare const replacer: (key: string, value: unknown) => unknown;
@@ -19,4 +19,4 @@ export declare const reviver: (key: string, value: {
     #private;
-    constructor(state: TraversalResult, seeksInputs: boolean);
-    get seeksInputs(): boolean;
+    constructor(state: TraversalResult, type: RunResultType);
+    get type(): RunResultType;
     get node(): NodeDescriptor;
@@ -29,2 +29,3 @@ get inputArguments(): InputValues;
     save(): string;
+    isAtExitNode(): boolean;
     static load(stringifiedResult: string): RunResult;
@@ -41,2 +42,7 @@ }
 }
+export declare class BeforeHandlerStageResult extends RunResult {
+    constructor(state: TraversalResult);
+    get inputArguments(): InputValues;
+    set inputs(inputs: InputValues);
+}
 //# sourceMappingURL=run.d.ts.map

dist/src/run.js

@@ -22,10 +22,10 @@ /**
 export class RunResult {
-    #seeksInputs;
+    #type;
     #state;
-    constructor(state, seeksInputs) {
+    constructor(state, type) {
         this.#state = state;
-        this.#seeksInputs = seeksInputs;
+        this.#type = type;
     }
-    get seeksInputs() {
-        return this.#seeksInputs;
+    get type() {
+        return this.#type;
     }
@@ -51,8 +51,12 @@ get node() {
     save() {
-        return JSON.stringify({ state: this.#state, seeksInputs: this.#seeksInputs }, replacer);
+        return JSON.stringify({ state: this.#state, type: this.#type }, replacer);
     }
+    isAtExitNode() {
+        return (this.#state.newOpportunities.length === 0 &&
+            this.#state.opportunities.length === 0);
+    }
     static load(stringifiedResult) {
-        const { state, seeksInputs } = JSON.parse(stringifiedResult, reviver);
+        const { state, type } = JSON.parse(stringifiedResult, reviver);
         const machineResult = MachineResult.fromObject(state);
-        return new RunResult(machineResult, seeksInputs);
+        return new RunResult(machineResult, type);
     }
@@ -62,6 +66,6 @@ }
     constructor(state) {
-        super(state, true);
+        super(state, "input");
     }
     get outputs() {
-        throw new Error("Outputs are not available in the input stage");
+        throw new Error('Outputs are not available in the "input" stage');
     }
@@ -71,8 +75,19 @@ }
     constructor(state) {
-        super(state, false);
+        super(state, "output");
     }
     get inputArguments() {
-        throw new Error("Input arguments are not available in the output stage");
+        throw new Error('Input arguments are not available in the "output" stage');
     }
     set inputs(inputs) {
+        throw new Error('Setting inputs is not available in the "output" stage');
+    }
+}
+export class BeforeHandlerStageResult extends RunResult {
+    constructor(state) {
+        super(state, "beforehandler");
+    }
+    get inputArguments() {
+        throw new Error('Input arguments are not available in the "befoerhandler" stage');
+    }
+    set inputs(inputs) {
         throw new Error("Setting inputs is not available in the output stage");
@@ -79,0 +94,0 @@ }

dist/src/types.d.ts

@@ -11,4 +11,10 @@ /**
 export type BreadboardSlotSpec = Record<string, GraphDescriptor>;
-export interface BreadbordRunResult {
+export type RunResultType = "input" | "output" | "beforehandler";
+export interface BreadboardRunResult {
     /**
+     * Type of the run result. This property indicates where the board
+     * currently is in the `run` process.
+     */
+    type: RunResultType;
+    /**
      * The current node that is being visited. This property can be used to get
@@ -20,7 +26,2 @@ * information about the current node, such as its id, type, and
     /**
-     * Returns `true` if the board is waiting for
-     * input values. Returns `false` if the board is providing outputs.
-     */
-    get seeksInputs(): boolean;
-    /**
      * Any arguments that were passed to the `input` node that triggered this
@@ -30,3 +31,3 @@ * stage.
      * to the user about what input is expected.
-     * This property is only available when `seeksInputs` is `true`.
+     * This property is only available when `ResultRunType` is `input`.
      */
@@ -37,3 +38,3 @@ get inputArguments(): InputValues;
      * Set this property to provide input values.
-     * This property is only available when `seeksInputs` is `true`.
+     * This property is only available when `ResultRunType` is `input`.
      */
@@ -43,3 +44,3 @@ set inputs(input: InputValues);
      * the output values the board is providing.
-     * This property is only available when `seeksInputs` is `false`.
+     * This property is only available when `ResultRunType` is `output`.
      */
@@ -46,0 +47,0 @@ get outputs(): OutputValues;

package.json

 {
   "name": "@google-labs/breadboard",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A library for rapid generative AI application prototyping",
@@ -48,6 +48,8 @@ "main": "./dist/src/index.js",
     "ava": "^5.2.0",
+    "typedoc": "^0.25.1",
+    "typedoc-plugin-markdown": "^3.16.0",
     "typescript": "^5.0.4"
   },
   "dependencies": {
-    "@google-labs/graph-runner": "^0.1.0"
+    "@google-labs/graph-runner": "^0.2.0"
   },
@@ -54,0 +56,0 @@ "engines": {

README.md

@@ -25,3 +25,3 @@ # Breadboard
 
-You will also likely need the [LLM Starter Kit](https://github.com/google/labs-prototypes/tree/main/seeds/llm-starter):
+You will also need the [LLM Starter Kit](https://github.com/google/labs-prototypes/tree/main/seeds/llm-starter):
 
@@ -32,2 +32,5 @@ ```sh
 
+The LLM Starter Kit comes with Breadboard nodes helpful for building LLM-based applications including the
+[promptTemplate node](https://github.com/google/labs-prototypes/tree/main/seeds/llm-starter#the-prompttemplate-node), [append node](https://github.com/google/labs-prototypes/tree/main/seeds/llm-starter#the-append-node), [generateText node](https://github.com/google/labs-prototypes/tree/main/seeds/llm-starter#the-generatetext-node), and more.
+
 ## Using breadboard
@@ -34,0 +37,0 @@

No alert changes

Improved metrics

Total package byte prevSize

105907

increased by11.15%

Number of package files

54

increased by17.39%

Lines of code

1676

increased by13.4%

Number of lines in readme file

158

increased by1.94%

Worsened metrics

Dev dependency count

9

increased by28.57%

Number of medium supply chain risk alerts

2

increased by100%

Dependency changes

• + Added@google-labs/graph-runner@0.2.0(transitive)

• - Removed@google-labs/graph-runner@0.1.0(transitive)

• Updated@google-labs/graph-runner@^0.2.0