feat: refactor docs and add content around tools and authoring

Signed-off-by: tylerslaton <[email protected]>

Author: tylerslaton

Makefile

@@ -38,4 +38,4 @@ ci: build
 	./bin/gptscript ./scripts/ci.gpt
 
 serve-docs:
-	(cd docs && npm start)
+	(cd docs && npm i && npm start)

docs/docs/01-overview.md

@@ -0,0 +1,37 @@
+---
+title: Overview
+slug: /
+---
+
+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. Natural language prompts can be mixed with traditional scripts such as bash and python or even external HTTP service 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), [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).
+
+```yaml
+# example.gpt
+
+Tools: sys.download, sys.exec, sys.remove
+
+Download https://www.sqlitetutorial.net/wp-content/uploads/2018/03/chinook.zip to a
+random file. Then expand the archive to a temporary location as there is a sqlite
+database in it.
+
+First inspect the schema of the database to understand the table structure.
+
+Form and run a SQL query to find the artist with the most number of albums and output
+the result of that.
+
+When done remove the database file and the downloaded content.
+```
+```
+$ gptscript ./example.gpt
+
+OUTPUT:
+
+The artist with the most number of albums in the database is Iron Maiden, with a total
+of 21 albums.
+```
+
+For more examples check out the [examples](https://github.com/gptscript-ai/gptscript/blob/main/examples) directory.
+
+## Community
+
+Join us on Discord: [![Discord](https://img.shields.io/discord/1204558420984864829?label=Discord)](https://discord.gg/9sSf4UyAMC)

docs/docs/02-getting-started.md

@@ -0,0 +1,53 @@
+# Getting Started
+
+### 1. Install the latest release
+
+#### Homebrew (macOS and Linux)
+
+```shell
+brew install gptscript-ai/tap/gptscript
+```
+
+#### Install Script (macOS and Linux):
+
+```shell
+curl https://get.gptscript.ai/install.sh | sh
+```
+
+#### WinGet (Windows)
+
+```shell
+winget install gptscript-ai.gptscript
+```
+
+#### Manually
+
+Download and install the archive for your platform and architecture from the [releases page](https://github.com/gptscript-ai/gptscript/releases).
+
+### 2. Get an API key from [OpenAI](https://platform.openai.com/api-keys).
+
+```shell
+export OPENAI_API_KEY="your-api-key"
+```
+
+### 3. Run Hello World
+
+```shell
+gptscript https://get.gptscript.ai/echo.gpt --input 'Hello, World!'
+
+OUTPUT:
+
+Hello, World!
+```
+The model used by default is `gpt-4-turbo-preview` and you must have access to that model in your OpenAI account.
+
+### 4. Extra Credit: Examples and Run Debugging UI
+
+Clone examples and run debugging UI
+```shell
+git clone https://github.com/gptscript-ai/gptscript
+cd gptscript/examples
+
+# Run the debugging UI
+gptscript --server
+```

docs/docs/tools/01-authoring/01-overview.md

@@ -0,0 +1,70 @@
+# Overview
+
+In GPTScript, tools are used to extend the capabilities of a script. The idea behind them is that AI performs better when it has very specific instructions for a given task. Tools are a way to break-up the problem into smaller and more focused pieces where each tool is responsible for a specific task. A typical flow like this is to have a main script that imports a set of tools it can use to accomplish its goal.
+
+## Using Tools
+
+GPTScripts can utilize tools in one of three ways:
+1. Built-in system tools
+2. In-script tools
+3. External tools
+
+### System Tools
+All GPTScripts have access to system tools, like `sys.read` and `sys.write`, that can be used without any additional configuration.
+
+```yaml
+tools: sys.read, sys.write
+
+Read all of the files in my current directory, do no recurse over any subdirectories, and give me a description of this directory's contents.s
+```
+
+System tools are a set of core tools that come packaged with GPTScript by default.
+
+### In-Script Tools
+Things get more interesting when you start to use custom tools.
+
+The most basic example of this is an in-script tool that is defined in the same file as the main script. This is useful for breaking up a large script into smaller, more manageable pieces.
+
+```yaml
+tools: random-number
+
+Select a number at random and, based on the results, write a poem about it.
+
+---
+name: random-number
+description: Generate a random number between 1 and 100.
+
+Select a number at random between 1 and 100 and return only the number.
+```
+
+### External Tools
+
+This is where the real power of GPTScript starts to become evident. For this example lets use the external [image-generation](https://github.com/gptscript-ai/image-generation) and [search](https://github.com/gptscript-ai/search) tools to generate an image and then search the web for similar images.
+
+```yaml
+tools: ./image-generation, ./search, sys.read
+
+Generate an image of a city skyline at night and write the resulting image to a file called city_skyline.png.
+
+Take this image and search the web for similar images. Write links for the top 5 results to a file called similar_images.txt.
+```
+
+External tools are tools that are defined by a `tool.gpt` file in their root directory. They can be imported into a GPTScript by specifying the path to the tool's root directory.
+
+## Authoring External Tools
+You can author your own tools for your own 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 tool 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.
+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}"
+```
+
+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.

docs/docs/tools/01-authoring/02-binary-tools.md

@@ -0,0 +1,89 @@
+# Binary Tools
+GPTScript can call binaries and scripts located on your system or externally. This is done by defining a `tool.gpt` file in the same directory that the binary or script is located. In that `tool.gpt` file, you call it directly using the `#!` directive.
+
+For example:
+
+```yaml
+description: This is a tool that calls a binary.
+args: arg1: The first argument.
+
+#!/usr/bin/env ./path/to/binary
+```
+
+## Shell
+You can call shell scripts directly using the `#!` directive. For example:
+
+```yaml
+description: This is a tool that calls a shell script.
+args: arg1: The first argument.
+
+#!/usr/bin/env sh
+echo "Hello, world!"
+./path/to/script.sh
+```
+
+## Python
+You can also call Python scripts directly the same way. For example:
+
+```yaml
+description: This is a tool that calls a Python script.
+args: arg1: The first argument.
+
+#!/usr/bin/env python3 ./path/to/script.py
+```
+
+If you need to bootstrap a Python environment, you can use a virtual environment. For example:
+
+```yaml
+description: This is a tool that calls a Python script in a virtual environment.
+args: arg1: The first argument.
+
+#!/usr/bin/env sh
+python3 -m venv .venv
+pip3 install -r requirements.txt
+python3 ./path/to/script.py
+```
+
+## Node
+
+You can also call Node.js scripts directly the same way. For example:
+
+```yaml
+description: This is a tool that calls a Node.js script.
+args: arg1: The first argument.
+
+#!/usr/bin/env node ./path/to/script.js
+```
+
+If you need to bootstrap a Node.js environment, you can use call npm in the `tool.gpt` file. For example:
+
+```yaml
+description: This is a tool that calls a Node.js script with a package manager.
+args: arg1: The first argument.
+
+#!/usr/bin/env sh
+npm install
+node ./path/to/script.js
+```
+
+## Golang
+
+You can also call Golang binaries directly the same way. For example:
+
+```yaml
+description: This is a tool that calls a Golang binary.
+args: arg1: The first argument.
+
+#!/usr/bin/env ./path/to/binary
+```
+
+If you need to bootstrap a Golang binary, you can the go CLI to build it before running it. For example:
+
+```yaml
+description: This is a tool that calls a Golang binary.
+args: arg1: The first argument.
+
+#!/usr/bin/env sh
+go build -o ./path/to/binary
+./path/to/binary
+```

docs/docs/tools/01-authoring/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Authoring",
+  "position": 1
+}

docs/docs/tools/image-generation.md renamed to docs/docs/tools/02-offerings/01-image-generation.md

@@ -0,0 +1,4 @@
+{
+  "label": "Offerings",
+  "position": 2
+}

docs/docs/tools/system.md renamed to docs/docs/tools/02-offerings/02-system.md

@@ -1,8 +1,4 @@
 {
   "label": "Tools",
-  "position": 2,
-  "link": {
-    "type": "generated-index",
-    "description": "Explore the various tools on offer for gptscripts"
-  }
+  "position": 2
 }