Skip to content

Commit 83fb0ab

Browse files
pixelasspixelass
authored
feat: improved api (#9)
1 parent 55cc83c commit 83fb0ab

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+1881
-4771
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ node_modules/
5151

5252
# outfolder for examples
5353
out
54+
examples/output
5455

5556
# distribution files
5657
dist

‎.ncurc.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"upgrade": true,
3+
"reject": ["@types/node"]
4+
}

‎docs/01_GETTING_STARTED.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,10 @@ Provide a question to the agent and obtain the answer:
3434

3535
```typescript
3636
try {
37-
const answer = await agent.assign({ question: "What is time?" });
38-
console.log(answer.message);
37+
const answer = await agent.assign({ question: "What is time?" });
38+
console.log(answer.message);
3939
} catch (error) {
40-
console.error("Error:", error);
40+
console.error("Error:", error);
4141
}
4242
```
4343

@@ -47,13 +47,13 @@ Execute the script and check the console output:
4747

4848
```json
4949
{
50-
"thought": "Time is a concept that humans use to measure the duration between events.",
51-
"reason": "It is a way to organize and understand the sequence of events that occur in our lives.",
52-
"reflection": "Time is a fundamental aspect of our existence, and yet it is something that we cannot see or touch. It is a human construct that helps us make sense of the world around us.",
53-
"answer": "Time can be defined as the duration between events, and it is a concept that is used to organize and understand the sequence of events that occur in our lives."
50+
"thought": "Time is a concept that humans use to measure the duration between events.",
51+
"reason": "It is a way to organize and understand the sequence of events that occur in our lives.",
52+
"reflection": "Time is a fundamental aspect of our existence, and yet it is something that we cannot see or touch. It is a human construct that helps us make sense of the world around us.",
53+
"answer": "Time can be defined as the duration between events, and it is a concept that is used to organize and understand the sequence of events that occur in our lives."
5454
}
5555
```
5656

5757
Next:
5858

59-
- [System Instructions](02_SYSTEM_INSTRUCTIONS.md)
59+
- [System Instructions](02_SYSTEM_INSTRUCTIONS.md)

