Merge pull request #42 from FormulaMonks/chore/show-usage-examples-fr…

…om-files

chore: get Kurt usage examples for `kurt` package README from example files.

examples/basic/package.json

@@ -5,7 +5,9 @@
   "private": true,
   "scripts": {
     "start": "run-s start:*",
-    "start:agnostic": "tsx --env-file=.env ./src/model-agnostic.ts",
+    "start:natural-language": "tsx --env-file=.env ./src/natural-language.ts",
+    "start:structured-data": "tsx --env-file=.env ./src/structured-data.ts",
+    "start:with-optional-tools": "tsx --env-file=.env ./src/with-optional-tools.ts",
     "start:vertex": "tsx --env-file=.env ./src/vertex.ts",
     "start:openai": "tsx --env-file=.env ./src/openai.ts",
     "type-check": "tsc --noEmit"

examples/basic/src/natural-language.ts

@@ -0,0 +1,27 @@
+import { createKurt } from "./util/createKurt"
+const kurt = createKurt(process.env.KURT_MODEL)
+
+const stream = kurt.generateNaturalLanguage({
+  prompt: "Say hello!",
+})
+
+for await (const event of stream) {
+  console.log(event)
+}
+// { chunk: "Hello" }
+// { chunk: "!" }
+// { chunk: " How" }
+// { chunk: " can" }
+// { chunk: " I" }
+// { chunk: " assist" }
+// { chunk: " you" }
+// { chunk: " today" }
+// { chunk: "?" }
+// {
+//   finished: true,
+//   text: "Hello! How can I assist you today?",
+//   data: undefined,
+// }
+
+const { text } = await stream.result
+console.log(text) // "Hello! How can I assist you today?"

examples/basic/src/structured-data.ts

@@ -0,0 +1,24 @@
+import { z } from "zod"
+import { createKurt } from "./util/createKurt"
+const kurt = createKurt(process.env.KURT_MODEL)
+
+const structuredDataStream = kurt.generateStructuredData({
+  prompt: "Say hello!",
+  schema: z.object({
+    say: z.string().describe("A single word to say"),
+  }),
+})
+
+for await (const event of structuredDataStream) {
+  console.log(event)
+}
+// { chunk: '{"' }
+// { chunk: "say" }
+// { chunk: '":"' }
+// { chunk: "hello" }
+// { chunk: '"}' }
+// { finished: true, text: '{"say":"hello"}', data: { say: "hello" } }
+
+const { data } = await structuredDataStream.result
+console.log(data)
+// { say: "hello" }

examples/basic/src/util/createKurt.ts

@@ -0,0 +1,29 @@
+import { Kurt, type KurtAdapter } from "@formula-monks/kurt"
+
+import { KurtOpenAI } from "@formula-monks/kurt-open-ai"
+import { OpenAI } from "openai"
+
+import { KurtVertexAI } from "@formula-monks/kurt-vertex-ai"
+import { VertexAI } from "@google-cloud/vertexai"
+
+const DEFAULT_MODEL = "gpt-4o"
+
+export const createKurt = (model = DEFAULT_MODEL): Kurt => {
+  const adapter = findAdapter(model)
+  if (!adapter) throw new Error(`Model ${model} is not supported.`)
+  return new Kurt(adapter)
+}
+
+const findAdapter = (model: string): KurtAdapter | undefined => {
+  if (KurtOpenAI.isSupportedModel(model))
+    return new KurtOpenAI({ openAI: new OpenAI(), model })
+
+  if (KurtVertexAI.isSupportedModel(model))
+    return new KurtVertexAI({
+      vertexAI: new VertexAI({
+        project: process.env.VERTEX_AI_PROJECT ?? "my-project",
+        location: process.env.VERTEX_AI_LOCATION ?? "us-central1",
+      }),
+      model,
+    })
+}

examples/basic/src/with-optional-tools.ts

@@ -0,0 +1,56 @@
+import { z } from "zod"
+import type { KurtMessage } from "@formula-monks/kurt"
+import { createKurt } from "./util/createKurt"
+const kurt = createKurt(process.env.KURT_MODEL)
+
+const prompt =
+  "What's 9876356 divided by 30487, rounded to the nearest integer?"
+
+const tools = {
+  subtract: z
+    .object({
+      minuend: z.number().describe("The number to subtract from"),
+      subtrahend: z.number().describe("The number to subtract by"),
+    })
+    .describe("Calculate a subtraction expression"),
+  divide: z
+    .object({
+      dividend: z.number().describe("The number to be divided"),
+      divisor: z.number().describe("The number to divide by"),
+    })
+    .describe("Calculate a division expression"),
+}
+
+// Run Kurt in a loop until it produces a natural language response,
+// or until we reach a maximum number of iterations.
+const extraMessages: KurtMessage[] = []
+const MAX_ITERATIONS = 3
+for (let i = 0; i < MAX_ITERATIONS; i++) {
+  const { text, data } = await kurt.generateWithOptionalTools({
+    prompt,
+    tools,
+    extraMessages,
+  }).result
+
+  // If there is data in the result, it means the LLM made a tool call.
+  if (data) {
+    const { name, args } = data
+    let result = {}
+    if (name === "divide") {
+      result = { quotient: args.dividend / args.divisor }
+    } else if (name === "subtract") {
+      result = { difference: args.minuend - args.subtrahend }
+    }
+    const toolCall = { name, args, result }
+    extraMessages.push({ role: "model", toolCall })
+    console.log(toolCall)
+    // {
+    //   name: "divide",
+    //   args: { dividend: 9876356, divisor: 30487 },
+    //   result: { quotient: 323.95302915996984 },
+    // }
+  } else {
+    console.log(text) // "The answer, rounded to the nearest integer, is 324."
+    break
+  }
+}

examples/basic/tsconfig.json

@@ -10,6 +10,6 @@
     "moduleResolution": "bundler",
     "target": "es2022"
   },
-  "include": ["src/*.ts"],
+  "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }