liminal 0.4.1 → 0.5.1

package/Action.ts

@@ -0,0 +1,29 @@
+import type { Scope } from "./Scope.ts"
+import type { Spec } from "./Spec.ts"
+import type { PromiseOr } from "./util/PromiseOr.ts"
+
+export interface Action<K extends string = string, S extends Spec = Spec> {
+  "": S
+  type: K
+  [ActionKey]: true
+  trace: string
+  reducer(this: this, scope: Scope): PromiseOr<Scope>
+}
+
+export type ActionReducer<K extends string, S extends Spec> = (this: Action<K, S>, scope: Scope) => PromiseOr<Scope>
+
+export function Action<K extends string, S extends Spec>(type: K, reducer: ActionReducer<K, S>): Action<K, S> {
+  return ({
+    type,
+    [ActionKey]: true,
+    trace: new Error().stack!,
+    reducer,
+  } satisfies Omit<Action<K, S>, "">) as never
+}
+
+export type ActionKey = typeof ActionKey
+export const ActionKey = Symbol("Liminal/Action")
+
+export function isAction(value: unknown): value is Action {
+  return typeof value === "object" && value !== null && ActionKey in value
+}

package/Actor.ts

@@ -0,0 +1,20 @@
+import type { Action } from "./Action.ts"
+import type { DeferredOr } from "./util/DeferredOr.ts"
+import type { IteratorLike } from "./util/IteratorLike.ts"
+import type { JSONKey } from "./util/JSONKey.ts"
+
+export type Actor<Y extends Action = Action, R = any> = IteratorLike<Y, R>
+
+export type ActorLike<Y extends Action = Action, R = any> = DeferredOr<Actor<Y, R>>
+export type ActorLikeY<A extends ActorLike> = A extends ActorLike<infer Y> ? Y : never
+export type ActorLikeT<A extends ActorLike> = A extends ActorLike<Action, infer T> ? T : never
+
+export type ActorLikes = ActorLikeArray | ActorLikeRecord
+export type ActorLikeArray = Array<ActorLike>
+export type ActorLikeRecord = Record<JSONKey, ActorLike>
+
+export type ActorLikesT<A extends ActorLikes> =
+  & {
+    -readonly [K in keyof A]: A[K] extends ActorLike<Action, infer T> ? T : never
+  }
+  & {}

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# liminal
+
+## 0.5.1
+
+### Patch Changes
+
+- 96339de: Fixing continuous publishing. No other changes contained in this release.
+
+## 0.1.1
+
+### Patch Changes
+
+- 171acfe: Initial publish of Liminal and the Vercel AI adapter library. Still heavily WIP.
+  More publishes to come!

package/Exec.ts

@@ -0,0 +1,63 @@
+import type { Action } from "./Action.ts"
+import type { Actor } from "./Actor.ts"
+import type { EventHandler } from "./events/EventHandler.ts"
+import type { EventResolved, ExtractEventResolved } from "./events/EventResolved.ts"
+import type { LanguageModel } from "./Model.ts"
+import { RootScope, type Scope } from "./Scope.ts"
+import type { FromEntries } from "./util/FromEntries.ts"
+import type { JSONKey } from "./util/JSONKey.ts"
+
+export interface Exec<Y extends Action = Action, T = any> {
+  (
+    handler?: EventHandler<
+      Extract<ExtractEventResolved<Y[""]> & {}, EventResolved>
+    >,
+    options?: ExecOptions,
+  ): Promise<T>
+}
+
+export interface ExecConfig {
+  default: LanguageModel
+  args?: Record<JSONKey, any>
+}
+
+export interface ExecOptions {
+  signal?: AbortSignal
+}
+
+export type ExtractExecConfig<Y extends Action> =
+  & {
+    default: LanguageModel
+  }
+  & (
+    [Y[""]["Entry"]] extends [never] ? {
+        args?: undefined
+      }
+      : {
+        args: FromEntries<Y[""]["Entry"]>
+      }
+  )
+
+export function Exec<Y extends Action, T>(
+  createActor: () => Actor<Y, T>,
+  config: ExtractExecConfig<Y>,
+): Exec<Y, T> {
+  // TODO: consider `Result` type.
+  return async (handler, options) => {
+    let scope: Scope = RootScope(config.default, config.args, handler as never, options?.signal)
+    scope = await scope.reduce(createActor())
+    const { signal: { aborted, reason } } = scope.controller
+    if (aborted) {
+      scope.event({
+        type: "aborted",
+        reason,
+      })
+      throw reason
+    }
+    scope.event({
+      type: "returned",
+      value: scope.value,
+    })
+    return scope.value
+  }
+}

