feat: improved api (#9)

.gitignore

@@ -51,6 +51,7 @@ node_modules/
 
 # outfolder for examples
 out
+examples/output
 
 # distribution files
 dist

.ncurc.json

@@ -0,0 +1,4 @@
+{
+  "upgrade": true,
+  "reject": ["@types/node"]
+}

docs/01_GETTING_STARTED.md

@@ -34,10 +34,10 @@ Provide a question to the agent and obtain the answer:
 
 ```typescript
 try {
-  const answer = await agent.assign({ question: "What is time?" });
-  console.log(answer.message);
+    const answer = await agent.assign({ question: "What is time?" });
+    console.log(answer.message);
 } catch (error) {
-  console.error("Error:", error);
+    console.error("Error:", error);
 }
 ```
 
@@ -47,13 +47,13 @@ Execute the script and check the console output:
 
 ```json
 {
-  "thought": "Time is a concept that humans use to measure the duration between events.",
-  "reason": "It is a way to organize and understand the sequence of events that occur in our lives.",
-  "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.",
-  "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."
+    "thought": "Time is a concept that humans use to measure the duration between events.",
+    "reason": "It is a way to organize and understand the sequence of events that occur in our lives.",
+    "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.",
+    "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."
 }
 ```
 
 Next:
 
-- [System Instructions](02_SYSTEM_INSTRUCTIONS.md)
+-   [System Instructions](02_SYSTEM_INSTRUCTIONS.md)

docs/02_SYSTEM_INSTRUCTIONS.md

@@ -4,8 +4,8 @@ With a system instruction in place, you can guide the language model to generate
 structured responses. You can learn more about system instructions in this
 [article by OpenAI](https://platform.openai.com/docs/guides/chat/instructing-chat-models).
 
-Hyv is designed to work seamlessly with JSON, and it includes a powerful helper that delivers
-reliable output.
+Hyv is designed to work seamlessly with Markdown and JSON, and it includes powerful helpers that
+deliver reliable output.
 
 ## Creating a System Instruction
 
@@ -17,25 +17,26 @@ import { Agent } from "@hyv/core";
 import { createInstruction, GPTModelAdapter } from "@hyv/openai";
 
 const mathModel = new GPTModelAdapter({
-  systemInstruction: createInstruction(
-    "Mathematician",
-    "think about the problem, reason your thoughts, solve the problems step by step",
-    {
-      thought: "detailed string",
-      reason: "detailed string",
-      steps: ["step"],
-      solution: "concise answer",
-    }
-  ),
+    format: "json", // Set the format to "json"
+    systemInstruction: createInstruction(
+        "Mathematician",
+        "think about the problem, reason your thoughts, solve the problems step by step",
+        {
+            thought: "detailed string",
+            reason: "detailed string",
+            steps: ["calculation step"],
+            solution: "concise answer",
+        }
+    ),
 });
 
 const mathAgent = new Agent(mathModel);
 
 try {
-  const answer = await mathAgent.assign({ problem: "(10 * 4 + 2) / (10 * 2 + 11 * 2) = ?" });
-  console.log(answer.message);
+    const answer = await mathAgent.assign({ problem: "(10 * 4 + 2) / (10 * 2 + 11 * 2) = x" });
+    console.log(answer.message);
 } catch (error) {
-  console.error("Error:", error);
+    console.error("Error:", error);
 }
 ```
 
@@ -53,11 +54,11 @@ Run the script and review the console output:
     '20 + 22 = 42',
     '42 / 42 = 1'
   ],
-  solution: '1'
+  solution: 'x = 1'
 }
 
 ```
 
 Next:
 
-- [Creating a sequence](03_CREATING_A_SEQUENCE.md)
+-   [Creating a sequence](03_CREATING_A_SEQUENCE.md)

docs/03_CREATING_A_SEQUENCE.md

@@ -19,9 +19,9 @@ import { GPTModelAdapter } from "@hyv/openai";
 const agent = new Agent(new GPTModelAdapter(), { verbosity: 1 });
 
 try {
-  await sequence({ question: "What is life?" }, [agent]);
+    await sequence({ question: "What is life?" }, [agent]);
 } catch (error) {
-  console.error("Error:", error);
+    console.error("Error:", error);
 }
 ```
 
@@ -56,40 +56,41 @@ import { Agent, sequence } from "@hyv/core";
 import { createInstruction, GPTModelAdapter } from "@hyv/openai";
 
 const agents = Array.from<undefined, Agent>(
-  { length: 3 },
-  () =>
-    new Agent(
-      new GPTModelAdapter({
-        model: "gpt-4",
-        systemInstruction: createInstruction(
-          "AI",
-          "think about the task, reason your thoughts, create a new task based on your decision!",
-          {
-            mainGoal: "{{mainGoal}}",
-            thoughts: "detailed string",
-            reason: "detailed string",
-            task: "full and detailed task without references",
-          }
-        ),
-      }),
-      {
-        async before({ task, mainGoal }) {
-          return {
-            task,
-            mainGoal,
-          };
-        },
-        verbosity: 1,
-      }
-    )
+    { length: 3 },
+    () =>
+        new Agent(
+            new GPTModelAdapter({
+                model: "gpt-4",
+                systemInstruction: createInstruction(
+                    "AI",
+                    "think about the task, reason your thoughts, create a new task based on your decision!",
+                    {
+                        mainGoal: "{{mainGoal}}",
+                        thoughts: "detailed string",
+                        reason: "detailed string",
+                        task: "full and detailed task without references",
+                    }
+                ),
+            }),
+            {
+                async before({ task, mainGoal }) {
+                    // Only use the mainGoal and task
+                    return {
+                        task,
+                        mainGoal,
+                    };
+                },
+                verbosity: 1,
+            }
+        )
 );
 
 try {
-  await sequence(
-    { task: "Make the world a better place!", mainGoal: "Make the world a better place!" },
-    agents
-  );
+    await sequence(
+        { task: "Make the world a better place!", mainGoal: "Make the world a better place!" },
+        agents
+    );
 } catch (error) {
-  console.error("Error:", error);
+    console.error("Error:", error);
 }
 ```

docs/api/AGENT.md

@@ -1,12 +1,12 @@
 # Agent API
 
-| Option                | Type         | Description                                                                                                                                                                                      |
-| --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `model`               | ModelAdapter | The model instance used by the agent.                                                                                                                                                            |
-| `options`             | AgentOptions | Configuration options for the agent.                                                                                                                                                             |
-| `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.                                              |
-| `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.                                               |
-| `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.                                          |
-| `options.sideEffects` | Array        | An optional array of side effect functions to be executed during the task processing.                                                                                                            |
-| `options.store`       | StoreAdapter | The store that should be used to save and retrieve messages.                                                                                                                                     |
-| `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. |
+| Option                | Type           | Description                                                                                                                                                                                      |
+| --------------------- |----------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `model`               | `ModelAdapter` | The model instance used by the agent.                                                                                                                                                            |
+| `options`             | `AgentOptions` | Configuration options for the agent.                                                                                                                                                             |
+| `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.                                              |
+| `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.                                               |
+| `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.                                          |
+| `options.sideEffects` | `SideEffect[]` | An optional array of side effect functions to be executed during the task processing.                                                                                                            |
+| `options.store`       | `StoreAdapter` | The store that should be used to save and retrieve messages.                                                                                                                                     |
+| `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

@@ -1,23 +1,10 @@
 # GPTModelAdapter API
 
-| Name              | Type                      | Description                                                                                                        |
-| ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| model             | GPTModel                  | The model name. Compatible GPT models: "gpt-3.5-turbo" or "gpt-4".                                                 |
-| temperature       | ReasonableTemperature     | The temperature value controlling the randomness of the model's output. Range: 0 to 0.9 with increments of 0.1.    |
-| maxTokens         | number                    | The maximum number of tokens in the output response.                                                               |
-| 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. |
-| systemInstruction | string                    | An initial system instruction to guide the model's behavior.                                                       |
-
-For GPT3 specific options:
-
-| Name        | Type            | Description                              |
-| ----------- | --------------- | ---------------------------------------- |
-| model       | "gpt-3.5-turbo" | GPT-3 model name.                        |
-| historySize | GPT3HistorySize | GPT-3 valid history size values: 1 or 2. |
-
-For GPT4 specific options:
-
-| Name        | Type            | Description                                     |
-| ----------- | --------------- | ----------------------------------------------- |
-| model       | "gpt-4"         | GPT-4 model name.                               |
-| historySize | GPT4HistorySize | GPT-4 valid history size values: 1, 2, 3, or 4. |
+| Name              | Type              | Description                                                            |
+|-------------------|-------------------|------------------------------------------------------------------------|
+| `model`             | `string`            | The model name                                                         |
+| `temperature`       | `number`            | The temperature value controlling the randomness of the model's output |
+| `maxTokens`         | `number`            | The maximum number of tokens in the output response.                   |
+| `historySize`       | `number`            | The number of chat messages to maintain in history.                    |
+| `format`            | `"json"\| "string"` | The number of chat messages to maintain in history. |
+| `systemInstruction` | `string`            | An initial system instruction to guide the model's behavior.           |

examples/auto-book.ts

@@ -37,7 +37,7 @@ export function createFileWriterWithReadingTime(
 	};
 }
 
-const dir = `out/auto-stories/${Date.now()}`;
+const dir = path.join(process.cwd(), `examples/output/auto-book/${Date.now()}`);
 const fileWriter = createFileWriterWithReadingTime(dir);
 const imageWriter = createFileWriter(dir, "base64");
 
@@ -132,6 +132,7 @@ const author = new Agent(
 		model: "gpt-4",
 		maxTokens: 4096,
 		temperature: 0.7,
+		format: "json",
 		systemInstruction: createInstruction(
 			"Author named Morgan Casey Patel",
 			minify`\

examples/auto-tweet.ts

@@ -1,11 +1,13 @@
+import path from "node:path";
+
 import type { ModelMessage } from "@hyv/core";
 import { Agent, sequence } from "@hyv/core";
 import { createInstruction, GPTModelAdapter } from "@hyv/openai";
 import type { ImageMessage } from "@hyv/stable-diffusion";
 import { Automatic1111ModelAdapter } from "@hyv/stable-diffusion";
 import { minify, createFileWriter } from "@hyv/utils";
 
-const dir = `out/auto-tweet/${Date.now()}`;
+const dir = path.join(process.cwd(), `examples/output/auto-tweet/${Date.now()}`);
 const fileWriter = createFileWriter(dir);
 const imageWriter = createFileWriter(dir, "base64");
 
@@ -14,6 +16,7 @@ const termAgent = new Agent(
 		model: "gpt-4",
 		maxTokens: 1024,
 		temperature: 0.8,
+		format: "json",
 		systemInstruction: createInstruction(
 			"mastermind, random term creator, very funny, hilarious",
 			minify`
@@ -49,6 +52,7 @@ const tweeter = new Agent(
 	new GPTModelAdapter({
 		model: "gpt-4",
 		maxTokens: 1024,
+		format: "json",
 		systemInstruction: createInstruction(
 			"Comedic Writer, Twitter trend expert",
 			minify`\

examples/book.ts

@@ -1,3 +1,5 @@
+import path from "node:path";
+
 import { Agent, sequence } from "@hyv/core";
 import type { FilesMessage } from "@hyv/openai";
 import { createInstruction, DallEModelAdapter, GPTModelAdapter } from "@hyv/openai";
@@ -9,13 +11,14 @@ const genre = "Science Fiction";
 const illustrationStyle = "flat";
 const context = "In a world where things are different";
 
-const dir = `out/stories/${slugify(title)}`;
+const dir = path.join(process.cwd(), `examples/output/book/${slugify(title)}`);
 const fileWriter = createFileWriter(dir);
 const imageWriter = createFileWriter(dir, "base64");
 
 const author = new Agent(
 	new GPTModelAdapter({
 		model: "gpt-4",
+		format: "json",
 	}),
 	{
 		sideEffects: [fileWriter],

examples/chaining.ts

@@ -1,5 +1,5 @@
 import { Agent, sequence } from "@hyv/core";
-import { createInstruction, GPTModelAdapter } from "@hyv/openai";
+import { createInstructionTemplate, GPTModelAdapter } from "@hyv/openai";
 import { minify } from "@hyv/utils";
 
 const agents = Array.from<undefined, Agent>(
@@ -8,7 +8,7 @@ const agents = Array.from<undefined, Agent>(
 		new Agent(
 			new GPTModelAdapter({
 				model: "gpt-4",
-				systemInstruction: createInstruction(
+				systemInstruction: createInstructionTemplate(
 					"AI",
 					minify`
 					You have deep thoughts,

examples/code-optimizer.ts

@@ -1,13 +1,13 @@
 import { inspect } from "node:util";
 
 import { Agent } from "@hyv/core";
-import { createInstructionTemplate, GPTModelAdapter2 } from "@hyv/openai";
+import { createInstructionTemplate, GPTModelAdapter } from "@hyv/openai";
 import { extractCode, minify } from "@hyv/utils";
 
 inspect.defaultOptions.depth = null;
 
 const developer = new Agent(
-	new GPTModelAdapter2({
+	new GPTModelAdapter({
 		maxTokens: 2048,
 		model: "gpt-4",
 		systemInstruction: createInstructionTemplate(
@@ -26,7 +26,7 @@ const developer = new Agent(
 );
 
 const optimizer = new Agent(
-	new GPTModelAdapter2({
+	new GPTModelAdapter({
 		maxTokens: 2048,
 		model: "gpt-4",
 		systemInstruction: createInstructionTemplate(

examples/dall-e.ts

@@ -1,8 +1,13 @@
+import path from "node:path";
+
 import { Agent, sequence } from "@hyv/core";
 import { DallEModelAdapter } from "@hyv/openai";
 import { createFileWriter } from "@hyv/utils";
 
-const imageWriter = createFileWriter(`out/dall-e/${Date.now()}`, "base64");
+const imageWriter = createFileWriter(
+	path.join(process.cwd(), `examples/output/dall-e/${Date.now()}`),
+	"base64"
+);
 
 const agent = new Agent(new DallEModelAdapter(), {
 	sideEffects: [imageWriter],