Merge pull request #210 from a-rothwell/main

More Docs
Ironclad · Oct 14, 2023 · dfe5969 · dfe5969
2 parents b9d6b97 + 0320e55
commit dfe5969
Show file tree

Hide file tree

Showing 34 changed files with 784 additions and 47 deletions.
diff --git a/packages/docs/docs/node-reference/assets/subgraph-node-example-01a.png b/packages/docs/docs/node-reference/assets/subgraph-node-example-01a.png
diff --git a/packages/docs/docs/node-reference/assets/subgraph-node-example-01b.png b/packages/docs/docs/node-reference/assets/subgraph-node-example-01b.png
diff --git a/packages/docs/docs/node-reference/assets/subgraph-node-example-02a.png b/packages/docs/docs/node-reference/assets/subgraph-node-example-02a.png
diff --git a/packages/docs/docs/node-reference/assets/subgraph-node-example-02b.png b/packages/docs/docs/node-reference/assets/subgraph-node-example-02b.png
diff --git a/packages/docs/docs/node-reference/assets/subgraph-node.png b/packages/docs/docs/node-reference/assets/subgraph-node.png
diff --git a/packages/docs/docs/node-reference/assets/text-node-example-01.png b/packages/docs/docs/node-reference/assets/text-node-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/text-node-example-02.png b/packages/docs/docs/node-reference/assets/text-node-example-02.png
diff --git a/packages/docs/docs/node-reference/assets/text-node-example-03.png b/packages/docs/docs/node-reference/assets/text-node-example-03.png
diff --git a/packages/docs/docs/node-reference/assets/text-node.png b/packages/docs/docs/node-reference/assets/text-node.png
diff --git a/packages/docs/docs/node-reference/assets/to-json-node-example-01.png b/packages/docs/docs/node-reference/assets/to-json-node-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/to-json-node.png b/packages/docs/docs/node-reference/assets/to-json-node.png
diff --git a/packages/docs/docs/node-reference/assets/to-yaml-node-example-01.png b/packages/docs/docs/node-reference/assets/to-yaml-node-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/to-yaml-node.png b/packages/docs/docs/node-reference/assets/to-yaml-node.png
diff --git a/packages/docs/docs/node-reference/assets/trim-chat-messages-node.png b/packages/docs/docs/node-reference/assets/trim-chat-messages-node.png
diff --git a/packages/docs/docs/node-reference/assets/trim-chat-node-example-01.png b/packages/docs/docs/node-reference/assets/trim-chat-node-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/user-input-node-example-01.png b/packages/docs/docs/node-reference/assets/user-input-node-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/user-input-node-example-02.png b/packages/docs/docs/node-reference/assets/user-input-node-example-02.png
diff --git a/packages/docs/docs/node-reference/assets/user-input-node.png b/packages/docs/docs/node-reference/assets/user-input-node.png
diff --git a/packages/docs/docs/node-reference/assets/vector-knn-node-example-01.png b/packages/docs/docs/node-reference/assets/vector-knn-node-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/vector-knn-node.png b/packages/docs/docs/node-reference/assets/vector-knn-node.png
diff --git a/packages/docs/docs/node-reference/assets/vector-store-node-example-01.png b/packages/docs/docs/node-reference/assets/vector-store-node-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/vector-store-node.png b/packages/docs/docs/node-reference/assets/vector-store-node.png
diff --git a/packages/docs/docs/node-reference/assets/wait-for-event-example-01.png b/packages/docs/docs/node-reference/assets/wait-for-event-example-01.png
diff --git a/packages/docs/docs/node-reference/assets/wait-for-event.png b/packages/docs/docs/node-reference/assets/wait-for-event.png
diff --git a/packages/docs/docs/node-reference/subgraph.mdx b/packages/docs/docs/node-reference/subgraph.mdx
@@ -1,5 +1,114 @@
 ---
-title: 'Subgraph'
+id: subgraph
+title: Subgraph Node
+sidebar_label: Subgraph
 ---
 
