@foresthubai/workflow-core 0.3.0 → 0.4.0

package/src/memory/serialization.ts

@@ -1,47 +1,47 @@
-import type { Schemas } from "../api";
-import type { Memory } from "./Memory";
-
-export type ApiMemory = Schemas["Memory"];
-
-/**
- * Serialize a domain Memory to the API discriminated-union shape.
- * MemoryFile drops `maxSizeBytes` when unset (absent and null both mean "unlimited").
- */
-export function serialize(mem: Memory): ApiMemory {
-  const { id, label, type, arguments: args } = mem;
-  switch (type) {
-    case "MemoryFile":
-      return {
-        type,
-        id,
-        label,
-        description: (args.description as string) ?? "",
-        content: (args.content as string) ?? "",
-        ...(args.maxSizeBytes != null ? { maxSizeBytes: args.maxSizeBytes as number } : {}),
-      };
-    case "VectorDatabase":
-      return {
-        type,
-        id,
-        label,
-        ...(args.description != null ? { description: args.description as string } : {}),
-      };
-  }
-}
-
-/** Convert an API Memory into a domain Memory. */
-export function deserialize(api: ApiMemory): Memory {
-  const { id, label, type } = api;
-  const args: Record<string, unknown> = {};
-  switch (type) {
-    case "MemoryFile":
-      args.description = api.description ?? "";
-      args.content = api.content ?? "";
-      if (api.maxSizeBytes != null) args.maxSizeBytes = api.maxSizeBytes;
-      break;
-    case "VectorDatabase":
-      if (api.description != null) args.description = api.description;
-      break;
-  }
-  return { id, label, type, arguments: args };
-}
+import type { Schemas } from "../api";
+import type { Memory } from "./Memory";
+
+export type ApiMemory = Schemas["Memory"];
+
+/**
+ * Serialize a domain Memory to the API discriminated-union shape.
+ * MemoryFile drops `maxSizeBytes` when unset (absent and null both mean "unlimited").
+ */
+export function serialize(mem: Memory): ApiMemory {
+  const { id, label, type, arguments: args } = mem;
+  switch (type) {
+    case "MemoryFile":
+      return {
+        type,
+        id,
+        label,
+        description: (args.description as string) ?? "",
+        content: (args.content as string) ?? "",
+        ...(args.maxSizeBytes != null ? { maxSizeBytes: args.maxSizeBytes as number } : {}),
+      };
+    case "VectorDatabase":
+      return {
+        type,
+        id,
+        label,
+        ...(args.description != null ? { description: args.description as string } : {}),
+      };
+  }
+}
+
+/** Convert an API Memory into a domain Memory. */
+export function deserialize(api: ApiMemory): Memory {
+  const { id, label, type } = api;
+  const args: Record<string, unknown> = {};
+  switch (type) {
+    case "MemoryFile":
+      args.description = api.description ?? "";
+      args.content = api.content ?? "";
+      if (api.maxSizeBytes != null) args.maxSizeBytes = api.maxSizeBytes;
+      break;
+    case "VectorDatabase":
+      if (api.description != null) args.description = api.description;
+      break;
+  }
+  return { id, label, type, arguments: args };
+}

package/src/migration/index.ts

@@ -1,4 +1,4 @@
-export { CURRENT_SCHEMA_VERSION, BASELINE_SCHEMA_VERSION } from "./version";
-export { migrate, readSchemaVersion } from "./migrate";
-export { MIGRATIONS } from "./migrations";
-export type { Migration } from "./migrations";
+export { CURRENT_SCHEMA_VERSION, BASELINE_SCHEMA_VERSION } from "./version";
+export { migrate, readSchemaVersion } from "./migrate";
+export { MIGRATIONS } from "./migrations";
+export type { Migration } from "./migrations";

package/src/migration/migrate.test.ts

