feat: add Run type for more manageable implementation

.gitignore

@@ -24,5 +24,6 @@ go.work
 .idea/
 .vscode/
 
+workspace/
 bin/
 workspace/

README.md

@@ -16,6 +16,14 @@ To use the module, you need to first set the OPENAI_API_KEY environment variable
 
 Additionally, you need the `gptscript` binary. You can install it on your system using the [installation instructions](https://github.com/gptscript-ai/gptscript?tab=readme-ov-file#1-install-the-latest-release). The binary can be on the PATH, or the `GPTSCRIPT_BIN` environment variable can be used to specify its location.
 
+## Client
+
+There are currently a couple "global" options, and the client helps to manage those. A client without any options is
+likely what you want. However, here are the current global options:
+
+- `gptscriptURL`: The URL (including `http(s)://) of an "SDK server" to use instead of the fork/exec model.
+- `gptscriptBin`: The path to a `gptscript` binary to use instead of the bundled one.
+
 ## Options
 
 These are optional options that can be passed to the various `exec` functions.
@@ -26,6 +34,10 @@ None of the options is required, and the defaults will reduce the number of call
 - `quiet`: No output logging
 - `chdir`: Change current working directory
 - `subTool`: Use tool of this name, not the first tool
+- `input`: Input arguments for the tool run
+- `workspace`: Directory to use for the workspace, if specified it will not be deleted on exit
+- `inlcudeEvents`: Whether to include the streaming of events. Default (false). Note that if this is true, you must stream the events. See below for details.
+- `chatState`: The chat state to continue, or null to start a new chat and return the state
 
 ## Functions
 
@@ -45,7 +57,9 @@ import (
 )
 
 func listTools(ctx context.Context) (string, error) {
-	return gogptscript.ListTools(ctx)
+	client := &gogptscript.Client{}
+	client.Complete()
+	return client.ListTools(ctx)
 }
 ```
 
@@ -65,13 +79,15 @@ import (
 )
 
 func listModels(ctx context.Context) ([]string, error) {
-	return gogptscript.ListModels(ctx)
+	client := &gogptscript.Client{}
+	client.Complete()
+	return client.ListModels(ctx)
 }
 ```
 
-### ExecTool
+### Parse
 
-Executes a prompt with optional arguments.
+Parse file into a Tool data structure
 
 ```go
 package main
@@ -82,18 +98,17 @@ import (
 	gogptscript "github.com/gptscript-ai/go-gptscript"
 )
 
-func runTool(ctx context.Context) (string, error) {
-	t := gogptscript.Tool{
-		Instructions: "who was the president of the united states in 1928?",
-	}
-
-	return gogptscript.ExecTool(ctx, gogptscript.Opts{}, t)
+func parse(ctx context.Context, fileName string) ([]gogptscript.Node, error) {
+	client := &gogptscript.Client{}
+	client.Complete()
+
+	return client.Parse(ctx, fileName)
 }
 ```
 
-### ExecFile
+### ParseTool
 
-Executes a GPT script file with optional input and arguments. The script is relative to the callers source directory.
+Parse contents that represents a GPTScript file into a data structure.
 
 ```go
 package main
@@ -104,18 +119,17 @@ import (
 	gogptscript "github.com/gptscript-ai/go-gptscript"
 )
 
-func execFile(ctx context.Context) (string, error) {
-	opts := gogptscript.Opts{
-		DisableCache: &[]bool{true}[0],
-	}
-
-	return gogptscript.ExecFile(ctx, "./hello.gpt", "--input World", opts)
+func parseTool(ctx context.Context, contents string) ([]gogptscript.Node, error) {
+	client := &gogptscript.Client{}
+	client.Complete()
+
+	return client.ParseTool(ctx, contents)
 }
 ```
 
-### StreamExecTool
+### Fmt
 
-Executes a gptscript with optional input and arguments, and returns the output streams.
+Parse convert a tool data structure into a GPTScript file.
 
 ```go
 package main
@@ -126,22 +140,17 @@ import (
 	gogptscript "github.com/gptscript-ai/go-gptscript"
 )
 
-func streamExecTool(ctx context.Context) error {
-	t := gogptscript.Tool{
-		Instructions: "who was the president of the united states in 1928?",
-	}
-
-	stdOut, stdErr, wait := gogptscript.StreamExecTool(ctx, gogptscript.Opts{}, t)
-
-	// Read from stdOut and stdErr before call wait()
-
-	return wait()
+func parse(ctx context.Context, nodes []gogptscript.node) (string, error) {
+	client := &gogptscript.Client{}
+	client.Complete()
+
+	return client.Fmt(ctx, nodes)
 }
 ```
 
-### StreamExecToolWithEvents
+### Evaluate
 
-Executes a gptscript with optional input and arguments, and returns the stdout, stderr, and gptscript events streams.
+Executes a tool with optional arguments.
 
 ```go
 package main
@@ -152,22 +161,26 @@ import (
 	gogptscript "github.com/gptscript-ai/go-gptscript"
 )
 
-func streamExecTool(ctx context.Context) error {
-	t := gogptscript.Tool{
+func runTool(ctx context.Context) (string, error) {
+	t := gogptscript.ToolDef{
 		Instructions: "who was the president of the united states in 1928?",
 	}
 
-	stdOut, stdErr, events, wait := gogptscript.StreamExecToolWithEvents(ctx, gogptscript.Opts{}, t)
+	client := &gogptscript.Client{}
+	client.Complete()
 
-	// Read from stdOut and stdErr before call wait()
+	run, err := client.Evaluate(ctx, gogptscript.Opts{}, t)
+	if err != nil {
+		return "", err
+	}
 
-	return wait()
+	return run.Text()
 }
 ```
 
-### streamExecFile
+### Run
 
-The script is relative to the callers source directory.
+Executes a GPT script file with optional input and arguments. The script is relative to the callers source directory.
 
 ```go
 package main
@@ -178,22 +191,27 @@ import (
 	gogptscript "github.com/gptscript-ai/go-gptscript"
 )
 
-func streamExecTool(ctx context.Context) error {
+func runFile(ctx context.Context) (string, error) {
 	opts := gogptscript.Opts{
 		DisableCache: &[]bool{true}[0],
+		Input: "--input hello",
 	}
 
-	stdOut, stdErr, wait := gogptscript.StreamExecFile(ctx, "./hello.gpt", "--input world", opts)
+	client := &gogptscript.Client{}
+	client.Complete()
 
-	// Read from stdOut and stdErr before call wait()
+	run, err := client.Run(ctx, "./hello.gpt",  opts)
+	if err != nil {
+		return "", err
+	}
 
-	return wait()
+	return run.Text()
 }
 ```
 
-### streamExecFileWithEvents
+### Streaming events
 
-The script is relative to the callers source directory.
+In order to stream events, you must set `IncludeEvents` option to `true`. You if you don't set this and try to stream events, then it will succeed, but you will not get any events. More importantly, if you set `IncludeEvents` to `true`, you must stream the events for the script to complete.
 
 ```go
 package main
@@ -206,14 +224,26 @@ import (
 
 func streamExecTool(ctx context.Context) error {
 	opts := gogptscript.Opts{
-		DisableCache: &[]bool{true}[0],
+		DisableCache:  &[]bool{true}[0],
+		IncludeEvents: true,
+		Input:         "--input world",
 	}
 
-	stdOut, stdErr, events, wait := gogptscript.StreamExecFileWithEvents(ctx, "./hello.gpt", "--input world", opts)
+	client := &gogptscript.Client{}
+	client.Complete()
 
-	// Read from stdOut and stdErr before call wait()
+	run, err := client.Run(ctx, "./hello.gpt", opts)
+	if err != nil {
+		return err
+	}
 
-	return wait()
+	for event := range run.Events() {
+		// Process event...
+	}
+
+	// Wait for the output to ensure the script completes successfully.
+	_, err = run.Text()
+	return err
 }
 ```
 
@@ -235,12 +265,6 @@ func streamExecTool(ctx context.Context) error {
 | instructions      | string         | `""`        | Instructions on how to use the tool.                                                          |
 | jsonResponse      | boolean        | `false`     | Whether the tool returns a JSON response instead of plain text. You must include the word 'json' in the body of the prompt                               |
 
-### FreeForm Parameters
-
-| Argument  | Type   | Default | Description                           |
-|-----------|--------|---------|---------------------------------------|
-| content   | string | `""`    | This is a multi-line string that contains the  entire contents of a valid gptscript file|
-
 ## License
 
 Copyright (c) 2024, [Acorn Labs, Inc.](https://www.acorn.io)