liminal 0.4.1 → 0.5.2

package/actions/actions_derived/declareModel.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test"
+import type { LEvent } from "../../events/LEvent.ts"
+import { exec } from "../../Exec.ts"
+import * as L from "../../L.ts"
+import { TestEmbeddingModel } from "../../testing/TestEmbeddingModel.ts"
+import { TestLanguageModel } from "../../testing/TestLanguageModel.ts"
+
+describe("Model", () => {
+  it("generates the expected event sequence", async () => {
+    const events: Array<LEvent> = []
+    await exec(function*() {
+      const a = yield* L.declareModel("secondary", "language")
+      yield* L.branch("fork-key", function*() {
+        const b = yield* L.declareModel("child_a", "language")
+        const c = yield* L.declareModel("child_b", "embedding")
+        yield* b
+        yield* c
+      })
+      const c = yield* L.declareModel("tertiary", "embedding")
+      yield* a
+      yield* c
+    }, {
+      default: TestLanguageModel(),
+      args: {
+        secondary: TestLanguageModel(),
+        child_a: TestLanguageModel(),
+        child_b: TestEmbeddingModel(),
+        tertiary: TestEmbeddingModel(),
+      },
+      handler(event) {
+        events.push(event)
+      },
+    })
+    expect(JSON.stringify(events, null, 2)).toMatchSnapshot()
+  })
+})

package/actions/actions_derived/declareModel.ts

@@ -0,0 +1,9 @@
+import type { Models, ModelType } from "../../Model.ts"
+import type { JSONKey } from "../../util/JSONKey.ts"
+import { declareArg } from "../declareArg.ts"
+import { pushModel } from "../pushModel.ts"
+
+export function* declareModel<K extends JSONKey, M extends ModelType>(key: K, _modelType: M) {
+  const model = yield* declareArg(key)<Models[M]>()
+  return yield* pushModel(key, model)
+}

package/actions/actions_derived/declareModel.type-test.ts

@@ -0,0 +1,70 @@
+// import type { RunEmbed, RunInfer } from "../../adapters.ts"
+// import type { ChildEvent } from "../../events/ChildEvent.ts"
+// import type { EmbeddingModelSetEvent } from "../../events/EmbeddingModelSetEvent.ts"
+// import type { LanguageModelSetEvent } from "../../events/LanguageModelSetEvent.ts"
+// import * as L from "../../L.ts"
+// import { ActorAssertions } from "../../testing/ActorAssertions.ts"
+// import { declareEmbeddingModel } from "./declareEmbeddingModel.ts"
+// import { declareLanguageModel } from "./declareLanguageModel.ts"
+
+// const languageModel = declareLanguageModel("A")
+// ActorAssertions(languageModel).assertSpec<{
+//   Entry: ["A", RunInfer]
+//   Event: LanguageModelSetEvent<"A">
+//   Throw: never
+//   Child: never
+// }>()
+
+// const embeddingModel = declareEmbeddingModel("B")
+// ActorAssertions(embeddingModel).assertSpec<{
+//   Entry: ["B", RunEmbed]
+//   Event: EmbeddingModelSetEvent<"B">
+//   Throw: never
+//   Child: never
+// }>()
+
+// function* both() {
+//   yield* languageModel
+//   yield* embeddingModel
+// }
+
+// ActorAssertions(both).assertSpec<{
+//   Entry: ["A", RunInfer] | ["B", RunEmbed]
+//   Event: LanguageModelSetEvent<"A"> | EmbeddingModelSetEvent<"B">
+//   Throw: never
+//   Child: never
+// }>()
+
+// function* parent() {
+//   yield* L.branch("fork-key", {
+//     *key() {
+//       yield* both()
+//     },
+//   })
+//   yield* declareLanguageModel("C")
+//   yield* declareEmbeddingModel("D")
+// }
+
+// ActorAssertions(parent).assertSpec<{
+//   Entry:
+//     | ["A", RunInfer]
+//     | ["B", RunEmbed]
+//     | ["C", RunInfer]
+//     | ["D", RunEmbed]
+//   Event:
+//     | ChildEvent<
+//       "branch",
+//       "fork-key",
+//       ChildEvent<
+//         "branch_arm",
+//         "key",
+//         LanguageModelSetEvent<"A"> | EmbeddingModelSetEvent<"B">,
+//         void
+//       >,
+//       { key: void }
+//     >
+//     | LanguageModelSetEvent<"C">
+//     | EmbeddingModelSetEvent<"D">
+//   Throw: never
+//   Child: never
+// }>()

package/actions/actions_derived/messages.test.ts

