liminal 0.4.1 → 0.5.2

package/actions/enableTool.type-test.ts

@@ -0,0 +1,118 @@
+import type { AssertTrue, IsExact } from "conditional-type-checks"
+import type { AgentLike } from "../Agent.ts"
+import type { Emitted } from "../events/Emitted.ts"
+import type { ToolCalled } from "../events/ToolCalled.ts"
+import type { ToolDisabled } from "../events/ToolDisabled.ts"
+import type { ToolEnabled } from "../events/ToolEnabled.ts"
+import * as L from "../L.ts"
+import { AgentAssertions } from "../testing/AgentAssertions.ts"
+import { emit } from "./emit.ts"
+import { enableTool } from "./enableTool.ts"
+
+type P = typeof P["T"]
+const P = L.object({
+  a: L.string,
+  b: L.string,
+})
+
+const arrowTool = L.enableTool("Tool", "", P, (params) => {
+  type _ = [AssertTrue<IsExact<typeof params, P>>]
+})
+
+AgentAssertions(arrowTool).assertSpec<{
+  Event:
+    | ToolEnabled<"Tool">
+    | ToolCalled<"Tool", {
+      a: string
+      b: string
+    }>
+  Child: never
+  Throw: never
+  Entry: never
+  Value: never
+}>()
+
+function* _0() {
+  const detach = yield* arrowTool
+  AgentAssertions(detach).assertSpec<{
+    Event: ToolDisabled<"Tool">
+    Child: never
+    Throw: never
+    Entry: never
+    Value: never
+  }>()
+}
+
+const genTool = enableTool("tool-key", "", P, function*(params) {
+  type _ = [AssertTrue<IsExact<typeof params, P>>]
+  yield* emit("Test")
+  return ""
+})
+
+AgentAssertions(genTool).assertSpec<{
+  Event:
+    | ToolEnabled<"tool-key">
+    | ToolCalled<"tool-key", {
+      a: string
+      b: string
+    }>
+  Child: ["tool-key", {
+    Event: Emitted<"Test">
+    Child: never
+    Throw: never
+    Entry: never
+    Value: never
+  }]
+  Throw: never
+  Entry: never
+  Value: string
+}>()
+
+function* parent() {
+  yield* L.enableTool("parent-tool", "", P, () => {})
+  yield* L.branch("fork-key", {
+    *"arm-key"() {
+      yield* arrowTool
+    },
+  })
+}
+
+type g = typeof parent extends AgentLike<infer Y> ? Y[""] : never
+
+AgentAssertions(parent).assertSpec<
+  {
+    Event:
+      | ToolEnabled<"parent-tool">
+      | ToolCalled<"parent-tool", {
+        a: string
+        b: string
+      }>
+    Child: never
+    Throw: never
+    Entry: never
+    Value: never
+  } | {
+    Event: never
+    Child: ["fork-key", {
+      Event: never
+      Child: ["arm-key", {
+        Event:
+          | ToolEnabled<"Tool">
+          | ToolCalled<"Tool", {
+            a: string
+            b: string
+          }>
+        Child: never
+        Throw: never
+        Entry: never
+        Value: never
+      }]
+      Throw: never
+      Entry: never
+      Value: void
+    }]
+    Throw: never
+    Entry: never
+    Value: never
+  }
+>()

package/actions/infer.ts