package/L.ts

@@ -0,0 +1,27 @@
+export * from "./_.ts"
+export * from "./actions/abort.ts"
+export * from "./actions/actions_derived/clear.ts"
+export * from "./actions/actions_derived/declareModel.ts"
+export * from "./actions/actions_derived/declareModel.ts"
+export * from "./actions/actions_derived/getMessages.ts"
+export * from "./actions/actions_derived/messages.ts"
+export * from "./actions/appendMessage.ts"
+export * from "./actions/await.ts"
+export * from "./actions/branch.ts"
+export * from "./actions/catch.ts"
+export * from "./actions/declareArg.ts"
+export * from "./actions/disableTool.ts"
+export * from "./actions/embed.ts"
+export * from "./actions/emit.ts"
+export * from "./actions/enableTool.ts"
+export * from "./actions/getScope.ts"
+export * from "./actions/getSignal.ts"
+export * from "./actions/getTools.ts"
+export * from "./actions/infer.ts"
+export * from "./actions/pushModel.ts"
+export * from "./actions/removeModel.ts"
+export * from "./actions/setMessages.ts"
+export * from "./actions/throw.ts"
+export * from "./types/factories.ts"
+
+export * from "./actions/actions_derived/metatype.ts"

package/LiminalAssertionError.ts

@@ -0,0 +1,3 @@
+export class LiminalAssertionError extends Error {
+  override readonly name = "LiminalAssertionError"
+}

package/LiminalConfig.ts

@@ -0,0 +1,7 @@
+import type { ExecConfig } from "./Exec.ts"
+
+export interface LiminalConfig extends ExecConfig {
+  actors?: string
+  silent?: boolean
+  write?: boolean | string
+}

package/Message.ts

@@ -0,0 +1,94 @@
+export type Message = Messages[keyof Messages]
+export type Messages = {
+  system: SystemMessage
+  user: UserMessage
+  assistant: AssistantMessage
+  tool: ToolMessage
+}
+
+export interface SystemMessage extends MessageBase<"system"> {}
+export interface UserMessage extends MessageBase<"user"> {}
+export interface AssistantMessage extends MessageBase<"assistant"> {}
+export interface ToolMessage extends MessageBase<"tool"> {}
+
+interface MessageBase<R extends MessageRole> {
+  readonly role: R
+  readonly content: MessageContents[R]
+}
+
+export type MessageRole = "system" | "user" | "assistant" | "tool"
+
+export type MessageContents = {
+  system: string
+  user: UserContent
+  assistant: AssistantContent
+  tool: ToolContent
+}
+
+export type AssistantContent =
+  | string
+  | ReadonlyArray<TextPart | FilePart | ReasoningPart | RedactedReasoningPart | ToolCallPart>
+
+export type UserContent = string | Array<TextPart | ImagePart | FilePart>
+
+export type ToolContent = Array<ToolContentPart>
+export interface ToolContentPart {
+  readonly type: "tool-result"
+  readonly toolCallId: string
+  readonly toolName: string
+  readonly result: unknown
+  readonly isError?: boolean
+}
+
+export interface TextPart {
+  readonly type: "text"
+  readonly text: string
+}
+
+// TODO: URL?
+export type DataContent = string | Uint8Array | ArrayBuffer | Buffer
+
+export interface FilePart {
+  type: "file"
+  /**
+   * File data. Can either be:
+   *
+   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
+   * - URL: a URL that points to the image
+   */
+  readonly data: DataContent | URL
+  /** Optional filename of the file.  */
+  readonly filename?: string
+  /** Mime type of the file.  */
+  readonly mimeType: string
+}
+
+export interface ReasoningPart {
+  readonly type: "reasoning"
+  /** The reasoning text. */
+  readonly text: string
+  /** An optional signature for verifying that the reasoning originated from the model. */
+  readonly signature?: string
+}
+
+export interface RedactedReasoningPart {
+  readonly type: "redacted-reasoning"
+  /** Redacted reasoning data. */
+  readonly data: string
+}
+
+export interface ToolCallPart {
+  readonly type: "tool-call"
+  /** ID of the tool call. This ID is used to match the tool call with the tool result.  */
+  readonly toolCallId: string
+  /** Name of the tool that is being called.  */
+  readonly toolName: string
+  /** Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema. */
+  readonly args: unknown
+}
+
+export interface ImagePart {
+  readonly type: "image"
+  readonly image: DataContent | URL
+  readonly mimeType?: string
+}