-# Subgraph Node
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+![Subgraph Node Screenshot](./assets/subgraph-node.png)
+
+## Overview
+
+The Subgraph Node allows you to execute another graph within the current graph. This is useful for reusing logic across multiple graphs, or for breaking down complex graphs into smaller, more manageable pieces.
+
+The inputs and outputs of the Subgraph Node are defined by [Graph Input Nodes](./graph-input.mdx) and [Graph Output Nodes](./graph-output.mdx) within the subgraph. The Subgraph Node will automatically update its inputs and outputs to match those of the selected subgraph.
+
+The Subgraph Node also has an optional error output. If enabled, any errors that occur while executing the subgraph will be caught and output from the error output port. If not enabled, errors will cause the entire graph to fail.
+
+<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                                                                                                                          |
+| -------------- | --------- | ----------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| (custom names) | Any       | The input values passed into the subgraph. Dynamic based on the inputs configured in the subgraph.   | N/A           | Always accepts any data type.                                                                                                  |
+
+</TabItem>
+
+<TabItem value="outputs">
+
+## Outputs
+
+| Title          | Data Type | Description                                                                                           | Notes                                                                                                                          |
+| -------------- | --------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| (custom names) | Any       | The output values from the execution of the subgraph. Dynamic based on the outputs configured in the subgraph. | Always accepts any data type.                                                                                                  |
+| Error          | `string`  | If the subgraph errors, will be populated with the error message.                                     | Only enabled if `Use Error Output` is turned on. If `Use Error Output` is turned off, the node will error instead.             |
+
+</TabItem>
+
+<TabItem value="settings">
+
+## Editor Settings
+
+| Setting          | Description                                                                                                                                                                                                | Default Value                  | Use Input Toggle | Input Data Type |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ---------------- | --------------- |
+| Graph            | The graph to execute when this node is ran. Must be a graph in the same project.                                                                                                                           | (required)                     | No               | N/A             |
+| Use Error Output | If enabled, then the Subgraph node will not fail, but instead any error will appear in the `Error` output port of the node. If disabled, the entire Subgraph node will error if the call errors. | False                           | No               | N/A             |
+
+</TabItem>
+
+</Tabs>
+
+## Example 1: Reuse a graph in multiple places
+
+1. Create a new graph in your project, and add a [Graph Input Node](./graph-input.mdx) and a [Graph Output Node](./graph-output.mdx) to it. Connect the Graph Input Node to a [Text Node](./text.mdx) and connect that node to Graph Output Node.
+2. Update the Text node to have the text `{{input}}
+Hi, From Subgraph`.
+3. In your main graph, add a Subgraph Node. In the editor settings, set the `Graph` to the graph you created in step 1.
+4. Connect a [Text Node](./text.mdx) to the input of the Subgraph Node.
+5. Set the Text of the Text Node to `Hello Subgraph!`.
+5. Run the graph. Note that the text is passed through the subgraph and back to the main graph with the text from the subgraph appended to it.
+
+
+![Subgraph Node Example 1a](./assets/subgraph-node-example-01a.png)
+![Subgraph Node Example 1b](./assets/subgraph-node-example-01b.png)
+
+## Example 2: Handle errors in a subgraph
+
+1. Using the same graphs from Example 1, in the subgraph add a vector store node.
+2. Connect all the outputs from the text node to the vector store node.
+3. This will cause the Vector Store Node to Error
+3. In your main graph, add a Subgraph Node. In the editor settings enable `Use Error Output`.
+4. Connect [Text Nodes](./text.mdx) to both outputs of the Subgraph Node.
+5. Run the graph. Note that the error is output on the `Error` port of the Subgraph Node, and the `Output` port is not ran.
+
+![Subgraph Node Example 2a](./assets/subgraph-node-example-02a.png)
+![Subgraph Node Example 2b](./assets/subgraph-node-example-02b.png)
+
+## Error Handling
+
+If the subgraph errors, then the Subgraph Node will error. If you want to handle errors in the graph, then you can enable the `Use Error Output` setting. This will cause the Subgraph Node to not error, but instead pass the error message to the `Error` output port. If the `Error` port is populated, then the `Result` port will not be ran. You can use an [If Node](./if.mdx) to check if the `Error` port is populated, and handle the error accordingly.
+
+## FAQ
+
+**Q: Can I use the Subgraph Node to execute a graph in a different project?**
+
+A: No, the Subgraph Node can only execute graphs within the same project.
+
+**Q: Can I use the Subgraph Node to execute a graph in a loop?**
+
+A: Yes, you can use a [Loop Controller Node](./loop-controller.mdx) to execute a Subgraph Node in a loop. Each iteration of the loop will execute the subgraph with the current loop value as an input.
+
+**Q: Can I use the Subgraph Node to execute a graph conditionally?**
+
+A: Yes, you can use an [If Node](./if.mdx) to conditionally execute a Subgraph Node. If the condition is false, the Subgraph Node will not be executed.
+
+## See Also
+
+- [Graph Input Node](./graph-input.mdx)
+- [Graph Output Node](./graph-output.mdx)
+- [If Node](./if.mdx)
+- [Loop Controller Node](./loop-controller.mdx)
+- [Print Node](./print.mdx)
+- [Text Node](./text.mdx)
diff --git a/packages/docs/docs/node-reference/text.mdx b/packages/docs/docs/node-reference/text.mdx
@@ -1,13 +1,115 @@
 ---