@@ -1,44 +1,44 @@
-import { describe, it, expect } from "vitest";
-import { migrate, readSchemaVersion } from "./migrate";
-import { CURRENT_SCHEMA_VERSION } from "./version";
-
-describe("readSchemaVersion", () => {
-  it("reads an explicit integer version", () => {
-    expect(readSchemaVersion({ schemaVersion: 3 })).toBe(3);
-  });
-
-  it("defaults missing, non-integer, or out-of-range to the baseline", () => {
-    expect(readSchemaVersion({})).toBe(1);
-    expect(readSchemaVersion({ schemaVersion: 1.5 })).toBe(1);
-    expect(readSchemaVersion({ schemaVersion: 0 })).toBe(1);
-    expect(readSchemaVersion({ schemaVersion: "2" })).toBe(1);
-  });
-});
-
-describe("migrate", () => {
-  it("stamps the current version on a baseline document", () => {
-    const out = migrate({ nodes: [], edges: [] });
-    expect(out.schemaVersion).toBe(CURRENT_SCHEMA_VERSION);
-  });
-
-  it("passes through a document already at the current version", () => {
-    const doc = { schemaVersion: CURRENT_SCHEMA_VERSION, nodes: [] };
-    expect(migrate(doc).schemaVersion).toBe(CURRENT_SCHEMA_VERSION);
-  });
-
-  it("does not mutate its input", () => {
-    const doc: Record<string, unknown> = { nodes: [] };
-    migrate(doc);
-    expect("schemaVersion" in doc).toBe(false);
-  });
-
-  it("rejects a document newer than this build supports", () => {
-    expect(() => migrate({ schemaVersion: CURRENT_SCHEMA_VERSION + 1 })).toThrow(/newer than this build/);
-  });
-
-  it("rejects a non-object document", () => {
-    expect(() => migrate(null)).toThrow(/must be a JSON object/);
-    expect(() => migrate([])).toThrow(/must be a JSON object/);
-    expect(() => migrate(42)).toThrow(/must be a JSON object/);
-  });
-});
+import { describe, it, expect } from "vitest";
+import { migrate, readSchemaVersion } from "./migrate";
+import { CURRENT_SCHEMA_VERSION } from "./version";
+
+describe("readSchemaVersion", () => {
+  it("reads an explicit integer version", () => {
+    expect(readSchemaVersion({ schemaVersion: 3 })).toBe(3);
+  });
+
+  it("defaults missing, non-integer, or out-of-range to the baseline", () => {
+    expect(readSchemaVersion({})).toBe(1);
+    expect(readSchemaVersion({ schemaVersion: 1.5 })).toBe(1);
+    expect(readSchemaVersion({ schemaVersion: 0 })).toBe(1);
+    expect(readSchemaVersion({ schemaVersion: "2" })).toBe(1);
+  });
+});
+
+describe("migrate", () => {
+  it("stamps the current version on a baseline document", () => {
+    const out = migrate({ nodes: [], edges: [] });
+    expect(out.schemaVersion).toBe(CURRENT_SCHEMA_VERSION);
+  });
+
+  it("passes through a document already at the current version", () => {
+    const doc = { schemaVersion: CURRENT_SCHEMA_VERSION, nodes: [] };
+    expect(migrate(doc).schemaVersion).toBe(CURRENT_SCHEMA_VERSION);
+  });
+
+  it("does not mutate its input", () => {
+    const doc: Record<string, unknown> = { nodes: [] };
+    migrate(doc);
+    expect("schemaVersion" in doc).toBe(false);
+  });
+
+  it("rejects a document newer than this build supports", () => {
+    expect(() => migrate({ schemaVersion: CURRENT_SCHEMA_VERSION + 1 })).toThrow(/newer than this build/);
+  });
+
+  it("rejects a non-object document", () => {
+    expect(() => migrate(null)).toThrow(/must be a JSON object/);
+    expect(() => migrate([])).toThrow(/must be a JSON object/);
+    expect(() => migrate(42)).toThrow(/must be a JSON object/);
+  });
+});

package/src/migration/migrate.ts