@@ -0,0 +1,49 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import { Action } from "../Action.ts"
+import type { InferenceRequested } from "../events/InferenceRequested.ts"
+import type { Inferred } from "../events/Inferred.ts"
+import type { Spec } from "../Spec.ts"
+import type { JSONObject } from "../util/JSONObject.ts"
+import type { JSONValue } from "../util/JSONValue.ts"
+import { peekLast } from "../util/peekLast.ts"
+
+export { infer_ as infer }
+
+interface infer_<_T> extends
+  Action<
+    "infer",
+    Spec.Make<{
+      Event: InferenceRequested | Inferred
+    }>
+  >
+{}
+
+const infer_ = Object.assign(
+  function* infer_<T extends JSONValue>(type: StandardSchemaV1<JSONObject, T>): Generator<infer_<T>, T> {
+    return yield* impl(type)
+  },
+  {
+    *[Symbol.iterator](): Iterator<infer_<string>, string> {
+      return yield* impl()
+    },
+  },
+)
+Object.defineProperty(infer_, "name", { value: "infer" })
+
+function* impl(type?: StandardSchemaV1<JSONObject, any>): Generator<infer_<any>, any> {
+  return yield Action("infer", async (scope) => {
+    scope.event({
+      type: "inference_requested",
+    })
+    const model = peekLast(scope.languageModels)!
+    scope = await scope.reduce(model.infer(type))
+    scope.event({
+      type: "inferred",
+      value: scope.value,
+    })
+    return {
+      ...scope,
+      nextArg: scope.value,
+    }
+  })
+}

package/actions/messages.ts

@@ -0,0 +1,62 @@
+import { Action } from "../Action.ts"
+import type { Agent } from "../Agent.ts"
+import type { MessagesSet } from "../events/MessagesSet.ts"
+import type { Message } from "../Message.ts"
+import type { Spec } from "../Spec.ts"
+import { isPropertyKey } from "../util/isPropertyKey.ts"
+import type { JSONKey } from "../util/JSONKey.ts"
+import type { PromiseOr } from "../util/PromiseOr.ts"
+import { type getScope, scope } from "./scope.ts"
+
+interface messages extends Iterable<getScope, Set<Message>> {
+  (messages: Array<Message>): Generator<Action<"set_messages", Spec.Make<{ Event: MessagesSet }>>, Array<Message>>
+  (
+    setter: (messages: Array<Message>) => PromiseOr<Array<Message>>,
+  ): Generator<Action<"set_messages", Spec.Make<{ Event: MessagesSet }>>, Array<Message>>
+  <K extends JSONKey, Y extends Action>(
+    key: K,
+    setter: (messages: Array<Message>) => Agent<Y, void>,
+  ): Generator<
+    Action<
+      "set_messages",
+      Spec.Make<{ Event: MessagesSet; Child: [K, Y[""]]; Entry: Y[""]["Entry"]; Value: Array<Message> }>
+    >,
+    Array<Message>
+  >
+}
+
+export const messages: messages = Object.assign(messages_, {
+  *[Symbol.iterator]() {
+    const scope_ = yield* scope
+    return scope_.messages
+  },
+}) as never
+
+function* messages_(
+  setterOrKey: JSONKey | ((messages: Array<Message>) => PromiseOr<Array<Message>>),
+  maybeSetter?: (messages: Array<Message>) => Agent<Action, void>,
+): Generator<Action<"set_messages">, Array<Message>> {
+  return yield Action("set_messages", async (scope) => {
+    if (isPropertyKey(setterOrKey)) {
+      const setterScope = scope.fork("set_messages", [setterOrKey])
+      const reduced = await setterScope.reduce(maybeSetter!([...scope.messages]))
+      const { messages } = reduced
+      setterScope.event({
+        type: "messages_set",
+        messages: [...messages],
+      })
+      return {
+        ...scope,
+        messages,
+        nextArg: scope.messages,
+      }
+    }
+    const messages = new Set(Array.isArray(setterOrKey) ? setterOrKey : await setterOrKey([...scope.messages]))
+    return {
+      ...scope,
+      messages,
+      nextArg: scope.messages,
+    }
+  })
+}
+Object.defineProperty(messages_, "name", { value: "messages" })

package/actions/pushModel.ts