@@ -0,0 +1,88 @@
+// import { describe, expect, test } from "bun:test"
+// import * as L from "../L.ts"
+// import { takeFirstAction } from "../testing/takeFirstAction.ts"
+
+// describe("message templates", () => {
+//   test("system messages with indentation", async () => {
+//     // Create a system message with indented multiline content
+//     const messageGenerator = L.system`
+//       Hello, I am an AI assistant.
+//       I can help with the following:
+//         - Code generation
+//         - Answering questions
+//         - General assistance
+//     `
+
+//     const action = await takeFirstAction(messageGenerator)
+
+//     expect(action?.message.content).toBe(
+//       "Hello, I am an AI assistant.\nI can help with the following:\n  - Code generation\n  - Answering questions\n  - General assistance",
+//     )
+//   })
+
+//   test("user messages with substitution", async () => {
+//     const name = "John"
+//     const messageGenerator = L.user`Hello, my name is ${name}.`
+
+//     const action = await takeFirstAction(messageGenerator)
+
+//     expect(action?.message.content).toBe("Hello, my name is John.")
+//   })
+
+//   test("user messages with multiline substitution and indentation", async () => {
+//     const codeBlock = "function example() {\n  console.log('Hello');\n}"
+
+//     const messageGenerator = L.user`
+//       Here's my code:
+//         ${codeBlock}
+//       Can you help me understand it?
+//     `
+
+//     const action = await takeFirstAction(messageGenerator)
+
+//     // The code block should get indentation applied to lines after the first
+//     expect(action?.message.content).toBe(
+//       "Here's my code:\n  function example() {\n    console.log('Hello');\n  }\nCan you help me understand it?",
+//     )
+//   })
+
+//   test("assistant messages with multiline substitution", async () => {
+//     const explanation =
+//       "1. First, we declare a function\n2. Then we log a message\n3. The function doesn't return anything"
+
+//     const messageGenerator = L.assistant`
+//       Let me explain:
+//         ${explanation}
+//       Does that help?
+//     `
+
+//     const action = await takeFirstAction(messageGenerator)
+
+//     // The explanation lines should get indentation
+//     expect(action?.message.content).toBe(
+//       "Let me explain:\n  1. First, we declare a function\n  2. Then we log a message\n  3. The function doesn't return anything\nDoes that help?",
+//     )
+//   })
+
+//   test("preserves code indentation", async () => {
+//     const code = `if (condition) {
+//   // This is indented once
+//   if (nestedCondition) {
+//     // This is indented twice
+//   }
+// }`
+
+//     const messageGenerator = L.user`
+//       My code:
+//         ${code}
+//     `
+
+//     const action = await takeFirstAction(messageGenerator)
+
+//     // The code's internal indentation structure should be preserved
+//     // while getting additional indentation from the template
+//     expect(action?.message.content).toBe(
+//       "My code:\n  if (condition) {\n    // This is indented once\n    if (nestedCondition) {\n      // This is indented twice\n    }\n  }",
+//     )
+//   })
+// })

package/actions/actions_derived/messages.ts

@@ -0,0 +1,18 @@
+import type { AssistantContent, UserContent } from "../../Message.ts"
+import { normalizeTaggableArgs, type TaggableArgs } from "../../util/Taggable.ts"
+import { appendMessage } from "../appendMessage.ts"
+
+export function user(...args: TaggableArgs<[content: UserContent]>) {
+  const [content] = normalizeTaggableArgs(...args)
+  return appendMessage("user", content)
+}
+
+export function system(...args: TaggableArgs<[content: string]>) {
+  const [content] = normalizeTaggableArgs(...args)
+  return appendMessage("system", content)
+}
+
+export function assistant(...args: TaggableArgs<[content: AssistantContent]>) {
+  const [content] = normalizeTaggableArgs(...args)
+  return appendMessage("assistant", content)
+}

package/actions/actions_derived/metatype.ts

@@ -0,0 +1,9 @@
+import { fromMetatypeRootDescriptor } from "../../types/Metatype/fromMetatypeDescriptor.ts"
+import { MetatypeRootDescriptor } from "../../types/Metatype/MetatypeDescriptor.ts"
+import type { Falsy } from "../../util/Falsy.ts"
+import type { TaggableArgs } from "../../util/Taggable.ts"
+
+export function* metatype(...args: TaggableArgs<[...description: Array<string | Falsy>]>) {
+  const descriptor = yield* MetatypeRootDescriptor(args.map((e) => typeof e === "string").join("\n"))
+  return fromMetatypeRootDescriptor(descriptor)
+}