‎docs/02_SYSTEM_INSTRUCTIONS.md

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ With a system instruction in place, you can guide the language model to generate
44
structured responses. You can learn more about system instructions in this
55
[article by OpenAI](https://platform.openai.com/docs/guides/chat/instructing-chat-models).
66

7-
Hyv is designed to work seamlessly with JSON, and it includes a powerful helper that delivers
8-
reliable output.
7+
Hyv is designed to work seamlessly with Markdown and JSON, and it includes powerful helpers that
8+
deliver reliable output.
99

1010
## Creating a System Instruction
1111

@@ -17,25 +17,26 @@ import { Agent } from "@hyv/core";
1717
import { createInstruction, GPTModelAdapter } from "@hyv/openai";
1818

1919
const mathModel = new GPTModelAdapter({
20-
systemInstruction: createInstruction(
21-
"Mathematician",
22-
"think about the problem, reason your thoughts, solve the problems step by step",
23-
{
24-
thought: "detailed string",
25-
reason: "detailed string",
26-
steps: ["step"],
27-
solution: "concise answer",
28-
}
29-
),
20+
format: "json", // Set the format to "json"
21+
systemInstruction: createInstruction(
22+
"Mathematician",
23+
"think about the problem, reason your thoughts, solve the problems step by step",
24+
{
25+
thought: "detailed string",
26+
reason: "detailed string",
27+
steps: ["calculation step"],
28+
solution: "concise answer",
29+
}
30+
),
3031
});
3132

3233
const mathAgent = new Agent(mathModel);
3334

3435
try {
35-
const answer = await mathAgent.assign({ problem: "(10 * 4 + 2) / (10 * 2 + 11 * 2) = ?" });
36-
console.log(answer.message);
36+
const answer = await mathAgent.assign({ problem: "(10 * 4 + 2) / (10 * 2 + 11 * 2) = x" });
37+
console.log(answer.message);
3738
} catch (error) {
38-
console.error("Error:", error);
39+
console.error("Error:", error);
3940
}
4041
```
4142

@@ -53,11 +54,11 @@ Run the script and review the console output:
5354
'20 + 22 = 42',
5455
'42 / 42 = 1'
5556
],
56-
solution: '1'
57+
solution: 'x = 1'
5758
}
5859

5960
```
6061

6162
Next:
6263

63-
- [Creating a sequence](03_CREATING_A_SEQUENCE.md)
64+
- [Creating a sequence](03_CREATING_A_SEQUENCE.md)

‎docs/03_CREATING_A_SEQUENCE.md

Lines changed: 34 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@ import { GPTModelAdapter } from "@hyv/openai";
1919
const agent = new Agent(new GPTModelAdapter(), { verbosity: 1 });
2020

2121
try {
22-
await sequence({ question: "What is life?" }, [agent]);
22+
await sequence({ question: "What is life?" }, [agent]);
2323
} catch (error) {
24-
console.error("Error:", error);
24+
console.error("Error:", error);
2525
}
2626
```
2727

@@ -56,40 +56,41 @@ import { Agent, sequence } from "@hyv/core";
5656
import { createInstruction, GPTModelAdapter } from "@hyv/openai";
5757

5858
const agents = Array.from<undefined, Agent>(
59-
{ length: 3 },
60-
() =>
61-
new Agent(
62-
new GPTModelAdapter({
63-
model: "gpt-4",
64-
systemInstruction: createInstruction(
65-
"AI",
66-
"think about the task, reason your thoughts, create a new task based on your decision!",
67-
{
68-
mainGoal: "{{mainGoal}}",
69-
thoughts: "detailed string",
70-
reason: "detailed string",
71-
task: "full and detailed task without references",
72-
}
73-
),
74-
}),
75-
{
76-
async before({ task, mainGoal }) {
77-
return {
78-
task,
79-
mainGoal,
80-
};
81-
},
82-
verbosity: 1,
83-
}
84-
)
59+
{ length: 3 },
60+
() =>
61+
new Agent(
62+
new GPTModelAdapter({
63+
model: "gpt-4",
64+
systemInstruction: createInstruction(
65+
"AI",
66+
"think about the task, reason your thoughts, create a new task based on your decision!",
67+
{
68+
mainGoal: "{{mainGoal}}",
69+
thoughts: "detailed string",
70+
reason: "detailed string",
71+
task: "full and detailed task without references",
72+
}
73+
),
74+
}),
75+
{
76+
async before({ task, mainGoal }) {
77+
// Only use the mainGoal and task
78+
return {
79+
task,
80+
mainGoal,
81+
};
82+
},
83+
verbosity: 1,
84+
}
85+
)
8586
);
8687

8788
try {
88-
await sequence(
89-
{ task: "Make the world a better place!", mainGoal: "Make the world a better place!" },
90-
agents
91-
);
89+
await sequence(
90+
{ task: "Make the world a better place!", mainGoal: "Make the world a better place!" },
91+
agents
92+
);
9293
} catch (error) {
93-
console.error("Error:", error);
94+
console.error("Error:", error);
9495
}
9596
```

‎docs/api/AGENT.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# Agent API
22

3-
| Option | Type | Description |
4-
| --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
5-
| `model` | ModelAdapter | The model instance used by the agent. |
6-
| `options` | AgentOptions | Configuration options for the agent. |
7-
| `options.before` | Function | An optional asynchronous function executed before the task is processed. Receives the task and should return an object containing the updated task. |
8-
| `options.after` | Function | An optional asynchronous function executed after the task is processed. Receives the task and should return an object containing the updated task. |
9-
| `options.finally` | Function | An optional asynchronous function executed when the process is done. Receives the messageId and the processed message, and should return the messageId. |
10-
| `options.sideEffects` | Array | An optional array of side effect functions to be executed during the task processing. |
11-
| `options.store` | StoreAdapter | The store that should be used to save and retrieve messages. |
12-
| `options.verbosity` | Number | An optional verbosity level (0, 1, or 2) that determines the amount of information displayed during the task processing. Higher values result in more information being displayed. Default is 0. |
3+
| Option | Type | Description |
4+
| --------------------- |----------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
5+
| `model` | `ModelAdapter` | The model instance used by the agent. |
6+
| `options` | `AgentOptions` | Configuration options for the agent. |
7+
| `options.before` | `Function` | An optional asynchronous function executed before the task is processed. Receives the task and should return an object containing the updated task. |
8+
| `options.after` | `Function` | An optional asynchronous function executed after the task is processed. Receives the task and should return an object containing the updated task. |
9+
| `options.finally` | `Function` | An optional asynchronous function executed when the process is done. Receives the messageId and the processed message, and should return the messageId. |
10+
| `options.sideEffects` | `SideEffect[]` | An optional array of side effect functions to be executed during the task processing. |
11+
| `options.store` | `StoreAdapter` | The store that should be used to save and retrieve messages. |
12+
| `options.verbosity` | `number` | An optional verbosity level (0, 1, or 2) that determines the amount of information displayed during the task processing. Higher values result in more information being displayed. Default is 0. |

‎docs/api/GPT_MODEL_ADAPTER.md

Lines changed: 8 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,10 @@
11
# GPTModelAdapter API
22

3-
| Name | Type | Description |
4-
| ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
5-
| model | GPTModel | The model name. Compatible GPT models: "gpt-3.5-turbo" or "gpt-4". |
6-
| temperature | ReasonableTemperature | The temperature value controlling the randomness of the model's output. Range: 0 to 0.9 with increments of 0.1. |
7-
| maxTokens | number | The maximum number of tokens in the output response. |
8-
| historySize | ModelHistorySize\[Model\] | The number of chat messages to maintain in history. GPT-3 history size: 1 or 2; GPT-4 history size: 1, 2, 3, or 4. |
9-
| systemInstruction | string | An initial system instruction to guide the model's behavior. |
10-
11-
For GPT3 specific options:
12-
13-
| Name | Type | Description |
14-
| ----------- | --------------- | ---------------------------------------- |
15-
| model | "gpt-3.5-turbo" | GPT-3 model name. |
16-
| historySize | GPT3HistorySize | GPT-3 valid history size values: 1 or 2. |
17-
18-
For GPT4 specific options:
19-
20-
| Name | Type | Description |
21-
| ----------- | --------------- | ----------------------------------------------- |
22-
| model | "gpt-4" | GPT-4 model name. |
23-
| historySize | GPT4HistorySize | GPT-4 valid history size values: 1, 2, 3, or 4. |
3+
| Name | Type | Description |
4+
|-------------------|-------------------|------------------------------------------------------------------------|
5+
| `model` | `string` | The model name |
6+
| `temperature` | `number` | The temperature value controlling the randomness of the model's output |
7+
| `maxTokens` | `number` | The maximum number of tokens in the output response. |
8+
| `historySize` | `number` | The number of chat messages to maintain in history. |
9+
| `format` | `"json"\| "string"` | The number of chat messages to maintain in history. |
10+
| `systemInstruction` | `string` | An initial system instruction to guide the model's behavior. |

‎examples/auto-book.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ export function createFileWriterWithReadingTime(
3737
};
3838
}
3939

