From 20ee1793f1944b0f0c6271aa1cc52b65a683cb31 Mon Sep 17 00:00:00 2001 From: Grant Linville Date: Thu, 14 Mar 2024 12:01:01 -0400 Subject: [PATCH 1/3] docs: add full 'hello world' Python example Signed-off-by: Grant Linville --- docs/docs/100-tools/02-authoring.md | 14 +++-- docs/docs/100-tools/03-authoring-example.md | 65 +++++++++++++++++++++ 2 files changed, 73 insertions(+), 6 deletions(-) create mode 100644 docs/docs/100-tools/03-authoring-example.md diff --git a/docs/docs/100-tools/02-authoring.md b/docs/docs/100-tools/02-authoring.md index 11a20cff..2a31ef1c 100644 --- a/docs/docs/100-tools/02-authoring.md +++ b/docs/docs/100-tools/02-authoring.md @@ -1,21 +1,23 @@ # Authoring Tools -You can author your own tools for your use or to share with others. The process for authoring a tool is as simple as creating a `tool.gpt` file in the root directory of your project. This file is itself a GPTScript that defines the tool's name, description, and what it should do. +You can author your own tools for your use or to share with others. +The process for authoring a tool is as simple as creating a `tool.gpt` file in the root directory of your project. +This file is itself a GPTScript that defines the tool's name, description, and what it should do. Here's an example of the `tool.gpt` file for the `image-generation` tool: -```yaml -description: I am a tool that can generate images based on arguments that are sent to me. I return a list of URLs to the generated images. +``` +description: Generates images based on the specified parameters and returns a list of URLs to the generated images. args: prompt: (required) The text prompt based on which the GPT model will generate a response -args: model: (optional) The model to use for image generation. Defaults to "dall-e-3". args: size: (optional) The size of the image to generate, format WxH (e.g. 1024x1024). Defaults to 1024x1024. args: quality: (optional) The quality of the generated image. Allowed values are "standard" or "hd". Default is "standard". args: number: (optional) The number of images to generate. Defaults to 1. -#!/usr/bin/env python3 ./cli.py --prompt="${prompt}" --model="${model}" --size="${size}" --quality="${quality}" --number="${number}" +#!/usr/bin/env python3 ${GPTSCRIPT_TOOL_DIR}/cli.py --prompt="${prompt}" --size="${size}" --quality="${quality}" --number="${number}" ``` -At the bottom you'll notice a shebang line that specifies the command to run when the tool is invoked. This is the exact command that will be executed when the tool is used in a GPTScript. Doing this with tools allows for a high degree of reliability that the tool would not otherwise have. +At the bottom you'll notice a shebang line that specifies the command to run when the tool is invoked. This is the exact command that will be executed when the tool is used in a GPTScript. +If there is no shebang line, then it will be treated as natural language for the LLM to process. :::tip Every arg becomes an environment variable when the tool is invoked. diff --git a/docs/docs/100-tools/03-authoring-example.md b/docs/docs/100-tools/03-authoring-example.md new file mode 100644 index 00000000..9febc918 --- /dev/null +++ b/docs/docs/100-tools/03-authoring-example.md @@ -0,0 +1,65 @@ +# Authoring Tools Example Guide + +This is a guide for writing portable tools for GPTScript. +The supported languages currently are Python, NodeJS, and Go. This guide uses Python. + +## 1. Write the code + +Create a file called `tool.py` with the following contents: + +```python +import os + +# Third party +import requests +from markdownify import markdownify as md + + +def parse_url(link: str) -> str: + try: + resp = requests.get(link) + if resp.status_code != 200: + print(f"unexpected status code when getting {link}: {resp.status_code}") + exit(0) + + # Convert HTML to Markdown + return md(resp.text) + except Exception as e: + print(f"Error in parse_url: {e}") + exit(0) + + +# Begin execution + +link = os.getenv("url") +if link is None: + print("please provide a URL") + exit(1) + +print(parse_url(link)) +``` + +Create a file called `requirements.txt` with the following contents: + +``` +requests +markdownify +``` + +## 2. Create the tool + +Create a file called `tool.gpt` with the following contents: + +``` +description: Returns the contents of a webpage as Markdown. +args: url: The URL of the webpage. + +#!/usr/bin/env python3 ${GPTSCRIPT_TOOL_DIR}/tool.py +``` + +The `GPTSCRIPT_TOOL_DIR` environment variable is automatically populated by GPTScript so that the tool +will be able to find the `tool.py` file no matter what the user's current working directory is. + +If you make the tool available in a public GitHub repo, then you will be able to refer to it by +the URL, i.e. `github.com//`. GPTScript will automatically set up a Python virtual +environment, install the required packages, and execute the tool. From 0570937ef2fe01dd906cf5dc5e34c825b44070e6 Mon Sep 17 00:00:00 2001 From: Grant Linville Date: Thu, 14 Mar 2024 12:25:10 -0400 Subject: [PATCH 2/3] simplify example Signed-off-by: Grant Linville --- docs/docs/100-tools/03-authoring-example.md | 30 ++------------------- 1 file changed, 2 insertions(+), 28 deletions(-) diff --git a/docs/docs/100-tools/03-authoring-example.md b/docs/docs/100-tools/03-authoring-example.md index 9febc918..5a33dab7 100644 --- a/docs/docs/100-tools/03-authoring-example.md +++ b/docs/docs/100-tools/03-authoring-example.md @@ -9,41 +9,15 @@ Create a file called `tool.py` with the following contents: ```python import os - -# Third party import requests -from markdownify import markdownify as md - - -def parse_url(link: str) -> str: - try: - resp = requests.get(link) - if resp.status_code != 200: - print(f"unexpected status code when getting {link}: {resp.status_code}") - exit(0) - - # Convert HTML to Markdown - return md(resp.text) - except Exception as e: - print(f"Error in parse_url: {e}") - exit(0) - - -# Begin execution - -link = os.getenv("url") -if link is None: - print("please provide a URL") - exit(1) -print(parse_url(link)) +print(requests.get(os.getenv("url")).text) ``` Create a file called `requirements.txt` with the following contents: ``` requests -markdownify ``` ## 2. Create the tool @@ -51,7 +25,7 @@ markdownify Create a file called `tool.gpt` with the following contents: ``` -description: Returns the contents of a webpage as Markdown. +description: Returns the contents of a webpage. args: url: The URL of the webpage. #!/usr/bin/env python3 ${GPTSCRIPT_TOOL_DIR}/tool.py From b7f0d0197a777baab4423b5341ec66e115f90dfe Mon Sep 17 00:00:00 2001 From: Grant Linville Date: Thu, 14 Mar 2024 13:18:12 -0400 Subject: [PATCH 3/3] PR feedback Signed-off-by: Grant Linville --- docs/docs/100-tools/02-authoring.md | 4 ++-- docs/docs/100-tools/03-authoring-example.md | 10 ++++++++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/docs/100-tools/02-authoring.md b/docs/docs/100-tools/02-authoring.md index 2a31ef1c..8eb1c329 100644 --- a/docs/docs/100-tools/02-authoring.md +++ b/docs/docs/100-tools/02-authoring.md @@ -16,11 +16,11 @@ args: number: (optional) The number of images to generate. Defaults to 1. #!/usr/bin/env python3 ${GPTSCRIPT_TOOL_DIR}/cli.py --prompt="${prompt}" --size="${size}" --quality="${quality}" --number="${number}" ``` -At the bottom you'll notice a shebang line that specifies the command to run when the tool is invoked. This is the exact command that will be executed when the tool is used in a GPTScript. +At the bottom you'll notice a shebang (`#!/usr/bin/env ...`) line that specifies the command to run when the tool is invoked. This is the exact command that will be executed when the tool is used in a GPTScript. If there is no shebang line, then it will be treated as natural language for the LLM to process. :::tip -Every arg becomes an environment variable when the tool is invoked. +Every arg becomes an environment variable when the tool is invoked. So instead of accepting args using flags like `--size="${size}", your program can just read the `size` environment variable. ::: ## Binary Tools diff --git a/docs/docs/100-tools/03-authoring-example.md b/docs/docs/100-tools/03-authoring-example.md index 5a33dab7..bf96ea97 100644 --- a/docs/docs/100-tools/03-authoring-example.md +++ b/docs/docs/100-tools/03-authoring-example.md @@ -37,3 +37,13 @@ will be able to find the `tool.py` file no matter what the user's current workin If you make the tool available in a public GitHub repo, then you will be able to refer to it by the URL, i.e. `github.com//`. GPTScript will automatically set up a Python virtual environment, install the required packages, and execute the tool. + +## 3. Use the tool + +Here is an example of how you can use the tool once it is on GitHub: + +``` +tools: github.com// + +Get the contents of https://github.com +```