package/actions/actions_derived/readers_derived.ts

@@ -0,0 +1,15 @@
+import { scope } from "../scope.ts"
+
+export const tools = {
+  *[Symbol.iterator]() {
+    const scope_ = yield* scope
+    return scope_.tools
+  },
+}
+
+export const signal = {
+  *[Symbol.iterator]() {
+    const scope_ = yield* scope
+    return scope_.controller.signal
+  },
+}

package/actions/appendMessage.ts

@@ -0,0 +1,54 @@
+import { Action } from "../Action.ts"
+import type { MessageAppended } from "../events/MessageAppended.ts"
+import type { MessageRemoved } from "../events/MessageRemoved.ts"
+import type { Message, MessageContents, MessageRole, Messages } from "../Message.ts"
+import type { Spec } from "../Spec.ts"
+import { peekLast } from "../util/peekLast.ts"
+
+export interface appendMessage<M extends Message = Message>
+  extends Action<"append_message", Spec.Make<{ Event: MessageAppended<M> }>>
+{}
+
+export interface removeMessage extends Action<"remove_message", Spec.Make<{ Event: MessageRemoved }>> {}
+
+export function* appendMessage<R extends MessageRole>(
+  role: R,
+  content: MessageContents[R],
+): Generator<appendMessage<Messages[R]>, Generator<removeMessage, void>> {
+  return yield Action("append_message", (scope) => {
+    const message = {
+      role,
+      content,
+    } as Messages[R] // <-- why isn't this inferred?
+    const section = peekLast(scope.sections)
+    if (section) {
+      section.messages.add(message)
+    }
+    scope.event({
+      type: "message_appended",
+      message,
+    })
+    return {
+      ...scope,
+      nextArg: (function*(): Generator<removeMessage> {
+        return yield Action("remove_message", (scope) => {
+          scope.event({
+            type: "message_removed",
+            message,
+          })
+          const messages = new Set(scope.messages)
+          messages.delete(message)
+          if (section) {
+            section.messages.delete(message)
+          }
+          return {
+            ...scope,
+            nextArg: message,
+            messages,
+          }
+        })
+      })(),
+      messages: new Set([...scope.messages, message]),
+    }
+  })
+}

package/actions/await.ts

@@ -0,0 +1,13 @@
+import { Action } from "../Action.ts"
+
+export interface await_<_T> extends Action<"await", never> {}
+
+function* await_<T>(value: T): Generator<await_<Awaited<T>>, Awaited<T>> {
+  return yield Action("await", async (scope) => ({
+    ...scope,
+    nextArg: await value,
+  }))
+}
+Object.defineProperty(await_, "name", { value: "await" })
+
+export { await_ as await }

package/actions/branch.ts