@@ -1,58 +1,58 @@
-import type { ApiWorkflow } from "../workflow/Workflow";
-import { MIGRATIONS, type Migration } from "./migrations";
-import { BASELINE_SCHEMA_VERSION, CURRENT_SCHEMA_VERSION } from "./version";
-
-/**
- * Index the registry by `from` and assert it forms a contiguous chain over
- * [BASELINE_SCHEMA_VERSION, CURRENT_SCHEMA_VERSION). A gap or duplicate is a
- * programming error, so it throws at module load rather than on first use.
- */
-function buildChain(migrations: readonly Migration[]): ReadonlyMap<number, Migration> {
-  const byFrom = new Map<number, Migration>();
-  for (const m of migrations) {
-    if (!Number.isInteger(m.from) || m.from < BASELINE_SCHEMA_VERSION || m.from >= CURRENT_SCHEMA_VERSION) {
-      throw new Error(`[migration] from must be an integer in [${BASELINE_SCHEMA_VERSION}, ${CURRENT_SCHEMA_VERSION}), got ${m.from}`);
-    }
-    if (byFrom.has(m.from)) {
-      throw new Error(`[migration] duplicate migration from ${m.from}`);
-    }
-    byFrom.set(m.from, m);
-  }
-  for (let v = BASELINE_SCHEMA_VERSION; v < CURRENT_SCHEMA_VERSION; v++) {
-    if (!byFrom.has(v)) throw new Error(`[migration] missing migration from ${v} -> ${v + 1}`);
-  }
-  return byFrom;
-}
-
-const CHAIN = buildChain(MIGRATIONS);
-
-/** Read the schema version, defaulting absent/invalid to the baseline. */
-export function readSchemaVersion(doc: Record<string, unknown>): number {
-  const v = doc.schemaVersion;
-  return typeof v === "number" && Number.isInteger(v) && v >= BASELINE_SCHEMA_VERSION ? v : BASELINE_SCHEMA_VERSION;
-}
-
-/**
- * Upgrade a raw, parsed workflow document to CURRENT_SCHEMA_VERSION and return
- * it as the current {@link ApiWorkflow}, ready for `deserialize`. Runs on
- * untyped JSON so each migration stays pinned to the shape it was written for.
- * Throws on a non-object, or a version newer than this build supports.
- */
-export function migrate(raw: unknown): ApiWorkflow {
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    throw new Error("[migration] workflow document must be a JSON object");
-  }
-  let doc: Record<string, unknown> = { ...(raw as Record<string, unknown>) };
-
-  const version = readSchemaVersion(doc);
-  if (version > CURRENT_SCHEMA_VERSION) {
-    throw new Error(`[migration] schemaVersion ${version} is newer than this build supports (${CURRENT_SCHEMA_VERSION})`);
-  }
-
-  for (let v = version; v < CURRENT_SCHEMA_VERSION; v++) {
-    doc = CHAIN.get(v)!.migrate(doc); // non-null: buildChain covers every v in range
-  }
-
-  doc.schemaVersion = CURRENT_SCHEMA_VERSION;
-  return doc as ApiWorkflow;
-}
+import type { ApiWorkflow } from "../workflow/Workflow";
+import { MIGRATIONS, type Migration } from "./migrations";
+import { BASELINE_SCHEMA_VERSION, CURRENT_SCHEMA_VERSION } from "./version";
+
+/**
+ * Index the registry by `from` and assert it forms a contiguous chain over
+ * [BASELINE_SCHEMA_VERSION, CURRENT_SCHEMA_VERSION). A gap or duplicate is a
+ * programming error, so it throws at module load rather than on first use.
+ */
+function buildChain(migrations: readonly Migration[]): ReadonlyMap<number, Migration> {
+  const byFrom = new Map<number, Migration>();
+  for (const m of migrations) {
+    if (!Number.isInteger(m.from) || m.from < BASELINE_SCHEMA_VERSION || m.from >= CURRENT_SCHEMA_VERSION) {
+      throw new Error(`[migration] from must be an integer in [${BASELINE_SCHEMA_VERSION}, ${CURRENT_SCHEMA_VERSION}), got ${m.from}`);
+    }
+    if (byFrom.has(m.from)) {
+      throw new Error(`[migration] duplicate migration from ${m.from}`);
+    }
+    byFrom.set(m.from, m);
+  }
+  for (let v = BASELINE_SCHEMA_VERSION; v < CURRENT_SCHEMA_VERSION; v++) {
+    if (!byFrom.has(v)) throw new Error(`[migration] missing migration from ${v} -> ${v + 1}`);
+  }
+  return byFrom;
+}
+
+const CHAIN = buildChain(MIGRATIONS);
+
+/** Read the schema version, defaulting absent/invalid to the baseline. */
+export function readSchemaVersion(doc: Record<string, unknown>): number {
+  const v = doc.schemaVersion;
+  return typeof v === "number" && Number.isInteger(v) && v >= BASELINE_SCHEMA_VERSION ? v : BASELINE_SCHEMA_VERSION;
+}
+
+/**
+ * Upgrade a raw, parsed workflow document to CURRENT_SCHEMA_VERSION and return
+ * it as the current {@link ApiWorkflow}, ready for `deserialize`. Runs on
+ * untyped JSON so each migration stays pinned to the shape it was written for.
+ * Throws on a non-object, or a version newer than this build supports.
+ */
+export function migrate(raw: unknown): ApiWorkflow {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error("[migration] workflow document must be a JSON object");
+  }
+  let doc: Record<string, unknown> = { ...(raw as Record<string, unknown>) };
+
+  const version = readSchemaVersion(doc);
+  if (version > CURRENT_SCHEMA_VERSION) {
+    throw new Error(`[migration] schemaVersion ${version} is newer than this build supports (${CURRENT_SCHEMA_VERSION})`);
+  }
+
+  for (let v = version; v < CURRENT_SCHEMA_VERSION; v++) {
+    doc = CHAIN.get(v)!.migrate(doc); // non-null: buildChain covers every v in range
+  }
+
+  doc.schemaVersion = CURRENT_SCHEMA_VERSION;
+  return doc as ApiWorkflow;
+}