@@ -0,0 +1,52 @@
+import { Action } from "../Action.ts"
+import type { ModelPushed } from "../events/ModelPushed.ts"
+import type { ModelRemoved } from "../events/ModelRemoved.ts"
+import type { Model, ModelType } from "../Model.ts"
+import type { Spec } from "../Spec.ts"
+import type { JSONKey } from "../util/JSONKey.ts"
+import { applyToModels } from "./actions_common/updateModels.ts"
+
+export interface pushModel<K extends JSONKey, M extends ModelType>
+  extends Action<"remove_model", Spec.Make<{ Event: ModelPushed<K, M> }>>
+{}
+
+export interface removeModel<K extends JSONKey, M extends ModelType>
+  extends Action<"remove_model", Spec.Make<{ Event: ModelRemoved<K, M> }>>
+{}
+
+export function* pushModel<K extends JSONKey, M extends Model>(
+  modelKey: K,
+  model: M,
+): Generator<pushModel<K, M["type"]>, Generator<removeModel<K, M["type"]>, void>> {
+  return yield Action("remove_model", (scope) => {
+    scope.event({
+      type: "model_pushed",
+      modelKey,
+      modelType: model.type,
+    })
+    return {
+      ...scope,
+      ...applyToModels(scope, model, (models) => {
+        models.add(model)
+        return models
+      }),
+      nextArg: (function*(): Generator<removeModel<K, M["type"]>, void> {
+        yield Action("remove_model", (scope) => {
+          scope.event({
+            type: "model_removed",
+            modelKey,
+            modelType: model.type,
+          })
+          return {
+            ...scope,
+            ...applyToModels(scope, model, (models) => {
+              models.delete(model)
+              return models
+            }),
+            nextArg: undefined,
+          }
+        })
+      })(),
+    }
+  })
+}

package/actions/scope.ts

@@ -0,0 +1,13 @@
+import { Action } from "../Action.ts"
+import type { Scope } from "../Scope.ts"
+
+export interface getScope extends Action<"get_scope", never> {}
+
+export const scope = {
+  *[Symbol.iterator](): Iterator<getScope, Scope> {
+    return yield Action("get_scope", (scope) => ({
+      ...scope,
+      nextArg: scope,
+    }))
+  },
+}

package/actions/section.ts

@@ -0,0 +1,105 @@
+import { Action } from "../Action.ts"
+import type { Agent, AgentLike } from "../Agent.ts"
+import type { SectionCleared } from "../events/SectionCleared.ts"
+import type { Sectioned } from "../events/Sectioned.ts"
+import type { Message } from "../Message.ts"
+import type { Section } from "../Scope.ts"
+import type { Spec } from "../Spec.ts"
+import type { JSONKey } from "../util/JSONKey.ts"
+import { unwrapDeferred } from "../util/unwrapDeferred.ts"
+
+export interface section<K extends JSONKey> extends Action<"section", Spec.Make<{ Event: Sectioned<K> }>> {}
+
+export interface SectionHandle<K extends JSONKey> {
+  clear: Generator<Action<"clear_section", Spec.Make<{ Event: SectionCleared<K> }>>, void>
+  getMessages: () => Generator<Action<"get_section_messages", never>, Set<Message>>
+
+  <L extends JSONKey, Y extends Action, T>(key: L, agentLike: AgentLike<Y, T>): Generator<
+    Action<
+      "run_section",
+      Spec.Make<{
+        Child: [L, Y[""]]
+        Entry: Y[""]["Entry"]
+        Value: T
+      }>
+    >,
+    T
+  >
+}
+
+export function* section<K extends JSONKey>(sectionKey: K): Generator<section<K>, SectionHandle<K>> {
+  return yield Action("section", (scope) => {
+    scope.event({
+      type: "sectioned",
+      sectionKey,
+    })
+    const section: Section = {
+      sectionKey,
+      messages: new Set(),
+    }
+    scope.sections.add(section)
+    return {
+      ...scope,
+      nextArg: Object.assign(
+        function*<L extends JSONKey, Y extends Action, T>(key: L, agentLike: AgentLike<Y, T>): Generator<
+          Action<
+            "run_section",
+            Spec.Make<{
+              Child: [L, Y[""]]
+              Entry: Y[""]["Entry"]
+              Value: T
+            }>
+          >,
+          T
+        > {
+          return yield Action("run_section", async (scope) => {
+            const sectionScope = scope.fork("run_section", [key], {
+              messages: new Set(section.messages),
+            })
+            const reduced = await sectionScope.reduce(unwrapDeferred(agentLike))
+            const { value } = reduced
+            sectionScope.event({
+              type: "returned",
+              value,
+            })
+            return {
+              ...scope,
+              nextArg: value,
+            }
+          })
+        },
+        {
+          getMessages: (function*(): Generator<Action<"get_section_messages", never>, Set<Message>> {
+            return yield Action("get_section_messages", (scope) => ({
+              ...scope,
+              nextArg: new Set(section.messages),
+            }))
+          })(),
+        },
+        {
+          clear:
+            (function*(): Generator<Action<"clear_section", Spec.Make<{ Event: SectionCleared<K> }>>, Set<Message>> {
+              return yield Action("clear_section", (scope) => {
+                const sections = new Set(scope.sections)
+                sections.delete(section)
+                const messages = new Set(scope.messages)
+                section.messages.forEach((message) => {
+                  messages.delete(message)
+                })
+                scope.event({
+                  type: "section_cleared",
+                  sectionKey,
+                })
+                return {
+                  ...scope,
+                  nextArg: messages,
+                  sections,
+                  messages,
+                }
+              })
+            })(),
+        },
+      ),
+    }
+  })
+}