package/Model.ts

@@ -0,0 +1,20 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import type { Action } from "./Action.ts"
+import type { Actor } from "./Actor.ts"
+import type { JSONObject } from "./util/JSONObject.ts"
+
+export type Model = LanguageModel | EmbeddingModel
+
+export interface LanguageModel extends ModelBase<"language"> {
+  infer: (type: StandardSchemaV1<JSONObject, any> | undefined) => Actor<Action, any>
+}
+
+export interface EmbeddingModel extends ModelBase<"embedding"> {
+  embed: (value: string) => Promise<Array<number>>
+}
+
+interface ModelBase<K extends ModelType> {
+  type: K
+}
+
+export type ModelType = "language" | "embedding"

package/PathLike.ts

@@ -0,0 +1,19 @@
+import type { _ } from "./_.ts"
+import type { JSONKey } from "./util/JSONKey.ts"
+
+export type Path = Array<JSONKey>
+export declare namespace Path {
+  export type FromPathLike<P extends PathLike> = Extract<
+    {
+      [K in keyof P]: P[K] extends _ ? JSONKey : P[K]
+    },
+    Path
+  >
+}
+
+export type PathLike = Array<JSONKey | _>
+export declare namespace PathLike {
+  export type FromPath<P extends Path> = {
+    [K in keyof P]: P[K] | _
+  }
+}

package/Scope.ts

@@ -0,0 +1,133 @@
+import type { Action } from "./Action.ts"
+import type { Actor } from "./Actor.ts"
+import type { EventHandler } from "./events/EventHandler.ts"
+import type { LEvent } from "./events/LEvent.ts"
+import type { Message } from "./Message.ts"
+import type { EmbeddingModel, LanguageModel } from "./Model.ts"
+import type { Tool } from "./Tool.ts"
+import type { JSONKey } from "./util/JSONKey.ts"
+
+export type Scope = RootScope | ChildScope
+
+export interface RootScope extends ScopeBase<RootScopeType> {}
+export interface ChildScope extends ScopeBase<ChildScopeType> {
+  readonly parent: Scope
+}
+
+export type RootScopeType = "root"
+export type ChildScopeType = "catch" | "tool" | "branch" | "branch_arm" | "set_messages"
+export type ScopeType = RootScopeType | ChildScopeType
+
+export interface ScopeBase<Type extends ScopeType> {
+  readonly type: Type
+  readonly path: Array<JSONKey>
+  readonly args?: Record<JSONKey, any>
+  readonly controller: AbortController
+  readonly messages: Set<Message>
+  readonly tools: Set<Tool>
+  readonly nextArg?: any
+  readonly value: any
+  readonly thrown?: any
+  readonly languageModels: Set<LanguageModel>
+  readonly embeddingModels: Set<EmbeddingModel>
+  readonly handler?: EventHandler
+  readonly childForkCounts: Record<JSONKey, number>
+  readonly index: number
+
+  reduce(actor: Actor): Promise<Scope>
+  fork(source: ChildScopeType, subpath: Array<JSONKey>): Scope
+  event(event: LEvent): void
+}
+
+export function RootScope(
+  defaultLanguageModel: LanguageModel,
+  args?: Record<JSONKey, any>,
+  handler: EventHandler = () => {},
+  signal?: AbortSignal,
+): RootScope {
+  const controller = new AbortController()
+  signal?.addEventListener("abort", () => {
+    controller.abort()
+  })
+  return {
+    type: "root",
+    args,
+    controller,
+    messages: new Set(),
+    tools: new Set(),
+    value: undefined,
+    path: [],
+    languageModels: new Set([defaultLanguageModel]),
+    embeddingModels: new Set(),
+    childForkCounts: {},
+    index: 0,
+    reduce,
+    fork,
+    handler,
+    event,
+  }
+}
+
+async function reduce(this: Scope, actor: Actor): Promise<Scope> {
+  const { signal } = this.controller
+  let scope = { ...this }
+  if (signal.aborted) return scope
+  let value: unknown
+  try {
+    let current = await actor.next()
+    while (!current.done) {
+      const { value } = current
+      if (signal.aborted) return scope
+      scope = await (value as Action).reducer(scope)
+      if (signal.aborted) return scope
+      current = await actor.next(scope.nextArg)
+    }
+    value = current.value
+  } catch (thrown: unknown) {
+    scope.controller.abort(thrown)
+  }
+  return {
+    ...scope,
+    value,
+    nextArg: undefined,
+  }
+}
+
+function fork(this: Scope, type: ChildScopeType, subpath: Array<JSONKey>): ChildScope {
+  const subpathStr = subpath.join(" ")
+  let index = this.childForkCounts[subpathStr]
+  if (typeof index === "number") {
+    this.childForkCounts[subpathStr]! += 1
+  } else {
+    index = 0
+    this.childForkCounts[subpathStr] = 1
+  }
+  const f: ChildScope = {
+    type,
+    controller: this.controller,
+    args: this.args,
+    messages: new Set(this.messages),
+    tools: new Set(),
+    languageModels: new Set(this.languageModels),
+    embeddingModels: new Set(this.embeddingModels),
+    childForkCounts: {},
+    handler: this.handler,
+    path: [...this.path, ...subpath],
+    parent: this,
+    value: undefined,
+    index,
+    reduce,
+    fork,
+    event,
+  }
+  f.event({ type: "forked" })
+  return f
+}
+
+function event(this: ChildScope, event: LEvent): void {
+  this.handler?.({
+    scope: this.path,
+    index: this.index,
+    ...event,
+  })
+}