package/src/migration/migrations.ts

@@ -1,24 +1,24 @@
-/**
- * A single-step upgrade of the persisted workflow format, from `from` to
- * `from + 1`. Operates on the raw parsed document, never the domain types.
- * Forward-only: there is no down-path.
- *
- * A shipped migration is immutable — saved files depend on its exact behaviour.
- * Express the next change as a new migration, never an edit to an old one.
- */
-export interface Migration {
-  /** Schema version this migration expects as input. Produces `from + 1`. */
-  readonly from: number;
-  /** Pure transform on the raw document; must not mutate its input. */
-  migrate(doc: Record<string, unknown>): Record<string, unknown>;
-}
-
-/**
- * Ordered registry of single-step format migrations. To change the format:
- * bump CURRENT_SCHEMA_VERSION, append one migration with `from` set to the
- * previous value, and reconcile serialize/deserialize. {@link migrate} asserts
- * at load that the chain is contiguous over [BASELINE, CURRENT).
- */
-export const MIGRATIONS: readonly Migration[] = [
-  // First entry will be `{ from: 1, migrate: (doc) => ... }`.
-];
+/**
+ * A single-step upgrade of the persisted workflow format, from `from` to
+ * `from + 1`. Operates on the raw parsed document, never the domain types.
+ * Forward-only: there is no down-path.
+ *
+ * A shipped migration is immutable — saved files depend on its exact behaviour.
+ * Express the next change as a new migration, never an edit to an old one.
+ */
+export interface Migration {
+  /** Schema version this migration expects as input. Produces `from + 1`. */
+  readonly from: number;
+  /** Pure transform on the raw document; must not mutate its input. */
+  migrate(doc: Record<string, unknown>): Record<string, unknown>;
+}
+
+/**
+ * Ordered registry of single-step format migrations. To change the format:
+ * bump CURRENT_SCHEMA_VERSION, append one migration with `from` set to the
+ * previous value, and reconcile serialize/deserialize. {@link migrate} asserts
+ * at load that the chain is contiguous over [BASELINE, CURRENT).
+ */
+export const MIGRATIONS: readonly Migration[] = [
+  // First entry will be `{ from: 1, migrate: (doc) => ... }`.
+];

package/src/migration/version.ts

@@ -1,9 +1,9 @@
-/**
- * Persisted-format version this build reads and writes. A plain monotonic
- * integer, decoupled from the contract/package semver. Bump only when the
- * serialized {@link ApiWorkflow} shape changes, adding a matching migration.
- */
-export const CURRENT_SCHEMA_VERSION = 1;
-
-/** Version assumed for documents that carry no `schemaVersion`. */
-export const BASELINE_SCHEMA_VERSION = 1;
+/**
+ * Persisted-format version this build reads and writes. A plain monotonic
+ * integer, decoupled from the contract/package semver. Bump only when the
+ * serialized {@link ApiWorkflow} shape changes, adding a matching migration.
+ */
+export const CURRENT_SCHEMA_VERSION = 1;
+
+/** Version assumed for documents that carry no `schemaVersion`. */
+export const BASELINE_SCHEMA_VERSION = 1;

