liminal 0.5.14 → 0.5.16

package/{Model.ts → Adapter.ts}

@@ -3,14 +3,14 @@ import type { SchemaObject } from "./Schema.ts"
 import type { Tool } from "./Tool.ts"
 import { attachCustomInspect } from "./util/attachCustomInspect.ts"
 
-export class Model {
+export class Adapter {
   constructor(
-    readonly vendor: string,
+    readonly name: string,
     readonly seal: (envelope: Envelope) => SealedEnvelope,
   ) {}
 
   static {
-    attachCustomInspect(this, ({ vendor }) => ({ vendor }))
+    attachCustomInspect(this, ({ name }) => ({ name }))
   }
 }
 
@@ -22,6 +22,6 @@ export interface Envelope {
 }
 
 export interface SealedEnvelope {
-  resolve(): Promise<string>
-  stream(): ReadableStream<string>
+  resolve: () => Promise<string>
+  stream: () => ReadableStream<string>
 }

package/AdapterRegistry.ts

@@ -0,0 +1,78 @@
+import type { Adapter } from "./Adapter.ts"
+import { LiminalAssertionError } from "./LiminalAssertionError.ts"
+
+/**
+ * An intrusive doubly-linked list for storing `Model`s.
+ * Provides efficient insertion, removal, and lookups.
+ */
+export class AdapterRegistry {
+  declare head?: ModelRegistryNode | undefined
+  declare tail?: ModelRegistryNode | undefined
+
+  /** Returns the most recently registered model */
+  peek() {
+    return this.tail?.adapter
+  }
+
+  /** Ensure */
+  ensure(): Adapter {
+    LiminalAssertionError.assert(
+      this.tail,
+      "No conversation adapter registered. Use `L.focus` to focus a conversation adapter.",
+    )
+    return this.tail.adapter
+  }
+
+  /**
+   * Registers a new model and returns the created node
+   * @param value The model to register
+   */
+  register(value: Adapter): ModelRegistryNode {
+    const node: ModelRegistryNode = {
+      prev: this.tail,
+      adapter: value,
+    }
+    if (this.tail) {
+      this.tail.next = node
+    } else {
+      this.head = node
+    }
+    this.tail = node
+    return node
+  }
+
+  /** Remove a model from the registry. */
+  remove(node: ModelRegistryNode) {
+    if (node.prev) {
+      node.prev.next = node.next
+    }
+    if (node.next) {
+      node.next.prev = node.prev
+    }
+    if (node === this.head) {
+      this.head = node.next
+    }
+    if (node === this.tail) {
+      this.tail = node.prev
+    }
+    node.prev = undefined
+    delete node.next
+  }
+
+  /** Creates a deep copy of this registry. */
+  clone() {
+    const instance = new AdapterRegistry()
+    for (let node = this.head; node; node = node.next) {
+      if (node.adapter) {
+        instance.register(node.adapter)
+      }
+    }
+    return instance
+  }
+}
+
+export interface ModelRegistryNode {
+  prev: ModelRegistryNode | undefined
+  adapter: Adapter
+  next?: ModelRegistryNode | undefined
+}

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # liminal
 
+## 0.5.16
+
+### Patch Changes
+
+- 6e70190: Renaming Model to Adapter and L.model to L.focus
+
+## 0.5.15
+
+### Patch Changes
+
+- 9c276c3: Fix message list cloning, add streaming to ollama adapter.
+
 ## 0.5.14
 
 ### Patch Changes

package/Config.ts

@@ -1,12 +1,12 @@
+import { AdapterRegistry } from "./AdapterRegistry.ts"
 import type { Message } from "./Message.ts"
-import { ModelRegistry } from "./ModelRegistry.ts"
 import type { Rune } from "./Rune.ts"
 import type { Strand } from "./Strand.ts"
 import type { Tool } from "./Tool.ts"
 
 export interface Config<Y extends Rune<any> = Rune<any>, T = any> {
   handler?: ((this: Strand<Y, T>, event: Rune.E<Y>) => void) | undefined
-  models?: ModelRegistry | undefined
+  models?: AdapterRegistry | undefined
   messages?: Array<Message>
   tools?: Set<Tool> | undefined
   signal?: AbortSignal | undefined

package/Context.ts

@@ -1,28 +1,45 @@
+import { AdapterRegistry } from "./AdapterRegistry.ts"
 import type { Handler } from "./Handler.ts"
 import type { Message } from "./Message.ts"
-import { ModelRegistry } from "./ModelRegistry.ts"
 import type { Tool } from "./Tool.ts"
 
+/**
+ * Context represents the execution environment for a Strand.
+ *
+ * It holds all the stateful components needed during strand execution:
+ * - Message history.
+ * - Event handler for processing events.
+ * - Model registry for tracking available language models.
+ * - Available tools for model-driven function calling.
+ */
 export interface Context {
+  /** Event handler for processing events during strand execution. */
   readonly handler: Handler | undefined
-  readonly models: ModelRegistry
+  /** Registry of available models for inference. */
+  readonly adapters: AdapterRegistry
+  /** Accumulated message history. */
   readonly messages: Array<Message>
+  /** Set of tools available to the models. */
   readonly tools: Set<Tool>
-
+  /** Creates a copy of the current `Context` for child strands. */
   clone(): Context
 }
 
+/**
+ * Factory function to create a new Context.
+ * @param context Optional base context from which to initialize.
+ * @returns A newly created Context.
+ */
 export function Context(context?: Omit<Context, "clone">): Context {
   return {
     handler: context?.handler,
-    models: context?.models.clone() ?? new ModelRegistry(),
-    messages: [],
+    adapters: context?.adapters?.clone() ?? new AdapterRegistry(),
+    messages: [...(context?.messages ?? [])],
     tools: new Set(context?.tools),
-
     clone(): Context {
       return {
         handler: this.handler,
-        models: this.models.clone(),
+        adapters: this.adapters.clone(),
         messages: [...this.messages],
         tools: new Set(this.tools),
         clone: this.clone,

package/Definition.ts

@@ -1,22 +1,38 @@
 import type { Rune } from "./Rune.ts"
 
 export type RuneIterator<Y extends Rune<any> = Rune<any>, T = any> = Iterator<Y, T> | AsyncIterator<Y, T>
+
 export type RuneIterable<Y extends Rune<any> = Rune<any>, T = any> = Iterable<Y, T> | AsyncIterable<Y, T>
+
 export type Definition<Y extends Rune<any> = Rune<any>, T = any> = RuneIterable<Y, T> | (() => RuneIterable<Y, T>)
 
 export namespace Definition {
+  /** Extracts the Rune type from a Definition. */
   export type Y<X extends Definition> = X extends RuneIterable<infer Y> ? Y
     : X extends () => RuneIterable<infer Y> ? Y
     : X extends RuneIterator<infer Y> ? Y
     : never
 
+  /** Extracts the result type from a Definition. */
   export type T<X extends Definition> = X extends RuneIterable<Rune<any>, infer T> ? T
     : X extends () => RuneIterable<Rune<any>, infer T> ? T
     : X extends RuneIterator<Rune<any>, infer T> ? T
     : never
 
+  /** Extracts the event type from a Definition. */
   export type E<X extends Definition> = Rune.E<Y<X>>
 
+  /**
+   * Converts a Definition into a RuneIterator.
+   *
+   * This function handles all the different forms a Definition can take:
+   * - Synchronous iterables
+   * - Asynchronous iterables
+   * - Factory functions returning iterables
+   *
+   * @param definition The definition to unwrap.
+   * @returns A RuneIterator ready for consumption.
+   */
   export function unwrap<Y extends Rune<any>, T>(definition: Definition<Y, T>): RuneIterator<Y, T> {
     if (Symbol.iterator in definition) {
       return definition[Symbol.iterator]()

package/L/L.ts

@@ -1,12 +1,11 @@
 export * from "./all.ts"
 export * from "./assistant.ts"
 export * from "./catch.ts"
-export * from "./context.ts"
 export * from "./continuation.ts"
 export * from "./emit.ts"
+export * from "./focus.ts"
 export * from "./infer.ts"
 export * from "./message.ts"
-export * from "./model.ts"
 export * from "./reflect.ts"
 export * from "./run.ts"
 export * from "./schema/anyOf.ts"

package/L/all.ts

@@ -6,6 +6,10 @@ import { Strand } from "../Strand.ts"
 import { continuation } from "./continuation.ts"
 import { reflect } from "./reflect.ts"
 
+/**
+ * Runs multiple definitions in parallel and collects their results.
+ * Can be used with an array or object of definitions.
+ */
 export function all<A extends Array<Definition>>(
   definitions: A,
   context?: Context,

package/L/assistant.ts

@@ -4,6 +4,10 @@ import { Schema } from "../Schema.ts"
 import { infer } from "./infer.ts"
 import { message } from "./message.ts"
 
+/**
+ * Produces an assistant message when yielded. Can be called with a schema
+ * for structured output. Otherwise produces a string.
+ */
 export interface assistant extends Iterable<Rune<LEvent>, string> {
   <T>(schema: Schema<T>): Generator<Rune<LEvent>, T>
 }

package/L/catch.ts

@@ -7,6 +7,10 @@ import { reflect } from "./reflect.ts"
 
 export { catch_ as catch }
 
+/**
+ * Error handling utility that catches exceptions from running a definition.
+ * Returns a result object indicating whether the operation succeeded or failed.
+ */
 function* catch_<Y extends Rune<any>, T>(
   definition: Definition<Y, T>,
 ): Generator<Rune<LEvent> | Rune<Y>, CatchResult<T>> {

package/L/continuation.ts

@@ -1,11 +1,12 @@
 import type { LEvent } from "../LEvent.ts"
 import { Rune, RuneKey } from "../Rune.ts"
 
+/** Yields a continuation rune that executes a function and passes its result to the next iteration. */
 export function* continuation<R>(debug: string, f: () => R): Generator<Rune<LEvent>, Awaited<R>> {
   return yield {
     [RuneKey]: true,
-    value: {
-      kind: "continuation",
+    instruction: {
+      kind: "continue",
       debug,
       f,
     },

package/L/emit.ts

@@ -1,11 +1,15 @@
 import { Rune, RuneKey } from "../Rune.ts"
 import type { EnsureNarrow } from "../util/EnsureNarrow.ts"
 
+/**
+ * Emits an event to be supplied to handlers.
+ * Used for broadcasting state changes and triggering side effects.
+ */
 export function* emit<E>(event: EnsureNarrow<E>): Generator<Rune<E>, void> {
   return yield {
     [RuneKey]: true,
-    value: {
-      kind: "event",
+    instruction: {
+      kind: "emit",
       event,
     },
   }

package/L/focus.ts

@@ -0,0 +1,17 @@
+import type { Adapter } from "../Adapter.ts"
+import type { LEvent } from "../LEvent.ts"
+import { AdapterFocused } from "../LEvent.ts"
+import type { Rune } from "../Rune.ts"
+import { emit } from "./emit.ts"
+import { reflect } from "./reflect.ts"
+
+/**
+ * Registers a model in the current context and emits a model registration event.
+ * Returns the registered model instance.
+ */
+export function* focus(adapter: Adapter): Generator<Rune<LEvent>, Adapter> {
+  const { context: { adapters } } = yield* reflect
+  adapters.register(adapter)
+  yield* emit(new AdapterFocused(adapter))
+  return adapter
+}

package/L/infer.ts

@@ -1,27 +1,31 @@
 import { InferenceRequested, Inferred, type LEvent } from "../LEvent.ts"
-import { LiminalAssertionError } from "../LiminalAssertionError.ts"
 import type { Rune } from "../Rune.ts"
 import { Schema } from "../Schema.ts"
 import { continuation } from "./continuation.ts"
 import { emit } from "./emit.ts"
 import { reflect } from "./reflect.ts"
 
+/**
+ * Requests an inference from the current model, optionally with a schema.
+ * Emits inference-related events and returns the model's response as a string.
+ */
 export function* infer(schema?: Schema): Generator<Rune<LEvent>, string> {
-  const { context: { models, messages }, signal } = yield* reflect
-  const model = models.peek()
-  LiminalAssertionError.assert(model)
+  const { context: { adapters: models, messages }, signal } = yield* reflect
+  const model = models.ensure()
   const requestId = crypto.randomUUID()
   yield* emit(new InferenceRequested(requestId, schema))
-  let inference = yield* continuation("infer", () =>
-    model.seal({
-      messages,
-      ...schema && {
-        schema: schema.type === "object"
-          ? schema
-          : Schema.wrap(schema),
-      },
-      signal,
-    }).resolve())
+  let inference = yield* continuation(
+    "infer",
+    model
+      .seal({
+        messages,
+        ...schema && {
+          schema: schema.type === "object" ? schema : Schema.wrap(schema),
+        },
+        signal,
+      })
+      .resolve,
+  )
   if (schema?.type && schema.type !== "object") {
     inference = JSON.stringify(JSON.parse(inference).value)
   }

package/L/message.ts

@@ -4,6 +4,10 @@ import type { Rune } from "../Rune.ts"
 import { emit } from "./emit.ts"
 import { reflect } from "./reflect.ts"
 
+/**
+ * Adds a new message to the current context's message list.
+ * Emits a message append event to observers.
+ */
 export function* message(role: MessageRole, content: Array<Content>): Generator<Rune<LEvent>, void> {
   const { context: { messages } } = yield* reflect
   const message: Message = { role, parts: content }

package/L/reflect.ts

@@ -2,11 +2,12 @@ import type { LEvent } from "../LEvent.ts"
 import { Rune, RuneKey } from "../Rune.ts"
 import type { Strand } from "../Strand.ts"
 
+/** Returns the current strand instance, providing access to context and parent information. */
 export const reflect: Iterable<Rune<LEvent>, Strand> = {
   *[Symbol.iterator]() {
     return yield {
       [RuneKey]: true,
-      value: { kind: "reflect" },
+      instruction: { kind: "reflect" },
     }
   },
 }

package/L/run.ts

@@ -1,15 +1,16 @@
+import { AdapterRegistry } from "../AdapterRegistry.ts"
 import { Context } from "../Context.ts"
 import type { Definition } from "../Definition.ts"
 import type { Handler } from "../Handler.ts"
 import type { Message } from "../Message.ts"
-import { ModelRegistry } from "../ModelRegistry.ts"
 import type { Rune } from "../Rune.ts"
 import { Strand } from "../Strand.ts"
 import type { Tool } from "../Tool.ts"
 
+/** Configuration options for running a definition. */
 export interface RunConfig<Y extends Rune<any>> {
   handler?: Handler<Y> | undefined
-  models?: ModelRegistry | undefined
+  models?: AdapterRegistry | undefined
   messages?: Array<Message> | undefined
   tools?: Set<Tool> | undefined
   signal?: AbortSignal | undefined
@@ -18,7 +19,7 @@ export interface RunConfig<Y extends Rune<any>> {
 export function run<Y extends Rune<any>, T>(definition: Definition<Y, T>, config?: RunConfig<Y>): Strand<Y, T> {
   const context = Context({
     handler: config?.handler,
-    models: config?.models ?? new ModelRegistry(),
+    adapters: config?.models ?? new AdapterRegistry(),
     messages: config?.messages ?? [],
     tools: config?.tools ?? new Set(),
   })

package/L/strand.ts

@@ -3,14 +3,18 @@ import type { Definition } from "../Definition.ts"
 import type { LEvent } from "../LEvent.ts"
 import { type Rune, RuneKey } from "../Rune.ts"
 
+/**
+ * Creates a child strand that executes a definition.
+ * Optionally specify the context. Otherwise the current context is inherited.
+ */
 export function* strand<Y extends Rune<any>, T>(
   definition: Definition<Y, T>,
   context?: Context,
 ): Generator<Rune<LEvent>, T> {
   return yield {
     [RuneKey]: true,
-    value: {
-      kind: "child",
+    instruction: {
+      kind: "create_child",
       definition,
       context,
     },

package/L/stream.ts

@@ -1,17 +1,16 @@
 import { InferenceRequested, type LEvent } from "../LEvent.ts"
-import { LiminalAssertionError } from "../LiminalAssertionError.ts"
 import type { Rune } from "../Rune.ts"
 import { continuation } from "./continuation.ts"
 import { emit } from "./emit.ts"
 import { reflect } from "./reflect.ts"
 
+/** Creates a readable stream of content from the current model. */
 export const stream: Iterable<Rune<LEvent>, ReadableStream<string>> = {
   *[Symbol.iterator]() {
-    const { context: { models, messages }, signal } = yield* reflect
-    const model = models.peek()
-    LiminalAssertionError.assert(model)
+    const { context: { adapters, messages }, signal } = yield* reflect
+    const adapter = adapters.ensure()
     const requestId = crypto.randomUUID()
     yield* emit(new InferenceRequested(requestId))
-    return yield* continuation("stream", () => model.seal({ messages, signal }).stream())
+    return yield* continuation("stream", adapter.seal({ messages, signal }).stream)
   },
 }

package/LEvent.ts

@@ -1,15 +1,15 @@
+import type { Adapter } from "./Adapter.ts"
 import { EventBase } from "./EventBase.ts"
 import type { Message } from "./Message.ts"
-import type { Model } from "./Model.ts"
 import type { Schema } from "./Schema.ts"
 import type { StrandStatus } from "./Strand.ts"
 
 export type LEvent =
-  | StrandStatusChanged
+  | AdapterFocused
   | InferenceRequested
   | Inferred
   | MessageAppended
-  | ModelRegistered
+  | StrandStatusChanged
 
 export namespace LEvent {
   export function is(value: unknown): value is LEvent {
@@ -20,8 +20,8 @@ export namespace LEvent {
 export const LEventTag: unique symbol = Symbol.for("liminal/LEvent")
 export type LEventTag = typeof LEventTag
 
-export class ModelRegistered extends EventBase(LEventTag, "model_registered") {
-  constructor(readonly model: Model) {
+export class AdapterFocused extends EventBase(LEventTag, "adapter_focused") {
+  constructor(readonly adapter: Adapter) {
     super()
   }
 }

package/Rune.ts

@@ -1,31 +1,60 @@
 import type { Context } from "./Context.ts"
 import type { Definition } from "./Definition.ts"
 
+/**
+ * `Rune` represents a computational unit within a Strand execution.
+ * It is a specialized protocol for expressing different kinds of operations
+ * that can be yielded from generator functions to control message state
+ * and concurrency within the Liminal runtime.
+ * @template E The event type this Rune can handle
+ */
 export interface Rune<E> {
   [RuneKey]: true
-  value: {
-    kind: "continuation"
+  instruction: RuneInstruction<E>
+}
+
+export type RuneInstruction<E> =
+  | RuneInstruction.Continue
+  | RuneInstruction.Emit<E>
+  | RuneInstruction.Reflect
+  | RuneInstruction.CreateChild
+export namespace RuneInstruction {
+  /** Tells the runtime to call this function and and pass the result to the next iteration. */
+  export interface Continue {
+    kind: "continue"
     debug: string
     f: () => any
-  } | {
-    kind: "event"
+  }
+
+  /** Dispatch an event to the registered handler. */
+  export interface Emit<E> {
+    kind: "emit"
     event: E
-  } | {
+  }
+
+  /** Tells the runtime to provide a reference to the current strand */
+  export interface Reflect {
     kind: "reflect"
-  } | {
-    kind: "child"
+  }
+
+  /** Creates a nested execution context with its own definition. */
+  export interface CreateChild {
+    kind: "create_child"
     definition: Definition
     context?: Context | undefined
   }
 }
 
 export namespace Rune {
+  /** Extract the event type from a Rune type. */
   export type E<X extends Rune<any>> = X extends Rune<infer E> ? E : never
 
+  /** Type guard to check if a value is a Rune. */
   export function is(value: unknown): value is Rune<any> {
     return typeof value === "object" && value !== null && RuneKey in value
   }
 }
 
+/** Symbol used to identify Rune objects. */
 export const RuneKey: unique symbol = Symbol.for("liminal/RuneKey")
 export type RuneKey = typeof RuneKey