-title: 'Text'
+id: text
+title: Text Node
+sidebar_label: Text
 ---
 
-# Text Node
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
-Text nodes are string constants used to pass data to other nodes.
+![Text Node Screenshot](./assets/text-node.png)
 
-## Config Data
-- text - The text to pass to other nodes.
+## Overview
 
-## Ports
-- output - Outputs the text to other nodes.
+The Text Node is used to output a string of text. It can also interpolate values using `{{tags}}` within the text. The inputs are dynamically generated based on the interpolation tags used in the text.
+
+This node is particularly useful for creating dynamic text based on the inputs to the node. The Text Node supports markdown, so you can use it to create richly formatted text.
+
+<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                                                                                     |
+| ---------- | --------- | --------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------- |
+| (dynamic)  | `string`  | The inputs are dynamically generated based on the interpolation tags used.  | N/A           | The input names are derived from the interpolation tags used in the text. For example, if the text contains `{{name}}`, then there will be an input named `name`. |
+
+</TabItem>
+
+<TabItem value="outputs">
+
+## Outputs
+
+| Title  | Data Type | Description                         | Notes |
+| ------ | --------- | ----------------------------------- | ----- |
+| Output | `string`  | The output text after interpolation |       |
+
+</TabItem>
+
+<TabItem value="settings">
+
+## Editor Settings
+
+| Setting | Description                                                                                                           | Default Value | Use Input Toggle | Input Data Type |
+| ------- | --------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------- | --------------- |
+| Text    | The text to output. You can use interpolation tags in the format `{{tag}}` to insert the values of the inputs. | `{{input}}`   | No               | `string`        |
+
+</TabItem>
+
+</Tabs>
+
+## Example 1: Simple Text Output
+
+1. Create a Text Node.
+2. Set the `Text` to `Hello World!`.
+3. Run the graph. The output of the Text Node will be `Hello World`.
+
+![Text Node Example 1](./assets/text-node-example-01.png)
+
+## Example 2: Interpolation
+
+1. Create a Text Node.
+2. Set the `Text` to `Hello, {{name}}!`.
+3. Create a [Text Node](./text.mdx) and set the text to `Rivet`. Connect it to the `name` input of the Text Node.
+4. Run the graph. The output of the Text Node will be `Hello, Rivet!`.
+
+![Text Node Example 2](./assets/text-node-example-02.png)
+
+## Example 3: Using Markdown
+
+1. Create a Text Node.
+2. Set the `Text` to `# Hello, {{name}}!`.
+3. Create a [Text Node](./text.mdx) and set the text to `Rivet`. Connect it to the `name` input of the Text Node.
+4. Run the graph. The output of the Text Node will be `# Hello, Rivet!`.
+
+![Text Node Example 3](./assets/text-node-example-03.png)
+
+## Error Handling
+
+The Text Node does not have any notable error handling behavior. If an input is missing or null, the corresponding interpolation tag will be replaced with an empty string.
+
+## FAQ
+
+**Q: Can I use markdown in the Text Node?**
+
+A: Yes, the Text Node supports markdown. You can use markdown syntax in the text to create richly formatted text.
+
+**Q: Can I use the Text Node to create a template?**
+
+A: Yes, you can use the Text Node to create a template by using interpolation tags. You can then connect other nodes to the inputs of the Text Node to fill in the values of the tags.
+
+**Q: Can I use the Text Node to concatenate strings?**
+
+A: Yes, you can use the Text Node to concatenate strings by using interpolation tags. For example, you can set the text to `{{string1}}{{string2}}` to concatenate the values of `string1` and `string2`.
+
+## See Also
+
+- [Code Node](./code.mdx)
+- [Number Node](./number.mdx)
+- [Boolean Node](./bool.mdx)
+- [Object Node](./object.mdx)
+- [Array Node](./array.mdx)
+- [Extract Object Path Node](./extract-object-path.mdx)
+- [Extract with Regex Node](./extract-with-regex.mdx)
+- [Extract JSON Node](./extract-json.mdx)
+- [Extract YAML Node](./extract-yaml.mdx)
+- [To JSON Node](./to-json.mdx)
+- [To YAML Node](./to-yaml.mdx)
diff --git a/packages/docs/docs/node-reference/to-json.mdx b/packages/docs/docs/node-reference/to-json.mdx
@@ -1,5 +1,99 @@
 ---