package/src/model/LLMModelDefinition.ts

@@ -1,12 +1,12 @@
-import type { ModelDefinition } from "./ModelDefinition";
-
-/**
- * A declared custom/self-hosted LLM model.
- * Capabilities default to ["chat"] on serialize; a capability editor can be added later.
- */
-export const LLMModelDefinition: ModelDefinition = {
-  type: "LLMModel",
-  label: "Custom LLM Model",
-  description: "A self-hosted or custom LLM the llmproxy doesn't ship by default",
-  parameters: [],
-};
+import type { ModelDefinition } from "./ModelDefinition";
+
+/**
+ * A declared custom/self-hosted LLM model.
+ * Capabilities default to ["chat"] on serialize; a capability editor can be added later.
+ */
+export const LLMModelDefinition: ModelDefinition = {
+  type: "LLMModel",
+  label: "Custom LLM Model",
+  description: "A self-hosted or custom LLM the llmproxy doesn't ship by default",
+  parameters: [],
+};

package/src/model/Model.ts

@@ -1,39 +1,39 @@
-// Domain Model — covers two distinct things that share a picker:
-//   1. The STATIC catalog (ModelInfo[]): the set of models the llmproxy already
-//      supports. Supplied to the editor as data (props), not declared per-workflow.
-//      A node simply stores the chosen catalog ModelID directly.
-//   2. DECLARED custom models (Model): self-hosted / custom models the
-//      llmproxy doesn't ship. These are channel-like — declared in the workflow,
-//      referenced by id from nodes, and mapped to an llmproxy provider at deploy.
-//
-// A node's `model` field is always just a ModelID string either way; static ids
-// resolve via the catalog (no mapping), custom ids via a declared Model.
-//
-// `type` is the api discriminator; new model families (e.g. future YOLO/ONNX
-// variants) register their own definition in ModelRegistry, mirroring nodes.
-
-import type { Schemas } from "../api";
-
-/** A capability a model supports (chat, embedding, vision, ...). From the api. */
-export type ModelCapability = Schemas["ModelCapability"];
-
-export type ModelType = "LLMModel";
-
-export const ALL_MODEL_TYPES: ModelType[] = ["LLMModel"];
-
-export interface Model {
-  id: string;
-  label: string;
-  type: ModelType;
-  arguments: Record<string, unknown>;
-}
-
-/**
- * One entry in the static model catalog handed to the builder via props. The
- * embedder maps the llmproxy's richer ModelInfo down to this minimal shape.
- */
-export interface ModelInfo {
-  id: string;
-  label: string;
-  capabilities: ModelCapability[];
-}
+// Domain Model — covers two distinct things that share a picker:
+//   1. The STATIC catalog (ModelInfo[]): the set of models the llmproxy already
+//      supports. Supplied to the editor as data (props), not declared per-workflow.
+//      A node simply stores the chosen catalog ModelID directly.
+//   2. DECLARED custom models (Model): self-hosted / custom models the
+//      llmproxy doesn't ship. These are channel-like — declared in the workflow,
+//      referenced by id from nodes, and mapped to an llmproxy provider at deploy.
+//
+// A node's `model` field is always just a ModelID string either way; static ids
+// resolve via the catalog (no mapping), custom ids via a declared Model.
+//
+// `type` is the api discriminator; new model families (e.g. future YOLO/ONNX
+// variants) register their own definition in ModelRegistry, mirroring nodes.
+
+import type { Schemas } from "../api";
+
+/** A capability a model supports (chat, embedding, vision, ...). From the api. */
+export type ModelCapability = Schemas["ModelCapability"];
+
+export type ModelType = "LLMModel";
+
+export const ALL_MODEL_TYPES: ModelType[] = ["LLMModel"];
+
+export interface Model {
+  id: string;
+  label: string;
+  type: ModelType;
+  arguments: Record<string, unknown>;
+}
+
+/**
+ * One entry in the static model catalog handed to the builder via props. The
+ * embedder maps the llmproxy's richer ModelInfo down to this minimal shape.
+ */
+export interface ModelInfo {
+  id: string;
+  label: string;
+  capabilities: ModelCapability[];
+}

