Skip to content

Commit be83eac

Browse files
thedadamsthedadams
committed
feat: refactor library to expose a smaller API
Signed-off-by: Donnie Adams <[email protected]>
1 parent b7f3a68 commit be83eac

16 files changed

+6758
-6496
lines changed

‎.github/workflows/release.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ jobs:
1515
- uses: actions/setup-node@v4
1616
with:
1717
node-version: 21
18-
- name : Install dependencies
19-
run: npm install
18+
- name: Install dependencies
19+
run: npm install -g typescript && npm install
2020
- name: Publish release
2121
run: npm run build && npm publish --access public
2222
env:

‎.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,10 @@ coverage
4949
.monitor
5050

5151
bin/
52+
dist/
5253
lib/
5354

5455
.npmrc
56+
57+
**/*.js
58+
**/*.d.ts

‎README.md

+88-161
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# node-gptscript
22

3-
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.
3+
This module provides a set of functions to interact with gptscripts. It allows for executing scripts, listing available
4+
tools and models, and more. The functions are designed to be used in a Node.js environment.
45

56
## Installation
67

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

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

15-
You can opt out of this behavior by setting the `NODE_GPTSCRIPT_SKIP_INSTALL_BINARY=true` environment variable before running `npm install`.
16+
You can opt out of this behavior by setting the `NODE_GPTSCRIPT_SKIP_INSTALL_BINARY=true` environment variable before
17+
running `npm install`.
1618

1719
## Usage
1820

19-
To use the module and run gptscripts, you need to first set the OPENAI_API_KEY environment variable to your OpenAI API key.
21+
To use the module and run gptscripts, you need to first set the OPENAI_API_KEY environment variable to your OpenAI API
22+
key.
2023

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

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

5154
async function listTools() {
52-
const tools = await gptscript.listTools();
53-
console.log(tools);
55+
const tools = await gptscript.listTools();
56+
console.log(tools);
5457
}
5558
```
5659

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

6669
async function listModels() {
67-
let models = [];
68-
try {
69-
models = await gptscript.listModels();
70-
} catch (error) {
71-
console.error(error);
72-
}
70+
let models = [];
71+
try {
72+
models = await gptscript.listModels();
73+
} catch (error) {
74+
console.error(error);
75+
}
7376
}
7477
```
7578

76-
### exec
79+
### version
7780

78-
Executes a prompt with optional arguments.
81+
Get the first of the current `gptscript` binary being used for the calls.
7982

80-
```javascript
81-
const gptscript = require('@gptscript-ai/gptscript');
82-
83-
const t = new gptscript.Tool({
84-
instructions: "who was the president of the united states in 1928?"
85-
});
86-
87-
try {
88-
const response = await gptscript.exec(t);
89-
console.log(response);
90-
} catch (error) {
91-
console.error(error);
92-
}
93-
```
94-
95-
### execFile
96-
97-
Executes a GPT script file with optional input and arguments. The script is relative to the callers source directory.
83+
**Usage:**
9884

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

