Skip to content

feat: refactor library to expose a smaller API #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 1, 2024
Merged

feat: refactor library to expose a smaller API #25

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/release.yaml
View file
Original file line number Diff line number Diff line change
@@ -15,8 +15,8 @@ jobs:
- uses: actions/setup-node@v4
with:
node-version: 21
- name : Install dependencies
run: npm install
- name: Install dependencies
run: npm install -g typescript && npm install
- name: Publish release
run: npm run build && npm publish --access public
env:
4 changes: 4 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -49,6 +49,10 @@ coverage
.monitor

bin/
dist/
lib/

.npmrc

**/*.js
**/*.d.ts
249 changes: 88 additions & 161 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# node-gptscript

This module provides a set of functions to interact with gptscripts. It allows for executing scripts, listing available tools and models, and more. The functions are designed to be used in a Node.js environment.
This module provides a set of functions to interact with gptscripts. It allows for executing scripts, listing available
tools and models, and more. The functions are designed to be used in a Node.js environment.

## Installation

@@ -12,11 +13,13 @@ npm install @gptscript-ai/gptscript

This will install the gptscript binary in the `node_modules/@gptscript-ai/gptscript/bin` directory.

You can opt out of this behavior by setting the `NODE_GPTSCRIPT_SKIP_INSTALL_BINARY=true` environment variable before running `npm install`.
You can opt out of this behavior by setting the `NODE_GPTSCRIPT_SKIP_INSTALL_BINARY=true` environment variable before
running `npm install`.

## Usage

To use the module and run gptscripts, you need to first set the OPENAI_API_KEY environment variable to your OpenAI API key.
To use the module and run gptscripts, you need to first set the OPENAI_API_KEY environment variable to your OpenAI API
key.

To ensure it is working properly, you can run the following command:

@@ -49,8 +52,8 @@ Lists all the available built-in tools.
const gptscript = require('@gptscript-ai/gptscript');

async function listTools() {
const tools = await gptscript.listTools();
console.log(tools);
const tools = await gptscript.listTools();
console.log(tools);
}
```

@@ -64,221 +67,145 @@ Lists all the available models, returns a list.
const gptscript = require('@gptscript-ai/gptscript');

async function listModels() {
let models = [];
try {
models = await gptscript.listModels();
} catch (error) {
console.error(error);
}
let models = [];
try {
models = await gptscript.listModels();
} catch (error) {
console.error(error);
}
}
```

### exec
### version

Executes a prompt with optional arguments.
Get the first of the current `gptscript` binary being used for the calls.

```javascript
const gptscript = require('@gptscript-ai/gptscript');

const t = new gptscript.Tool({
instructions: "who was the president of the united states in 1928?"
});

try {
const response = await gptscript.exec(t);
console.log(response);
} catch (error) {
console.error(error);
}
```

### execFile

Executes a GPT script file with optional input and arguments. The script is relative to the callers source directory.
**Usage:**

```javascript
const gptscript = require('@gptscript-ai/gptscript');

const opts = {
disableCache: false,
};

async function execFile() {
try {
const out = await foo.execFile('./hello.gpt', "--input World", opts);
console.log(out);
} catch (e) {
console.error(e);
}
async function version() {
try {
console.log(await gptscript.version());
} catch (error) {
console.error(error);
}
}
```

### streamExec
### evaluate

Executes a gptscript with optional input and arguments, and returns the output streams.
Executes a prompt with optional arguments. The first argument can be a `ToolDef`, an array of `ToolDef`s, or a `string`
representing the contents of a gptscript file.

```javascript
const gptscript = require('@gptscript-ai/gptscript');

const opts = {
disableCache: false,
const t = {
instructions: "Who was the president of the united states in 1928?"
};

const t = new gptscript.Tool({
instructions: "who was the president of the united states in 1928?"
});

async function streamExec() {
try {
const { stdout, stderr, promise } = await gptscript.streamExec(t, opts);

stdout.on('data', data => {
console.log(`system: ${data}`);
});

stderr.on('data', data => {
console.log(`system: ${data}`);
});

await promise;
} catch (e) {
console.error(e);
}
try {
const run = gptscript.evaluate(t);
console.log(await run.text());
} catch (error) {
console.error(error);
}
```

### streamExecWithEvents
### run

Executes a gptscript with optional input and arguments, and returns the output and event streams.
Executes a GPT script file with optional input and arguments. The script is relative to the callers source directory.

```javascript
const gptscript = require('@gptscript-ai/gptscript');

const opts = {
disableCache: false,
disableCache: true,
input: "--input World"
};

const t = new gptscript.Tool({
instructions: "who was the president of the united states in 1928?"
});

async function streamExecWithEvents() {
try {
const { stdout, stderr, events, promise } = await gptscript.streamExecWithEvents(t, opts);

stdout.on('data', data => {
console.log(`system: ${data}`);
});

stderr.on('data', data => {
console.log(`system: ${data}`);
});

events.on('data', data => {
console.log(`events: ${data}`);
});

await promise;
} catch (e) {
console.error(e);
}
async function execFile() {
try {
const run = gptscript.run('./hello.gpt', opts);
console.log(await run.text());
} catch (e) {
console.error(e);
}
}
```

