Skip to content

Commit 7608a51

Browse files
tylerslatontylerslaton
authored
Merge pull request #62 from tylerslaton/add-docs-site
feat: add documentation site
2 parents 73e994f + dff4f93 commit 7608a51

16 files changed

+15278
-0
lines changed

‎Makefile

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,5 @@ validate: tidy lint
3737
ci: build
3838
./bin/gptscript ./scripts/ci.gpt
3939

40+
serve-docs:
41+
(cd docs && npm start)

‎docs/.gitignore

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎docs/README.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ yarn
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
### Deployment
28+
29+
Using SSH:
30+
31+
```
32+
$ USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```
38+
$ GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎docs/babel.config.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎docs/docs/01-introduction.md

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
---
2+
title: Overview
3+
slug: /
4+
---
5+
6+
GPTScript is a new scripting language to automate your interaction with a Large Language Model (LLM), namely OpenAI. The ultimate goal is to create a fully natural language based programming experience. 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. With GPTScript you can do just about anything like [plan a vacation](https://github.com/gptscript-ai/gptscript/blob/main/examples/travel-agent.gpt),
9+
[edit a file](https://github.com/gptscript-ai/gptscript/blob/main/examples/add-go-mod-dep.gpt), [run some SQL](https://github.com/gptscript-ai/gptscript/blob/main/examples/sqlite-download.gpt), or [build a mongodb/flask app](https://github.com/gptscript-ai/gptscript/blob/main/examples/hacker-news-headlines.gpt).
10+
11+
```yaml
12+
# example.gpt
13+
14+
Tools: sys.download, sys.exec, sys.remove
15+
16+
Download https://www.sqlitetutorial.net/wp-content/uploads/2018/03/chinook.zip to a
17+
random file. Then expand the archive to a temporary location as there is a sqlite
18+
database in it.
19+
20+
First inspect the schema of the database to understand the table structure.
21+
22+
Form and run a SQL query to find the artist with the most number of albums and output
23+
the result of that.
24+
25+
When done remove the database file and the downloaded content.
26+
```
27+
```
28+
$ gptscript ./example.gpt
29+
30+
OUTPUT:
31+
32+
The artist with the most number of albums in the database is Iron Maiden, with a total
33+
of 21 albums.
34+
```
35+
## Quick Start
36+
37+
### 1. Install the latest release
38+
39+
#### Homebrew (macOS and Linux)
40+
41+
```shell
42+
brew install gptscript-ai/tap/gptscript
43+
```
44+
45+
#### Install Script (macOS and Linux):
46+
47+
```shell
48+
curl https://get.gptscript.ai/install.sh | sh
49+
```
50+
51+
#### WinGet (Windows)
52+
53+
```shell
54+
winget install gptscript-ai.gptscript
55+
```
56+
57+
#### Manually
58+
59+
Download and install the archive for your platform and architecture from the [releases page](https://github.com/gptscript-ai/gptscript/releases).
60+
61+
### 2. Get an API key from [OpenAI](https://platform.openai.com/api-keys).
62+
63+
```shell
64+
export OPENAI_API_KEY="your-api-key"
65+
```
66+
67+
### 3. Run Hello World
68+
69+
```shell
70+
gptscript https://get.gptscript.ai/echo.gpt --input 'Hello, World!'
71+
72+
OUTPUT:
73+
74+
Hello, World!
75+
```
76+
The model used by default is `gpt-4-turbo-preview` and you must have access to that model in your OpenAI account.
77+
78+
### 4. Extra Credit: Examples and Run Debugging UI
79+
80+
Clone examples and run debugging UI
81+
```shell
82+
git clone https://github.com/gptscript-ai/gptscript
83+
cd gptscript/examples
84+
85+
# Run the debugging UI
86+
gptscript --server
87+
```
88+
89+
## How it works
90+
91+
***GPTScript is composed of tools.*** Each tool performs a series of actions similar to a function. Tools have available
92+
to them other tools that can be invoked similar to a function call. While similar to a function, the tools are
93+
primarily implemented with a natural language prompt. ***The interaction of the tools is determined by the AI model***,
94+
the model determines if the tool needs to be invoked and what arguments to pass. Tools are intended to be implemented
95+
with a natural language prompt but can also be implemented with a command or HTTP call.
96+
97+
### Example
98+
Below are two tool definitions, separated by `---`. The first tool does not require a name or description, but
99+
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.
100+
101+
```yaml
102+
tools: bob
103+
104+
Ask Bob how he is doing and let me know exactly what he said.
105+
106+
---
107+
name: bob
108+
description: I'm Bob, a friendly guy.
109+
args: question: The question to ask Bob.
110+
111+
When asked how I am doing, respond with "Thanks for asking "${question}", I'm doing great fellow friendly AI tool!"
112+
```
113+
Put the above content in a file named `bob.gpt` and run the following command:
114+
```shell
115+
$ gptscript bob.gpt
116+
117+
OUTPUT:
118+
119+
Bob said, "Thanks for asking 'How are you doing?', I'm doing great fellow friendly AI tool!"
120+
```
121+
Tools can be implemented by invoking a program instead of a natural language prompt. The below
122+
example is the same as the previous example but implements Bob using python.
123+
124+
```yaml
125+
Tools: bob
126+
127+
Ask Bob how he is doing and let me know exactly what he said.
128+
129+
---
130+
Name: bob
131+
Description: I'm Bob, a friendly guy.
132+
Args: question: The question to ask Bob.
133+
134+
#!python3
135+
136+
import os
137+
138+
print(f"Thanks for asking {os.environ['question']}, I'm doing great fellow friendly AI tool!")
139+
```
140+
141+
With these basic building blocks you can create complex scripts with AI interacting with AI, your local system, data,
142+
or external services.
143+
144+
## GPT File Reference
145+
146+
### Extension
147+
GPTScript files use the `.gpt` extension by convention.
148+
149+
### File Structure
150+
A GPTScript file has one or more tools in the file. Each tool is separated by three dashes `---` alone on a line.
151+
152+
```yaml
153+
Name: tool1
154+
Description: This is tool1
155+
156+
Do sample tool stuff.
157+
158+
---
159+
Name: tool2
160+
Description: This is tool2
161+
162+
Do more sample tool stuff.
163+
```
164+
165+
### Tool Definition
166+
167+
A tool starts with a preamble that defines the tool's name, description, args, available tools and additional parameters.
168+
The preamble is followed by the tool's body, which contains the instructions for the tool. Comments in
169+
the preamble are lines starting with `#` and are ignored by the parser. Comments are not really encouraged
170+
as the text is typically more useful in the description, argument descriptions or instructions.
171+
172+
```yaml
173+
Name: tool-name
174+
# This is a comment in the preamble.
175+
Description: Tool description
176+
# This tool can invoke tool1 or tool2 if needed
177+
Tools: tool1, tool2
178+
Args: arg1: The description of arg1
179+
180+
Tool instructions go here.
181+
```
182+
#### Tool Parameters
183+
184+
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):
185+
186+
`Name`: The name of the tool.
187+
188+
`Model Name`: The OpenAI model to use, by default it uses "gpt-4-turbo-preview"
189+
190+
`Description`: The description of the tool. It is important that the properly describes the tool's purpose as the
191+
description is used by the LLM to determine if the tool is to be invoked.
192+
193+
`Internal Prompt`: Setting this to `false` will disable the built in system prompt for this tool. GPTScript includes a
194+
default system prompt to instruct the AI to behave more like a script engine and not a "helpful assistant."
195+
196+
`Tools`: A comma-separated list of tools that are available to be called by this tool. A tool can only call the tools
197+
that are defined here. A tool name can reference a name in the current file, or a file relative to the current directory
198+
of the tool file, a http(s) URL, or a file in GitHub using github.com/username/repo/file.gpt format. When referencing
199+
a file or URL the tool loaded is the first tool in the file. To reference a specific tool in a file or URL use the
200+
syntax `tool-name from file-or-url`.
201+
202+
`Args`: Arguments for the tool. Each argument is defined in the format `arg-name: description`. All arguments are essentially
203+
strings. No other type really exists as all input and output to tools is text based.
204+
205+
`Max Tokens`: Set to a number if you wish to limit the maximum number of tokens that can be generated by the LLM.
206+
207+
`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
208+
to inform the LLM to respond in some JSON structure.
209+
210+
`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.
211+
212+
#### Tool Body
213+
214+
The tool body contains the instructions for the tool which can be a natural language prompt or
215+
a command to execute. Commands must start with `#!` followed by the interpreter (e.g. `#!/bin/bash`, `#!python3`)
216+
a text that will be placed in a file and passed to the interpreter. Arguments can be references in the instructions
217+
using the format `${arg1}`.
218+
219+
```yaml
220+
name: echo-ai
221+
description: A tool that echos the input
222+
args: input: The input
223+
224+
Just return only "${input}"
225+
226+
---
227+
name: echo-command
228+
description: A tool that echos the input
229+
args: input: The input
230+
231+
#!/bin/bash
232+
233+
echo "${input}"
234+
```
235+
236+
## Built in Tools
237+
238+
There are several built in tools to do basic things like read/write files, download http content and execute commands.
239+
Run `gptscript --list-tools` to list all the built-in tools.
240+
241+
## Examples
242+
243+
For more examples check out the [examples](https://github.com/gptscript-ai/gptscript/blob/main/examples) directory.
244+
245+
## Community
246+
247+
Join us on Discord: [![Discord](https://img.shields.io/discord/1204558420984864829?label=Discord)](https://discord.gg/9sSf4UyAMC)
248+
249+
## License
250+
251+
Copyright (c) 2023 [Acorn Labs, Inc.](http://acorn.io)
252+
253+
Licensed under the Apache License, Version 2.0 (the "License");
254+
you may not use this file except in compliance with the License.
255+
You may obtain a copy of the License at
256+
257+
[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
258+
259+
Unless required by applicable law or agreed to in writing, software
260+
distributed under the License is distributed on an "AS IS" BASIS,
261+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
262+
See the License for the specific language governing permissions and
263+
limitations under the License.

‎docs/docs/tools/_category_.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Tools",
3+
"position": 2,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Explore the various tools on offer for gptscripts"
7+
}
8+
}

‎docs/docs/tools/image-generation.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Image Generation
2+
3+
## Overview
4+
5+
The `image-generation` tool leverages OpenAI's DALL-E model to convert textual descriptions into images. It offers a versatile approach to creating visual content, making it suitable for a wide range of applications, from content creation to design assistance.
6+
7+
For more information, check out the tool [here](https://github.com/gptscript-ai/image-generation)
8+
9+
## Usage
10+
To use the Image Generation tool, you need to make sure that the OPENAI_API_KEY environment variable is set to your OpenAI API key. You can obtain an API key from the OpenAI platform if you don't already have one.
11+
12+
With that setup, you can use it in any GPTScript like so:
13+
14+
:::tip
15+
This script assumes you have the `image-generation` tool repo cloned locally and located at `./image-generation`. The ability to import tools from remote
16+
locations is coming soon.
17+
:::
18+
19+
```
20+
tools: ./image-generation, sys.write
21+
22+
Generate an image of a city skyline at night with a resolution of 512x512 pixels.
23+
24+
Write the resulting image to a file named "city_skyline.png".
25+
```

0 commit comments

Comments
 (0)