package/src/model/ModelDefinition.ts

@@ -1,15 +1,15 @@
-import type { Parameter } from "../parameter";
-import type { ModelType } from "./Model";
-
-/**
- * Static, per-type metadata for a declared (custom) model variant. Mirrors
- * MemoryDefinition / NodeDefinition: one definition object per ModelType,
- * registered in ModelRegistry. `label` is a top-level instance field (edited
- * like a channel label), so it is never a parameter here.
- */
-export interface ModelDefinition {
-  type: ModelType;
-  label: string;
-  description: string;
-  parameters: Parameter[];
-}
+import type { Parameter } from "../parameter";
+import type { ModelType } from "./Model";
+
+/**
+ * Static, per-type metadata for a declared (custom) model variant. Mirrors
+ * MemoryDefinition / NodeDefinition: one definition object per ModelType,
+ * registered in ModelRegistry. `label` is a top-level instance field (edited
+ * like a channel label), so it is never a parameter here.
+ */
+export interface ModelDefinition {
+  type: ModelType;
+  label: string;
+  description: string;
+  parameters: Parameter[];
+}

package/src/model/ModelRegistry.ts

@@ -1,33 +1,33 @@
-import type { ModelType } from "./Model";
-import type { ModelDefinition } from "./ModelDefinition";
-import { LLMModelDefinition } from "./LLMModelDefinition";
-
-/**
- * Central registry for declared (custom) model variant definitions (one per
- * ModelType). Mirrors MemoryRegistry / NodeRegistry.
- */
-class ModelDefinitionRegistry {
-  private models: Map<ModelType, ModelDefinition> = new Map();
-  private initialized = false;
-
-  initialize() {
-    if (this.initialized) return;
-    this.register(LLMModelDefinition);
-    this.initialized = true;
-  }
-
-  private register(definition: ModelDefinition) {
-    this.models.set(definition.type, definition);
-  }
-
-  getAll(): ModelDefinition[] {
-    return Array.from(this.models.values());
-  }
-
-  getByType(type: ModelType): ModelDefinition | undefined {
-    return this.models.get(type);
-  }
-}
-
-export const ModelRegistry = new ModelDefinitionRegistry();
-ModelRegistry.initialize();
+import type { ModelType } from "./Model";
+import type { ModelDefinition } from "./ModelDefinition";
+import { LLMModelDefinition } from "./LLMModelDefinition";
+
+/**
+ * Central registry for declared (custom) model variant definitions (one per
+ * ModelType). Mirrors MemoryRegistry / NodeRegistry.
+ */
+class ModelDefinitionRegistry {
+  private models: Map<ModelType, ModelDefinition> = new Map();
+  private initialized = false;
+
+  initialize() {
+    if (this.initialized) return;
+    this.register(LLMModelDefinition);
+    this.initialized = true;
+  }
+
+  private register(definition: ModelDefinition) {
+    this.models.set(definition.type, definition);
+  }
+
+  getAll(): ModelDefinition[] {
+    return Array.from(this.models.values());
+  }
+
+  getByType(type: ModelType): ModelDefinition | undefined {
+    return this.models.get(type);
+  }
+}
+
+export const ModelRegistry = new ModelDefinitionRegistry();
+ModelRegistry.initialize();

package/src/model/index.ts

@@ -1,7 +1,7 @@
-export type { ModelType, Model, ModelCapability, ModelInfo } from "./Model";
-export { ALL_MODEL_TYPES } from "./Model";
-export type { ModelDefinition } from "./ModelDefinition";
-export { LLMModelDefinition } from "./LLMModelDefinition";
-export { ModelRegistry } from "./ModelRegistry";
-export { serialize, deserialize } from "./serialization";
-export type { ApiModel } from "./serialization";
+export type { ModelType, Model, ModelCapability, ModelInfo } from "./Model";
+export { ALL_MODEL_TYPES } from "./Model";
+export type { ModelDefinition } from "./ModelDefinition";
+export { LLMModelDefinition } from "./LLMModelDefinition";
+export { ModelRegistry } from "./ModelRegistry";
+export { serialize, deserialize } from "./serialization";
+export type { ApiModel } from "./serialization";