### streamExecFile
### Getting events during runs

The script is relative to the callers source directory.
The `Run` object exposes event handlers so callers can access the progress events as the script is running.

```javascript
const gptscript = require('@gptscript-ai/gptscript');
The `Run` object exposes these events with their corresponding event type:

const opts = {
disableCache: false,
};

async function streamExecFile() {
try {
const { stdout, stderr, promise } = await gptscript.streamExecFile('./test.gpt', "--testin how high is that there mouse?", opts);

stdout.on('data', data => {
console.log(`system: ${data}`);
});

stderr.on('data', data => {
console.log(`system: ${data}`);
});

await promise;
} catch (e) {
console.error(e);
}
}
```

### streamExecFileWithEvents
| Event type | Event object |
|---------------------------|-------------------|
| RunEventType.RunStart | RunStartFrame |
| RunEventType.RunFinish | RunFinishFrame |
| RunEventType.CallStart | CallStartFrame |
| RunEventType.CallChat | CallChatFrame |
| RunEventType.CallContinue | CallContinueFrame |
| RunEventType.CallProgress | CallProgressFrame |
| RunEventType.CallFinish | CallFinishFrame |
| RunEventType.Event | Frame |

The script is relative to the callers source directory.
Subscribing to `RunEventType.Event` gets you all events.

```javascript
const gptscript = require('@gptscript-ai/gptscript');

const opts = {
disableCache: false,
disableCache: true,
input: "--testin how high is that there mouse?"
};

async function streamExecFileWithEvents() {
try {
const { stdout, stderr, events, promise } = await gptscript.streamExecFileWithEvents('./test.gpt', "--testin how high is that there mouse?", opts);

stdout.on('data', data => {
console.log(`system: ${data}`);
});

stderr.on('data', data => {
console.log(`system: ${data}`);
});
try {
const run = gptscript.run('./test.gpt', opts);

events.on('data', data => {
console.log(`event: ${data}`);
});
run.on(gptscript.RunEventType.Event, data => {
console.log(`event: ${data}`);
});

await promise;
} catch (e) {
console.error(e);
}
await run.text();
} catch (e) {
console.error(e);
}
}
```

## Types

### Tool Parameters

| Argument | Type | Default | Description |
|----------------|----------------|-------------|-----------------------------------------------------------------------------------------------|
| name | string | `""` | The name of the tool. Optional only on the first tool if there are multiple tools defined. |
| description | string | `""` | A brief description of what the tool does, this is important for explaining to the LLM when it should be used. |
| tools | array | `[]` | An array of tools that the current tool might depend on or use. |
| maxTokens | number/undefined | `undefined` | The maximum number of tokens to be used. Prefer `undefined` for uninitialized or optional values. |
| model | string | `""` | The model that the tool uses, if applicable. |
| disableCache | boolean | `true` | Whether caching is enabled for the tool. |
| temperature | number/undefined | `undefined` | The temperature setting for the model, affecting randomness. `undefined` for default behavior. |
| args | object | `{}` | Additional arguments specific to the tool, described by key-value pairs. |
| internalPrompt | boolean | `false` | An internal prompt used by the tool, if any. |
| 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|
| Argument | Type | Default | Description |
|----------------|------------------|-------------|----------------------------------------------------------------------------------------------------------------------------|
| name | string | `""` | The name of the tool. Optional only on the first tool if there are multiple tools defined. |
| description | string | `""` | A brief description of what the tool does, this is important for explaining to the LLM when it should be used. |
| tools | array | `[]` | An array of tools that the current tool might depend on or use. |
| maxTokens | number/undefined | `undefined` | The maximum number of tokens to be used. Prefer `undefined` for uninitialized or optional values. |
| modelName | string | `""` | The model that the tool uses, if applicable. |
| cache | boolean | `true` | Whether caching is enabled for the tool. |
| temperature | number/undefined | `undefined` | The temperature setting for the model, affecting randomness. `undefined` for default behavior. |
| args | object | `{}` | Additional arguments specific to the tool, described by OpenAPIv3 spec. |
| internalPrompt | boolean | `false` | An internal prompt used by the tool, if any. |
| 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 |
| export | string[] | [] | A list of tools exported by this tool |

## License

Copyright (c) 2024, [Acorn Labs, Inc.](https://www.acorn.io)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at

<http://www.apache.org/licenses/LICENSE-2.0>

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "
AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
language governing permissions and limitations under the License.
Loading