@@ -0,0 +1,106 @@
+import { Action } from "../Action.ts"
+import type { Agent, AgentLike, AgentLikeT, AgentLikeY } from "../Agent.ts"
+import type { Spec } from "../Spec.ts"
+import type { JSONKey } from "../util/JSONKey.ts"
+import { unwrapDeferred } from "../util/unwrapDeferred.ts"
+
+export function branch<
+  K extends JSONKey,
+  Y extends Action,
+  T,
+>(
+  key: K,
+  agentLike: AgentLike<Y, T>,
+): Generator<
+  Action<
+    "branch",
+    Spec.Make<{
+      Child: [Y[""]] extends [never] ? never : [K, Y[""]]
+      Entry: Y[""]["Entry"]
+      Value: T
+    }>
+  >,
+  T
+>
+export function branch<K extends JSONKey, const A extends Array<AgentLike>>(name: K, agentLikes: A): Generator<
+  Action<
+    "branch",
+    Spec.Make<{
+      Child: [
+        K,
+        {
+          [L in keyof A]: Spec.Make<{
+            Child: [L, AgentLikeY<A[L]>[""]]
+            Entry: AgentLikeY<A[L]>[""]["Entry"]
+            Value: AgentLikeT<A[L]>
+          }>
+        }[keyof A],
+      ]
+      Entry: AgentLikeY<A[number]>[""]["Entry"]
+    }>
+  >,
+  AgentLikesT<A>
+>
+export function branch<K extends JSONKey, A extends Record<JSONKey, AgentLike>>(name: K, agentLikes: A): Generator<
+  Action<
+    "branch",
+    Spec.Make<{
+      Child: [
+        K,
+        {
+          [L in Exclude<keyof A, symbol>]: Spec.Make<{
+            Child: [L, AgentLikeY<A[L]>[""]]
+            Entry: AgentLikeY<A[L]>[""]["Entry"]
+            Value: AgentLikeT<A[L]>
+          }>
+        }[Exclude<keyof A, symbol>],
+      ]
+      Entry: AgentLikeY<A[keyof A]>[""]["Entry"]
+    }>
+  >,
+  AgentLikesT<A>
+>
+export function* branch(key: JSONKey, a1: AgentLike | AgentLikes): Generator<Action<"branch">, any> {
+  return yield Action("branch", async (scope) => {
+    if (typeof a1 === "function") {
+      const branchScope = scope.fork("branch", [key])
+      const agent = unwrapDeferred(a1 as AgentLike)
+      const { value } = await branchScope.reduce(agent)
+      branchScope.event({
+        type: "returned",
+        value,
+      })
+      return {
+        ...scope,
+        nextArg: value,
+      }
+    }
+    const armKeys = Array.isArray(a1)
+      ? Array.from({ length: a1.length }, (_0, i) => i)
+      : Reflect.ownKeys(a1) as Array<string>
+    const values = await Promise.all(armKeys.map(async (armKey) => {
+      const branchArmScope = scope.fork("branch_arm", [key, armKey])
+      const agent = unwrapDeferred(a1[armKey as never]) as Agent
+      const { value } = await branchArmScope.reduce(agent)
+      branchArmScope.event({
+        type: "returned",
+        value,
+      })
+      return value
+    }))
+    const value = Array.isArray(a1)
+      ? values
+      : Object.fromEntries(armKeys.map((key, i) => [key, values[i]]))
+    return {
+      ...scope,
+      nextArg: value,
+    }
+  })
+}
+
+export type AgentLikes = Array<AgentLike> | Record<JSONKey, AgentLike>
+export type AgentLikesT<A extends AgentLikes> =
+  & {
+    -readonly [K in keyof A]: A[K] extends AgentLike<Action, infer T> ? T : never
+  }
+  & {}

package/actions/catch.ts

@@ -0,0 +1,42 @@
+import { Action } from "../Action.ts"
+import type { AgentLike } from "../Agent.ts"
+import type { Spec } from "../Spec.ts"
+import type { JSONKey } from "../util/JSONKey.ts"
+import type { Result } from "../util/Result.ts"
+import { unwrapDeferred } from "../util/unwrapDeferred.ts"
+
+export { catch_ as catch }
+function* catch_<K extends JSONKey, Y extends Action, T>(
+  key: K,
+  agentLike: AgentLike<Y, T>,
+): Generator<
+  Action<
+    "catch",
+    Spec.Make<{
+      Child: [K, Y[""]]
+      Value: T
+    }>
+  >,
+  Result<T, Y[""]["Throw"]>
+> {
+  return yield Action("catch", async (scope) => {
+    const catchScope = scope.fork("catch", [key])
+    try {
+      const { value } = await catchScope.reduce(unwrapDeferred(agentLike))
+      catchScope.event({
+        type: "returned",
+        value,
+      })
+      return {
+        ...scope,
+        nextArg: { value },
+      }
+    } catch (thrown: unknown) {
+      return {
+        ...scope,
+        nextArg: { thrown },
+      }
+    }
+  })
+}
+Object.defineProperty(catch_, "name", { value: "catch" })

package/actions/declareArg.ts

@@ -0,0 +1,14 @@
+import { Action } from "../Action.ts"
+import type { Spec } from "../Spec.ts"
+import type { JSONKey } from "../util/JSONKey.ts"
+
+export interface declareArg<K extends JSONKey, T> extends Action<"declare_arg", Spec.Make<{ Entry: [K, T] }>> {}
+
+export function declareArg<K extends JSONKey>(key: K): <T>() => Generator<declareArg<K, T>, T> {
+  return function*() {
+    return yield Action("declare_arg", (scope) => ({
+      ...scope,
+      nextArg: scope.args?.[key],
+    }))
+  }
+}

package/actions/disableTool.ts

@@ -0,0 +1,26 @@
+import { Action } from "../Action.ts"
+import type { ToolDisabled } from "../events/ToolDisabled.ts"
+import type { Spec } from "../Spec.ts"
+import type { Tool } from "../Tool.ts"
+import type { JSONKey } from "../util/JSONKey.ts"
+
+export interface disableTool<K extends JSONKey> extends Action<"disable_tool", Spec.Make<{ Event: ToolDisabled<K> }>> {}
+
+export function* disableTool<K extends JSONKey>(tool: Tool<K>): Generator<
+  disableTool<K>,
+  void
+> {
+  yield Action("disable_tool", (scope) => {
+    scope.event({
+      type: "tool_disabled",
+      tool: tool.toolKey,
+    })
+    const tools = new Set(scope.tools)
+    tools.delete(tool)
+    return {
+      ...scope,
+      tools,
+      nextArg: undefined,
+    }
+  })
+}