package/actions/throw.ts

@@ -0,0 +1,18 @@
+import { Action } from "../Action.ts"
+import type { Spec } from "../Spec.ts"
+import type { EnsureNarrow } from "../util/EnsureNarrow.ts"
+
+export { throw_ as throw }
+
+interface throw_<V> extends Action<"throw", Spec.Make<{ Throw: V }>> {}
+
+function* throw_<V>(value: V, ...[_error]: EnsureNarrow<V>): Generator<throw_<V>, never> {
+  return (yield Action("throw", (scope) => {
+    return {
+      ...scope,
+      thrown: value,
+      nextArg: undefined,
+    }
+  })) as never
+}
+Object.defineProperty(throw_, "name", { value: "throw" })

package/cli/WriteHandler.ts

@@ -0,0 +1,35 @@
+import { mkdir, writeFile } from "node:fs/promises"
+import { type ParsedPath, relative, resolve } from "node:path"
+import type { EventResolved } from "../events/EventResolved.ts"
+
+export async function WriteHandler({
+  stateDir,
+  parsedPath,
+  configDir,
+  startTime,
+}: {
+  stateDir: string
+  execId: string | undefined
+  parsedPath: ParsedPath
+  startTime: number
+  configDir: string
+}): Promise<(event: EventResolved) => Promise<void>> {
+  const destDir = resolve(stateDir, relative(configDir, parsedPath.dir), parsedPath.name, startTime.toString())
+  let ensureDir: undefined | PromiseWithResolvers<void>
+  let i = 0
+  return async (event) => {
+    if (!ensureDir) {
+      ensureDir = Promise.withResolvers()
+      ;(async () => {
+        try {
+          await mkdir(destDir, { recursive: true })
+        } catch (_e: unknown) {}
+        ensureDir.resolve()
+      })()
+    }
+    await ensureDir.promise
+    const key = `${i++}__${event.scope.join("__")}__${event.type}.json`
+    const destPath = resolve(destDir, key)
+    await writeFile(destPath, JSON.stringify(event, null, 2), "utf-8")
+  }
+}

package/cli/cli_common.ts

@@ -0,0 +1,4 @@
+export interface CliCtx {
+  ctl: AbortController
+  error(message: string): never
+}

