docs

Ironclad · Nov 11, 2023 · 2fd16a2 · 2fd16a2
1 parent d1370cb
commit 2fd16a2
Show file tree

Hide file tree

Showing 14 changed files with 298 additions and 2 deletions.
diff --git a/packages/app/src/assets/node_images/destructure_node.png b/packages/app/src/assets/node_images/destructure_node.png
diff --git a/packages/app/src/hooks/useBuiltInNodeImages.ts b/packages/app/src/hooks/useBuiltInNodeImages.ts
@@ -65,6 +65,7 @@ import sliceNodeImage from '../assets/node_images/slice_node.png';
 import extractMarkdownCodeBlocksImage from '../assets/node_images/extract_markdown_code_blocks_node.png';
 import assembleMessageNodeImage from '../assets/node_images/assemble_message_node.png';
 import urlReferenceNodeImage from '../assets/node_images/url_reference_node.png';
+import destructureNodeImage from '../assets/node_images/destructure_node.png';
 
 export const useBuiltInNodeImages = (): Record<BuiltInNodeType, string> => {
   return {
@@ -133,5 +134,6 @@ export const useBuiltInNodeImages = (): Record<BuiltInNodeType, string> => {
     extractMarkdownCodeBlocks: extractMarkdownCodeBlocksImage,
     assembleMessage: assembleMessageNodeImage,
     urlReference: urlReferenceNodeImage,
+    destructure: destructureNodeImage,
   };
 };
diff --git a/packages/core/src/model/nodes/ChatNode.ts b/packages/core/src/model/nodes/ChatNode.ts
@@ -272,7 +272,7 @@ export class ChatNodeImpl extends NodeImpl<ChatNode> {
         dataType: ['gpt-function', 'gpt-function[]'] as const,
         id: 'functions' as PortId,
         title: 'Functions',
-        description: 'Functions to use in the model.',
+        description: 'Functions to use in the model. To connect multiple functions, use an Array node.',
         coerced: false,
       });
     }

