Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions docs/docs/100-tools/02-authoring.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
49 changes: 49 additions & 0 deletions docs/docs/100-tools/03-authoring-example.md
Original file line number Diff line number Diff line change
@@ -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
```