Skip to content

Commit a73140f

Browse files
ibuildthecloudibuildthecloud
committed
Initial README.md
1 parent c558ca5 commit a73140f

File tree

3 files changed

+187
-39
lines changed

3 files changed

+187
-39
lines changed

‎README.md

+173-38
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,190 @@
1-
# README.md for GPTscript Project
1+
# GPTScript
22

3-
## Project Description
3+
## Overview
44

5-
This project utilizes `GPTscript`, a powerful scripting tool that leverages OpenAI's GPT plugins to execute tasks specified in `.gpt` files. These scripts can combine traditional scripting with GPT's AI capabilities to automate complex workflows, parse information, and more.
5+
GPTScript is a new scripting language to automate your interaction with a Large Language Model (LLM), namely OpenAI.
6+
The syntax of GPTScript is largely natural language, making it very easy to learn and use.
7+
Natural language prompts can be mixed with traditional scripts such as bash and python or even external HTTP service
8+
calls.
69

7-
## Usage
10+
```yaml
11+
Tools: sys.download, sys.exec, sys.remove
812

9-
The primary command used to run GPT scripts is `gptscript`, which can be invoked with various flags to control the script execution. A typical usage pattern looks like this:
13+
Download https://www.sqlitetutorial.net/wp-content/uploads/2018/03/chinook.zip to a
14+
random file. Then expand the archive to a temporary location as there is a sqlite
15+
database in it.
1016

11-
```bash
12-
gptscript [flags] PROGRAM_FILE [INPUT...]
17+
First inspect the schema of the database to understand the table structure.
18+
19+
Form and run a SQL query to find the artist with the most number of albums and output
20+
the result of that.
21+
22+
When done remove the database file and the downloaded content.
23+
```
24+
25+
## Quick Start
26+
27+
1. Install with brew (or from [releases](https://github.com/gptscript-ai/gptscript/releases/latest))
28+
```shell
29+
brew install gptscript-ai/tap/gptscript
30+
```
31+
2. Get an API key from [OpenAI](https://platform.openai.com/api-keys).
32+
```shell
33+
export OPENAI_API_KEY="your-api-key"
34+
```
35+
3. Run Hello World:
36+
```shell
37+
gptscript https://gptscript.ai/echo.gpt --input "Hello, World!"
38+
```
39+
40+
## How it works
41+
42+
***GPTScript is composed of tools.*** Each tool performs a series of actions similar to a function. Tools have available
43+
to them other tools that can be invoked similar to a function call. While similar to a function, the tools are
44+
implemented with a natural language and not code. ***The interaction of the tools is determined by the AI model***,
45+
the model determines if the tool needs to be invoked and what arguments to pass. Tools are intended to be implemented
46+
with a natural language prompt but can also be implemented with a command or HTTP call.
47+
48+
### Example
49+
Below are two tool definitions, separated by `---`. The first tool does not require a name or description, but
50+
every tool after name and description are required. The first tool, has the parameter `tools: bob` meaning that the tool named `bob` is available to be called if needed.
51+
52+
```yaml
53+
tools: bob
54+
55+
Ask Bob how he is doing and let me know exactly what he said.
56+
57+
---
58+
name: bob
59+
description: I'm Bob, a friendly guy.
60+
args: question: The question to ask Bob.
61+
62+
When asked how I am doing, respond with "Thanks for asking "${question}", I'm doing great fellow friendly AI tool!"
63+
```
64+
Put the above content in a file named `bob.gpt` and run the following command:
65+
```shell
66+
$ gptscript bob.gpt
67+
68+
OUTPUT:
69+
70+
Bob said, "I'm doing great fellow friendly AI tool!"
71+
```
72+
Tools can be implemented by invoking a program instead of a natural language prompt. The below
73+
example is the same as the previous example but implements Bob using bash.
74+
75+
```yaml
76+
Tools: bob
77+
78+
Ask Bob how he is doing and let me know exactly what he said.
79+
80+
---
81+
Name: bob
82+
Description: I'm Bob, a friendly guy.
83+
Args: question: The question to ask Bob.
84+
85+
#!/bin/bash
86+
87+
echo "Thanks for asking ${question}, I'm doing great fellow friendly AI tool!"
88+
```
89+
90+
With these basic building blocks you can create complex scripts with AI interacting with, your local system, data,
91+
or external services.
92+
93+
## GPT File Reference
94+
95+
### Extension
96+
GPTScript files use the `.gpt` extension by convention.
97+
98+
### File Structure
99+
A GPTScript file has one or more tools in the file. Each tool is separated by three dashes `---` alone on a line.
100+
101+
```yaml
102+
Name: tool1
103+
Description: This is tool1
104+
105+
Do sample tool stuff.
106+
107+
---
108+
Name: tool2
109+
Description: This is tool2
110+
111+
Do more sample tool stuff.
112+
```
113+
114+
### Tool Definition
115+
116+
A tool starts with a preamble that defines the tool's name, description, args, available tools and additional parameters.
117+
The preamble is followed by the tool's body, which contains the instructions for the tool. Comments in
118+
the preamble are lines starting with `#` and are ignored by the parser. Comments are not really encouraged
119+
as the text is typically more useful in the description, argument descriptions or instructions.
120+
121+
```yaml
122+
Name: tool-name
123+
# This is a comment in the preamble. Comments don't typically provide much value
124+
Description: Tool description
125+
# This tool can invoke tool1 or tool2 if needed
126+
Tools: tool1, tool2
127+
Args: arg1: The description of arg1
128+
129+
Tool instructions go here.
13130
```
131+
#### Tool Parameters
14132