package/Spec.ts

@@ -0,0 +1,29 @@
+import type { LEvent } from "./events/LEvent.ts"
+import type { Expand } from "./util/Expand.ts"
+import type { JSONEntry } from "./util/JSONEntry.ts"
+import type { JSONKey } from "./util/JSONKey.ts"
+
+export interface Spec<
+  Key extends JSONKey = JSONKey,
+  Event extends LEvent = LEvent,
+  Spec_ extends Spec = any,
+  Entry_ extends JSONEntry = JSONEntry,
+  Throw = any,
+  Value = any,
+> {
+  Event: Event
+  Child: [Key, Spec_]
+  Entry: Entry_
+  Throw: Throw
+  Value: Value
+}
+
+export declare namespace Spec {
+  export type Make<P extends Partial<Spec>> = Expand<{
+    Event: [unknown] extends [P["Event"]] ? never : P["Event"]
+    Child: [unknown] extends [P["Child"]] ? never : P["Child"]
+    Throw: [unknown] extends [P["Throw"]] ? never : P["Throw"]
+    Entry: [unknown] extends [P["Entry"]] ? never : P["Entry"]
+    Value: [unknown] extends [P["Value"]] ? never : P["Value"]
+  }>
+}

package/Tool.ts

@@ -0,0 +1,58 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import type { Action } from "./Action.ts"
+import type { Actor } from "./Actor.ts"
+import type { Scope } from "./Scope.ts"
+import { assert } from "./util/assert.ts"
+import { isJSONValue } from "./util/isJSONValue.ts"
+import type { JSONKey } from "./util/JSONKey.ts"
+import type { JSONObject } from "./util/JSONObject.ts"
+import type { JSONValue } from "./util/JSONValue.ts"
+import type { PromiseOr } from "./util/PromiseOr.ts"
+
+export interface ToolConfig<K extends JSONKey = JSONKey> {
+  toolKey: K
+  description: string
+  params: StandardSchemaV1<JSONObject, any>
+  implementation: ToolImplementation
+}
+
+export interface Tool<K extends JSONKey = JSONKey> extends ToolConfig<K> {
+  executor: (scope: Scope) => ToolExecutor
+}
+
+export function Tool<K extends JSONKey>(config: ToolConfig<K>): Tool<K> {
+  return {
+    ...config,
+    executor,
+  }
+}
+
+export type ToolImplementation = (params: any) => Actor<Action, ToolResult> | PromiseOr<ToolResult>
+
+export type ToolExecutor = (args: any) => Promise<JSONValue>
+
+export type ToolResult = JSONValue | void
+
+function executor(this: Tool, scope: Scope): ToolExecutor {
+  return async (args) => {
+    scope.event({
+      type: "tool_called",
+      args,
+      tool: this.toolKey,
+    })
+    const parsed = await this.params["~standard"].validate(args)
+    assert(!parsed.issues)
+    const { value: transformed } = parsed
+    const initial = await this.implementation(transformed)
+    if (isJSONValue(initial)) {
+      return { value: initial }
+    }
+    const fork = scope.fork("tool", [this.toolKey])
+    const { value } = await fork.reduce(initial as Actor)
+    fork.event({
+      type: "returned",
+      value,
+    })
+    return { value }
+  }
+}

