Necessity to pass all input and output references to build function

[Mearman]

It seems unnecessary to have to explicitly pass all of the inputs and outputs to the board function.
Before, as long as a node that was part of the graph was serialised, you got the whole graph.

example of all inputs and outputs explicitly having to be passed to the board build function

const inputOne = input();
const inputTwo = input();
const inputThree = input();

const pass = passthrough({
  one: inputOne,
  two: inputTwo,
  three: inputThree,
});

board({
  inputs: {
    one: inputOne,
    two: inputTwo,
    three: inputThree,
  },
  outputs: {
    one: output(pass.outputs.one),
    two: output(pass.outputs.two),
    three: output(pass.outputs.three),
  },
});

examples with old serialisation method

const inputs = base.input({
  schema: {
    type: "object",
    properties: {
      one: {},
      two: {},
      three: {},
    },
  },
});

const passThroughNode = core.passthrough(inputs);
const outputNode = base.output(passThroughNode)

const serialised = await passThroughNode.serialize();

const passThroughNode = core.passthrough({
  one: input(),
  two: input(),
  three: input(),
});

base.output({
  one: passThroughNode.one,
  two: passThroughNode.two,
  three: passThroughNode.three,
});

const serialised = await passThroughNode.serialize();

const serialised = await (base.output(
  core.passthrough(
    base.input({
      schema: {
        type: "object",
        properties: {
          one: {},
          two: {},
          three: {},
        },
      },
    })
  )
)).serialize();

[Mearman]

I realised it also prevents the use use of inline inputs. such as:

const outputValue = output(
  passthrough({
    inputValue: input({
      title: "Value",
      type: "string",
      default: "Hello, World!",
    }),
  }).outputs.inputValue
  );

[Mearman]

ok. these are the causes. this much hand holding is getting in the way of actually writing a board.

breadboard/packages/build/src/internal/board/serialize.ts

Lines 266 to 269 in 6ada218

	errors.push(
	`Board input "${inputObjectsToInputNodeInfo.get(input)!.portName}" ` +
	`is not reachable from any of its outputs.`
	);

breadboard/packages/build/src/internal/board/serialize.ts

Lines 386 to 389 in 6ada218

	errors.push(
	`${thisNodeId}:${portName} was wired to an input, ` +
	`but that input was not provided to the board inputs.`
	);

If the input or output has been declared and is part of the graph, it will be emitted with the serialisation.
This "strict" behaviour should be behind a flag that is explicitly enabled.

[Mearman]

Also I think using input function currently prevents having multiple input nodes.

[aomarks]

Hello!

The reason you have to tell the board function about your inputs directly is that it allows TypeScript to understand at compile time what the signature of the board definition is. That's important because in addition to being able to serialize a board definition, you can also call it as a function, giving you an instance which you can then use like a node within another board (caveat: this way of composing/nesting boards isn't actually fully supported yet, but it's on my radar and I plan to make it work soon). And we want to be able to validate at compile time that the inputs and outputs of those nodes are correctly typed.

If you want multiple input nodes, you can set the id property when describing the board. I apologize for not documenting this yet, but here's an example from the tests: https://github.com/breadboard-ai/breadboard/blob/main/packages/build/src/test/input_test.ts#L228

Hope that helps, let me know if anything is unclear or you have more questions. I will also prioritize expanding the documentation.

[Mearman]

Ahhh I saw the id param and forgot to try it!
Is there any reason not to have it just increment the id by default?
As then the board wouldn't be bound to have synchronous inputs.

[aomarks]

1. In Breadboard in general, a board can have N input nodes, and each input node can have N input ports. So, a design goal of the API is to allow the board-author to describe any valid arrangement of input nodes and ports.

2. The best way to think about the special input function is that it returns you "an input port which is not yet bound to any particular input node". It's only when you eventually pass those input objects into the board function that they get assigned to particular input nodes.

3. Is there any reason not to have it just increment the id by default?

   If I understand the question correctly, I think this would mean that the API is limited to describing N input nodes each with exactly 1 input port each, which would mean we wouldn't support the full range of input shapes Breadboard supports as described in (1) above.

   Most boards seem to have one input node, with N input ports. That's the simplest kind of shape for a board, which I would recommend trying to achieve whenever you can. You get that if you call input N times and then just pass them all in as board({inputs: {a,b,c}, ...}).

   So far, I haven't found a need for more complex arrangements, but we do have some boards like that, (agent kit I think?). Would love to see specific cases if this comes up and think about it though. I do think this area of the API is a bit confusing.

[Mearman]

The use-cases for multiple input nodes are similar to the anonymous input node . The more magic node may have the content port fulfilled by the magic node or the second input if needed.

const input = base
  .input({
    schema: {
      type: "object",
      properties: {
        content: {
          type: "string",
        },
      },
    },
  })
  .content.to(
    core.passthrough({
      $metadata: {
        title: "Magic",
      },
    })
  )
  .to(
    core.passthrough({
      $metadata: {
        title: "More Magic",
      },
      content: base.input({
        schema: {
          type: "object",
          properties: {
            content: {
              type: "string",
            },
          },
        },
      }),
    })
  )
  .content.to(base.output());

export default await input.serialize({
  title: "Demo",
});

verbose version

import { base } from "@google-labs/breadboard";
import { core } from "@google-labs/core-kit";

const input = base.input({
  schema: {
    type: "object",
    properties: {
      content: {
        type: "string",
      },
    },
  },
});

const output = base.output();

const magic = core.passthrough({
  $metadata: {
    title: "Magic",
  },
});

const moreMagic = core.passthrough({
  $metadata: {
    title: "More Magic",
  },
  content: base.input({
    schema: {
      type: "object",
      properties: {
        content: {
          type: "string",
        },
      },
    },
  }),
});

input.content.to(magic).to(moreMagic).content.to(output);

export default await input.serialize({
  title: "Demo",
});

how would the equivalent be achieved with build? I also discovered an issue which may be more fundamental in this case whereby it's not possible to have two input nodes with ports of the same name.
This is as close as I can get, but the port is still of the wrong name.

import { board, input, output } from "@breadboard-ai/build";
import { passthrough } from "@google-labs/core-kit";

const content = input({
  type: "string",
});

const magic = passthrough({
  $metadata: {
    title: "Magic",
  },
  content: content,
});

const secondaryInput = input({
  $id: "secondary",
  type: "string",
});

const moreMagic = passthrough({
  $metadata: {
    title: "More Magic",
  },
  content: magic.outputs.content,
  "*": secondaryInput,
});

const contentOutput = output(moreMagic.outputs.content);

export default board({
  title: "Demo 2",
  inputs: {
    content: content,
    secondaryInput,
  },
  outputs: {
    content: contentOutput,
  },
});