diff --git a/packages/docs/docs/node-reference/assemble-message.mdx b/packages/docs/docs/node-reference/assemble-message.mdx
@@ -0,0 +1,94 @@
+---
+id: assemble-message
+title: Assemble Message Node
+sidebar_label: Assemble Message
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+![Assemble Message Node Screenshot](./assets/assemble-message-node.png)
+
+## Overview
+
+The Assemble Message Node is designed to assemble a single chat message from multiple parts. It is similar to a [Prompt Node](./prompt.mdx), but it works with multimodal models, allowing you to include both text and images in the message. This node is particularly useful when working with multimodal LLMs such as GPT-4 Vision that can process both text and images simultaneously.
+
+The Assemble Message Node can be used in conjunction with the [Image Node](./image.mdx) or [URL Reference Node](./url-reference.mdx) to include images in a message.
+
+The Assemble Message Node outputs a chat message in the same format as a [Prompt Node](./prompt.mdx).
+
+<Tabs
+  defaultValue="inputs"
+  values={[
+    {label: 'Inputs', value: 'inputs'},
+    {label: 'Outputs', value: 'outputs'},
+    {label: 'Editor Settings', value: 'settings'},
+  ]
+}>
+
+<TabItem value="inputs">
+
+## Inputs
+
+| Title  | Data Type                             | Description                                                                                                                                                             | Default Value | Notes                                                                                     |
+| ------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------- |
+| Part N | `string`/`string[]`/`image`/`image[]` | A part of the message to assemble. Arrays connected to inputs will be flattened, so connecting a single `image[]` connection will put multiple images into the message. | N/A           | Dynamic number of input ports based on how many inputs are already connected to the node. |
+
+</TabItem>
+
+<TabItem value="outputs">
+
+## Outputs
+
+| Title   | Data Type      | Description                                                                                                         | Notes                                                                                                                |
+| ------- | -------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Message | `chat-message` | The assembled chat message. The message will be in the same format as a message from a [Prompt Node](./prompt.mdx). | The output will be a chat message containing the assembled data. The type of the message will be the specified type. |
+
+</TabItem>
+
+<TabItem value="settings">
+
+## Editor Settings
+
+| Setting | Description                                                                                               | Default Value | Use Input Toggle | Input Data Type |
+| ------- | --------------------------------------------------------------------------------------------------------- | ------------- | ---------------- | --------------- |
+| Type    | The type of message to assemble. The value should be either 'system', 'user', 'assistant', or 'function'. | 'user'        | Yes              | `string`        |
+
+</TabItem>
+
+</Tabs>
+
+## Example 1: Assemble a user message with text and an image
+
+1. Create an Assemble Message Node and set the Type to 'user'.
+1. Create a [Text Node](./text.mdx) and set the value to "Here is an image:". Connect the output of the Text Node to the first input of the Assemble Message Node.
+1. Create an [Image Node](./image.mdx) and browse for your image. Connect the output of the Image Node to the second input of the Assemble Message Node.
+1. Run the graph. The `Message` output of the Assemble Message Node should contain a user message with the text "Here is an image of a cat:" and the text `(Image)` indicating that an image is included in the message.
+
+![Assemble Message Node Example 1](./assets/assemble-message-node-example-01.png)
+
+## Error Handling
+
+The Assemble Message Node will error if the `Type` input is enabled and is set to an invalid value.
+
+## FAQ
+
+**Q: Can I include multiple images in a message?**
+
+A: Yes, you can include multiple images in a message by connecting multiple input nodes.
+
+**Q: Can I use the Assemble Message Node with a function tool call?**
+
+A: Yes, you can set the Type to 'function' to assemble a function response tool call message. Note that function tool call messages require a Tool Call ID, which can be provided via the `Tool Call ID` input or setting. The output of the tool call is the assembled message content.
+
+**Q: Can I include a function call with an `assistant`-type message?**
+
+A: At this time, only the [Prompt Node](./prompt.mdx) supports function/tool calls with `assistant`-type messages.
+
+## See Also
+
+- [Prompt Node](./prompt.mdx)
+- [Image Node](./image.mdx)
+- [URL Reference Node](./url-reference.mdx)
+- [Array Node](./array.mdx)
+- [Chat Node](./chat.mdx)
diff --git a/packages/docs/docs/node-reference/assets/assemble-message-node-example-01.png b/packages/docs/docs/node-reference/assets/assemble-message-node-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/assemble-message-node.png b/packages/docs/docs/node-reference/assets/assemble-message-node.png
diff --git a/packages/docs/docs/node-reference/assets/destructure-node-example-01.png b/packages/docs/docs/node-reference/assets/destructure-node-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/destructure-node.png b/packages/docs/docs/node-reference/assets/destructure-node.png
diff --git a/packages/docs/docs/node-reference/assets/url-reference-node-example-01.png b/packages/docs/docs/node-reference/assets/url-reference-node-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/url-reference-node-example-02.png b/packages/docs/docs/node-reference/assets/url-reference-node-example-02.png
diff --git a/packages/docs/docs/node-reference/assets/url-reference-node.png b/packages/docs/docs/node-reference/assets/url-reference-node.png
diff --git a/packages/docs/docs/node-reference/destructure.mdx b/packages/docs/docs/node-reference/destructure.mdx
@@ -0,0 +1,98 @@
+---
+id: destructure
+title: Destructure Node
+sidebar_label: Destructure
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+![Destructure Node Screenshot](./assets/destructure-node.png)
+
+## Overview
+
+The Destructure Node is used to extract multiple values from an object or array at once. It uses JSONPath notation to navigate through the input value and extract the values at the specified paths. This node is similar to the [Extract Object Path Node](./extract-object-path.mdx), but it allows you to specify multiple paths and extract multiple values at once, which can be more convenient than using multiple Extract Object Path nodes.
+
+<Tabs
+  defaultValue="inputs"
+  values={[
+    {label: 'Inputs', value: 'inputs'},
+    {label: 'Outputs', value: 'outputs'},
+    {label: 'Editor Settings', value: 'settings'},
+  ]
+}>
+
+<TabItem value="inputs">
+
+## Inputs
+
+| Title  | Data Type | Description                        | Default Value | Notes |
+| ------ | --------- | ---------------------------------- | ------------- | ----- |
+| Object | `object`  | The object to extract values from. | (required)    |       |
+
+</TabItem>
+
+<TabItem value="outputs">
+
+## Outputs
+
+| Title      | Data Type | Description                                                    | Notes                                                                                                                                     |
+| ---------- | --------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| (JSONPath) | `any`     | The value extracted from the object at the corresponding path. | If the value is not found, this port is not ran. The number of outputs is dynamic based on the number of paths specified in the settings. |
+
+</TabItem>
+
+<TabItem value="settings">
+
+## Editor Settings
+
+| Setting | Description                                                                                      | Default Value | Use Input Toggle | Input Data Type |
+| ------- | ------------------------------------------------------------------------------------------------ | ------------- | ---------------- | --------------- |
+| Paths   | One or more JSONPath expressions. Each expression will correspond to an output port of the node. | `['$.value']` | No               | `string[]`      |
+
+</TabItem>
+
+</Tabs>
+
+## Example 1: Extract multiple properties from an object
+
+1. Create an [Object Node](./object.mdx) and set the value to the following:
+
+   ```json
+   {
+     "name": "John Doe",
+     "age": 30,
+     "job": "Engineer"
+   }
+   ```
+
+2. Create a Destructure Node and set the Paths to `$.name`, `$.age`, and `$.job`.
+3. Connect the Object Node to the `Object` input of the Destructure Node.
+4. Run the graph. The Destructure Node should have three outputs: `$.name` with the value `John Doe`, `$.age` with the value `30`, and `$.job` with the value `Engineer`.
+
+![Destructure Node Example 1](./assets/destructure-node-example-01.png)
+
+## Error Handling
+
+If a path is invalid or does not exist in the input object, the corresponding output port will not be run.
+
+## FAQ
+
+**Q: How is the Destructure Node different from the Extract Object Path Node?**
+
+A: The Destructure Node is similar to the Extract Object Path Node, but it allows you to specify multiple paths and extract multiple values at once. This can be more convenient than using multiple Extract Object Path nodes to extract multiple paths. The Destructure Node does not allow you specify a path and extract every value at that path, which is possible with the Extract Object Path Node.
+
+**Q: Can I use the Destructure Node to extract array values?**
+
+A: Yes, you can use the Destructure Node to extract array values, but only with a known length. You can use paths such as `$[0]`, `$[1]`, etc. to extract values from an array. However, you cannot use paths such as `$[*]` or `$[?]` to extract all values from an array.
+
+**Q: What happens if a path does not exist in the input object?**
+
+A: If a path does not exist in the input object, the corresponding output port will not be run.
+
+## See Also
+
+- [Extract Object Path Node](./extract-object-path.mdx)
+- [Object Node](./object.mdx)
+- [Array Node](./array.mdx)
+- [Data Types](../user-guide/data-types.md)
diff --git a/packages/docs/docs/node-reference/url-reference.mdx b/packages/docs/docs/node-reference/url-reference.mdx
@@ -0,0 +1,94 @@
+---
+id: url-reference
+title: URL Reference Node
+sidebar_label: URL Reference
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+![URL Reference Node Screenshot](./assets/url-reference-node.png)
+
+## Overview
+
+The URL Reference Node is used to define a reference to a URL or convert a string into a URL reference. This node is particularly useful when used with the Assemble Message node to define URLs for attachments or images, allowing the LLM to download the image instead of having to upload the image with your chat request.
+
+<Tabs
+  defaultValue="inputs"
+  values={[
+    {label: 'Inputs', value: 'inputs'},
+    {label: 'Outputs', value: 'outputs'},
+    {label: 'Editor Settings', value: 'settings'},
+  ]
+}>
+
+<TabItem value="inputs">
+
+## Inputs
+
+| Title | Data Type | Description                                      | Default Value | Notes                                                                   |
+| ----- | --------- | ------------------------------------------------ | ------------- | ----------------------------------------------------------------------- |
+| URL   | `string`  | The string to be converted into a URL reference. | (empty)       | This input is only available if the `Use URL Input` setting is enabled. |
+
+</TabItem>
+
+<TabItem value="outputs">
+
+## Outputs
+
+| Title         | Data Type | Description                       | Notes |
+| ------------- | --------- | --------------------------------- | ----- |
+| URL Reference | `object`  | A reference to the specified URL. | None  |
+
+</TabItem>
+
+<TabItem value="settings">
+
+## Editor Settings
+
+| Setting       | Description                                                 | Default Value | Use Input Toggle | Input Data Type |
+| ------------- | ----------------------------------------------------------- | ------------- | ---------------- | --------------- |
+| URL           | The URL to be converted into a URL reference.               | (empty)       | Yes              | `string`        |
+| Use URL Input | If enabled, the URL can be provided via the URL input port. | False         | No               | N/A             |
+
+</TabItem>
+
+</Tabs>
+
+## Example 1: Define a URL Reference
+
+1. Create a URL Reference Node.
+2. Set the `URL` setting to the URL you want to reference (e.g., `https://example.com/image.jpg`).
+3. Run the graph. The `URL Reference` output of the URL Reference Node should contain a reference to the specified URL.
+
+![URL Reference Node Example 1](./assets/url-reference-node-example-01.png)
+
+## Example 2: Convert a String into a URL Reference
+
+1. Create a URL Reference Node and enable the `Use URL Input` setting.
+2. Create a [Text Node](./text.mdx) and set the text to the URL you want to reference (e.g., `https://example.com/image.jpg`).
+3. Connect the Text Node to the `URL` input of the URL Reference Node.
+4. Run the graph. The `URL Reference` output of the URL Reference Node should contain a reference to the specified URL.
+
+![URL Reference Node Example 2](./assets/url-reference-node-example-02.png)
+
+## Error Handling
+
+The URL Reference Node cannot error under normal circumstances. If the `URL` input is not provided, the node will use the URL specified in the settings.
+
+## FAQ
+
+**Q: Can I use the URL Reference Node to reference a file on my local machine?**
+
+A: No, the URL Reference Node is intended for referencing URLs on the internet. If you want to reference a file on your local machine, you would need to upload the file to a web server and reference the URL of the uploaded file, or use the Image Node to load the image from your local machine.
+
+**Q: What happens if I provide an invalid URL?**
+
+A: The URL Reference Node does not validate the URL. It simply creates a reference to the provided URL. If the URL is invalid, any nodes that use the URL reference may fail or behave unexpectedly.
+
+## See Also
+
+- [Assemble Message Node](./assemble-message.mdx)
+- [Text Node](./text.mdx)
+- [HTTP Call Node](./http-call.mdx)
+- [Load Image Node](./load-image.mdx)
diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js
@@ -182,6 +182,7 @@ const sidebars = {
       collapsible: true,
       collapsed: false,
       items: [
+        'node-reference/assemble-message',
         'node-reference/assemble-prompt',
         'node-reference/chat',
         'node-reference/gpt-function',
@@ -216,6 +217,7 @@ const sidebars = {
       collapsible: true,
       collapsed: false,
       items: [
+        'node-reference/destructure',
         'node-reference/extract-json',
         'node-reference/extract-object-path',
         'node-reference/extract-yaml',
@@ -227,7 +229,13 @@ const sidebars = {
       label: 'Data',
       collapsible: true,
       collapsed: false,
-      items: ['node-reference/audio', 'node-reference/bool', 'node-reference/hash', 'node-reference/image'],
+      items: [
+        'node-reference/audio',
+        'node-reference/bool',
+        'node-reference/hash',
+        'node-reference/image',
+        'node-reference/url-reference',
+      ],
     },
     {
       type: 'category',