docs: add full 'hello world' Python example (#156)

Signed-off-by: Grant Linville <[email protected]>

Author: g-linville

docs/docs/100-tools/02-authoring.md

@@ -1,24 +1,26 @@
 # 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 (`#!/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

docs/docs/100-tools/03-authoring-example.md

@@ -0,0 +1,49 @@
+# 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
+import requests
+
+print(requests.get(os.getenv("url")).text)
+```
+
+Create a file called `requirements.txt` with the following contents:
+
+```
+requests
+```
+
+## 2. Create the tool
+
+Create a file called `tool.gpt` with the following contents:
+
+```
+description: Returns the contents of a webpage.
+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/<user>/<repo name>`. 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/<user>/<repo name>
+
+Get the contents of https://github.com
+```