package/_.ts

@@ -0,0 +1,11 @@
+export interface _ {
+  type: "_"
+}
+
+export const _: _ = {
+  type: "_",
+}
+
+export function is_(value: unknown): value is _ {
+  return typeof value === "object" && value !== null && "type" in value && value.type === "_"
+}

package/actions/abort.ts

@@ -0,0 +1,23 @@
+import { Action } from "../Action.ts"
+import type { Aborted } from "../events/Aborted.ts"
+import type { Spec } from "../Spec.ts"
+import type { EnsureNarrow } from "../util/EnsureNarrow.ts"
+
+export interface abort<V> extends Action<"abort", Spec.Make<{ Event: Aborted<V> }>> {}
+
+export function* abort<V>(reason: V, ...[_error]: EnsureNarrow<V>): Generator<
+  abort<V>,
+  never
+> {
+  return (yield (Action("abort", (scope) => {
+    scope.event({
+      type: "aborted",
+      reason,
+    })
+    scope.controller.abort(reason)
+    return {
+      ...scope,
+      nextArg: undefined,
+    }
+  }))) as never
+}

package/actions/actions_common/updateModels.ts

@@ -0,0 +1,23 @@
+import type { EmbeddingModel, LanguageModel, Model } from "../../Model.ts"
+import type { Scope } from "../../Scope.ts"
+import { unreachable } from "../../util/unreachable.ts"
+
+export function applyToModels<M extends Model>(
+  scope: Scope,
+  model: M,
+  f: (initial: Set<M>) => Set<M>,
+): Pick<Scope, "languageModels" | "embeddingModels"> {
+  const initial: Set<M> = (model.type === "language" ? scope.languageModels : scope.embeddingModels) as never
+  const models = f(new Set(initial))
+  return model.type === "language"
+    ? {
+      languageModels: models as Set<LanguageModel>,
+      embeddingModels: scope.embeddingModels,
+    }
+    : model.type === "embedding"
+    ? {
+      languageModels: scope.languageModels,
+      embeddingModels: models as Set<EmbeddingModel>,
+    }
+    : unreachable()
+}

package/actions/actions_derived/__snapshots__/declareModel.test.ts.snap

@@ -0,0 +1,89 @@
+// Bun Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Model generates the expected event sequence 1`] = `
+"[
+  {
+    "scope": [],
+    "index": 0,
+    "type": "model_pushed",
+    "modelKey": "secondary",
+    "modelType": "language"
+  },
+  {
+    "scope": [
+      "fork-key"
+    ],
+    "index": 0,
+    "type": "forked"
+  },
+  {
+    "scope": [
+      "fork-key"
+    ],
+    "index": 0,
+    "type": "model_pushed",
+    "modelKey": "child_a",
+    "modelType": "language"
+  },
+  {
+    "scope": [
+      "fork-key"
+    ],
+    "index": 0,
+    "type": "model_pushed",
+    "modelKey": "child_b",
+    "modelType": "embedding"
+  },
+  {
+    "scope": [
+      "fork-key"
+    ],
+    "index": 0,
+    "type": "model_removed",
+    "modelKey": "child_a",
+    "modelType": "language"
+  },
+  {
+    "scope": [
+      "fork-key"
+    ],
+    "index": 0,
+    "type": "model_removed",
+    "modelKey": "child_b",
+    "modelType": "embedding"
+  },
+  {
+    "scope": [
+      "fork-key"
+    ],
+    "index": 0,
+    "type": "returned"
+  },
+  {
+    "scope": [],
+    "index": 0,
+    "type": "model_pushed",
+    "modelKey": "tertiary",
+    "modelType": "embedding"
+  },
+  {
+    "scope": [],
+    "index": 0,
+    "type": "model_removed",
+    "modelKey": "secondary",
+    "modelType": "language"
+  },
+  {
+    "scope": [],
+    "index": 0,
+    "type": "model_removed",
+    "modelKey": "tertiary",
+    "modelType": "embedding"
+  },
+  {
+    "scope": [],
+    "index": 0,
+    "type": "returned"
+  }
+]"
+`;

package/actions/actions_derived/clear.ts

@@ -0,0 +1,6 @@
+import { setMessages } from "../../actions/setMessages.ts"
+import type { MessagesSet } from "../../events/MessagesSet.ts"
+
+export function clear() {
+  return setMessages(() => [])
+}