40-
const dir = `out/auto-stories/${Date.now()}`;
40+
const dir = path.join(process.cwd(), `examples/output/auto-book/${Date.now()}`);
4141
const fileWriter = createFileWriterWithReadingTime(dir);
4242
const imageWriter = createFileWriter(dir, "base64");
4343

@@ -132,6 +132,7 @@ const author = new Agent(
132132
model: "gpt-4",
133133
maxTokens: 4096,
134134
temperature: 0.7,
135+
format: "json",
135136
systemInstruction: createInstruction(
136137
"Author named Morgan Casey Patel",
137138
minify`\

‎examples/auto-tweet.ts

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
1+
import path from "node:path";
2+
13
import type { ModelMessage } from "@hyv/core";
24
import { Agent, sequence } from "@hyv/core";
35
import { createInstruction, GPTModelAdapter } from "@hyv/openai";
46
import type { ImageMessage } from "@hyv/stable-diffusion";
57
import { Automatic1111ModelAdapter } from "@hyv/stable-diffusion";
68
import { minify, createFileWriter } from "@hyv/utils";
79

8-
const dir = `out/auto-tweet/${Date.now()}`;
10+
const dir = path.join(process.cwd(), `examples/output/auto-tweet/${Date.now()}`);
911
const fileWriter = createFileWriter(dir);
1012
const imageWriter = createFileWriter(dir, "base64");
1113

@@ -14,6 +16,7 @@ const termAgent = new Agent(
1416
model: "gpt-4",
1517
maxTokens: 1024,
1618
temperature: 0.8,
19+
format: "json",
1720
systemInstruction: createInstruction(
1821
"mastermind, random term creator, very funny, hilarious",
1922
minify`
@@ -49,6 +52,7 @@ const tweeter = new Agent(
4952
new GPTModelAdapter({
5053
model: "gpt-4",
5154
maxTokens: 1024,
55+
format: "json",
5256
systemInstruction: createInstruction(
5357
"Comedic Writer, Twitter trend expert",
5458
minify`\

‎examples/book.ts

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import path from "node:path";
2+
13
import { Agent, sequence } from "@hyv/core";
24
import type { FilesMessage } from "@hyv/openai";
35
import { createInstruction, DallEModelAdapter, GPTModelAdapter } from "@hyv/openai";
@@ -9,13 +11,14 @@ const genre = "Science Fiction";
911
const illustrationStyle = "flat";
1012
const context = "In a world where things are different";
1113

12-
const dir = `out/stories/${slugify(title)}`;
14+
const dir = path.join(process.cwd(), `examples/output/book/${slugify(title)}`);
1315
const fileWriter = createFileWriter(dir);
1416
const imageWriter = createFileWriter(dir, "base64");
1517

1618
const author = new Agent(
1719
new GPTModelAdapter({
1820
model: "gpt-4",
21+
format: "json",
1922
}),
2023
{
2124
sideEffects: [fileWriter],

0 commit comments

Comments
 (0)