liminal 0.5.13 → 0.5.15

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # liminal
 
+## 0.5.15
+
+### Patch Changes
+
+- 9c276c3: Fix message list cloning, add streaming to ollama adapter.
+
+## 0.5.14
+
+### Patch Changes
+
+- d12049c: Fix L.run return type. Add L.<type> for JSON-schema building.
+
 ## 0.5.13
 
 ### Patch Changes

package/Context.ts

@@ -3,22 +3,39 @@ 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
+  /** Registry of available models for inference. */
   readonly models: ModelRegistry
+  /** 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: [],
+    models: context?.models?.clone() ?? new ModelRegistry(),
+    messages: [...(context?.messages ?? [])],
     tools: new Set(context?.tools),
-
     clone(): Context {
       return {
         handler: this.handler,

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,7 +1,6 @@
 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 "./infer.ts"
@@ -9,6 +8,16 @@ export * from "./message.ts"
 export * from "./model.ts"
 export * from "./reflect.ts"
 export * from "./run.ts"
+export * from "./schema/anyOf.ts"
+export * from "./schema/array.ts"
+export * from "./schema/boolean.ts"
+export * from "./schema/const.ts"
+export * from "./schema/enum.ts"
+export * from "./schema/integer.ts"
+export * from "./schema/null.ts"
+export * from "./schema/number"
+export * from "./schema/object.ts"
+export * from "./schema/string.ts"
 export * from "./strand.ts"
 export * from "./stream.ts"
 export * from "./system.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

@@ -1,10 +1,13 @@
 import type { LEvent } from "../LEvent.ts"
 import type { Rune } from "../Rune.ts"
 import { Schema } from "../Schema.ts"
-import { continuation } from "./continuation.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>
 }
@@ -13,8 +16,7 @@ export const assistant: assistant = Object.assign(
   function* assistant<T>(schema: Schema<T>): Generator<Rune<LEvent>, T> {
     const inference = yield* infer(schema)
     yield* message("assistant", [{ part: inference }])
-    const input = JSON.parse(inference)
-    return yield* continuation("validate_assistant_message", () => Schema.validateValue(schema, input))
+    return JSON.parse(inference)
   },
   {
     *[Symbol.iterator]() {

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/infer.ts

@@ -6,22 +6,28 @@ 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 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)
-        : undefined,
-      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

@@ -1,12 +1,16 @@
 import { LEvent, MessageAppended } from "../LEvent.ts"
-import type { ContentPart, Message, MessageRole } from "../Message.ts"
+import type { Content, Message, MessageRole } from "../Message.ts"
 import type { Rune } from "../Rune.ts"
 import { emit } from "./emit.ts"
 import { reflect } from "./reflect.ts"
 
-export function* message(role: MessageRole, content: Array<ContentPart>): Generator<Rune<LEvent>, void> {
+/**
+ * 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, content }
+  const message: Message = { role, parts: content }
   yield* emit(new MessageAppended(message))
   messages.push(message)
 }

package/L/model.ts

@@ -5,6 +5,10 @@ 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* model(model: Model): Generator<Rune<LEvent>, Model> {
   const { context: { models } } = yield* reflect
   models.register(model)

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

@@ -7,6 +7,7 @@ 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
@@ -15,7 +16,7 @@ export interface RunConfig<Y extends Rune<any>> {
   signal?: AbortSignal | undefined
 }
 
-export function run<Y extends Rune<any>, T>(definition: Definition<Y, T>, config?: RunConfig<Y>): Strand {
+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(),

package/L/schema/_schema_common.ts

@@ -0,0 +1,29 @@
+import type { Schema } from "../../Schema.ts"
+import { isTemplateStringsArray } from "../../util/isTemplateStringsArray.ts"
+
+export function make<S extends Schema>(schema: Omit<S, "T">, description?: string): S & TypeBase {
+  const schema_ = {
+    ...schema,
+    ...description && { description },
+  }
+
+  const Type = Object.assign(function describe(e0?: TemplateStringsArray | string, ...rest: Array<string>) {
+    const junction = isTemplateStringsArray(e0) ? String.raw(e0, ...rest) : e0
+    return make(
+      schema_,
+      description ? `${description}${junction ? `\n\n${junction}` : ""}` : junction,
+    )
+  }, schema_)
+  Object.defineProperty(Type, "toJSON", {
+    value() {
+      return schema_
+    },
+    enumerable: false,
+  })
+  return Type as never
+}
+
+export interface TypeBase {
+  (template: TemplateStringsArray, ...substitutions: Array<string>): this
+  (...values: Array<string>): this
+}

package/L/schema/anyOf.ts

@@ -0,0 +1,10 @@
+import type { Schema, SchemaAnyOf } from "../../Schema.ts"
+import { make } from "./_schema_common.ts"
+
+export interface anyOf<XA extends Array<Schema> = Array<Schema>> extends SchemaAnyOf<XA[number]["T"]> {
+  anyOf: XA
+}
+
+export function anyOf<XA extends Array<Schema>>(anyOf: XA): anyOf<XA> {
+  return make({ anyOf })
+}

package/L/schema/array.ts

@@ -0,0 +1,13 @@
+import type { Schema, SchemaArray } from "../../Schema.ts"
+import { make } from "./_schema_common.ts"
+
+export interface LArray<X extends Schema = Schema> extends SchemaArray<Array<X["T"]>> {
+  items: X
+}
+
+export function array<X extends Schema>(items: X): LArray<X> {
+  return make({
+    type: "array",
+    items,
+  })
+}

package/L/schema/boolean.ts

@@ -0,0 +1,8 @@
+import type { SchemaBoolean } from "../../Schema.ts"
+import { make, type TypeBase } from "./_schema_common.ts"
+
+interface boolean_ extends SchemaBoolean<boolean>, TypeBase {}
+
+const boolean_: boolean_ = make({ type: "boolean" })
+
+export { boolean_ as boolean }

package/L/schema/const.ts

@@ -0,0 +1,18 @@
+import type { SchemaString } from "../../Schema.ts"
+import { make, type TypeBase } from "./_schema_common.ts"
+
+interface const_<K extends string> extends SchemaString<K>, TypeBase {
+  enum?: never
+  const: K
+}
+
+function const_<K extends string>(value: K): const_<K> {
+  return make({
+    type: "string",
+    const: value,
+  })
+}
+
+Object.defineProperty(const_, "name", { value: "const" })
+
+export { const_ as const }

package/L/schema/enum.ts

@@ -0,0 +1,18 @@
+import type { SchemaString } from "../../Schema.ts"
+import { make, type TypeBase } from "./_schema_common.ts"
+
+interface enum_<V extends Array<string> = Array<string>> extends SchemaString<V[number]>, TypeBase {
+  enum: V
+  const?: never
+}
+
+function enum_<const V extends Array<string>>(...values: V): enum_<V> {
+  return make({
+    type: "string",
+    enum: values,
+  })
+}
+
+Object.defineProperty(enum_, "name", { value: "enum" })
+
+export { enum_ as enum }

package/L/schema/integer.ts

@@ -0,0 +1,6 @@
+import type { SchemaInteger } from "../../Schema.ts"
+import { make, type TypeBase } from "./_schema_common.ts"
+
+export interface integer extends SchemaInteger<number>, TypeBase {}
+
+export const integer: integer = make({ type: "integer" })

package/L/schema/null.ts

@@ -0,0 +1,8 @@
+import type { SchemaNull } from "../../Schema.ts"
+import { make, type TypeBase } from "./_schema_common.ts"
+
+export interface null_ extends SchemaNull<null>, TypeBase {}
+
+const null_: null_ = make({ type: "null" })
+
+export { null_ as null }

package/L/schema/number.ts

@@ -0,0 +1,8 @@
+import type { SchemaNumber } from "../../Schema.ts"
+import { make, type TypeBase } from "./_schema_common.ts"
+
+interface number_ extends SchemaNumber<number>, TypeBase {}
+
+const number_: number_ = make({ type: "number" })
+
+export { number_ as number }

package/L/schema/object.ts

@@ -0,0 +1,21 @@
+import type { Schema, SchemaObject } from "../../Schema.ts"
+import { make } from "./_schema_common.ts"
+
+interface object_<F extends Record<string, Schema> = Record<string, Schema>>
+  extends SchemaObject<{ [K in keyof F]: F[K]["T"] }>
+{
+  properties: F
+  required: Array<Extract<keyof F, string>>
+}
+
+function object_<XR extends Record<string, Schema>>(properties: XR): object_<XR> {
+  return make({
+    type: "object",
+    properties,
+    additionalProperties: false,
+    required: Object.keys(properties) as never,
+  })
+}
+
+Object.defineProperty(object_, "name", { value: "object" })
+export { object_ as object }

package/L/schema/string.ts

@@ -0,0 +1,11 @@
+import type { SchemaString } from "../../Schema.ts"
+import { make, type TypeBase } from "./_schema_common.ts"
+
+interface string_ extends SchemaString<string>, TypeBase {
+  enum?: never
+  const?: never
+}
+
+const string_: string_ = make({ type: "string" })
+
+export { string_ as string }

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

@@ -5,6 +5,7 @@ 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
@@ -12,6 +13,6 @@ export const stream: Iterable<Rune<LEvent>, ReadableStream<string>> = {
     LiminalAssertionError.assert(model)
     const requestId = crypto.randomUUID()
     yield* emit(new InferenceRequested(requestId))
-    return yield* continuation("stream", () => model.seal({ messages, signal }).stream())
+    return yield* continuation("stream", model.seal({ messages, signal }).stream)
   },
 }

package/Message.ts

@@ -1,13 +1,14 @@
 export interface Message {
   readonly role: MessageRole
-  readonly content: Array<ContentPart>
+  readonly parts: Array<Content>
 }
 
 export type MessageRole = "system" | "user" | "assistant"
 
-export type ContentPart = {
+export type Content = {
   readonly part: string
   readonly alt?: never
+  readonly mime?: never
 } | {
   readonly part: URL
   readonly alt: string

package/Model.ts

@@ -5,12 +5,12 @@ import { attachCustomInspect } from "./util/attachCustomInspect.ts"
 
 export class Model {
   constructor(
-    readonly vendor: string,
+    readonly client: string,
     readonly seal: (envelope: Envelope) => SealedEnvelope,
   ) {}
 
   static {
-    attachCustomInspect(this, ({ vendor }) => ({ vendor }))
+    attachCustomInspect(this, ({ client }) => ({ client }))
   }
 }
 
@@ -22,6 +22,6 @@ export interface Envelope {
 }
 
 export interface SealedEnvelope {
-  resolve(): Promise<string>
-  stream(): ReadableStream<string>
+  resolve: () => Promise<string>
+  stream: () => ReadableStream<string>
 }

package/ModelRegistry.ts

@@ -1,14 +1,22 @@
 import type { Model } from "./Model.ts"
 
-/** An intrusive list for storing `Model`s. */
+/**
+ * An intrusive doubly-linked list for storing `Model`s.
+ * Provides efficient insertion, removal, and lookups.
+ */
 export class ModelRegistry {
   declare head?: ModelRegistryNode | undefined
   declare tail?: ModelRegistryNode | undefined
 
+  /** Returns the most recently registered model */
   peek() {
     return this.tail?.model
   }
 
+  /**
+   * Registers a new model and returns the created node
+   * @param value The model to register
+   */
   register(value: Model): ModelRegistryNode {
     const node: ModelRegistryNode = {
       prev: this.tail,
@@ -23,6 +31,7 @@ export class ModelRegistry {
     return node
   }
 
+  /** Remove a model from the registry. */
   remove(node: ModelRegistryNode) {
     if (node.prev) {
       node.prev.next = node.next
@@ -36,13 +45,17 @@ export class ModelRegistry {
     if (node === this.tail) {
       this.tail = node.prev
     }
-    node.prev = node.next = undefined
+    node.prev = undefined
+    delete node.next
   }
 
+  /** Creates a deep copy of this registry. */
   clone() {
     const instance = new ModelRegistry()
     for (let node = this.head; node; node = node.next) {
-      instance.register(node.model)
+      if (node.model) {
+        instance.register(node.model)
+      }
     }
     return instance
   }