package/actions/embed.ts

@@ -0,0 +1,29 @@
+import { Action } from "../Action.ts"
+import type { Embedded } from "../events/Embedded.ts"
+import type { EmbeddingRequested } from "../events/EmbeddingRequested.ts"
+import type { Spec } from "../Spec.ts"
+import { assert } from "../util/assert.ts"
+import { peekLast } from "../util/peekLast.ts"
+
+export interface embed extends Action<"embed", Spec.Make<{ Event: EmbeddingRequested | Embedded }>> {}
+
+export function* embed(value: string): Generator<embed, Array<number>> {
+  return yield Action("embed", async (scope) => {
+    const model = peekLast(scope.embeddingModels)
+    assert(model)
+    scope.event({
+      type: "embedding_requested",
+      value,
+    })
+    const embedding = await model.embed(value)
+    scope.event({
+      type: "embedded",
+      value,
+      embedding,
+    })
+    return {
+      ...scope,
+      nextArg: scope.value,
+    }
+  })
+}

package/actions/emit.ts

@@ -0,0 +1,21 @@
+import { Action } from "../Action.ts"
+import type { Emitted } from "../events/Emitted.ts"
+import type { Spec } from "../Spec.ts"
+import type { JSONValue } from "../util/JSONValue.ts"
+
+export interface emit<V extends JSONValue> extends Action<"emit", Spec.Make<{ Event: Emitted<V> }>> {}
+
+export function* emit<V extends JSONValue = never>(
+  value: V = undefined as never,
+): Generator<emit<V>, void> {
+  return yield Action("emit", (scope) => {
+    scope.event({
+      type: "emitted",
+      value,
+    })
+    return {
+      ...scope,
+      nextArg: undefined,
+    }
+  }) as never
+}

package/actions/enableTool.ts

@@ -0,0 +1,75 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import { Action } from "../Action.ts"
+import type { Agent } from "../Agent.ts"
+import type { ToolCalled } from "../events/ToolCalled.ts"
+import type { ToolEnabled } from "../events/ToolEnabled.ts"
+import type { Spec } from "../Spec.ts"
+import { Tool, type ToolImplementation, type ToolResult } from "../Tool.ts"
+import type { JSONKey } from "../util/JSONKey.ts"
+import type { JSONObject } from "../util/JSONObject.ts"
+import { JSONSchemaMemo } from "../util/JSONSchemaMemo.ts"
+import type { PromiseOr } from "../util/PromiseOr.ts"
+import { disableTool } from "./disableTool.ts"
+
+export function enableTool<K extends JSONKey, A>(
+  key: K,
+  description: string,
+  params: StandardSchemaV1<JSONObject, A>,
+  implementation: (params: A) => PromiseOr<ToolResult>,
+): Generator<
+  Action<
+    "enable_tool",
+    Spec.Make<{
+      Event: ToolEnabled<K> | ToolCalled<K, A>
+    }>
+  >,
+  Generator<disableTool<K>, void>
+>
+export function enableTool<
+  K extends JSONKey,
+  A,
+  Y extends Action,
+  T extends ToolResult,
+>(
+  key: K,
+  description: string,
+  params: StandardSchemaV1<JSONObject, A>,
+  implementation: (params: A) => Agent<Y, T>,
+): Generator<
+  Action<
+    "enable_tool",
+    Spec.Make<{
+      Event: ToolEnabled<K> | ToolCalled<K, A>
+      Child: [K, Y[""]]
+      Entry: Y[""]["Entry"]
+      Value: T
+    }>
+  >,
+  Generator<disableTool<K>, void>
+>
+export function* enableTool(
+  key: JSONKey,
+  description: string,
+  params: StandardSchemaV1<JSONObject, any>,
+  implementation: ToolImplementation,
+): Generator<Action<"enable_tool">, Generator<Action<"disable_tool">, void>> {
+  return yield Action("enable_tool", async (scope) => {
+    scope.event({
+      type: "tool_enabled",
+      description,
+      schema: await JSONSchemaMemo(params),
+      tool: key,
+    })
+    const tool = Tool({
+      toolKey: key,
+      description,
+      params,
+      implementation,
+    })
+    return {
+      ...scope,
+      tools: new Set([...scope.tools, tool]),
+      nextArg: disableTool(tool),
+    }
+  })
+}