diff --git a/README.md b/README.md index 6fe14c39..6f252939 100644 --- a/README.md +++ b/README.md @@ -240,31 +240,19 @@ Tool instructions go here. 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): -`Name`: The name of the tool. -`Model Name`: The OpenAI model to use, by default it uses "gpt-4-turbo-preview" +| Key | Description | +|------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| `Name` | The name of the tool. | +| `Model Name` | The OpenAI model to use, by default it uses "gpt-4-turbo-preview" | +| `Description` | The description of the tool. It is important that this properly describes the tool's purpose as the description is used by the LLM. | +| `Internal Prompt`| Setting this to `false` will disable the built-in system prompt for this tool. | +| `Tools` | A comma-separated list of tools that are available to be called by this tool. | +| `Args` | Arguments for the tool. Each argument is defined in the format `arg-name: description`. | +| `Max Tokens` | Set to a number if you wish to limit the maximum number of tokens that can be generated by the LLM. | +| `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. | +| `Temperature` | A floating-point number representing the temperature parameter. By default, the temperature is 0. Set to a higher number for more creativity. | -`Description`: The description of the tool. It is important that the properly describes the tool's purpose as the -description is used by the LLM to determine if the tool is to be invoked. - -`Internal Prompt`: Setting this to `false` will disable the built in system prompt for this tool. GPTScript includes a -default system prompt to instruct the AI to behave more like a script engine and not a "helpful assistant." - -`Tools`: A comma-separated list of tools that are available to be called by this tool. A tool can only call the tools -that are defined here. A tool name can reference a name in the current file, or a file relative to the current directory -of the tool file, a http(s) URL, or a file in GitHub using github.com/username/repo/file.gpt format. When referencing -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 -syntax `tool-name from file-or-url`. - -`Args`: Arguments for the tool. Each argument is defined in the format `arg-name: description`. All arguments are essentially -strings. No other type really exists as all input and output to tools is text based. - -`Max Tokens`: Set to a number if you wish to limit the maximum number of tokens that can be generated by the LLM. - -`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 -to inform the LLM to respond in some JSON structure. - -`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. #### Tool Body diff --git a/docs/docs/100-tools/01-using.md b/docs/docs/03-tools/01-using.md similarity index 100% rename from docs/docs/100-tools/01-using.md rename to docs/docs/03-tools/01-using.md diff --git a/docs/docs/03-tools/02-authoring.md b/docs/docs/03-tools/02-authoring.md new file mode 100644 index 00000000..e50b50bb --- /dev/null +++ b/docs/docs/03-tools/02-authoring.md @@ -0,0 +1,87 @@ +# 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. + +## Quickstart + +This is a guide for writing portable tools for GPTScript. The supported languages currently are Python, NodeJS, and Go. This guide uses Python but you can see documentation for the other language below. + +### 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 +``` + +:::tip +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. +::: + +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//`. 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// + +Get the contents of https://github.com +``` + +## Sharing Tools + +GPTScript is designed to easily export and import tools. Doing this is currently based entirely around the use of GitHub repositories. You can export a tool by creating a GitHub repository and ensureing you have the `tool.gpt` file in the root of the repository. You can then import the tool into a GPTScript by specifying the URL of the repository in the `tools` section of the script. For example, we can leverage the `image-generation` tool by adding the following line to a GPTScript: + +```yaml +tools: github.com/gptscript-ai/image-generation + +Generate an image of a city skyline at night. +``` + +### Supported Languages + +GPTScript can execute any binary that you ask it to. However, it can also manage the installation of a language runtime and dependencies for you. Currently this is only supported for a few languages. Here are the supported languages and examples of tools written in those languages: + +| Language | Example | +|----------|---------| +| `Python` | [Image Generation](https://github.com/gptscript-ai/image-generation) - Generate images based on a prompt | +| `Node.js` | [Vision](https://github.com/gptscript-ai/vision) - Analyze and interpret images | +| `Golang` | [Search](https://github.com/gptscript-ai/search) - Use various providers to search the internet | + + +### Automatic Documentation + +Each GPTScript tool is self-documented using the `tool.gpt` file. You can automatically generate documentation for your tools by visiting `tools.gptscript.ai/`. This documentation site allows others to easily search and explore the tools that have been created. + +You can add more information about how to use your tool by adding an `examples` directory to your repository and adding a collection of `.gpt` files that demonstrate how to use your tool. These examples will be automatically included in the documentation. + +For more information and to explore existing tools, visit [tools.gptscript.ai](https://tools.gptscript.ai). \ No newline at end of file diff --git a/docs/docs/100-tools/_category_.json b/docs/docs/03-tools/_category_.json similarity index 100% rename from docs/docs/100-tools/_category_.json rename to docs/docs/03-tools/_category_.json diff --git a/docs/docs/04-use-cases.md b/docs/docs/04-use-cases.md new file mode 100644 index 00000000..a88598f2 --- /dev/null +++ b/docs/docs/04-use-cases.md @@ -0,0 +1,91 @@ +# Use Cases + +## Retrieval + +Retrieval-Augmented Generation (RAG) leverages a knowledge base outside of the training data before consulting the LLM to generate a response. +The following GPTScript implements RAG: + +```yaml +name: rag +description: implements retrieval-augmented generation +args: prompt: a string +tools: query + +First query the ${prompt} in the knowledge base, then construsts an answer to ${prompt} based on the result of the query. + +--- + +name: query +description: queries the prompt in the knowledge base +args: prompt: a string + +... (implementation of knowledge base query follows) ... +``` + +The idea behind RAG is simple. Its core logic can be implemented in one GPTScript statement: `First query the ${prompt} in the knowledge base, then construsts an answer to ${prompt} based on the result of the query.` The real work of building RAG lies in the tool that queries your knowledge base. + +You construct the appropriate query tool based on the type of knowledge base you have. + +| Knowledge Base | Query Tool | +|------|------| +| A vector database storing common document types such as text, HTML, PDF, and Word | Integrate with LlamaIndex for vector database support [Link to example]| +| Use the public or private internet to supply up-to-date knowledge | Implement query tools using a search engine, as shown in [`search.gpt`](https://github.com/gptscript-ai/gptscript/tree/main/examples/search.gpt)| +| A structured database supporting SQL such as sqlite, MySQL, PostgreSQL, and Oracle DB | Implement query tools using database command line tools such as `sqlite` and `mysql` [Link to example]| +| An ElasticSearch/OpenSearch database storing logs or other text files | Implement query tools using database command line tools [Link to example]| +| Other databases such as graph or time series databases | Implement query tools using database command line tools [Link to example]| + +## Task Automation + +### Planning + +Here is a GPTScript that produces a detailed travel itinerary based on inputs from a user: [`travel-agent.gpt`](https://github.com/gptscript-ai/gptscript/tree/main/examples/travel-agent.gpt) + +### Web UI Automation + +Here is a GPTScript that automates a web browser to browse and navigate website, extract information: [coachella-browse.gpt](https://github.com/gptscript-ai/browser/tree/main/examples/coachella-browse.gpt) + +For additional examples, please explore [here](https://github.com/gptscript-ai/browser?tab=readme-ov-file#examples). + +### API Automation + +Here are a few GPTScripts that interact with issues on GitHub: + +- [Create GitHub Issues](https://github.com/gptscript-ai/create-github-issues/tree/main/examples/example.gpt) +- [Modify GitHub Issues](https://github.com/gptscript-ai/modify-github-issues/tree/main/examples/example.gpt) +- [Query GitHub Issues](https://github.com/gptscript-ai/gptscriptquery-github-issues/tree/main/examples/example.gpt) + +## Agents and Assistants + +Agents and assistants are synonyms. They are software programs that leverage LLM to carry out tasks. + +In GPTScript, agents and assistants are implemented using tools. Tools can use other tools. Tools can be implemented using natural language prompts or using traditional programming languages such as Python or JavaScript. You can therefore build arbitrarily complex agents and assistants in GPTScript. Here is an example of an assistant that leverages an HTTP client, MongoDB, and Python code generation to display Hacker News headlines: [`hacker-news-headlines.gpt`](https://github.com/gptscript-ai/gptscript/tree/main/examples/hacker-news-headlines.gpt) + +## Data Analysis + +Depending on the context window supported by the LLM, you can either send a large amount of data to the LLM to analyze in one shot or supply data in batches. + +### Summarization + +Here is a GPTScript that sends a large document in batches to the LLM and produces a summary of the entire document. [hamlet-summarizer](https://github.com/gptscript-ai/gptscript/tree/main/examples/hamlet-summarizer) + +### Tagging + +Here is a GPTScript that performs sentiment analysis on the input text: [Social Media Post Sentiment Analyzer](https://github.com/gptscript-ai/gptscript/tree/main/examples/sentiments) + +### CSV Files + +Here is a GPTScript that reads the content of a CSV file and make query using natural language: [csv-reader.gpt](https://github.com/gptscript-ai/csv-reader/tree/main/examples/csv-reader.gpt) + +### Understanding Code + +Here is a GPTScript that summarizes the code stored under the current directory: [`describe-code.gpt`](https://github.com/gptscript-ai/gptscript/tree/main/examples/describe-code.gpt) + +## Vision, Image, and Audio + +### Vision + +Here is an example of a web app that leverages GPTScript to recognize ingredients in a photo and suggest a recipe based on them: [recipe-generator](https://github.com/gptscript-ai/gptscript/tree/main/examples/recipegenerator). + +### Image Generation + +Here is a GPTScript that takes a story prompt and generates an illustrated children's book: [story-book.gpt](https://github.com/gptscript-ai/gptscript/tree/main/examples/story-book) diff --git a/docs/docs/05-how-it-works.md b/docs/docs/05-how-it-works.md new file mode 100644 index 00000000..c6538395 --- /dev/null +++ b/docs/docs/05-how-it-works.md @@ -0,0 +1,61 @@ +# How it works + +**_GPTScript is composed of tools._** Each tool performs a series of actions similar to a function. Tools have available +to them other tools that can be invoked similar to a function call. While similar to a function, the tools are +primarily implemented with a natural language prompt. **_The interaction of the tools is determined by the AI model_**, +the model determines if the tool needs to be invoked and what arguments to pass. Tools are intended to be implemented +with a natural language prompt but can also be implemented with a command or HTTP call. + +## Example + +Below are two tool definitions, separated by `---`. The first tool does not require a name or description, but +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. + +```yaml +tools: bob + +Ask Bob how he is doing and let me know exactly what he said. + +--- +name: bob +description: I'm Bob, a friendly guy. +args: question: The question to ask Bob. + +When asked how I am doing, respond with "Thanks for asking "${question}", I'm doing great fellow friendly AI tool!" +``` + +Put the above content in a file named `bob.gpt` and run the following command: + +```shell +$ gptscript bob.gpt +``` + +``` +OUTPUT: + +Bob said, "Thanks for asking 'How are you doing?', I'm doing great fellow friendly AI tool!" +``` + +Tools can be implemented by invoking a program instead of a natural language prompt. The below +example is the same as the previous example but implements Bob using python. + +```yaml +Tools: bob + +Ask Bob how he is doing and let me know exactly what he said. + +--- +Name: bob +Description: I'm Bob, a friendly guy. +Args: question: The question to ask Bob. + +#!python3 + +import os + +print(f"Thanks for asking {os.environ['question']}, I'm doing great fellow friendly AI tool!") +``` + +With these basic building blocks you can create complex scripts with AI interacting with AI, your local system, data, +or external services. + diff --git a/docs/docs/06-gpt-file-reference.md b/docs/docs/06-gpt-file-reference.md new file mode 100644 index 00000000..fd57bfe5 --- /dev/null +++ b/docs/docs/06-gpt-file-reference.md @@ -0,0 +1,82 @@ +# GPT File Reference + +## Extension + +GPTScript files use the `.gpt` extension by convention. + +## File Structure + +A GPTScript file has one or more tools in the file. Each tool is separated by three dashes `---` alone on a line. + +```yaml +Name: tool1 +Description: This is tool1 + +Do sample tool stuff. + +--- +Name: tool2 +Description: This is tool2 + +Do more sample tool stuff. +``` + +## Tool Definition + +A tool starts with a preamble that defines the tool's name, description, args, available tools and additional parameters. +The preamble is followed by the tool's body, which contains the instructions for the tool. Comments in +the preamble are lines starting with `#` and are ignored by the parser. Comments are not really encouraged +as the text is typically more useful in the description, argument descriptions or instructions. + +```yaml +Name: tool-name +# This is a comment in the preamble. +Description: Tool description +# This tool can invoke tool1 or tool2 if needed +Tools: tool1, tool2 +Args: arg1: The description of arg1 + +Tool instructions go here. +``` + +## Tool Parameters + +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): + +| Key | Description | +|------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| `Name` | The name of the tool. | +| `Model Name` | The OpenAI model to use, by default it uses "gpt-4-turbo-preview" | +| `Description` | The description of the tool. It is important that this properly describes the tool's purpose as the description is used by the LLM. | +| `Internal Prompt`| Setting this to `false` will disable the built-in system prompt for this tool. | +| `Tools` | A comma-separated list of tools that are available to be called by this tool. | +| `Args` | Arguments for the tool. Each argument is defined in the format `arg-name: description`. | +| `Max Tokens` | Set to a number if you wish to limit the maximum number of tokens that can be generated by the LLM. | +| `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. | +| `Temperature` | A floating-point number representing the temperature parameter. By default, the temperature is 0. Set to a higher number for more creativity. | + + + +## Tool Body + +The tool body contains the instructions for the tool which can be a natural language prompt or +a command to execute. Commands must start with `#!` followed by the interpreter (e.g. `#!/bin/bash`, `#!python3`) +a text that will be placed in a file and passed to the interpreter. Arguments can be references in the instructions +using the format `${arg1}`. + +```yaml +name: echo-ai +description: A tool that echos the input +args: input: The input + +Just return only "${input}" + +--- +name: echo-command +description: A tool that echos the input +args: input: The input + +#!/bin/bash + +echo "${input}" +``` diff --git a/docs/docs/100-tools/02-authoring.md b/docs/docs/100-tools/02-authoring.md deleted file mode 100644 index 8eb1c329..00000000 --- a/docs/docs/100-tools/02-authoring.md +++ /dev/null @@ -1,114 +0,0 @@ -# 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. - -Here's an example of the `tool.gpt` file for the `image-generation` tool: - -``` -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: 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 ${GPTSCRIPT_TOOL_DIR}/cli.py --prompt="${prompt}" --size="${size}" --quality="${quality}" --number="${number}" -``` - -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. So instead of accepting args using flags like `--size="${size}", your program can just read the `size` environment variable. -::: - -## 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 --arg1="${arg1}" -``` - -## 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 --arg1="${arg1}" -``` - -## Python -You can call Python scripts directly, 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 --arg1="${arg1}" -``` - -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 --arg1="${arg1}" -``` - -## Node - -You can call Node.js scripts directly, 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 --arg1="${arg1}" -``` - -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 --arg1="${arg1}" -``` - -## Golang - -You can call Golang binaries directly, for example: - -```yaml -description: This is a tool that calls a Golang binary. -args: arg1: The first argument. - -#!/usr/bin/env ./path/to/binary --arg1="${arg1}" -``` - -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 --arg1="${arg1}" -``` diff --git a/docs/docs/100-tools/03-authoring-example.md b/docs/docs/100-tools/03-authoring-example.md deleted file mode 100644 index bf96ea97..00000000 --- a/docs/docs/100-tools/03-authoring-example.md +++ /dev/null @@ -1,49 +0,0 @@ -# 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//`. 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// - -Get the contents of https://github.com -``` diff --git a/docs/docs/100-tools/03-offerings/01-system.md b/docs/docs/100-tools/03-offerings/01-system.md deleted file mode 100644 index 9575b9e5..00000000 --- a/docs/docs/100-tools/03-offerings/01-system.md +++ /dev/null @@ -1,115 +0,0 @@ -# System Tools - -GPTScript comes with a set of system tools that provide various core functionalities. - -## sys.abort - -Aborts the operation and provides an error message. - -#### Arguments - -- `message`: The description of the error or unexpected result that caused abort to be called. - -## sys.download - -Downloads a file from a specified URL to an optional location on disk with an option to override existing files. - -#### Arguments - -- `location` (optional): The on-disk location to store the downloaded file. -- `override`: If true, allows overwriting of an existing file. Default is false. -- `url`: The HTTP or HTTPS URL of the file to be downloaded. - -## sys.exec - -Executes a command with the ability to specify command arguments and the working directory. - -#### Arguments - -- `command`: The full command to run, including all arguments. -- `directory`: The working directory for the command. Defaults to the current directory ".". - -## sys.find - -Searches for files within a directory that match a given pattern using Unix glob format. - -#### Arguments - -- `directory`: The directory to perform the search in. Defaults to the current directory ".". -- `pattern`: The pattern to match against filenames. - -## sys.getenv - -Retrieves the value of an environment variable. - -#### Arguments - -- `name`: The name of the environment variable to retrieve. - -## sys.http.get - -Performs an HTTP GET request to the specified URL. - -#### Arguments - -- `url`: The URL to perform the GET request. - -## sys.http.html2text - -Converts the HTML content from a given URL to plain text. - -#### Arguments - -- `url`: The URL of the HTML content to be converted. - -## sys.http.post - -Sends an HTTP POST request with given content to a specified URL. - -#### Arguments - -- `content`: The content to be posted. -- `contentType`: The MIME type of the content being posted. -- `url`: The URL to which the POST request should be sent. - -## sys.read - -Reads the content from a specified file. - -#### Arguments - -- `filename`: The name of the file from which to read content. - -## sys.remove - -Removes a file from the specified location. - -#### Arguments - -- `location`: The path to the file that needs to be removed. - -## sys.stat - -Retrieves the status of a file, such as size, permissions, and last modified time. - -#### Arguments - -- `filepath`: The path to the file for which to retrieve status. - -## sys.write - -Writes content to a specified file. - -#### Arguments - -- `content`: The content to be written to the file. -- `filename`: The filename where the content should be written. - -## sys.append - -Appends the contents to a file. - -#### Arguments - -- `content`: The content to append. -- `filename`: The name of the file to append to. diff --git a/docs/docs/100-tools/03-offerings/02-image-generation.md b/docs/docs/100-tools/03-offerings/02-image-generation.md deleted file mode 100644 index b47d3c8f..00000000 --- a/docs/docs/100-tools/03-offerings/02-image-generation.md +++ /dev/null @@ -1,39 +0,0 @@ -# Image Generation - -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. - -For more information, check out the tool [here](https://github.com/gptscript-ai/image-generation) - -## Installation -We are working on an process where installation of tools will be as simple as -referencing the tool's link in your GPTScript. For now, you can follow the steps below to install the image-generation tool. - -1. Clone the image-generation tool repository [from GitHub](https://github.com/gptscript-ai/image-generation). - -```shell -git clone https://github.com/gptscript-ai/image-generation -``` - -2. In the newly cloned repo, run `make bootstrap` to setup the python venv and install the required dependencies. Then activate the virtual environment. - -```shell -make bootstrap -source .venv/bin/activate -``` - -> Note: You can install the python dependencies manually by running `pip install -r requirements.txt` in the root of the cloned repository. This prevents the need to run `make bootstrap` or activate the virtual environment. - -3. In the same shell session that your virtual environment is activated, reference `/tool.gpt` in your GPTScript. - -## Usage -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. - -With that setup, you can use it in any GPTScript like so: - -``` -tools: ./image-generation/tool.gpt, sys.download, sys.write - -Generate an image of a city skyline at night with a resolution of 512x512 pixels. - -Write the resulting image to a file named "city_skyline.png". -``` diff --git a/docs/docs/100-tools/03-offerings/03-internet-search.md b/docs/docs/100-tools/03-offerings/03-internet-search.md deleted file mode 100644 index b8992e97..00000000 --- a/docs/docs/100-tools/03-offerings/03-internet-search.md +++ /dev/null @@ -1,107 +0,0 @@ -# Internet Search - -## Overview - -There are a few different Internet search tools for GPTScript: - -- `bing` -- `bing-image` -- `brave` -- `brave-image` -- `duckduckgo` -- `google` -- `google-image` - -Each of these tools use the corresponding search engine's API to perform searches and return results that -the LLM can process. The number of results returned will depend on the -search engine. This is the format of the results: - -Web search format: -``` -Title: the title of the web page -URL: the link to the web page -Description: a short snippet from the web page - -Title: ... -URL: ... -Description: ... - - -``` - -Image search format: -``` -Title: the title of the image -Source: the link to the web page where the image came from -Image URL: the link to the image - -Title: ... -Source: ... -Image URL: ... - - -``` - -The tools are developed in the [gptscript-ai/search repo](https://github.com/gptscript-ai/search). - -## Setup - -:::note -This will become easier in the future, once packaging for remote GPTScript tools has been implemented. -::: - -To set up your local environment to use these tools, do the following: - -```bash -# Clone the repo -git clone https://github.com/gptscript-ai/search.git - -# Build the Go binary -make build -``` - -Now you can reference the search tools by the relative path to the `tool.gpt` file in the cloned repo, like this: - -```yaml -tools: google-image from ./search/tool.gpt, sys.download - -Search for images of pandas and download one. -``` - -:::tip -You must always specify which tool you are specifically importing from the tool.gpt file, as shown -in the example above. If no tool is specified, it will default to the first tool defined in the file, -which currently is `bing`. -::: - -Specific instructions for each search engine follow. - -## Bing - -The `bing` and `bing-image` tools return search results from the [Bing Web Search API](https://www.microsoft.com/en-us/bing/apis/bing-web-search-api). - -The environment variable `GPTSCRIPT_BING_SEARCH_TOKEN` must be set to your API key in order for it to work. - -## Brave - -The `brave` and `brave-image` tools return search results from the [Brave Search API](https://brave.com/search/api/). - -The environment variable `GPTSCRIPT_BRAVE_SEARCH_TOKEN` must be set to your API key in order for it to work. - -## DuckDuckGo - -The `duckduckgo` tool returns search results from the [DuckDuckGo HTML-only Site](https://html.duckduckgo.com). - -No API key is required to use this tool. - -By default, this tool will make an HTTP request to DuckDuckGo and parse the results. -If you do this enough times, it will start to get rate limited. -Rate limits can be more easily avoided by using Google Chrome in headless mode. -The tool will do this if the `GPTSCRIPT_USE_CHROME` environment variable is set to `true`. - -## Google - -The `google` and `google-image` tools return search results from the [Google Custom Search JSON API](https://developers.google.com/custom-search/v1/overview). - -The environment variable `GPTSCRIPT_GOOGLE_SEARCH_TOKEN` must be set to your API key in order for it to work, -and `GPTSCRIPT_GOOGLE_SEARCH_ENGINE_ID` must be set to your Programmable Search Engine's engine ID. diff --git a/docs/docs/100-tools/03-offerings/_category_.json b/docs/docs/100-tools/03-offerings/_category_.json deleted file mode 100644 index 700c3642..00000000 --- a/docs/docs/100-tools/03-offerings/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Offerings", - "collapsible": true, - "link": { - "type": "generated-index", - "title": "Offerings" - } -} diff --git a/docs/docs/100-tools/100-tools.md b/docs/docs/100-tools/100-tools.md deleted file mode 100644 index 111a0ace..00000000 --- a/docs/docs/100-tools/100-tools.md +++ /dev/null @@ -1,144 +0,0 @@ -# Tools - -***GPTScript is composed of tools.*** Each tool performs a series of actions similar to a function. Tools have available to them other tools that can be invoked similar to a function call. While similar to a function, the tools are -primarily implemented with a natural language prompt. ***The interaction of the tools is determined by the AI model***, the model determines if the tool needs to be invoked and what arguments to pass. Tools are intended to be implemented -with a natural language prompt but can also be implemented with a command or HTTP call. - -### Example -Below are two tool definitions, separated by `---`. The first tool does not require a name or description, but -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. - -```yaml -tools: bob - -Ask Bob how he is doing and let me know exactly what he said. - ---- -name: bob -description: I'm Bob, a friendly guy. -args: question: The question to ask Bob. - -When asked how I am doing, respond with "Thanks for asking "${question}", I'm doing great fellow friendly AI tool!" -``` - - -Put the above content in a file named `bob.gpt` and run the following command: -```shell -$ gptscript bob.gpt -``` -``` -OUTPUT: - -Bob said, "Thanks for asking 'How are you doing?', I'm doing great fellow friendly AI tool!" -``` - -Tools can be implemented by invoking a program instead of a natural language prompt. The below -example is the same as the previous example but implements Bob using python. - -```yaml -Tools: bob - -Ask Bob how he is doing and let me know exactly what he said. - ---- -Name: bob -Description: I'm Bob, a friendly guy. -Args: question: The question to ask Bob. - -#!python3 - -import os - -print(f"Thanks for asking {os.environ['question']}, I'm doing great fellow friendly AI tool!") -``` - -With these basic building blocks you can create complex scripts with AI interacting with AI, your local system, data, -or external services. - - -### File Structure -A GPTScript file has one or more tools in the file. Each tool is separated by three dashes `---` alone on a line. - -```yaml -Name: tool1 -Description: This is tool1 - -Do sample tool stuff. - ---- -Name: tool2 -Description: This is tool2 - -Do more sample tool stuff. -``` - -### Tool Definition - -A tool starts with a preamble that defines the tool's name, description, args, available tools and additional parameters. -The preamble is followed by the tool's body, which contains the instructions for the tool. Comments in -the preamble are lines starting with `#` and are ignored by the parser. Comments are not really encouraged -as the text is typically more useful in the description, argument descriptions or instructions. - -```yaml -Name: tool-name -# This is a comment in the preamble. -Description: Tool description -# This tool can invoke tool1 or tool2 if needed -Tools: tool1, tool2 -Args: arg1: The description of arg1 - -Tool instructions go here. -``` -#### Tool Parameters - -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): - -`Name`: The name of the tool. - -`Model Name`: The OpenAI model to use, by default it uses "gpt-4-turbo-preview" - -`Description`: The description of the tool. It is important that the properly describes the tool's purpose as the -description is used by the LLM to determine if the tool is to be invoked. - -`Internal Prompt`: Setting this to `false` will disable the built in system prompt for this tool. GPTScript includes a -default system prompt to instruct the AI to behave more like a script engine and not a "helpful assistant." - -`Tools`: A comma-separated list of tools that are available to be called by this tool. A tool can only call the tools -that are defined here. A tool name can reference a name in the current file, or a file relative to the current directory -of the tool file, a http(s) URL, or a file in GitHub using github.com/username/repo/file.gpt format. When referencing -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 -syntax `tool-name from file-or-url`. - -`Args`: Arguments for the tool. Each argument is defined in the format `arg-name: description`. All arguments are essentially -strings. No other type really exists as all input and output to tools is text based. - -`Max Tokens`: Set to a number if you wish to limit the maximum number of tokens that can be generated by the LLM. - -`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 -to inform the LLM to respond in some JSON structure. - -`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. - -#### Tool Body - -The tool body contains the instructions for the tool which can be a natural language prompt or -a command to execute. Commands must start with `#!` followed by the interpreter (e.g. `#!/bin/bash`, `#!python3`) -a text that will be placed in a file and passed to the interpreter. Arguments can be references in the instructions -using the format `${arg1}`. - -```yaml -name: echo-ai -description: A tool that echos the input -args: input: The input - -Just return only "${input}" - ---- -name: echo-command -description: A tool that echos the input -args: input: The input - -#!/bin/bash - -echo "${input}" -``` diff --git a/docs/docs/101-cookbook/_category_.json b/docs/docs/101-cookbook/_category_.json deleted file mode 100644 index 64bd7f52..00000000 --- a/docs/docs/101-cookbook/_category_.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "label": "Cookbook", - "collapsible": true, - "link": { - "type": "generated-index", - "title": "Cookbook" - }, - "customProps": { - "description": "Explore the various things you can do with GPTScript and how to do them." - } -} diff --git a/docs/docs/101-cookbook/image-generator.md b/docs/docs/101-cookbook/image-generator.md deleted file mode 100644 index 9d5b861e..00000000 --- a/docs/docs/101-cookbook/image-generator.md +++ /dev/null @@ -1,48 +0,0 @@ -# Image Generator - -In this example, let's say that we want to create an image generator tool that will take a prompt from the user and generate an image based on that prompt but -in a specific style that we tell the tool to use. - -1. Clone the image-generation tool repository from Github. - - ```shell - git clone https://github.com/gptscript-ai/image-generation - ``` - -2. Bootstrap the tool. - - ```shell - make bootstrap - ``` - -3. Create a file called `painter.gpt`. - - ```yaml - tools: ./image-generation/tool.gpt, sys.download, sys.write - args: prompt: (required) The prompt to use for generating the image. - - Generate the ${prompt} in the style of a 17th century impressionist oil painting. - - Write the resulting image to a file named "painting.png". - ``` - -4. Run the script. - - ```shell - gptscript painter.gpt --prompt "a city skyline at night" - ``` - -This will generate an image of a city skyline at night in the style of a 17th century impressionist oil painting and write the resulting image to a file named `painting.png`. - -## Recap -In this example, we have created a GPTScript that leverages the `image-generation` tool to generate an image based on a prompt. We gave it some flexibility by specifying an argument `prompt` that the user can provide when running the script. We also specified gave the script a specific style of the image that we want to generate, that being a 17th century impressionist oil painter. - -Notable things to point out: -#### Tools -The `tools` directive was used here to reference the `image-generation` tool and the `sys.download` and `sys.write` system tools. GPTScript will know the tools available to it and will use them when it sees fit in the script. - -#### Args -We used the `args` directive to specify the `prompt` argument that the user can provide when running the script. This is a required argument and the user must provide it when running the script. - -#### Interpolation -The `${prompt}` syntax can we used to reference the `prompt` argument in the script. This is a made-up syntax and can be replaced with any other syntax that you prefer. The LLM should be able to understand the syntax and use the argument in the script. diff --git a/docs/docs/101-cookbook/vision.md b/docs/docs/101-cookbook/vision.md deleted file mode 100644 index 934b76af..00000000 --- a/docs/docs/101-cookbook/vision.md +++ /dev/null @@ -1,48 +0,0 @@ -# Vision - -In this example, let's say that we want to create a `.gpt` script that uses vision to describe an image on the internet in a certain style. - -1. Clone the vision tool repository from Github - - ```shell - git clone https://github.com/gptscript-ai/vision - ``` - -2. Install the tool's dependencies - - ```shell - npm install - ``` - -3. Create a file called `describe.gpt`. - - ```yaml - Tools: sys.write, ./vision/tool.gpt - Args: url: (required) URL of the image to describe. - - Describe the image at ${url} as if you were the narrator of a Wes Anderson film and write it to a file named description.txt. - ``` - -4. Run the script. - - ```shell - gptscript describe.gpt --url "https://github.com/gptscript-ai/vision/blob/main/examples/eiffel-tower.png?raw=true" - ``` - -## Recap - -In this example, we have created a GPTScript that leverages the `vision` tool to describe an image at a given URL. We gave it some flexibility by specifying an argument `url` that the user can provide when running the script. We also gave the script a specific style to generate the description with. - -Notable things to point out: - -#### Tools - -The `tools` directive was used here to reference the `vision` and the `sys.write` tools. GPTScript will know the tools available to it and will use them when it sees fit in the script. - -#### Args - -We used the `args` directive to specify the `url` argument that the user can provide when running the script. This is a required argument and the user must provide it when running the script. - -#### Interpolation - -The `${url}` syntax can we used to reference the `url` argument in the script. This is a made-up syntax and can be replaced with any other syntax that you prefer. The LLM should be able to understand the syntax and use the argument in the script. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 7b67a9ae..be2e504d 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -65,6 +65,11 @@ const config = { label: "Discord", position: "right", }, + { + href: "https://tools.gptscript.ai/", + label: "Tool Search", + position: "right", + }, ], }, footer: {