package/cli/main.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+import process from "node:process"
+import { L } from "../index.ts"
+import type { CliCtx } from "./cli_common.ts"
+import { runExec } from "./runExec.ts"
+
+const args = process.argv.slice(2)
+const command = L.enum("exec").assert(args.shift())
+const ctl = new AbortController()
+
+const cliCtx: CliCtx = {
+  ctl,
+  error(message) { // TODO
+    throw new Error(message)
+  },
+}
+
+switch (command) {
+  case "exec": {
+    await runExec(cliCtx, args)
+    break
+  }
+}

package/cli/runExec.ts

@@ -0,0 +1,72 @@
+import { dirname, isAbsolute, parse, resolve } from "node:path"
+import { parseArgs, type ParseArgsConfig } from "node:util"
+import { type Agent, type EventResolved, exec, L, type LiminalConfig } from "../index.ts"
+import type { CliCtx } from "./cli_common.ts"
+import { WriteHandler } from "./WriteHandler.ts"
+
+const options = {
+  config: {
+    type: "string",
+    default: "liminal.ts",
+    short: "c",
+  },
+  execId: {
+    type: "string",
+    short: "i",
+  },
+} satisfies ParseArgsConfig["options"]
+
+export async function runExec(ctx: CliCtx, args: Array<string>) {
+  let {
+    values: {
+      config: configPath,
+      execId,
+    },
+    positionals,
+  } = parseArgs({
+    args,
+    strict: true,
+    allowPositionals: true,
+    options,
+  })
+  const configPathResolved = resolve(configPath)
+  const configDir = dirname(configPathResolved)
+  const config = await import(configPathResolved).then(({ default: default_ }) => default_ as LiminalConfig)
+  const agentPathInitial = L.string.assert(positionals[0])
+  let agentPathResolved: string
+  if (isAbsolute(agentPathInitial)) {
+    agentPathResolved = agentPathInitial
+  } else {
+    agentPathResolved = resolve(configDir, ...config.agents ? [config.agents] : [], agentPathInitial)
+  }
+  if (!agentPathResolved.endsWith(".ts")) {
+    agentPathResolved = `${agentPathResolved}.ts`
+  }
+  const parsedPath = parse(agentPathResolved)
+  let agentLike: () => Agent
+  try {
+    agentLike = await import(agentPathResolved).then(({ default: default_ }) => default_ as () => Agent)
+  } catch (_e: unknown) {
+    ctx.error(`Could not fine agent file at "${agentPathResolved}".`)
+  }
+  const startTime = Date.now()
+  const writeHandlerOrNoop = config.write
+    ? await WriteHandler({
+      configDir,
+      parsedPath,
+      execId,
+      startTime,
+      stateDir: typeof config.write === "string" ? config.write : ".liminal",
+    })
+    : undefined
+  const printHandlerOrNoop = config.silent ? undefined : (event: EventResolved) => console.log(event)
+  await exec(agentLike, {
+    default: config.default,
+    args: config.args!,
+    handler(event) {
+      printHandlerOrNoop?.(event)
+      writeHandlerOrNoop?.(event)
+    },
+    signal: ctx.ctl.signal,
+  })
+}

package/dist/Action.d.ts

@@ -0,0 +1,15 @@
+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 declare function Action<K extends string, S extends Spec>(type: K, reducer: ActionReducer<K, S>): Action<K, S>;
+export type ActionKey = typeof ActionKey;
+export declare const ActionKey: unique symbol;
+export declare function isAction(value: unknown): value is Action;

package/dist/Action.js

@@ -0,0 +1,13 @@
+export function Action(type, reducer) {
+    return {
+        type,
+        [ActionKey]: true,
+        trace: new Error().stack,
+        reducer,
+    };
+}
+export const ActionKey = Symbol("Liminal/Action");
+export function isAction(value) {
+    return typeof value === "object" && value !== null && ActionKey in value;
+}
+//# sourceMappingURL=Action.js.map