102-
const opts = {
103-
disableCache: false,
104-
};
105-
106-
async function execFile() {
107-
try {
108-
const out = await foo.execFile('./hello.gpt', "--input World", opts);
109-
console.log(out);
110-
} catch (e) {
111-
console.error(e);
112-
}
88+
async function version() {
89+
try {
90+
console.log(await gptscript.version());
91+
} catch (error) {
92+
console.error(error);
93+
}
11394
}
11495
```
11596

116-
### streamExec
97+
### evaluate
11798

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

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

123-
const opts = {
124-
disableCache: false,
105+
const t = {
106+
instructions: "Who was the president of the united states in 1928?"
125107
};
126108

127-
const t = new gptscript.Tool({
128-
instructions: "who was the president of the united states in 1928?"
129-
});
130-
131-
async function streamExec() {
132-
try {
133-
const { stdout, stderr, promise } = await gptscript.streamExec(t, opts);
134-
135-
stdout.on('data', data => {
136-
console.log(`system: ${data}`);
137-
});
138-
139-
stderr.on('data', data => {
140-
console.log(`system: ${data}`);
141-
});
142-
143-
await promise;
144-
} catch (e) {
145-
console.error(e);
146-
}
109+
try {
110+
const run = gptscript.evaluate(t);
111+
console.log(await run.text());
112+
} catch (error) {
113+
console.error(error);
147114
}
148115
```
149116

150-
### streamExecWithEvents
117+
### run
151118

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

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

157124
const opts = {
158-
disableCache: false,
125+
disableCache: true,
126+
input: "--input World"
159127
};
160128

161-
const t = new gptscript.Tool({
162-
instructions: "who was the president of the united states in 1928?"
163-
});
164-
165-
async function streamExecWithEvents() {
166-
try {
167-
const { stdout, stderr, events, promise } = await gptscript.streamExecWithEvents(t, opts);
168-
169-
stdout.on('data', data => {
170-
console.log(`system: ${data}`);
171-
});
172-
173-
stderr.on('data', data => {
174-
console.log(`system: ${data}`);
175-
});
176-
177-
events.on('data', data => {
178-
console.log(`events: ${data}`);
179-
});
180-
181-
await promise;
182-
} catch (e) {
183-
console.error(e);
184-
}
129+
async function execFile() {
130+
try {
131+
const run = gptscript.run('./hello.gpt', opts);
132+
console.log(await run.text());
133+
} catch (e) {
134+
console.error(e);
135+
}
185136
}
186137
```
187138

188-
### streamExecFile
139+
### Getting events during runs
189140

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

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

195-
const opts = {
196-
disableCache: false,
197-
};
198-
199-
async function streamExecFile() {
200-
try {
201-
const { stdout, stderr, promise } = await gptscript.streamExecFile('./test.gpt', "--testin how high is that there mouse?", opts);
202-
203-
stdout.on('data', data => {
204-
console.log(`system: ${data}`);
205-
});
206-
207-
stderr.on('data', data => {
208-
console.log(`system: ${data}`);
209-
});
210-
211-
await promise;
212-
} catch (e) {
213-
console.error(e);
214-
}
215-
}
216-
```
217-
218-
### streamExecFileWithEvents
145+
| Event type | Event object |
146+
|---------------------------|-------------------|
147+
| RunEventType.RunStart | RunStartFrame |
148+
| RunEventType.RunFinish | RunFinishFrame |
149+
| RunEventType.CallStart | CallStartFrame |
150+
| RunEventType.CallChat | CallChatFrame |
151+
| RunEventType.CallContinue | CallContinueFrame |
152+
| RunEventType.CallProgress | CallProgressFrame |
153+
| RunEventType.CallFinish | CallFinishFrame |
154+
| RunEventType.Event | Frame |
219155

220-
The script is relative to the callers source directory.
156+
Subscribing to `RunEventType.Event` gets you all events.
221157

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

225161
const opts = {
226-
disableCache: false,
162+
disableCache: true,
163+
input: "--testin how high is that there mouse?"
227164
};
228165

229166
async function streamExecFileWithEvents() {
230-
try {
231-
const { stdout, stderr, events, promise } = await gptscript.streamExecFileWithEvents('./test.gpt', "--testin how high is that there mouse?", opts);
232-
233-
stdout.on('data', data => {
234-
console.log(`system: ${data}`);
235-
});
236-
237-
stderr.on('data', data => {
238-
console.log(`system: ${data}`);
239-
});
167+
try {
168+
const run = gptscript.run('./test.gpt', opts);
240169

241-
events.on('data', data => {
242-
console.log(`event: ${data}`);
243-
});
170+
run.on(gptscript.RunEventType.Event, data => {
171+
console.log(`event: ${data}`);
172+
});
244173

245-
await promise;
246-
} catch (e) {
247-
console.error(e);
248-
}
174+
await run.text();
175+
} catch (e) {
176+
console.error(e);
177+
}
249178
}
250179
```
251180

252181
## Types
253182

254183
### Tool Parameters
255184

256-
| Argument | Type | Default | Description |
257-
|----------------|----------------|-------------|-----------------------------------------------------------------------------------------------|
258-
| name | string | `""` | The name of the tool. Optional only on the first tool if there are multiple tools defined. |
259-
| description | string | `""` | A brief description of what the tool does, this is important for explaining to the LLM when it should be used. |
260-
| tools | array | `[]` | An array of tools that the current tool might depend on or use. |
261-
| maxTokens | number/undefined | `undefined` | The maximum number of tokens to be used. Prefer `undefined` for uninitialized or optional values. |
262-
| model | string | `""` | The model that the tool uses, if applicable. |
263-
| disableCache | boolean | `true` | Whether caching is enabled for the tool. |
264-
| temperature | number/undefined | `undefined` | The temperature setting for the model, affecting randomness. `undefined` for default behavior. |
265-
| args | object | `{}` | Additional arguments specific to the tool, described by key-value pairs. |
266-
| internalPrompt | boolean | `false` | An internal prompt used by the tool, if any. |
267-
| instructions | string | `""` | Instructions on how to use the tool. |
268-
| 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 |
269-
270-
### FreeForm Parameters
271-
272-
| Argument | Type | Default | Description |
273-
|-----------|--------|---------|---------------------------------------|
274-
| content | string | `""` | This is a multi-line string that contains the entire contents of a valid gptscript file|
185+
| Argument | Type | Default | Description |
186+
|----------------|------------------|-------------|----------------------------------------------------------------------------------------------------------------------------|
187+
| name | string | `""` | The name of the tool. Optional only on the first tool if there are multiple tools defined. |
188+
| description | string | `""` | A brief description of what the tool does, this is important for explaining to the LLM when it should be used. |
189+
| tools | array | `[]` | An array of tools that the current tool might depend on or use. |
190+
| maxTokens | number/undefined | `undefined` | The maximum number of tokens to be used. Prefer `undefined` for uninitialized or optional values. |
191+
| modelName | string | `""` | The model that the tool uses, if applicable. |
192+
| cache | boolean | `true` | Whether caching is enabled for the tool. |
193+
| temperature | number/undefined | `undefined` | The temperature setting for the model, affecting randomness. `undefined` for default behavior. |
194+
| args | object | `{}` | Additional arguments specific to the tool, described by OpenAPIv3 spec. |
195+
| internalPrompt | boolean | `false` | An internal prompt used by the tool, if any. |
196+
| instructions | string | `""` | Instructions on how to use the tool. |
197+
| 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 |
198+
| export | string[] | [] | A list of tools exported by this tool |
275199

276200
## License
277201

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

280-
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
204+
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
205+
License. You may obtain a copy of the License at
281206

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

284-
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.
209+
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "
210+
AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
211+
language governing permissions and limitations under the License.

0 commit comments

Comments
 (0)