15-
Where `PROGRAM_FILE` is the script to be executed, optionally followed by `INPUT` arguments to pass into the script.
133+
Tool parameters are key-value pairs defined at the beginning of a tool block, before any instructional text. They are specified in the format `key: value`. The parser recognizes the following keys (case-insensitive and spaces are ignored):
16134

17-
## GPT File Syntax
135+
`Name`: The name of the tool.
18136

19-
GPT script files (`*.gpt`) follow a syntax which allows for defining tools, their descriptions, arguments, and embedded traditional scripting codes. Here's a breakdown of the syntax:
137+
`Model Name`: The OpenAI model to use, by default it uses "gpt-4-turbo-preview"
20138

21-
- `tools:` Followed by the tool names to be used.
22-
- `name:` Defines the tool's name.
23-
- `description:` Describes what the tool does.
24-
- `args:` Lists arguments the tool accepts, describing the expected input.
25-
- `tools:` Below the main tool definition, you can specify other tools used by this tool.
26-
- A line containing `---` signifies the separation between tool metadata and the script code itself.
139+
`Description`: The description of the tool. It is important that the properly describes the tool's purpose as the
140+
description is used by the LLM to determine if the tool is to be invoked.
27141

28-
## Example `.gpt` Files and Their Syntax
142+
`Internal Prompt`: Setting this to `false` will disable the built in system prompt for this tool. GPTScript includes a
143+
default system prompt to instruct the AI to behave more like a script engine and not a "helpful assistant."
29144

30-
The repository contains several example `.gpt` files, such as:
145+
`Tools`: A comma-separated list of tools that are available to be called by this tool. A tool can only call the tools
146+
that are defined here.
31147

32-
- `describe.gpt`: Provides functionalities for working with Go files, with tools like `ls`, `count`, `summarize`, and `compare`.
33-
- `echo.gpt`: A simple script that echoes the provided input.
34-
- `fib.gpt`: An example demonstrating a recursive function `myfunction`.
35-
- `git-commit.gpt`: Automates the creation of a well-formed git commit message.
36-
- `helloworld.gpt`: A basic script outputs the traditional "hello world" message.
37-
- `summarize-syntax.gpt`: Meta-script for generating documentation based on `.gpt` files in a directory.
38-
- `tables.gpt`: Using SQLite, identifies the table in a database with the most rows.
148+
`Args`: Arguments for the tool. Each argument is defined in the format `arg-name: description`. All arguments are essentially
149+
strings. No other type really exists as all input and output to tools is text based.
150+
151+
`Vision`: If set to true this model will use vision capabilities. Vision models currently do not support the `Args` or `Tools` parameters.
152+
153+
`Max Tokens`: Set to a number if you wish to limit the maximum number of tokens that can be generated by the LLM.
154+
155+
`JSON Response`: Setting to `true` will cause the LLM to respond in a JSON format. If you set true you must also include instructions in the tool
156+
to inform the LLM to respond in some JSON structure.
157+
158+
`Temperature`: A floating-point number representing the temperature parameter. By default the temperature is 0. Set to a higher number to make the LLM more creative.
159+
160+
#### Tool Body
161+
162+
The tool body contains the instructions for the tool which can be a natural language prompt or
163+
a command to execute. Commands must start with `#!` followed by the interpreter (e.g. `#!/bin/bash`, `#!python3`)
164+
a text that will be placed in a file and passed to the interpreter. Arguments can be references in the instructions
165+
using the format `${arg1}`.
166+
167+
```yaml
168+
name: echo-ai
169+
description: A tool that echos the input
170+
args: input: The input
171+
172+
Just return only "${input}"
173+
174+
---
175+
name: echo-command
176+
description: A tool that echos the input
177+
args: input: The input
178+
179+
#!/bin/bash
180+
181+
echo "${input}"
182+
```
39183

40-
## gptscript Command Help
184+
## Examples
41185

42-
The help output for `gptscript` provides vital information on how to use the command along with the available flags. Here's an abbreviated listing of the flags:
186+
For more examples check out the [examples](examples) directory.
43187

44-
- `--assemble`: Assemble tool to a single artifact, with output specified by `--output`.
45-
- `--cache`, `--cache-dir`: Controls caching behavior and cache directory location.
46-
- `--debug`: Enable debug logging.
47-
- `--help`: Displays help information for `gptscript`.
48-
- `--input`: Specify an input file or stdin.
49-
- `--list-models`, `--list-tools`: Lists available models or built-in tools.
50-
- `--openai-api-key`: Specifies the OpenAI API key to use.
51-
- `--output`: Saves output to a specified file.
52-
- `--quiet`: Suppresses output logging.
53-
- `--sub-tool`: Selects a specific sub-tool to use from the `.gpt` file.
188+
## License
54189

55-
For a detailed description and more options, refer to the `gptscript --help` command.
190+
GPTScript is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.

‎examples/bob-as-shell.gpt

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
tools: bob
2+
3+
Ask Bob how he is doing and let me know exactly what he said.
4+
5+
---
6+
name: bob
7+
description: I'm Bob, a friendly guy.
8+
args: question: The question to ask Bob.
9+
10+
#!/bin/bash
11+
12+
echo "Thanks for asking ${question}, I'm doing great fellow friendly AI tool!"

‎examples/bob.gpt

+2-1
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,6 @@ Ask Bob how he is doing and let me know exactly what he said.
55
---
66
name: bob
77
description: I'm Bob, a friendly guy.
8+
args: question: The question to ask Bob.
89

9-
When asked how I am doing, respond with "I'm doing great fellow friendly AI tool!"
10+
When asked how I am doing, respond with "Thanks for asking "${question}", I'm doing great fellow friendly AI tool!"

0 commit comments

Comments
 (0)