feat: rework the API

enables several defaults
better config options

README.md

@@ -8,7 +8,7 @@ Hyv is a modular software development library centered on AI collaboration that
 ## Features 🌟
 
 - 🚀 **Streamlined Task Management**: Hyv enhances your projects with efficient task distribution and coordination, simplifying resource utilization.
-- 🧩 **Flexible Modular Design**: Hyv's modular architecture allows seamless integration of various tools, models, and adapters, providing a customizable solution.
+- 🧩 **Flexible Modular Design**: Hyv's modular architecture allows seamless integration of various sideEffects, models, and adapters, providing a customizable solution.
 - 🌐 **Broad Compatibility**: Designed for various technologies, Hyv is a versatile option for developers working with diverse platforms and frameworks.
 - 📚 **Comprehensive Documentation**: Hyv includes detailed documentation and examples, aiding in understanding its features and effective implementation in projects.
 - 🌱 **Community-Driven**: Hyv is developed and maintained by a devoted community of developers, continually working to refine and extend its capabilities.
@@ -23,7 +23,7 @@ npm install "@hyv/core" "@hyv/openai" "@hyv/store"
 
 ```typescript
 import process from "node:process";
-import { Agent, createInstruction, sprint } from "@hyv/core";
+import { Agent, createInstruction, sequence } from "@hyv/core";
 import type { ModelMessage } from "@hyv/core";
 import { DallEModelAdapter, GPTModelAdapter } from "@hyv/openai";
 import type { DallEOptions, GPT3Options } from "@hyv/openai";
@@ -63,7 +63,7 @@ const author = new Agent(
     ),
   }, openai),
   store,
-  { tools: [fileWriter] }
+  { sideEffects: [fileWriter] }
 );
 
 const illustrator = new Agent(
@@ -72,12 +72,12 @@ const illustrator = new Agent(
     n: 1,
   }, openai),
   store,
-  { tools: [imageWriter] }
+  { sideEffects: [imageWriter] }
 );
 
 try {
   const messageId = await store.set(book);
-  await sprint(messageId, [author, illustrator]);
+  await sequence(messageId, [author, illustrator]);
   console.log("Done");
 } catch (error) {
   console.error("Error:", error);

examples/book.ts

@@ -1,106 +1,83 @@
+import { Agent, createFileWriter, createInstruction, minify, sequence } from "@hyv/core";
+import { DallEModelAdapter, GPTModelAdapter } from "@hyv/openai";
 import slugify from "@sindresorhus/slugify";
 
-import { Agent } from "../packages/core/src/agent.js";
-import type { ModelMessage } from "../packages/core/src/types.js";
-import type { AgentOptions } from "../packages/core/src/types.js";
-import type { ModelAdapter } from "../packages/core/src/types.js";
-import type { StoreAdapter } from "../packages/core/src/types.js";
-import { createInstruction, minify, sprint } from "../packages/core/src/utils.js";
-import { GPTModelAdapter } from "../packages/openai/src/gpt-model-adapter.js";
-import { DallEModelAdapter } from "../packages/openai/src/index.js";
-import type { GPT4Options } from "../packages/openai/src/types.js";
-import { createFileWriter, FSAdapter } from "../packages/store/src/index.js";
-
-import { openai } from "./config.js";
-
-const title = "The AIgent";
-const genre = "Science Fiction";
-const illustrationStyle = "watercolor illustration";
-const context = "AGI has become reality";
+const title = "Greg the Hero";
+const genre = "Adventure";
+const illustrationStyle = "flat";
+const context = "Greg writes the best AI libraries";
 
 const dir = `out/stories/${slugify(title)}`;
-const store = new FSAdapter(dir);
 const fileWriter = createFileWriter(dir);
 const imageWriter = createFileWriter(dir, "base64");
 
-const book: ModelMessage & {
-	title: string;
-	context: string;
-	genre: string;
-	imageCount: number;
-	chapterCount: number;
-	illustrationStyle: string;
-} = {
-	title,
-	context,
-	genre,
-	imageCount: 3,
-	chapterCount: 3,
-	illustrationStyle,
-};
+const author = new Agent(
+	new GPTModelAdapter({
+		model: "gpt-4",
+	}),
+	{
+		sideEffects: [fileWriter],
+	}
+);
 
-interface AuthorData extends ModelMessage {
-	images: [{ path: string; prompt: string }];
-	files: [{ path: string; content: string }];
+const illustrator = new Agent(new DallEModelAdapter(), { sideEffects: [imageWriter] });
+
+/**
+ * Estimates reading time for a text
+ * @param text
+ */
+function getReadingTime(text: string) {
+	return text.length / 1_000;
 }
 
-const options: AgentOptions<ModelMessage, AuthorData> = {
-	tools: [fileWriter],
-	async after<Message>(message) {
-		return {
-			...message,
-			files: message.files.map(file => ({
-				...file,
-				readingTime: file.content.length / 1000,
-			})),
-		} as Message;
-	},
-};
+/**
+ * Estimates reading time for a text
+ * @param text
+ */
+function getWordCount(text: string) {
+	return text.split(" ").length;
+}
 
-const author = new Agent(
-	new GPTModelAdapter<GPT4Options>(
-		{
-			model: "gpt-4",
-			temperature: 0.7,
-			maxTokens: 4096,
-			historySize: 1,
-			systemInstruction: createInstruction(
-				"Author",
-				minify`
-				1. Write a long bestseller story (500-600 words long)!
-				2. Write a Markdown document WITH IMAGE TAGS and short alt text!
-				3. INLINE all images (as Markdown) **as part of the story**!
+// Give the agent some tools
+author.after = async message => ({
+	...message,
+	files: message.files.map(file => ({
+		...file,
+		readingTime: getReadingTime(file.content),
+		words: getWordCount(file.content),
+	})),
+});
+
+// Adjust the agent's model
+author.model.maxTokens = 1024;
+author.model.systemInstruction = createInstruction(
+	"Author",
+	minify`
+				1. Write a long("approximateWordCount") story!
+				2. Write a VALID Markdown document WITH IMAGE TAGS and SHORT alt text!
+				3. INLINE all images (as VALID Markdown) **within the story**!
 				4. All images should be LOCAL FILES!
-				5. Add a DETAILED, CLEAR and very DESCRIPTIVE prompt with "illustrationStyle" for each image to be generated.
+				5. Add a DETAILED, CLEAR, DESCRIPTIVE prompt("illustrationStyle") for each image to be generated.
 				`,
-				{
-					images: [{ path: "string", prompt: "string" }],
-					files: [{ path: "story.md", content: "markdown" }],
-				}
-			),
-		},
-		openai
-	),
-	store,
-	options
+	{
+		images: [{ path: "path/to/file.jpg", prompt: "string" }],
+		files: [{ path: "story.md", content: "Markdown" }],
+	}
 );
 
-const illustrator = new Agent(
-	new DallEModelAdapter(
+try {
+	await sequence(
 		{
-			size: "256x256",
-			n: 1,
+			title,
+			context,
+			genre,
+			approximateWordCount: 100,
+			imageCount: 2,
+			chapterCount: 2,
+			illustrationStyle,
 		},
-		openai
-	),
-	store,
-	{ tools: [imageWriter] }
-);
-
-try {
-	const messageId = await store.set(book);
-	await sprint<ModelAdapter<ModelMessage>, StoreAdapter>(messageId, [author, illustrator]);
-	console.log("Done");
+		[author, illustrator]
+	);
 } catch (error) {
 	console.error("Error:", error);
 }

examples/simple.ts

@@ -0,0 +1,10 @@
+import { Agent, sequence } from "@hyv/core";
+import { GPTModelAdapter } from "@hyv/openai";
+
+const agent = new Agent(new GPTModelAdapter());
+
+try {
+	await sequence({ question: "What is life?" }, [agent]);
+} catch (error) {
+	console.error("Error:", error);
+}