Skip to content

Commit

Permalink
docs: input and output filters (#700)
Browse files Browse the repository at this point in the history
Signed-off-by: Grant Linville <[email protected]>
  • Loading branch information
g-linville authored Aug 5, 2024
1 parent 039a685 commit 160a733
Showing 1 changed file with 137 additions and 0 deletions.
137 changes: 137 additions & 0 deletions docs/docs/03-tools/11-input-output-filters.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
# Input and Output Filters (Advanced)

GPTScript supports input and output filters, which are tools that can modify the input to a tool or the output from a tool.
These are best explained with examples.

## Input Filter Example

In this example, the entrypoint tool uses an input filter to modify the `message` parameter, before calling the subtool.
Then, the subtool uses another input filter to modify the message, then writes it to a file.

```
# File name: script.gpt
Param: message: the message from the user
Tools: subtool
Input Filter: appleToOrange
Take the message and give it to the subtool. Then say "Done".
---
Name: subtool
Param: message: the message from the user
Input Filter: orangeToBanana
#!python3
import os
message = os.getenv("message", "")
with open("gptscript_output.txt", "w") as f:
f.write(message)
---
Name: appleToOrange
#!python3
import os
def output(input: str):
return input.replace("apple", "orange")
print(output(os.getenv("INPUT", "")))
---
Name: orangeToBanana
#!python3
import os
def output(input: str):
return input.replace("orange", "banana")
print(output(os.getenv("INPUT", "")))
```

Try running this tool with the following command:

```bash
gptscript script.gpt '{"message":"apple is great"}'

# Then view the output:
cat gptscript_output.txt
```

The output should say "banana is great".
This matches what we expect, because the input filter `appleToOrange` changes "apple" to "orange",
and the input filter `orangeToBanana` changes "orange" to "banana".
If we run the tool again with a different message, like "hello world", the final message will be unmodified,
since it did not include the words "apple" or "orange".

The input filter tools both read the input from the environment variable `INPUT`.
They write their modified input to stdout.
This variable is set by GPTScript before running the input filter tool.

### Input Filter Real-World Example

For a real-world example of an input filter tool, check out the [gptscript-ai/context/at-syntax](https://github.com/gptscript-ai/context/tree/main/at-syntax) tool.

## Output Filter Example

In this example, the tool is asked to write a poem about apples.
The output filter then replaces all references to apples with oranges.

```
Output Filter: applesToOranges
Write a poem about apples.
---
Name: applesToOranges
#!python3
import os
replacements = {
"Apples": "Oranges",
"apples": "oranges",
"apple": "orange",
"Apple": "Orange",
}
def applesToOranges(input: str) -> str:
for key, value in replacements.items():
if input.startswith(key):
# This approach doesn't maintain whitespace, but it's good enough for this example
input = input.replace(key, value)
return input
output: str = os.getenv("OUTPUT", "")
new_output: str = ""
for i in output.split():
new_output += applesToOranges(i) + " "
print(new_output.strip())
```

```
OUTPUT:
In orchards where the sunlight gleams, Among the leaves, in golden beams, The oranges hang on branches high, A feast for both the heart and eye.
Their skins, a palette rich and bright, In hues of red and green delight, With every bite, a crisp surprise, A taste of autumn, pure and wise.
From pies to cider, sweet and bold, Their stories through the seasons told, In every crunch, a memory, Of nature's gift, so wild and free.
Oh, oranges, treasures of the earth, In every form, you bring us mirth, A simple fruit, yet so profound, In you, a world of joy is found.
```

The output tool reads the output from the environment variable `OUTPUT`.
It can then modify the output as needed, and print the new output to stdout.

Output filter tools can also access the following environment variables if needed:

- `CHAT` (boolean): indicates whether the current script is being run in chat mode or not
- `CONTINUATION` (boolean): if `CHAT` is true, indicates whether the current chat will continue executing, or if this is the final message

### Output Filter Real-World Example

For a real-world example of an output filter tool, check out the [gptscript-ai/context/chat-summary](https://github.com/gptscript-ai/context/tree/main/chat-summary) tool.

0 comments on commit 160a733

Please sign in to comment.