package/dist/Action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Action.js","sourceRoot":"","sources":["../Action.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,MAAM,CAAmC,IAAO,EAAE,OAA4B;IAC5F,OAAQ;QACN,IAAI;QACJ,CAAC,SAAS,CAAC,EAAE,IAAI;QACjB,KAAK,EAAE,IAAI,KAAK,EAAE,CAAC,KAAM;QACzB,OAAO;KACmC,CAAA;AAC9C,CAAC;AAGD,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAA;AAEjD,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,SAAS,IAAI,KAAK,CAAA;AAC1E,CAAC"}

package/dist/Agent.d.ts

@@ -0,0 +1,7 @@
+import type { Action } from "./Action.ts";
+import type { DeferredOr } from "./util/DeferredOr.ts";
+import type { IteratorLike } from "./util/IteratorLike.ts";
+export type Agent<Y extends Action = Action, R = any> = IteratorLike<Y, R>;
+export type AgentLike<Y extends Action = Action, R = any> = DeferredOr<Agent<Y, R>>;
+export type AgentLikeY<A extends AgentLike> = A extends AgentLike<infer Y> ? Y : never;
+export type AgentLikeT<A extends AgentLike> = A extends AgentLike<Action, infer T> ? T : never;

package/dist/Agent.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Agent.js.map

package/dist/Agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../Agent.ts"],"names":[],"mappings":""}

package/dist/Exec.d.ts

@@ -0,0 +1,25 @@
+import type { Action } from "./Action.ts";
+import type { Agent } from "./Agent.ts";
+import type { EventHandler } from "./events/EventHandler.ts";
+import type { EventResolved, ExtractEventResolved } from "./events/EventResolved.ts";
+import type { LanguageModel } from "./Model.ts";
+import type { FromEntries } from "./util/FromEntries.ts";
+import type { JSONKey } from "./util/JSONKey.ts";
+export interface ExecConfig {
+    default: LanguageModel;
+    args?: Record<JSONKey, any>;
+    signal?: AbortSignal;
+    handler?: EventHandler;
+}
+export type ExtractExecConfig<Y extends Action> = {
+    default: LanguageModel;
+    signal?: AbortSignal;
+    handler?: EventHandler<Extract<ExtractEventResolved<Y[""]> & {}, EventResolved>>;
+} & ([
+    Y[""]["Entry"]
+] extends [never] ? {
+    args?: undefined;
+} : {
+    args: FromEntries<Y[""]["Entry"]>;
+});
+export declare function exec<Y extends Action, T>(createAgent: () => Agent<Y, T>, config: ExtractExecConfig<Y>): Promise<T>;

package/dist/Exec.js

@@ -0,0 +1,19 @@
+import { RootScope } from "./Scope.js";
+export async function exec(createAgent, config) {
+    let scope = RootScope(config);
+    scope = await scope.reduce(createAgent());
+    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;
+}
+//# sourceMappingURL=Exec.js.map

package/dist/Exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Exec.js","sourceRoot":"","sources":["../Exec.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,SAAS,EAAc,MAAM,YAAY,CAAA;AA0BlD,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,WAA8B,EAC9B,MAA4B;IAE5B,IAAI,KAAK,GAAU,SAAS,CAAC,MAAe,CAAC,CAAA;IAC7C,KAAK,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAA;IACzC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,KAAK,CAAC,UAAU,CAAA;IACxD,IAAI,OAAO,EAAE,CAAC;QACZ,KAAK,CAAC,KAAK,CAAC;YACV,IAAI,EAAE,SAAS;YACf,MAAM;SACP,CAAC,CAAA;QACF,MAAM,MAAM,CAAA;IACd,CAAC;IACD,KAAK,CAAC,KAAK,CAAC;QACV,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC,CAAA;IACF,OAAO,KAAK,CAAC,KAAK,CAAA;AACpB,CAAC"}