-sidebar_label: 'To JSON'
+id: to-json
+title: To JSON Node
+sidebar_label: To JSON
 ---
 
-# To JSON Node
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+![To JSON Node Screenshot](./assets/to-json-node.png)
+
+## Overview
+
+The To JSON Node is used to convert a given input into its JSON equivalent, effectively stringifying the value. This can be useful when you need to serialize an object or array into a string format for further processing or storage.
+
+The node provides an option to format the JSON output with indentation for easier reading.
+
+<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 |
+| ----- | --------- | ----------------------------------- | ------------- | ----- |
+| Data  | `any`     | The data to be converted to JSON.   | (required)    |       |
+
+</TabItem>
+
+<TabItem value="outputs">
+
+## Outputs
+
+| Title | Data Type | Description                        | Notes |
+| ----- | --------- | ---------------------------------- | ----- |
+| JSON  | `string`  | The JSON string representation.    |       |
+
+</TabItem>
+
+<TabItem value="settings">
+
+## Editor Settings
+
+| Setting  | Description                                                                 | Default Value | Use Input Toggle | Input Data Type |
+| -------- | --------------------------------------------------------------------------- | ------------- | ---------------- | --------------- |
+| Indented | If enabled, the JSON output will be formatted with indentation for readability. | True          | No               | N/A             |
+
+</TabItem>
+
+</Tabs>
+
+## Example 1: Convert an object to JSON
+
+1. Create an [Object Node](./object.mdx) and set the value to the following:
+
+   ```json
+   {
+     "name": "Claude Shannon",
+     "occupation": "Computer scientist"
+   }
+   ```
+
+2. Create a To JSON Node and connect the Object Node to it.
+3. Run the graph. The To JSON Node should output the JSON string representation of the object.
+
+![To JSON Node Example 1](./assets/to-json-node-example-01.png)
+
+## Error Handling
+
+The To JSON Node will throw an error if it fails to convert the input to a JSON string. This can happen if the input contains a value that is not serializable, such as a function or a circular reference.
+
+## FAQ
+
+**Q: Can I use the To JSON Node to convert a string to JSON?**
+
+A: Yes, but the output will be a JSON string representation of the original string. If you want to parse a JSON string into an object or array, use the [Extract JSON Node](./extract-json.mdx) or the [Extract Object Path Node](./extract-object-path.mdx).
+
+**Q: Can I use the To JSON Node to convert a number or boolean to JSON?**
+
+A: Yes, the To JSON Node can convert any data type to a JSON string. For numbers and booleans, the output will be the string representation of the original value.
+
+**Q: What does the "Indented" setting do?**
+
+A: When the "Indented" setting is enabled, the JSON output will be formatted with indentation and line breaks for easier reading. This can be useful when you need to inspect the JSON output for debugging purposes.
+
+## See Also
+
+- [Extract JSON Node](./extract-json.mdx)
+- [Extract Object Path Node](./extract-object-path.mdx)
+- [Object Node](./object.mdx)
+- [Array Node](./array.mdx)
+- [Data Types](../user-guide/data-types.md)