@jaex/dstsx 0.1.0

package/dist/index.js

@@ -0,0 +1,2781 @@
+// src/signatures/Field.ts
+function InputField(meta = {}) {
+  return { type: "string", ...meta };
+}
+function OutputField(meta = {}) {
+  return { type: "string", ...meta };
+}
+
+// src/signatures/Signature.ts
+var Signature = class _Signature {
+  inputs;
+  outputs;
+  instructions;
+  constructor(meta) {
+    this.inputs = meta.inputs;
+    this.outputs = meta.outputs;
+    this.instructions = meta.instructions;
+  }
+  // ---------------------------------------------------------------------------
+  // Factory helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Parse a shorthand signature string of the form:
+   *   `"field1, field2? -> out1, out2"`
+   *
+   * A trailing `?` marks the field as optional.
+   */
+  static from(shorthand, instructions) {
+    const [inputPart, outputPart] = shorthand.split("->").map((s) => s.trim());
+    if (outputPart === void 0) {
+      throw new Error(
+        `Invalid signature shorthand "${shorthand}". Expected "inputs -> outputs".`
+      );
+    }
+    const parseFields = (part) => {
+      const map = /* @__PURE__ */ new Map();
+      for (const raw of part.split(",")) {
+        const trimmed = raw.trim();
+        const isOptional = trimmed.endsWith("?");
+        const name = trimmed.replace(/\?$/, "");
+        if (name.length === 0) continue;
+        map.set(name, InputField(isOptional ? { optional: true } : {}));
+      }
+      return map;
+    };
+    const inputs = parseFields(inputPart ?? "");
+    const outputs = parseFields(outputPart);
+    for (const [key, val] of outputs) {
+      outputs.set(key, OutputField(val));
+    }
+    return new _Signature({ inputs, outputs, instructions });
+  }
+  // ---------------------------------------------------------------------------
+  // Mutation helpers (return new Signature; never mutates)
+  // ---------------------------------------------------------------------------
+  /**
+   * Return a new Signature with additional or overridden fields / instructions.
+   */
+  with(overrides) {
+    return new _Signature({
+      inputs: overrides.inputs ?? new Map(this.inputs),
+      outputs: overrides.outputs ?? new Map(this.outputs),
+      instructions: overrides.instructions ?? this.instructions
+    });
+  }
+  /**
+   * Append an extra input field and return a new Signature.
+   */
+  withInput(name, meta = {}) {
+    const inputs = new Map(this.inputs);
+    inputs.set(name, InputField(meta));
+    return this.with({ inputs });
+  }
+  /**
+   * Append an extra output field and return a new Signature.
+   */
+  withOutput(name, meta = {}) {
+    const outputs = new Map(this.outputs);
+    outputs.set(name, OutputField(meta));
+    return this.with({ outputs });
+  }
+  // ---------------------------------------------------------------------------
+  // Serialization
+  // ---------------------------------------------------------------------------
+  toJSON() {
+    return {
+      inputs: Object.fromEntries(this.inputs),
+      outputs: Object.fromEntries(this.outputs),
+      instructions: this.instructions
+    };
+  }
+  static fromJSON(json) {
+    const toMap = (obj) => {
+      if (typeof obj !== "object" || obj === null) return /* @__PURE__ */ new Map();
+      return new Map(Object.entries(obj));
+    };
+    return new _Signature({
+      inputs: toMap(json["inputs"]),
+      outputs: toMap(json["outputs"]),
+      instructions: typeof json["instructions"] === "string" ? json["instructions"] : void 0
+    });
+  }
+};
+
+// src/primitives/Example.ts
+var Example = class _Example {
+  #data;
+  constructor(data) {
+    this.#data = Object.freeze({ ...data });
+  }
+  /** Return the value for `key`, or `undefined` if absent. */
+  get(key) {
+    return this.#data[key];
+  }
+  /** Return a shallow-frozen copy of the underlying data record. */
+  toDict() {
+    return this.#data;
+  }
+  /**
+   * Return a new Example with the provided key-value pairs merged in.
+   */
+  with(overrides) {
+    return new _Example({ ...this.#data, ...overrides });
+  }
+  /**
+   * Return a new Example containing only the keys listed in `keys`.
+   */
+  inputs(keys) {
+    return new _Example(
+      Object.fromEntries(keys.filter((k) => k in this.#data).map((k) => [k, this.#data[k]]))
+    );
+  }
+  /**
+   * Return a new Example containing only the keys NOT listed in `inputKeys`
+   * (i.e. the label / output keys).
+   */
+  labels(inputKeys) {
+    return new _Example(
+      Object.fromEntries(
+        Object.entries(this.#data).filter(([k]) => !inputKeys.includes(k))
+      )
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Serialization
+  // ---------------------------------------------------------------------------
+  toJSON() {
+    return { ...this.#data };
+  }
+  static fromDict(data) {
+    return new _Example(data);
+  }
+};
+
+// src/primitives/Prediction.ts
+var Prediction = class extends Example {
+  /** All candidate completions when `n > 1` was requested. */
+  completions;
+  constructor(data, completions = []) {
+    super(data);
+    this.completions = Object.freeze([...completions]);
+  }
+  /** Typed accessor — casts the value to `T` (caller is responsible for type safety). */
+  getTyped(key) {
+    return this.get(key);
+  }
+  // ---------------------------------------------------------------------------
+  // Serialization
+  // ---------------------------------------------------------------------------
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      completions: this.completions
+    };
+  }
+};
+
+// src/primitives/majority.ts
+function majority(field = "answer") {
+  return (predictions) => {
+    if (predictions.length === 0) {
+      throw new Error("majority: empty predictions array");
+    }
+    const counts = /* @__PURE__ */ new Map();
+    for (const p of predictions) {
+      const val = JSON.stringify(p.get(field));
+      counts.set(val, (counts.get(val) ?? 0) + 1);
+    }
+    let bestKey = "";
+    let bestCount = 0;
+    for (const [k, c] of counts) {
+      if (c > bestCount) {
+        bestCount = c;
+        bestKey = k;
+      }
+    }
+    return predictions.find((p) => JSON.stringify(p.get(field)) === bestKey);
+  };
+}
+
+// src/primitives/Image.ts
+import { readFileSync } from "fs";
+var Image = class _Image {
+  url;
+  base64;
+  mimeType;
+  constructor(init) {
+    this.url = init.url;
+    this.base64 = init.base64;
+    this.mimeType = init.mimeType;
+  }
+  /** Create an Image from a URL. */
+  static fromURL(url) {
+    return new _Image({ url });
+  }
+  /** Create an Image from base64-encoded data. */
+  static fromBase64(data, mimeType = "image/jpeg") {
+    return new _Image({ base64: data, mimeType });
+  }
+  /** Create an Image by reading a local file synchronously. */
+  static fromFile(path, mimeType) {
+    const data = readFileSync(path);
+    const base64 = data.toString("base64");
+    const ext = path.split(".").pop()?.toLowerCase();
+    const detectedMime = ext === "png" ? "image/png" : ext === "gif" ? "image/gif" : ext === "webp" ? "image/webp" : "image/jpeg";
+    return new _Image({ base64, mimeType: mimeType ?? detectedMime });
+  }
+  /** Serialize to an OpenAI-compatible image_url content part. */
+  toOpenAIContentPart() {
+    if (this.url) {
+      return { type: "image_url", image_url: { url: this.url } };
+    }
+    if (this.base64 && this.mimeType) {
+      return { type: "image_url", image_url: { url: `data:${this.mimeType};base64,${this.base64}` } };
+    }
+    throw new Error("Image: no url or base64 data available");
+  }
+  /** Serialize to an Anthropic-compatible image content block. */
+  toAnthropicContentBlock() {
+    if (this.url) {
+      return { type: "image", source: { type: "url", url: this.url } };
+    }
+    if (this.base64 && this.mimeType) {
+      return { type: "image", source: { type: "base64", media_type: this.mimeType, data: this.base64 } };
+    }
+    throw new Error("Image: no url or base64 data available");
+  }
+  /** Returns a string representation (used when Image is serialized in prompts). */
+  toString() {
+    if (this.url) return `[Image: ${this.url}]`;
+    if (this.base64) return `[Image: base64 data, ${this.mimeType ?? "unknown type"}]`;
+    return "[Image]";
+  }
+};
+
+// src/lm/cache.ts
+var LRUCache = class {
+  #maxSize;
+  #ttlMs;
+  #map = /* @__PURE__ */ new Map();
+  constructor(maxSize = 512, ttlMs = 6e4 * 60) {
+    this.#maxSize = maxSize;
+    this.#ttlMs = ttlMs;
+  }
+  get(key) {
+    const entry = this.#map.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAt) {
+      this.#map.delete(key);
+      return void 0;
+    }
+    this.#map.delete(key);
+    this.#map.set(key, entry);
+    return entry.value;
+  }
+  set(key, value) {
+    if (this.#map.has(key)) this.#map.delete(key);
+    else if (this.#map.size >= this.#maxSize) {
+      const oldest = this.#map.keys().next().value;
+      if (oldest !== void 0) this.#map.delete(oldest);
+    }
+    this.#map.set(key, { value, expiresAt: Date.now() + this.#ttlMs });
+  }
+  has(key) {
+    return this.get(key) !== void 0;
+  }
+  delete(key) {
+    this.#map.delete(key);
+  }
+  clear() {
+    this.#map.clear();
+  }
+  get size() {
+    return this.#map.size;
+  }
+};
+
+// src/lm/DiskCache.ts
+import { createHash } from "crypto";
+import {
+  readFileSync as readFileSync2,
+  writeFileSync,
+  readdirSync,
+  unlinkSync,
+  mkdirSync,
+  statSync
+} from "fs";
+import { join } from "path";
+var DiskCache = class {
+  #cacheDir;
+  #maxSize;
+  #ttlMs;
+  constructor(cacheDir, maxSize = 500, ttlMs) {
+    this.#cacheDir = cacheDir;
+    this.#maxSize = maxSize;
+    this.#ttlMs = ttlMs;
+    mkdirSync(cacheDir, { recursive: true });
+  }
+  get(key) {
+    const path = this.#pathFor(key);
+    try {
+      const raw = readFileSync2(path, "utf8");
+      const entry = JSON.parse(raw);
+      if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+        unlinkSync(path);
+        return void 0;
+      }
+      return entry.value;
+    } catch {
+      return void 0;
+    }
+  }
+  set(key, value) {
+    this.#evictIfNeeded();
+    const entry = {
+      key,
+      value,
+      expiresAt: this.#ttlMs != null ? Date.now() + this.#ttlMs : null
+    };
+    writeFileSync(this.#pathFor(key), JSON.stringify(entry), "utf8");
+  }
+  clear() {
+    try {
+      for (const file of readdirSync(this.#cacheDir)) {
+        if (file.endsWith(".json")) {
+          try {
+            unlinkSync(join(this.#cacheDir, file));
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  #pathFor(key) {
+    const hash = createHash("sha256").update(key).digest("hex").slice(0, 16);
+    return join(this.#cacheDir, `${hash}.json`);
+  }
+  #evictIfNeeded() {
+    let files;
+    try {
+      files = readdirSync(this.#cacheDir).filter((f) => f.endsWith(".json")).map((f) => {
+        const p = join(this.#cacheDir, f);
+        try {
+          return { name: f, mtime: statSync(p).mtimeMs };
+        } catch {
+          return { name: f, mtime: 0 };
+        }
+      });
+    } catch {
+      return;
+    }
+    if (files.length < this.#maxSize) return;
+    const sorted = files.sort((a, b) => a.mtime - b.mtime);
+    const toDelete = sorted.slice(0, files.length - this.#maxSize + 1);
+    for (const f of toDelete) {
+      try {
+        unlinkSync(join(this.#cacheDir, f.name));
+      } catch {
+      }
+    }
+  }
+};
+
+// src/lm/LM.ts
+var LM = class {
+  /** Human-readable name / identifier for this model instance. */
+  model;
+  #cache;
+  #diskCache;
+  #requestCount = 0;
+  #tokenUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+  constructor(model, cacheOptions = {}) {
+    this.model = model;
+    this.#cache = new LRUCache(cacheOptions.maxSize, cacheOptions.ttlMs);
+    this.#diskCache = cacheOptions.cacheDir !== void 0 ? new DiskCache(cacheOptions.cacheDir, cacheOptions.maxSize, cacheOptions.ttlMs) : void 0;
+  }
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+  /**
+   * Call the language model with either a plain string prompt or a list of
+   * chat messages.
+   */
+  async call(prompt, config = {}) {
+    const cacheKey = config.cacheKey ?? this.#buildCacheKey(prompt, config);
+    const cached = this.#cache.get(cacheKey);
+    if (cached) return cached;
+    if (this.#diskCache) {
+      const diskCached = this.#diskCache.get(cacheKey);
+      if (diskCached) {
+        this.#cache.set(cacheKey, diskCached);
+        return diskCached;
+      }
+    }
+    const response = await this._call(prompt, config);
+    this.#cache.set(cacheKey, response);
+    if (this.#diskCache) {
+      this.#diskCache.set(cacheKey, response);
+    }
+    this.#requestCount += 1;
+    if (response.usage) {
+      this.#tokenUsage.promptTokens += response.usage.promptTokens;
+      this.#tokenUsage.completionTokens += response.usage.completionTokens;
+      this.#tokenUsage.totalTokens += response.usage.totalTokens;
+    }
+    return response;
+  }
+  /** Total number of (non-cached) API calls made. */
+  get requestCount() {
+    return this.#requestCount;
+  }
+  /** Accumulated token usage across all (non-cached) calls. */
+  get tokenUsage() {
+    return { ...this.#tokenUsage };
+  }
+  /** Clear the in-memory response cache. */
+  clearCache() {
+    this.#cache.clear();
+  }
+  /**
+   * Stream the language model response token by token.
+   *
+   * Returns an `AsyncIterable<StreamChunk>`. The last chunk has `done: true`.
+   * Subclasses override this to provide real streaming; the base implementation
+   * falls back to calling {@link LM.call} and yielding the full response as a
+   * single chunk.
+   */
+  async *stream(prompt, config = {}) {
+    const response = await this.call(prompt, config);
+    yield { delta: response.text, done: true, raw: response.raw };
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  #buildCacheKey(prompt, config) {
+    const promptStr = typeof prompt === "string" ? prompt : JSON.stringify(prompt);
+    const configStr = JSON.stringify({
+      model: config.model ?? this.model,
+      temperature: config.temperature,
+      maxTokens: config.maxTokens,
+      stop: config.stop,
+      n: config.n
+    });
+    return `${promptStr}|||${configStr}`;
+  }
+};
+
+// src/lm/adapters/OpenAI.ts
+var OpenAI = class extends LM {
+  #options;
+  constructor(options = {}) {
+    super(options.model ?? "gpt-4o");
+    this.#options = options;
+  }
+  async _call(prompt, config) {
+    const { default: OpenAIClient } = await import("openai").catch(() => {
+      throw new Error(
+        "The `openai` package is required for the OpenAI adapter.\nInstall it with: npm install openai"
+      );
+    });
+    const client = new OpenAIClient({
+      apiKey: this.#options.apiKey ?? process.env["OPENAI_API_KEY"],
+      baseURL: this.#options.baseURL,
+      maxRetries: this.#options.maxRetries ?? 3
+    });
+    const messages = typeof prompt === "string" ? [{ role: "user", content: prompt }] : prompt;
+    const response = await client.chat.completions.create({
+      model: config.model ?? this.model,
+      messages,
+      temperature: config.temperature,
+      max_tokens: config.maxTokens,
+      stop: config.stop,
+      n: config.n ?? 1,
+      ...config.extra ?? {}
+    });
+    const texts = (response.choices ?? []).map(
+      (c) => c.message?.content ?? ""
+    );
+    return {
+      text: texts[0] ?? "",
+      texts,
+      usage: response.usage ? {
+        promptTokens: response.usage.prompt_tokens,
+        completionTokens: response.usage.completion_tokens,
+        totalTokens: response.usage.total_tokens
+      } : null,
+      raw: response
+    };
+  }
+  async *stream(prompt, config = {}) {
+    const { default: OpenAIClient } = await import("openai").catch(() => {
+      throw new Error(
+        "The `openai` package is required for the OpenAI adapter.\nInstall it with: npm install openai"
+      );
+    });
+    const client = new OpenAIClient({
+      apiKey: this.#options.apiKey ?? process.env["OPENAI_API_KEY"],
+      baseURL: this.#options.baseURL,
+      maxRetries: this.#options.maxRetries ?? 3
+    });
+    const messages = typeof prompt === "string" ? [{ role: "user", content: prompt }] : prompt;
+    const stream = await client.chat.completions.create({
+      model: config.model ?? this.model,
+      messages,
+      temperature: config.temperature,
+      max_tokens: config.maxTokens,
+      stop: config.stop,
+      stream: true,
+      ...config.extra ?? {}
+    });
+    for await (const chunk of stream) {
+      const c = chunk.choices?.[0];
+      const delta = c?.delta?.content ?? "";
+      const done = c?.finish_reason != null;
+      yield { delta, done, raw: chunk };
+      if (done) break;
+    }
+  }
+};
+
+// src/lm/adapters/Anthropic.ts
+var Anthropic = class extends LM {
+  #options;
+  constructor(options = {}) {
+    super(options.model ?? "claude-3-5-sonnet-20241022");
+    this.#options = options;
+  }
+  async _call(prompt, config) {
+    const { default: Anthropic2 } = await import("@anthropic-ai/sdk").catch(() => {
+      throw new Error(
+        "The `@anthropic-ai/sdk` package is required for the Anthropic adapter.\nInstall it with: npm install @anthropic-ai/sdk"
+      );
+    });
+    const client = new Anthropic2({
+      apiKey: this.#options.apiKey ?? process.env["ANTHROPIC_API_KEY"],
+      maxRetries: this.#options.maxRetries ?? 3
+    });
+    const msgs = typeof prompt === "string" ? [{ role: "user", content: prompt }] : prompt;
+    const systemMsg = msgs.find((m) => m.role === "system");
+    const userMsgs = msgs.filter((m) => m.role !== "system");
+    const response = await client.messages.create({
+      model: config.model ?? this.model,
+      max_tokens: config.maxTokens ?? 1024,
+      system: systemMsg?.content,
+      messages: userMsgs.map((m) => ({ role: m.role, content: m.content })),
+      temperature: config.temperature,
+      ...config.extra ?? {}
+    });
+    const text = response.content.filter((b) => b.type === "text").map((b) => b.text ?? "").join("") ?? "";
+    return {
+      text,
+      texts: [text],
+      usage: response.usage ? {
+        promptTokens: response.usage.input_tokens,
+        completionTokens: response.usage.output_tokens,
+        totalTokens: response.usage.input_tokens + response.usage.output_tokens
+      } : null,
+      raw: response
+    };
+  }
+  async *stream(prompt, config = {}) {
+    const { default: Anthropic2 } = await import("@anthropic-ai/sdk").catch(() => {
+      throw new Error(
+        "The `@anthropic-ai/sdk` package is required for the Anthropic adapter.\nInstall it with: npm install @anthropic-ai/sdk"
+      );
+    });
+    const client = new Anthropic2({
+      apiKey: this.#options.apiKey ?? process.env["ANTHROPIC_API_KEY"],
+      maxRetries: this.#options.maxRetries ?? 3
+    });
+    const msgs = typeof prompt === "string" ? [{ role: "user", content: prompt }] : prompt;
+    const systemMsg = msgs.find((m) => m.role === "system");
+    const userMsgs = msgs.filter((m) => m.role !== "system");
+    const stream = client.messages.stream({
+      model: config.model ?? this.model,
+      max_tokens: config.maxTokens ?? 1024,
+      system: systemMsg?.content,
+      messages: userMsgs.map((m) => ({ role: m.role, content: m.content })),
+      ...config.extra ?? {}
+    });
+    for await (const event of stream) {
+      const e = event;
+      if (e.type === "content_block_delta" && e.delta?.type === "text_delta") {
+        yield { delta: e.delta.text ?? "", done: false, raw: event };
+      } else if (e.type === "message_stop") {
+        yield { delta: "", done: true, raw: event };
+        break;
+      }
+    }
+  }
+};
+
+// src/lm/adapters/Cohere.ts
+var Cohere = class extends LM {
+  #options;
+  constructor(options = {}) {
+    super(options.model ?? "command-r-plus");
+    this.#options = options;
+  }
+  async _call(prompt, config) {
+    const { CohereClient } = await import("cohere-ai").catch(() => {
+      throw new Error(
+        "The `cohere-ai` package is required for the Cohere adapter.\nInstall it with: npm install cohere-ai"
+      );
+    });
+    const client = new CohereClient({
+      token: this.#options.apiKey ?? process.env["COHERE_API_KEY"]
+    });
+    const text = typeof prompt === "string" ? prompt : this.#messagesToText(prompt);
+    const response = await client.chat({
+      model: config.model ?? this.model,
+      message: text,
+      temperature: config.temperature,
+      maxTokens: config.maxTokens,
+      ...config.extra ?? {}
+    });
+    const responseText = response.text ?? "";
+    return {
+      text: responseText,
+      texts: [responseText],
+      usage: response.meta?.tokens ? {
+        promptTokens: response.meta.tokens.inputTokens ?? 0,
+        completionTokens: response.meta.tokens.outputTokens ?? 0,
+        totalTokens: (response.meta.tokens.inputTokens ?? 0) + (response.meta.tokens.outputTokens ?? 0)
+      } : null,
+      raw: response
+    };
+  }
+  #messagesToText(messages) {
+    return messages.map((m) => `${m.role}: ${m.content}`).join("\n");
+  }
+};
+
+// src/lm/adapters/GoogleAI.ts
+var GoogleAI = class extends LM {
+  #options;
+  constructor(options = {}) {
+    super(options.model ?? "gemini-1.5-pro");
+    this.#options = options;
+  }
+  async _call(prompt, config) {
+    const { GoogleGenerativeAI } = await import("@google/generative-ai").catch(() => {
+      throw new Error(
+        "The `@google/generative-ai` package is required for the GoogleAI adapter.\nInstall it with: npm install @google/generative-ai"
+      );
+    });
+    const client = new GoogleGenerativeAI(
+      this.#options.apiKey ?? process.env["GOOGLE_API_KEY"] ?? ""
+    );
+    const genModel = client.getGenerativeModel({ model: config.model ?? this.model });
+    const text = typeof prompt === "string" ? prompt : this.#messagesToText(prompt);
+    const result = await genModel.generateContent({
+      contents: [{ role: "user", parts: [{ text }] }],
+      generationConfig: {
+        temperature: config.temperature,
+        maxOutputTokens: config.maxTokens,
+        stopSequences: config.stop,
+        candidateCount: config.n ?? 1
+      }
+    });
+    const texts = (result.response.candidates ?? []).map(
+      (c) => c.content?.parts?.map((p) => p.text ?? "").join("") ?? ""
+    );
+    return {
+      text: texts[0] ?? "",
+      texts,
+      usage: null,
+      raw: result
+    };
+  }
+  #messagesToText(messages) {
+    return messages.map((m) => `${m.role}: ${m.content}`).join("\n");
+  }
+};
+
+// src/lm/adapters/Ollama.ts
+var Ollama = class extends LM {
+  #baseURL;
+  constructor(options = {}) {
+    super(options.model ?? "llama3");
+    this.#baseURL = options.baseURL ?? "http://localhost:11434";
+  }
+  async _call(prompt, config) {
+    const messages = typeof prompt === "string" ? [{ role: "user", content: prompt }] : prompt;
+    const response = await fetch(`${this.#baseURL}/api/chat`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: config.model ?? this.model,
+        messages,
+        stream: false,
+        options: {
+          temperature: config.temperature,
+          num_predict: config.maxTokens,
+          stop: config.stop,
+          ...config.extra ?? {}
+        }
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Ollama request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    const text = data.message?.content ?? "";
+    return {
+      text,
+      texts: [text],
+      usage: data.prompt_eval_count != null ? {
+        promptTokens: data.prompt_eval_count,
+        completionTokens: data.eval_count ?? 0,
+        totalTokens: (data.prompt_eval_count ?? 0) + (data.eval_count ?? 0)
+      } : null,
+      raw: data
+    };
+  }
+};
+
+// src/lm/adapters/LMStudio.ts
+var LMStudio = class extends LM {
+  #baseURL;
+  constructor(options = {}) {
+    super(options.model ?? "local-model");
+    this.#baseURL = options.baseURL ?? "http://localhost:1234/v1";
+  }
+  async _call(prompt, config) {
+    const messages = typeof prompt === "string" ? [{ role: "user", content: prompt }] : prompt;
+    const response = await fetch(`${this.#baseURL}/chat/completions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: config.model ?? this.model,
+        messages,
+        temperature: config.temperature,
+        max_tokens: config.maxTokens,
+        stop: config.stop,
+        n: config.n ?? 1,
+        ...config.extra ?? {}
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`LMStudio request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    const texts = (data.choices ?? []).map((c) => c.message?.content ?? "");
+    return {
+      text: texts[0] ?? "",
+      texts,
+      usage: data.usage ? {
+        promptTokens: data.usage.prompt_tokens,
+        completionTokens: data.usage.completion_tokens,
+        totalTokens: data.usage.total_tokens
+      } : null,
+      raw: data
+    };
+  }
+};
+
+// src/lm/adapters/HuggingFace.ts
+var HuggingFace = class extends LM {
+  #options;
+  constructor(options = {}) {
+    super(options.model ?? "mistralai/Mistral-7B-Instruct-v0.3");
+    this.#options = options;
+  }
+  async _call(prompt, config) {
+    const apiKey = this.#options.apiKey ?? process.env["HF_API_KEY"];
+    const model = config.model ?? this.model;
+    const url = this.#options.endpointURL ?? `https://api-inference.huggingface.co/models/${model}`;
+    const inputText = typeof prompt === "string" ? prompt : this.#messagesToText(prompt);
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+      },
+      body: JSON.stringify({
+        inputs: inputText,
+        parameters: {
+          temperature: config.temperature,
+          max_new_tokens: config.maxTokens,
+          stop: config.stop,
+          ...config.extra ?? {}
+        }
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`HuggingFace request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    const generated = Array.isArray(data) ? data[0]?.generated_text ?? "" : data.generated_text ?? "";
+    return {
+      text: generated,
+      texts: [generated],
+      usage: null,
+      raw: data
+    };
+  }
+  #messagesToText(messages) {
+    return messages.map((m) => `${m.role}: ${m.content}`).join("\n");
+  }
+};
+
+// src/lm/adapters/MockLM.ts
+var MockLM = class extends LM {
+  #responses;
+  #defaultResponse;
+  constructor(responses = {}, defaultResponse) {
+    super("mock");
+    this.#responses = new Map(Object.entries(responses));
+    this.#defaultResponse = defaultResponse;
+  }
+  async _call(prompt, config) {
+    const key = typeof prompt === "string" ? prompt : JSON.stringify(prompt);
+    const text = this.#responses.get(key) ?? this.#defaultResponse ?? (() => {
+      throw new Error(`MockLM: no response configured for prompt: "${key}"`);
+    })();
+    const n = config.n ?? 1;
+    return {
+      text,
+      texts: Array.from({ length: n }, () => text),
+      usage: null,
+      raw: null
+    };
+  }
+  /** Register (or overwrite) a prompt → response mapping at runtime. */
+  addResponse(prompt, response) {
+    this.#responses.set(prompt, response);
+  }
+};
+
+// src/modules/Module.ts
+var Module = class _Module {
+  /**
+   * Recursively discover all {@link Predict} sub-modules by walking the own
+   * enumerable properties of this instance.
+   */
+  namedPredictors() {
+    const results = [];
+    for (const [key, value] of Object.entries(this)) {
+      if (value instanceof _Module) {
+        results.push([key, value]);
+        results.push(...value.namedPredictors().map(([k, v]) => [`${key}.${k}`, v]));
+      }
+    }
+    return results;
+  }
+  /**
+   * Serialize the module's learnable parameters (e.g. `Predict.demos`) to a
+   * plain JSON-compatible object.
+   */
+  dump() {
+    const state = {};
+    for (const [name, predictor] of this.namedPredictors()) {
+      state[name] = predictor.dump();
+    }
+    return state;
+  }
+  /**
+   * Restore learnable parameters from a plain object previously produced by
+   * {@link Module.dump}.
+   */
+  load(state) {
+    for (const [name, predictor] of this.namedPredictors()) {
+      const sub = state[name];
+      if (sub && typeof sub === "object") {
+        predictor.load(sub);
+      }
+    }
+  }
+  /**
+   * Create a deep clone of this module.
+   *
+   * Returns a new module with the same prototype.  All sub-{@link Module}
+   * properties are recursively cloned so that mutating the clone's learnable
+   * parameters (e.g. `Predict.demos`) does **not** affect the original.
+   * Array properties are shallow-copied (their elements are not cloned).
+   * All other properties are copied by reference.
+   */
+  clone() {
+    const cloned = Object.create(Object.getPrototypeOf(this));
+    for (const key of Object.keys(this)) {
+      const value = this[key];
+      if (value instanceof _Module) {
+        cloned[key] = value.clone();
+      } else if (Array.isArray(value)) {
+        cloned[key] = [...value];
+      } else {
+        cloned[key] = value;
+      }
+    }
+    return cloned;
+  }
+};
+
+// src/settings/Settings.ts
+import { AsyncLocalStorage } from "async_hooks";
+var contextStore = new AsyncLocalStorage();
+var Settings = class {
+  #global = {};
+  // ---------------------------------------------------------------------------
+  // Effective settings: async-context overrides take precedence over globals.
+  // ---------------------------------------------------------------------------
+  get #current() {
+    const ctx = contextStore.getStore();
+    return ctx !== void 0 ? { ...this.#global, ...ctx } : this.#global;
+  }
+  // ---------------------------------------------------------------------------
+  // Accessors
+  // ---------------------------------------------------------------------------
+  get lm() {
+    return this.#current.lm;
+  }
+  get rm() {
+    return this.#current.rm;
+  }
+  get lmConfig() {
+    return this.#current.lmConfig;
+  }
+  get logLevel() {
+    return this.#current.logLevel ?? "warn";
+  }
+  get cacheDir() {
+    return this.#current.cacheDir;
+  }
+  // ---------------------------------------------------------------------------
+  // Mutation
+  // ---------------------------------------------------------------------------
+  /**
+   * Merge `options` into the global settings.  Existing keys are overwritten;
+   * omitted keys are unchanged.  This does NOT affect currently running
+   * {@link Settings.context} scopes.
+   */
+  configure(options) {
+    this.#global = { ...this.#global, ...options };
+  }
+  /**
+   * Reset all global settings to their defaults.
+   */
+  reset() {
+    this.#global = {};
+  }
+  /**
+   * Return a deep-frozen snapshot of the currently effective settings
+   * (respects any active async-context overrides).
+   */
+  inspect() {
+    return Object.freeze({ ...this.#current });
+  }
+  /**
+   * Run `fn` inside an async-context-local settings scope.
+   *
+   * The `overrides` are merged on top of the current global settings and
+   * stored in an `AsyncLocalStorage` context.  Concurrent calls each get
+   * their own isolated snapshot — they never overwrite each other's settings.
+   *
+   * @example
+   * ```ts
+   * // In an Express/Fastify handler:
+   * await settings.context({ lm: perRequestLM }, () => program.forward(inputs));
+   * ```
+   */
+  async context(overrides, fn) {
+    const merged = { ...this.#global, ...overrides };
+    return contextStore.run(merged, fn);
+  }
+};
+var settings = new Settings();
+
+// src/modules/Predict.ts
+var Predict = class extends Module {
+  signature;
+  /** Few-shot demonstration examples (learnable parameter). */
+  demos;
+  /** System instruction override (learnable parameter). */
+  instructions;
+  constructor(signature) {
+    super();
+    this.signature = typeof signature === "string" ? Signature.from(signature) : signature;
+    this.demos = [];
+    this.instructions = this.signature.instructions;
+  }
+  // ---------------------------------------------------------------------------
+  // Forward pass
+  // ---------------------------------------------------------------------------
+  async forward(inputs) {
+    const lm = settings.lm;
+    if (!lm) {
+      throw new Error(
+        "No LM configured. Call settings.configure({ lm }) before using Predict."
+      );
+    }
+    const prompt = this.#buildPrompt(inputs);
+    const config = settings.lmConfig ?? {};
+    const response = await lm.call(prompt, config);
+    const outputs = this.#parseCompletion(response.text);
+    const completions = response.texts.map((t) => this.#parseCompletion(t));
+    return new Prediction(outputs, completions);
+  }
+  /**
+   * Stream the LM response token by token.
+   * Returns an `AsyncGenerator<StreamChunk>`.
+   */
+  async *stream(inputs) {
+    const lm = settings.lm;
+    if (!lm) throw new Error("No LM configured. Call settings.configure({ lm }) before using Predict.");
+    const prompt = this.#buildPrompt(inputs);
+    const config = settings.lmConfig ?? {};
+    yield* lm.stream(prompt, config);
+  }
+  // ---------------------------------------------------------------------------
+  // Serialization
+  // ---------------------------------------------------------------------------
+  dump() {
+    return {
+      signature: this.signature.toJSON(),
+      demos: this.demos.map((d) => d.toJSON()),
+      instructions: this.instructions
+    };
+  }
+  load(state) {
+    if (Array.isArray(state["demos"])) {
+      this.demos = state["demos"].map(
+        (d) => new Example(d)
+      );
+    }
+    if (typeof state["instructions"] === "string") {
+      this.instructions = state["instructions"];
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  #buildPrompt(inputs) {
+    const lines = [];
+    if (this.instructions) {
+      lines.push(this.instructions, "");
+    }
+    if (this.demos.length > 0) {
+      for (const demo of this.demos) {
+        lines.push(this.#formatExample(demo.toDict()));
+        lines.push("---");
+      }
+    }
+    lines.push(this.#formatInputs(inputs));
+    for (const [name] of this.signature.outputs) {
+      lines.push(`${name}:`);
+    }
+    return lines.join("\n");
+  }
+  #formatExample(data) {
+    return [...this.signature.inputs, ...this.signature.outputs].map(([name]) => `${name}: ${String(data[name] ?? "")}`).join("\n");
+  }
+  #formatInputs(inputs) {
+    return [...this.signature.inputs].map(([name]) => `${name}: ${String(inputs[name] ?? "")}`).join("\n");
+  }
+  /**
+   * Parse a raw completion string into a map of field name → value.
+   *
+   * Looks for `fieldName: <value>` lines in the completion.
+   */
+  #parseCompletion(text) {
+    const result = {};
+    const outputKeys = [...this.signature.outputs.keys()];
+    for (const key of outputKeys) {
+      const regex = new RegExp(`^${key}:\\s*(.*)$`, "mi");
+      const match = regex.exec(text);
+      if (match) {
+        result[key] = (match[1] ?? "").trim();
+      }
+    }
+    if (outputKeys.length === 1 && !(outputKeys[0] in result)) {
+      result[outputKeys[0]] = text.trim();
+    }
+    return result;
+  }
+};
+
+// src/modules/ChainOfThought.ts
+var ChainOfThought = class extends Predict {
+  constructor(signature, options = {}) {
+    const base = typeof signature === "string" ? Signature.from(signature) : signature;
+    const rationaleSig = base.withOutput("rationale", {
+      description: options.rationaleDescription ?? "Think step by step to reason through the problem",
+      prefix: "Reasoning:"
+    });
+    const reordered = new Signature({
+      inputs: rationaleSig.inputs,
+      outputs: new Map([
+        ["rationale", rationaleSig.outputs.get("rationale")],
+        ...rationaleSig.outputs
+      ]),
+      instructions: rationaleSig.instructions
+    });
+    super(reordered);
+  }
+  /** Returns the answer without the internal rationale. */
+  async forward(inputs) {
+    const prediction = await super.forward(inputs);
+    const { rationale: _rationale, ...rest } = prediction.toDict();
+    void _rationale;
+    return new Prediction(rest, prediction.completions);
+  }
+};
+
+// src/modules/ChainOfThoughtWithHint.ts
+var ChainOfThoughtWithHint = class extends ChainOfThought {
+  constructor(signature, options = {}) {
+    const base = typeof signature === "string" ? signature : signature;
+    super(base, options);
+    const extendedSig = this.signature.withInput("hint", {
+      description: "An optional hint to guide the reasoning",
+      optional: true
+    });
+    Object.assign(this, { signature: extendedSig });
+  }
+  async forward(inputs) {
+    return super.forward(inputs);
+  }
+};
+
+// src/modules/MultiChainComparison.ts
+var MultiChainComparison = class extends Module {
+  M;
+  #cot;
+  #aggregator;
+  constructor(signature, M = 3) {
+    super();
+    this.M = M;
+    this.#cot = new ChainOfThought(signature);
+    this.#aggregator = new Predict(
+      "completions -> answer"
+    );
+  }
+  async forward(inputs) {
+    const completions = [];
+    for (let i = 0; i < this.M; i++) {
+      const result = await this.#cot.forward(inputs);
+      const outputKey = [...this.#cot.signature.outputs.keys()].find((k) => k !== "rationale");
+      completions.push(String(result.get(outputKey ?? "answer") ?? ""));
+    }
+    return this.#aggregator.forward({
+      completions: completions.map((c, i) => `Option ${i + 1}: ${c}`).join("\n")
+    });
+  }
+};
+
+// src/modules/ReAct.ts
+var ReAct = class extends Module {
+  tools;
+  maxIter;
+  #predictor;
+  constructor(signature, tools, maxIter = 5) {
+    super();
+    this.tools = new Map(tools.map((t) => [t.name, t]));
+    this.maxIter = maxIter;
+    const toolDescriptions = tools.map((t) => `${t.name}: ${t.description}`).join("\n");
+    const base = typeof signature === "string" ? signature : signature;
+    const instructions = `You are an agent. Use the following tools:
+${toolDescriptions}
+
+Respond in the format:
+Thought: <reasoning>
+Action: <tool>[<args>]
+Observation: <result>
+...
+Finish[<answer>]`;
+    this.#predictor = new Predict(
+      typeof base === "string" ? `${base}` : base
+    );
+    this.#predictor.instructions = instructions;
+  }
+  async forward(inputs) {
+    const trajectory = [];
+    let finalAnswer = "";
+    for (let i = 0; i < this.maxIter; i++) {
+      const augmented = {
+        ...inputs,
+        trajectory: trajectory.join("\n")
+      };
+      const result = await this.#predictor.forward(augmented);
+      const text = String(result.get([...this.#predictor.signature.outputs.keys()][0] ?? "") ?? "");
+      trajectory.push(text);
+      const finishMatch = /Finish\[(.+)\]/i.exec(text);
+      if (finishMatch) {
+        finalAnswer = finishMatch[1] ?? "";
+        break;
+      }
+      const actionMatch = /Action:\s*(\w+)\[(.+?)\]/i.exec(text);
+      if (actionMatch) {
+        const toolName = actionMatch[1] ?? "";
+        const toolArgs = actionMatch[2] ?? "";
+        const tool = this.tools.get(toolName);
+        const observation = tool ? await tool.fn(toolArgs) : `Tool "${toolName}" not found.`;
+        trajectory.push(`Observation: ${observation}`);
+      }
+    }
+    const outputKey = [...this.#predictor.signature.outputs.keys()][0] ?? "answer";
+    return new Prediction({
+      [outputKey]: finalAnswer || trajectory.at(-1) || "",
+      trajectory: trajectory.join("\n")
+    });
+  }
+};
+
+// src/modules/ProgramOfThought.ts
+var ProgramOfThought = class extends Module {
+  maxAttempts;
+  /** Wall-clock timeout (ms) for each code execution attempt. */
+  timeoutMs;
+  sandbox;
+  #codeGenerator;
+  #corrector;
+  #outputKey;
+  constructor(signature, maxAttempts = 3, timeoutMs = 5e3, sandbox = "function") {
+    super();
+    this.maxAttempts = maxAttempts;
+    this.timeoutMs = timeoutMs;
+    this.sandbox = sandbox;
+    const base = typeof signature === "string" ? Signature.from(signature) : signature;
+    const genSig = new Signature({
+      inputs: new Map([
+        ...base.inputs,
+        [
+          "instructions",
+          InputField({
+            description: "Task instructions for code generation",
+            optional: true
+          })
+        ]
+      ]),
+      outputs: /* @__PURE__ */ new Map([
+        [
+          "code",
+          OutputField({
+            description: "JavaScript code that computes and returns the answer via a `return` statement"
+          })
+        ]
+      ]),
+      instructions: base.instructions
+    });
+    this.#codeGenerator = new Predict(genSig);
+    this.#corrector = new Predict("code, error -> fixed_code");
+    this.#outputKey = [...base.outputs.keys()][0] ?? "answer";
+  }
+  async forward(inputs) {
+    let code = "";
+    let result;
+    let lastError = "";
+    for (let attempt = 0; attempt < this.maxAttempts; attempt++) {
+      const genInputs = attempt === 0 ? {
+        ...inputs,
+        instructions: "Write JavaScript code to compute the answer. Use a `return` statement for the final value."
+      } : { code, error: lastError };
+      const generated = attempt === 0 ? await this.#codeGenerator.forward(genInputs) : await this.#corrector.forward(genInputs);
+      code = String(generated.get("code") ?? generated.get("fixed_code") ?? "");
+      try {
+        if (this.sandbox === "worker") {
+          result = await this.#executeInWorker(code, this.timeoutMs);
+        } else if (this.sandbox === "none") {
+          const fn = new Function(`return (async () => { ${code} })()`);
+          result = await fn();
+        } else {
+          const fn = new Function(`return (async () => { ${code} })()`);
+          result = await this.#executeWithTimeout(fn(), this.timeoutMs);
+        }
+        break;
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+        result = void 0;
+      }
+    }
+    return new Prediction({
+      [this.#outputKey]: result !== void 0 ? String(result) : "",
+      code
+    });
+  }
+  async #executeInWorker(code, timeoutMs) {
+    const { Worker } = await import("worker_threads");
+    const WORKER_CODE = `
+const { workerData, parentPort } = require('node:worker_threads');
+const { code } = workerData;
+(async () => {
+  try {
+    const fn = new Function('return (async () => { ' + code + ' })()');
+    const result = await fn();
+    parentPort.postMessage({ result: String(result ?? '') });
+  } catch (err) {
+    parentPort.postMessage({ error: err.message ?? String(err) });
+  }
+})();
+`;
+    return new Promise((resolve, reject) => {
+      const worker = new Worker(WORKER_CODE, {
+        eval: true,
+        workerData: { code }
+      });
+      const timer = setTimeout(() => {
+        void worker.terminate();
+        reject(new Error("ProgramOfThought: worker execution timed out"));
+      }, timeoutMs);
+      worker.on("message", (msg) => {
+        clearTimeout(timer);
+        void worker.terminate();
+        if (msg.error) reject(new Error(msg.error));
+        else resolve(msg.result ?? "");
+      });
+      worker.on("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+  }
+  /**
+   * Race `promise` against a wall-clock timer.
+   * The underlying async work is not cancelled on timeout (no true abort), but
+   * the returned Promise rejects promptly.
+   */
+  #executeWithTimeout(promise, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(
+          new Error(
+            `ProgramOfThought: code execution timed out after ${timeoutMs}ms`
+          )
+        ),
+        timeoutMs
+      );
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+};
+
+// src/modules/Retrieve.ts
+var Retrieve = class extends Module {
+  k;
+  constructor(k = 3) {
+    super();
+    this.k = k;
+  }
+  async forward(query) {
+    const rm = settings.rm;
+    if (!rm) {
+      throw new Error(
+        "No retriever configured. Call settings.configure({ rm }) before using Retrieve."
+      );
+    }
+    const passages = await rm.retrieve(query, this.k);
+    return new Prediction({ passages, query });
+  }
+};
+
+// src/assertions/Assert.ts
+var AssertionError = class extends Error {
+  constructor(message = "Assertion failed") {
+    super(message);
+    this.name = "AssertionError";
+  }
+};
+function Assert(condition, message) {
+  if (!condition) {
+    throw new AssertionError(message ?? "Assertion failed");
+  }
+}
+
+// src/assertions/Suggest.ts
+function Suggest(condition, message) {
+  if (!condition) {
+    console.warn(`[DSTsx Suggest] ${message ?? "Condition not met"}`);
+  }
+}
+
+// src/modules/Retry.ts
+var Retry = class extends Module {
+  #inner;
+  maxAttempts;
+  constructor(inner, maxAttempts = 3) {
+    super();
+    this.#inner = inner;
+    this.maxAttempts = maxAttempts;
+  }
+  async forward(...args) {
+    let lastError;
+    for (let attempt = 0; attempt < this.maxAttempts; attempt++) {
+      try {
+        return await this.#inner.forward(...args);
+      } catch (err) {
+        if (err instanceof AssertionError) {
+          lastError = err;
+          const firstArg = args[0];
+          if (firstArg && typeof firstArg === "object") {
+            firstArg["feedback"] = err.message;
+          }
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw lastError ?? new Error("Retry: all attempts exhausted");
+  }
+};
+
+// src/modules/BestOfN.ts
+var BestOfN = class extends Module {
+  N;
+  #inner;
+  #reduce;
+  constructor(inner, N = 3, reduceFunc) {
+    super();
+    this.#inner = inner;
+    this.N = N;
+    this.#reduce = reduceFunc ?? ((preds) => preds[0] ?? new Prediction({}));
+  }
+  async forward(...args) {
+    const results = await Promise.all(
+      Array.from(
+        { length: this.N },
+        () => this.#inner.forward(...args)
+      )
+    );
+    return this.#reduce(results);
+  }
+};
+
+// src/modules/Ensemble.ts
+var Ensemble = class extends Module {
+  #modules;
+  #reduce;
+  constructor(modules, reduceFunc) {
+    super();
+    this.#modules = modules;
+    this.#reduce = reduceFunc ?? ((preds) => preds[0] ?? new Prediction({}));
+  }
+  async forward(...args) {
+    const results = await Promise.all(
+      this.#modules.map(
+        (m) => m.forward(...args)
+      )
+    );
+    return this.#reduce(results);
+  }
+};
+
+// src/modules/TypedPredictor.ts
+var TypedPrediction = class extends Prediction {
+  typed;
+  constructor(data, typed, completions = []) {
+    super(data, completions);
+    this.typed = typed;
+  }
+};
+var TypedPredictor = class _TypedPredictor extends Predict {
+  #schema;
+  #maxRetries;
+  constructor(signature, schema, options = {}) {
+    super(signature);
+    this.#schema = schema;
+    this.#maxRetries = options.maxRetries ?? 3;
+  }
+  async forward(inputs) {
+    const origInstructions = this.instructions;
+    const jsonSuffix = "\n\nRespond with a JSON object matching the output schema.";
+    this.instructions = (origInstructions ?? "") + jsonSuffix;
+    let lastError;
+    try {
+      for (let attempt = 0; attempt <= this.#maxRetries; attempt++) {
+        try {
+          const prediction = await super.forward(inputs);
+          const dict = prediction.toDict();
+          let parsed;
+          let found = false;
+          let lastParseError;
+          for (const key of this.signature.outputs.keys()) {
+            const val = dict[key];
+            if (typeof val === "string" && val.length > 0) {
+              try {
+                parsed = _TypedPredictor.#parseJSON(val);
+                found = true;
+                break;
+              } catch (parseErr) {
+                lastParseError = parseErr;
+              }
+            }
+          }
+          if (!found) {
+            if (lastParseError !== void 0) {
+              throw lastParseError;
+            }
+            parsed = dict;
+          }
+          let typed;
+          if (this.#schema) {
+            typed = this.#schema.parse(parsed);
+          } else {
+            typed = parsed;
+          }
+          return new TypedPrediction(
+            dict,
+            typed,
+            prediction.completions
+          );
+        } catch (err) {
+          lastError = err;
+        }
+      }
+    } finally {
+      this.instructions = origInstructions;
+    }
+    throw lastError;
+  }
+  static #parseJSON(raw) {
+    if (typeof raw !== "string") return raw;
+    let text = raw.trim();
+    const fence = /^```(?:json)?\s*([\s\S]*?)\s*```$/m.exec(text);
+    if (fence) text = (fence[1] ?? "").trim();
+    return JSON.parse(text);
+  }
+};
+var TypedChainOfThought = class extends TypedPredictor {
+  constructor(signature, schema, options = {}) {
+    const base = typeof signature === "string" ? Signature.from(signature) : signature;
+    const withRationale = base.withOutput("rationale", {
+      description: "Think step by step to reason through the problem",
+      prefix: "Reasoning:"
+    });
+    const reordered = new Signature({
+      inputs: withRationale.inputs,
+      outputs: new Map([
+        ["rationale", withRationale.outputs.get("rationale")],
+        ...withRationale.outputs
+      ]),
+      instructions: withRationale.instructions
+    });
+    super(reordered, schema, options);
+  }
+  async forward(inputs) {
+    const result = await super.forward(inputs);
+    const { rationale: _rationale, ...rest } = result.toDict();
+    void _rationale;
+    return new TypedPrediction(
+      rest,
+      result.typed,
+      result.completions
+    );
+  }
+};
+
+// src/modules/Parallel.ts
+var Parallel = class extends Module {
+  #modules;
+  #timeoutMs;
+  constructor(modules, options = {}) {
+    super();
+    this.#modules = modules;
+    this.#timeoutMs = options.timeoutMs;
+  }
+  /** Run all modules in parallel and return all predictions. */
+  async run(...args) {
+    const tasks = this.#modules.map(
+      (m) => m.forward(...args)
+    );
+    if (this.#timeoutMs !== void 0) {
+      const timeoutMs = this.#timeoutMs;
+      const withTimeout = tasks.map(
+        (t) => Promise.race([
+          t,
+          new Promise(
+            (_, reject) => setTimeout(() => reject(new Error("Parallel: timeout")), timeoutMs)
+          )
+        ])
+      );
+      return Promise.all(withTimeout);
+    }
+    return Promise.all(tasks);
+  }
+  /** For Module interface compatibility — returns first prediction. */
+  async forward(...args) {
+    const results = await this.run(...args);
+    return results[0];
+  }
+};
+
+// src/modules/Refine.ts
+var Refine = class extends Module {
+  #inner;
+  #maxRefinements;
+  #feedbackField;
+  #stopCondition;
+  #critic;
+  constructor(inner, options = {}) {
+    super();
+    this.#inner = inner;
+    this.#maxRefinements = options.maxRefinements ?? 2;
+    this.#feedbackField = options.feedbackField ?? "feedback";
+    this.#stopCondition = options.stopCondition;
+    this.#critic = new Predict("output -> critique, is_satisfactory");
+  }
+  async forward(...args) {
+    const innerForward = this.#inner.forward.bind(this.#inner);
+    let prediction = await innerForward(...args);
+    for (let i = 0; i < this.#maxRefinements; i++) {
+      if (this.#stopCondition?.(prediction)) break;
+      const outputStr = JSON.stringify(prediction.toDict());
+      let critique;
+      try {
+        critique = await this.#critic.forward({ output: outputStr });
+      } catch {
+        break;
+      }
+      const isSatisfactory = String(
+        critique.get("is_satisfactory") ?? ""
+      ).toLowerCase().trim();
+      if (isSatisfactory === "yes" || isSatisfactory === "true") break;
+      const feedback = String(critique.get("critique") ?? "");
+      const newArgs = [...args];
+      if (newArgs.length > 0 && typeof newArgs[0] === "object" && newArgs[0] !== null) {
+        newArgs[0] = {
+          ...newArgs[0],
+          [this.#feedbackField]: feedback
+        };
+      }
+      try {
+        prediction = await innerForward(...newArgs);
+      } catch {
+        break;
+      }
+    }
+    return prediction;
+  }
+};
+
+// src/modules/NativeReAct.ts
+var NativeReAct = class extends Module {
+  tools;
+  maxIter;
+  #signatureStr;
+  #outputKey;
+  constructor(signatureStr, tools, maxIter = 5) {
+    super();
+    this.#signatureStr = signatureStr;
+    this.tools = new Map(tools.map((t) => [t.name, t]));
+    this.maxIter = maxIter;
+    const sig = Signature.from(signatureStr);
+    this.#outputKey = [...sig.outputs.keys()][0] ?? "answer";
+  }
+  async forward(inputs) {
+    const lm = settings.lm;
+    if (!lm) throw new Error("No LM configured.");
+    const toolSchemas = [...this.tools.values()].map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: {
+          type: "object",
+          properties: { args: { type: "string", description: "Tool arguments as JSON or plain string" } },
+          required: ["args"]
+        }
+      }
+    }));
+    const inputStr = Object.entries(inputs).map(([k, v]) => `${k}: ${String(v)}`).join("\n");
+    const messages = [
+      {
+        role: "system",
+        content: `You are a helpful assistant. Use tools when needed.
+Signature: ${this.#signatureStr}
+Tools: ${[...this.tools.keys()].join(", ")}`
+      },
+      { role: "user", content: inputStr }
+    ];
+    let finalAnswer = "";
+    const trajectory = [];
+    for (let i = 0; i < this.maxIter; i++) {
+      const response = await lm.call(messages, {
+        extra: { tools: toolSchemas, tool_choice: "auto" }
+      });
+      const raw = response.raw;
+      const choices = raw?.["choices"] ?? [];
+      const choice = choices[0];
+      const toolCalls = choice?.["message"]?.["tool_calls"];
+      if (toolCalls && toolCalls.length > 0) {
+        for (const tc of toolCalls) {
+          const toolName = tc.function.name;
+          const args = tc.function.arguments;
+          const tool = this.tools.get(toolName);
+          const observation = tool ? await tool.fn(args).catch((e) => String(e)) : `Unknown tool: ${toolName}`;
+          trajectory.push({
+            thought: `Using tool: ${toolName}`,
+            action: `${toolName}(${args})`,
+            observation
+          });
+          messages.push({ role: "assistant", content: `Tool: ${toolName}
+Args: ${args}` });
+          messages.push({ role: "user", content: `Observation: ${observation}` });
+        }
+      } else {
+        finalAnswer = response.text;
+        break;
+      }
+    }
+    return new Prediction({ [this.#outputKey]: finalAnswer, trajectory: JSON.stringify(trajectory) });
+  }
+};
+
+// src/retrieve/Retriever.ts
+var Retriever = class {
+};
+
+// src/retrieve/backends/ColBERTv2.ts
+var ColBERTv2 = class extends Retriever {
+  #url;
+  constructor(options) {
+    super();
+    this.#url = typeof options === "string" ? options : options.url;
+  }
+  async retrieve(query, k) {
+    const url = new URL("/search", this.#url);
+    url.searchParams.set("query", query);
+    url.searchParams.set("k", String(k));
+    const response = await fetch(url.toString());
+    if (!response.ok) {
+      throw new Error(`ColBERTv2 request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    return (data.topk ?? []).map((p) => p.content ?? "").filter(Boolean);
+  }
+};
+
+// src/retrieve/backends/PineconeRM.ts
+var PineconeRM = class extends Retriever {
+  #options;
+  constructor(options) {
+    super();
+    this.#options = options;
+  }
+  async retrieve(query, k) {
+    const { Pinecone } = await import("@pinecone-database/pinecone").catch(() => {
+      throw new Error(
+        "The `@pinecone-database/pinecone` package is required.\nInstall it with: npm install @pinecone-database/pinecone"
+      );
+    });
+    const client = new Pinecone({
+      apiKey: this.#options.apiKey ?? process.env["PINECONE_API_KEY"] ?? ""
+    });
+    const index = client.index(this.#options.indexName);
+    const embedding = await this.#options.embeddingFn(query);
+    const queryResponse = await index.namespace(this.#options.namespace ?? "").query({
+      vector: embedding,
+      topK: k,
+      includeMetadata: true
+    });
+    return (queryResponse.matches ?? []).map(
+      (m) => String(m.metadata?.["text"] ?? m.metadata?.["content"] ?? "")
+    ).filter(Boolean);
+  }
+};
+
+// src/retrieve/backends/WeaviateRM.ts
+var WeaviateRM = class extends Retriever {
+  #options;
+  constructor(options) {
+    super();
+    this.#options = options;
+  }
+  async retrieve(query, k) {
+    const weaviate = await import("weaviate-client").catch(() => {
+      throw new Error(
+        "The `weaviate-client` package is required.\nInstall it with: npm install weaviate-client"
+      );
+    });
+    const client = await weaviate.default.connectToCustom({
+      httpHost: this.#options.url,
+      ...this.#options.apiKey ? { authCredentials: new weaviate.default.ApiKey(this.#options.apiKey) } : {}
+    });
+    const embedding = await this.#options.embeddingFn(query);
+    const textProp = this.#options.textProperty ?? "text";
+    const result = await client.collections.get(this.#options.className).query.nearVector(embedding, { limit: k, returnProperties: [textProp] });
+    return (result.objects ?? []).map(
+      (obj) => String(obj.properties?.[textProp] ?? "")
+    ).filter(Boolean);
+  }
+};
+
+// src/retrieve/backends/ChromadbRM.ts
+var ChromadbRM = class extends Retriever {
+  #options;
+  constructor(options) {
+    super();
+    this.#options = options;
+  }
+  async retrieve(query, k) {
+    const { ChromaClient } = await import("chromadb").catch(() => {
+      throw new Error(
+        "The `chromadb` package is required.\nInstall it with: npm install chromadb"
+      );
+    });
+    const client = new ChromaClient({ path: this.#options.url ?? "http://localhost:8000" });
+    const collection = await client.getCollection({ name: this.#options.collectionName });
+    const results = await collection.query({
+      queryTexts: [query],
+      nResults: k
+    });
+    return (results.documents?.[0] ?? []).filter((d) => d !== null);
+  }
+};
+
+// src/retrieve/backends/QdrantRM.ts
+var QdrantRM = class extends Retriever {
+  #options;
+  constructor(options) {
+    super();
+    this.#options = options;
+  }
+  async retrieve(query, k) {
+    const { QdrantClient } = await import("@qdrant/js-client-rest").catch(() => {
+      throw new Error(
+        "The `@qdrant/js-client-rest` package is required.\nInstall it with: npm install @qdrant/js-client-rest"
+      );
+    });
+    const client = new QdrantClient({
+      url: this.#options.url ?? "http://localhost:6333",
+      apiKey: this.#options.apiKey
+    });
+    const embedding = await this.#options.embeddingFn(query);
+    const textField = this.#options.textField ?? "text";
+    const result = await client.search(this.#options.collectionName, {
+      vector: embedding,
+      limit: k,
+      with_payload: [textField]
+    });
+    return result.map(
+      (hit) => String(hit.payload?.[textField] ?? "")
+    ).filter(Boolean);
+  }
+};
+
+// src/retrieve/backends/FaissRM.ts
+var FaissRM = class extends Retriever {
+  #passages;
+  #precomputedEmbeddings;
+  #embeddingFn;
+  /** Lazily populated passage-embedding cache. */
+  #cachedEmbeddings;
+  constructor(options) {
+    super();
+    this.#passages = options.passages;
+    this.#precomputedEmbeddings = options.embeddings;
+    this.#embeddingFn = options.embeddingFn;
+  }
+  async retrieve(query, k) {
+    const queryEmbedding = await this.#embeddingFn(query);
+    if (!this.#cachedEmbeddings) {
+      this.#cachedEmbeddings = this.#precomputedEmbeddings ? [...this.#precomputedEmbeddings] : await Promise.all(this.#passages.map((p) => this.#embeddingFn(p)));
+    }
+    const scored = this.#cachedEmbeddings.map((emb, i) => ({
+      index: i,
+      score: this.#cosineSimilarity(queryEmbedding, emb)
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, k).map((s) => this.#passages[s.index] ?? "");
+  }
+  #cosineSimilarity(a, b) {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += (a[i] ?? 0) * (b[i] ?? 0);
+      normA += (a[i] ?? 0) ** 2;
+      normB += (b[i] ?? 0) ** 2;
+    }
+    return normA === 0 || normB === 0 ? 0 : dot / (Math.sqrt(normA) * Math.sqrt(normB));
+  }
+};
+
+// src/retrieve/backends/YouRM.ts
+var YouRM = class extends Retriever {
+  #options;
+  constructor(options = {}) {
+    super();
+    this.#options = options;
+  }
+  async retrieve(query, k) {
+    const apiKey = this.#options.apiKey ?? process.env["YDC_API_KEY"];
+    const url = new URL("https://api.ydc-index.io/search");
+    url.searchParams.set("query", query);
+    url.searchParams.set("num_web_results", String(k));
+    const response = await fetch(url.toString(), {
+      headers: {
+        ...apiKey ? { "X-API-Key": apiKey } : {}
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`YouRM request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    return (data.hits ?? []).flatMap((hit) => hit.snippets ?? []).slice(0, k);
+  }
+};
+
+// src/retrieve/backends/MockRetriever.ts
+var MockRetriever = class extends Retriever {
+  #passages;
+  constructor(passages) {
+    super();
+    this.#passages = passages;
+  }
+  async retrieve(query, k) {
+    const lower = query.toLowerCase();
+    const matches = this.#passages.filter((p) => p.toLowerCase().includes(lower));
+    const results = matches.length > 0 ? matches : this.#passages;
+    return results.slice(0, k);
+  }
+};
+
+// src/optimizers/Optimizer.ts
+var Optimizer = class {
+};
+
+// src/optimizers/LabeledFewShot.ts
+var LabeledFewShot = class extends Optimizer {
+  #k;
+  /**
+   * @param k - Maximum number of demos to assign per predictor (default: 16).
+   */
+  constructor(k = 16) {
+    super();
+    this.#k = k;
+  }
+  async compile(student, trainset, _metric) {
+    const optimized = student.clone();
+    for (const [, predictor] of optimized.namedPredictors()) {
+      if (predictor instanceof Predict) {
+        predictor.demos = trainset.slice(0, this.#k);
+      }
+    }
+    return optimized;
+  }
+};
+
+// src/optimizers/BootstrapFewShot.ts
+var BootstrapFewShot = class extends Optimizer {
+  #opts;
+  constructor(options = {}) {
+    super();
+    this.#opts = {
+      maxBootstrappedDemos: options.maxBootstrappedDemos ?? 4,
+      maxLabeledDemos: options.maxLabeledDemos ?? 16,
+      teacher: options.teacher ?? null
+    };
+  }
+  async compile(student, trainset, metric) {
+    const teacher = this.#opts.teacher ?? student;
+    const demos = [];
+    for (const example of trainset) {
+      if (demos.length >= this.#opts.maxBootstrappedDemos) break;
+      try {
+        const inputs = example.toDict();
+        const prediction = await teacher.forward(inputs);
+        const raw = metric(example, prediction);
+        const passed = typeof raw === "boolean" ? raw : raw > 0;
+        if (passed) {
+          demos.push(example.with(prediction.toDict()));
+        }
+      } catch {
+      }
+    }
+    const optimized = student.clone();
+    for (const [, predictor] of optimized.namedPredictors()) {
+      if (predictor instanceof Predict) {
+        predictor.demos = demos.slice(0, this.#opts.maxBootstrappedDemos);
+      }
+    }
+    return optimized;
+  }
+};
+
+// src/evaluate/evaluate.ts
+async function evaluate(program, examples, metric, options = {}) {
+  const { numThreads = 1, displayProgress = false } = options;
+  const results = [];
+  const runExample = async (example) => {
+    const inputs = example.toDict();
+    let prediction;
+    try {
+      prediction = await program.forward(inputs);
+    } catch {
+      prediction = new Prediction({});
+    }
+    const raw = metric(example, prediction);
+    const score2 = typeof raw === "boolean" ? raw ? 1 : 0 : raw;
+    return { example, prediction, score: score2, passed: score2 > 0 };
+  };
+  if (numThreads <= 1) {
+    for (let i = 0; i < examples.length; i++) {
+      const result = await runExample(examples[i]);
+      results.push(result);
+      if (displayProgress) {
+        console.log(`[${i + 1}/${examples.length}] score=${result.score.toFixed(2)}`);
+      }
+    }
+  } else {
+    for (let i = 0; i < examples.length; i += numThreads) {
+      const batch = examples.slice(i, i + numThreads);
+      const batchResults = await Promise.all(batch.map(runExample));
+      results.push(...batchResults);
+      if (displayProgress) {
+        console.log(`[${i + batchResults.length}/${examples.length}]`);
+      }
+    }
+  }
+  const total = results.length;
+  const numPassed = results.filter((r) => r.passed).length;
+  const score = total > 0 ? results.reduce((s, r) => s + r.score, 0) / total : 0;
+  return { score, numPassed, total, results };
+}
+
+// src/evaluate/metrics.ts
+function exactMatch(field = "answer", caseSensitive = false) {
+  return (example, prediction) => {
+    const expected = String(example.get(field) ?? "");
+    const actual = String(prediction.get(field) ?? "");
+    return caseSensitive ? expected === actual : expected.toLowerCase() === actual.toLowerCase();
+  };
+}
+function f1(field = "answer") {
+  return (example, prediction) => {
+    const expected = tokenize(String(example.get(field) ?? ""));
+    const actual = tokenize(String(prediction.get(field) ?? ""));
+    if (expected.length === 0 && actual.length === 0) return 1;
+    if (expected.length === 0 || actual.length === 0) return 0;
+    const expectedSet = new Set(expected);
+    const actualSet = new Set(actual);
+    const common = [...expectedSet].filter((t) => actualSet.has(t));
+    const precision = common.length / actual.length;
+    const recall = common.length / expected.length;
+    if (precision + recall === 0) return 0;
+    return 2 * precision * recall / (precision + recall);
+  };
+}
+function passAtK(innerMetric, k) {
+  return (example, prediction, trace) => {
+    for (let i = 0; i < Math.min(k, prediction.completions.length + 1); i++) {
+      const candidate = i === 0 ? prediction : buildPrediction(prediction.completions[i - 1] ?? {});
+      const result = innerMetric(example, candidate, trace);
+      if (result === true || typeof result === "number" && result > 0) return 1;
+    }
+    return 0;
+  };
+}
+function bleu(field = "answer") {
+  return (example, prediction) => {
+    const reference = tokenize(String(example.get(field) ?? ""));
+    const hypothesis = tokenize(String(prediction.get(field) ?? ""));
+    if (hypothesis.length === 0) return 0;
+    const refSet = new Set(reference);
+    const uni = hypothesis.filter((t) => refSet.has(t)).length / hypothesis.length;
+    if (hypothesis.length < 2) return uni;
+    const refBigrams = new Set(
+      reference.slice(0, -1).map((t, i) => `${t} ${reference[i + 1] ?? ""}`)
+    );
+    const hypBigrams = hypothesis.slice(0, -1).map((t, i) => `${t} ${hypothesis[i + 1] ?? ""}`);
+    const bi = hypBigrams.filter((b) => refBigrams.has(b)).length / hypBigrams.length;
+    return Math.sqrt(uni * bi);
+  };
+}
+function rouge(field = "answer") {
+  return (example, prediction) => {
+    const reference = tokenize(String(example.get(field) ?? ""));
+    const hypothesis = tokenize(String(prediction.get(field) ?? ""));
+    if (reference.length === 0 && hypothesis.length === 0) return 1;
+    if (reference.length === 0 || hypothesis.length === 0) return 0;
+    const lcsLen = lcs(reference, hypothesis);
+    const precision = lcsLen / hypothesis.length;
+    const recall = lcsLen / reference.length;
+    if (precision + recall === 0) return 0;
+    return 2 * precision * recall / (precision + recall);
+  };
+}
+function tokenize(text) {
+  return text.toLowerCase().replace(/[^\w\s]/g, "").split(/\s+/).filter(Boolean);
+}
+function lcs(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] + 1 : Math.max(dp[i - 1][j], dp[i][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+function buildPrediction(data) {
+  return new Prediction(data);
+}
+
+// src/optimizers/BootstrapFewShotWithRandomSearch.ts
+var BootstrapFewShotWithRandomSearch = class extends BootstrapFewShot {
+  #numCandidates;
+  #valset;
+  constructor(options = {}) {
+    super(options);
+    this.#numCandidates = options.numCandidatePrograms ?? 8;
+    this.#valset = options.valset;
+  }
+  async compile(student, trainset, metric) {
+    const bootstrapped = await super.compile(student, trainset, metric);
+    const allDemos = [];
+    for (const [, pred] of bootstrapped.namedPredictors()) {
+      if (pred instanceof Predict) {
+        allDemos.push(...pred.demos);
+      }
+    }
+    if (allDemos.length === 0) return bootstrapped;
+    const evalSet = this.#valset ?? trainset;
+    let bestScore = -Infinity;
+    let bestModule = bootstrapped;
+    for (let i = 0; i < this.#numCandidates; i++) {
+      const candidate = bootstrapped.clone();
+      const shuffle = [...allDemos].sort(() => Math.random() - 0.5);
+      const k = Math.floor(Math.random() * allDemos.length) + 1;
+      for (const [, pred] of candidate.namedPredictors()) {
+        if (pred instanceof Predict) {
+          pred.demos = shuffle.slice(0, k);
+        }
+      }
+      const { score } = await evaluate(candidate, evalSet, metric);
+      if (score > bestScore) {
+        bestScore = score;
+        bestModule = candidate;
+      }
+    }
+    return bestModule;
+  }
+};
+
+// src/optimizers/BootstrapFewShotWithOptuna.ts
+var BootstrapFewShotWithOptuna = class extends BootstrapFewShot {
+  #numTrials;
+  #valset;
+  constructor(options = {}) {
+    super(options);
+    this.#numTrials = options.numTrials ?? 20;
+    this.#valset = options.valset;
+  }
+  async compile(student, trainset, metric) {
+    const bootstrapped = await super.compile(student, trainset, metric);
+    const allDemos = [];
+    for (const [, predictor] of bootstrapped.namedPredictors()) {
+      if (predictor instanceof Predict) {
+        allDemos.push(...predictor.demos);
+      }
+    }
+    if (allDemos.length === 0) {
+      return bootstrapped;
+    }
+    const evalSet = this.#valset ?? trainset;
+    const maxDemos = Math.max(1, allDemos.length);
+    const TOP_TRIALS_FRACTION = 0.25;
+    const GOOD_TRIAL_SAMPLING_PROBABILITY = 0.7;
+    const trials = [];
+    const evaluate2 = async (candidate) => {
+      let score = 0;
+      for (const example of evalSet) {
+        try {
+          const inputs = example.toDict();
+          const prediction = await candidate.forward(inputs);
+          const raw = metric(example, prediction);
+          score += typeof raw === "boolean" ? raw ? 1 : 0 : raw;
+        } catch {
+        }
+      }
+      return evalSet.length > 0 ? score / evalSet.length : 0;
+    };
+    const sampleIndices = (goodTrials, badTrials, n) => {
+      const useGood = goodTrials.length > 0 && Math.random() < GOOD_TRIAL_SAMPLING_PROBABILITY;
+      const pool = useGood ? goodTrials : badTrials.length > 0 ? badTrials : null;
+      if (pool !== null && pool.length > 0) {
+        const base = pool[Math.floor(Math.random() * pool.length)];
+        const result = new Set(base.indices);
+        if (Math.random() < 0.5 && result.size < maxDemos) {
+          result.add(Math.floor(Math.random() * maxDemos));
+        } else if (result.size > 1) {
+          const arr = [...result];
+          result.delete(arr[Math.floor(Math.random() * arr.length)]);
+        }
+        return [...result].slice(0, n);
+      }
+      const indices = Array.from({ length: maxDemos }, (_, i) => i);
+      return indices.sort(() => Math.random() - 0.5).slice(0, Math.min(n, maxDemos));
+    };
+    let bestScore = -Infinity;
+    let bestModule = bootstrapped;
+    for (let t = 0; t < this.#numTrials; t++) {
+      const sortedTrials = [...trials].sort((a, b) => b.score - a.score);
+      const topK = Math.max(1, Math.floor(sortedTrials.length * TOP_TRIALS_FRACTION));
+      const goodTrials = sortedTrials.slice(0, topK);
+      const badTrials = sortedTrials.slice(topK);
+      const numDemos = Math.max(1, Math.floor(maxDemos * 0.5));
+      const indices = sampleIndices(goodTrials, badTrials, numDemos);
+      const selectedDemos = indices.map((i) => allDemos[i]).filter((d) => d !== void 0);
+      const candidate = bootstrapped.clone();
+      for (const [, predictor] of candidate.namedPredictors()) {
+        if (predictor instanceof Predict) {
+          predictor.demos = selectedDemos;
+        }
+      }
+      const score = await evaluate2(candidate);
+      trials.push({ indices, score });
+      if (score > bestScore) {
+        bestScore = score;
+        bestModule = candidate;
+      }
+    }
+    return bestModule;
+  }
+};
+
+// src/optimizers/COPRO.ts
+var COPRO = class extends Optimizer {
+  #breadth;
+  #depth;
+  constructor(options = {}) {
+    super();
+    this.#breadth = options.breadth ?? 5;
+    this.#depth = options.depth ?? 3;
+  }
+  async compile(student, trainset, metric) {
+    const lm = settings.lm;
+    if (!lm) throw new Error("COPRO requires a configured LM.");
+    let best = student;
+    let bestScore = (await evaluate(student, trainset.slice(0, 10), metric)).score;
+    for (let round = 0; round < this.#depth; round++) {
+      for (const [name, predictor] of best.namedPredictors()) {
+        if (!(predictor instanceof Predict)) continue;
+        const candidates = [];
+        for (let i = 0; i < this.#breadth; i++) {
+          const prompt = this.#buildInstructionPrompt(predictor.instructions ?? "", name);
+          const resp = await lm.call(prompt, { temperature: 0.9 });
+          candidates.push(resp.text.trim());
+        }
+        for (const candidate of candidates) {
+          const clone = best.clone();
+          for (const [n, p] of clone.namedPredictors()) {
+            if (n === name && p instanceof Predict) {
+              p.instructions = candidate;
+            }
+          }
+          const { score } = await evaluate(clone, trainset.slice(0, 10), metric);
+          if (score > bestScore) {
+            bestScore = score;
+            best = clone;
+          }
+        }
+      }
+    }
+    return best;
+  }
+  #buildInstructionPrompt(currentInstruction, fieldName) {
+    return `You are an expert prompt engineer.
+Current instruction for the "${fieldName}" field: "${currentInstruction}"
+
+Write an improved, concise instruction for this field that will produce better outputs from a language model. Output only the instruction text.`;
+  }
+};
+
+// src/optimizers/MIPRO.ts
+var MIPRO = class extends Optimizer {
+  #opts;
+  constructor(options = {}) {
+    super();
+    this.#opts = {
+      numCandidates: options.numCandidates ?? 5,
+      initTemperature: options.initTemperature ?? 0.9,
+      numCandidatePrograms: options.numCandidatePrograms ?? 8,
+      verbose: options.verbose ?? false
+    };
+  }
+  async compile(student, trainset, metric) {
+    if (this.#opts.verbose) console.log("[MIPRO] Phase 1: Instruction optimization (COPRO)");
+    const copro = new COPRO({ breadth: this.#opts.numCandidates, depth: 2 });
+    const instructionOptimized = await copro.compile(student, trainset, metric);
+    if (this.#opts.verbose) console.log("[MIPRO] Phase 2: Demo optimization (BootstrapFewShotWithRandomSearch)");
+    const bootstrap = new BootstrapFewShotWithRandomSearch({
+      numCandidatePrograms: this.#opts.numCandidatePrograms
+    });
+    return bootstrap.compile(instructionOptimized, trainset, metric);
+  }
+};
+
+// src/optimizers/KNNFewShot.ts
+var KNNFewShot = class extends Optimizer {
+  #opts;
+  constructor(options) {
+    super();
+    this.#opts = {
+      k: options.k ?? 3,
+      embeddingFn: options.embeddingFn,
+      keyField: options.keyField ?? ""
+    };
+  }
+  async compile(student, trainset, _metric) {
+    const embeddingFn = this.#opts.embeddingFn;
+    const k = this.#opts.k;
+    const trainEmbeddings = await Promise.all(
+      trainset.map(async (ex) => {
+        const key = this.#opts.keyField ? String(ex.get(this.#opts.keyField) ?? "") : Object.values(ex.toDict()).join(" ");
+        return { ex, embedding: await embeddingFn(key) };
+      })
+    );
+    const optimized = student.clone();
+    for (const [, predictor] of optimized.namedPredictors()) {
+      if (!(predictor instanceof Predict)) continue;
+      const originalForward = predictor.forward.bind(predictor);
+      predictor.forward = async (inputs) => {
+        const queryText = Object.values(inputs).join(" ");
+        const queryEmb = await embeddingFn(queryText);
+        const scored = trainEmbeddings.map(({ ex, embedding }) => ({
+          ex,
+          score: cosineSimilarity(queryEmb, embedding)
+        }));
+        scored.sort((a, b) => b.score - a.score);
+        predictor.demos = scored.slice(0, k).map((s) => s.ex);
+        return originalForward(inputs);
+      };
+    }
+    return optimized;
+  }
+};
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += (a[i] ?? 0) * (b[i] ?? 0);
+    normA += (a[i] ?? 0) ** 2;
+    normB += (b[i] ?? 0) ** 2;
+  }
+  return normA === 0 || normB === 0 ? 0 : dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+// src/optimizers/Ensemble.ts
+var EnsembleOptimizer = class extends Optimizer {
+  #reduceFunc;
+  constructor(options = {}) {
+    super();
+    this.#reduceFunc = options.reduceFunc;
+  }
+  async compile(student, _trainset, _metric) {
+    const reduceFunc = this.#reduceFunc;
+    const wrapper = {
+      namedPredictors: student.namedPredictors.bind(student),
+      dump: student.dump.bind(student),
+      load: student.load.bind(student),
+      async forward(...args) {
+        const pred = await student.forward(
+          ...args
+        );
+        return reduceFunc ? reduceFunc([pred]) : pred;
+      }
+    };
+    return wrapper;
+  }
+};
+
+// src/optimizers/BootstrapFinetune.ts
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { dirname } from "path";
+var BootstrapFinetune = class extends Optimizer {
+  #exportPath;
+  #format;
+  #maxBootstrappedDemos;
+  #bootstrap;
+  constructor(options = {}) {
+    super();
+    this.#exportPath = options.exportPath ?? "./finetune_data.jsonl";
+    this.#format = options.format ?? "openai";
+    this.#maxBootstrappedDemos = options.maxBootstrappedDemos ?? 4;
+    this.#bootstrap = new BootstrapFewShot({
+      maxBootstrappedDemos: this.#maxBootstrappedDemos
+    });
+  }
+  async compile(student, trainset, metric) {
+    const compiled = await this.#bootstrap.compile(student, trainset, metric);
+    const records = [];
+    for (const [, predictor] of compiled.namedPredictors()) {
+      if (predictor instanceof Predict) {
+        for (const demo of predictor.demos) {
+          const dict = demo.toDict();
+          const inputFields = [...predictor.signature.inputs.keys()];
+          const outputFields = [...predictor.signature.outputs.keys()];
+          const inputStr = inputFields.map((k) => `${k}: ${String(dict[k] ?? "")}`).join("\n");
+          const outputStr = outputFields.map((k) => `${k}: ${String(dict[k] ?? "")}`).join("\n");
+          if (this.#format === "openai") {
+            records.push(
+              JSON.stringify({
+                messages: [
+                  { role: "user", content: inputStr },
+                  { role: "assistant", content: outputStr }
+                ]
+              })
+            );
+          } else {
+            records.push(JSON.stringify({ prompt: inputStr, completion: outputStr }));
+          }
+        }
+      }
+    }
+    const dir = dirname(this.#exportPath);
+    mkdirSync2(dir, { recursive: true });
+    writeFileSync2(this.#exportPath, records.join("\n"), "utf8");
+    return compiled;
+  }
+};
+
+// src/optimizers/GRPO.ts
+var GRPO = class extends Optimizer {
+  #numSteps;
+  #groupSize;
+  #temperature;
+  #maxLabeledDemos;
+  constructor(options = {}) {
+    super();
+    this.#numSteps = options.numSteps ?? 20;
+    this.#groupSize = options.groupSize ?? 8;
+    this.#temperature = options.temperature ?? 1;
+    this.#maxLabeledDemos = options.maxLabeledDemos ?? 16;
+  }
+  async compile(student, trainset, metric) {
+    const lm = settings.lm;
+    if (!lm) throw new Error("GRPO requires a configured LM.");
+    const bootstrap = new BootstrapFewShot({
+      maxBootstrappedDemos: this.#maxLabeledDemos
+    });
+    let best = await bootstrap.compile(student, trainset, metric);
+    const evalSet = trainset.slice(0, Math.min(10, trainset.length));
+    let bestScore = (await evaluate(best, evalSet, metric)).score;
+    for (let step = 0; step < this.#numSteps; step++) {
+      const candidates = [];
+      for (let g = 0; g < this.#groupSize; g++) {
+        const candidate = best.clone();
+        for (const [, predictor] of candidate.namedPredictors()) {
+          if (predictor instanceof Predict) {
+            const currentInstr = predictor.instructions ?? "";
+            const prompt = `You are an expert prompt engineer.
+Current instruction: "${currentInstr}"
+
+Write an improved instruction for a language model. Output only the instruction text.`;
+            const resp = await lm.call(prompt, { temperature: this.#temperature });
+            predictor.instructions = resp.text.trim();
+          }
+        }
+        const { score } = await evaluate(candidate, evalSet, metric);
+        candidates.push({ module: candidate, score });
+      }
+      const scores = candidates.map((c) => c.score);
+      const mean = scores.reduce((a, b) => a + b, 0) / scores.length;
+      const std = Math.sqrt(scores.reduce((a, b) => a + (b - mean) ** 2, 0) / scores.length) || 1;
+      const advantages = scores.map((s) => (s - mean) / std);
+      const bestIdx = advantages.indexOf(Math.max(...advantages));
+      const topScore = candidates[bestIdx]?.score ?? 0;
+      if (topScore > bestScore) {
+        bestScore = topScore;
+        best = candidates[bestIdx].module;
+      }
+    }
+    return best;
+  }
+};
+
+// src/optimizers/SIMBA.ts
+var SIMBA = class extends Optimizer {
+  #numIter;
+  #batchSize;
+  #maxBootstrappedDemos;
+  constructor(options = {}) {
+    super();
+    this.#numIter = options.numIter ?? 10;
+    this.#batchSize = options.batchSize ?? 8;
+    this.#maxBootstrappedDemos = options.maxBootstrappedDemos ?? 4;
+  }
+  async compile(student, trainset, metric) {
+    const bootstrap = new BootstrapFewShot({
+      maxBootstrappedDemos: this.#maxBootstrappedDemos
+    });
+    let best = await bootstrap.compile(student, trainset, metric);
+    const evalBatch = trainset.slice(0, Math.min(this.#batchSize, trainset.length));
+    let bestScore = (await evaluate(best, evalBatch, metric)).score;
+    for (let iter = 0; iter < this.#numIter; iter++) {
+      const shuffled = [...trainset];
+      for (let i = shuffled.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+      }
+      const batch = shuffled.slice(0, Math.min(this.#batchSize, shuffled.length));
+      const candidate = best.clone();
+      for (const [, predictor] of candidate.namedPredictors()) {
+        if (predictor instanceof Predict && predictor.demos.length > 1) {
+          const dropIdx = Math.floor(Math.random() * predictor.demos.length);
+          predictor.demos = predictor.demos.filter((_, i) => i !== dropIdx);
+        }
+      }
+      const { score } = await evaluate(candidate, batch, metric);
+      if (score >= bestScore) {
+        bestScore = score;
+        best = candidate;
+      }
+    }
+    return best;
+  }
+};
+
+// src/optimizers/AvatarOptimizer.ts
+var AvatarOptimizer = class extends Optimizer {
+  #numAvatars;
+  #maxLabeledDemos;
+  constructor(options = {}) {
+    super();
+    this.#numAvatars = options.numAvatars ?? 4;
+    this.#maxLabeledDemos = options.maxLabeledDemos ?? 8;
+  }
+  async compile(student, trainset, metric) {
+    const lm = settings.lm;
+    if (!lm) throw new Error("AvatarOptimizer requires a configured LM.");
+    let best = student.clone();
+    const evalSet = trainset.slice(0, Math.min(this.#maxLabeledDemos, trainset.length));
+    let bestScore = (await evaluate(best, evalSet, metric)).score;
+    for (const [name, predictor] of best.namedPredictors()) {
+      if (!(predictor instanceof Predict)) continue;
+      const avatarCandidates = [];
+      for (let i = 0; i < this.#numAvatars; i++) {
+        const prompt = `You are an expert at designing AI personas.
+Task field: "${name}"
+Current instruction: "${predictor.instructions ?? ""}"
+
+Write a concise role/persona prefix (1-2 sentences) for an AI assistant that excels at this task. Output only the persona description.`;
+        const resp = await lm.call(prompt, { temperature: 0.9 });
+        avatarCandidates.push(resp.text.trim());
+      }
+      for (const avatar of avatarCandidates) {
+        const clone = best.clone();
+        for (const [n, p] of clone.namedPredictors()) {
+          if (n === name && p instanceof Predict) {
+            const base = p.instructions ?? "";
+            p.instructions = `${avatar}
+
+${base}`.trim();
+          }
+        }
+        const { score } = await evaluate(clone, evalSet, metric);
+        if (score > bestScore) {
+          bestScore = score;
+          best = clone;
+        }
+      }
+    }
+    return best;
+  }
+};
+
+// src/mcp/MCPAdapter.ts
+var MCPToolAdapter = class {
+  #options;
+  #tools;
+  constructor(options = {}) {
+    this.#options = options;
+  }
+  async getTools() {
+    if (this.#tools) return this.#tools;
+    if (this.#options.tools && this.#options.callHandler) {
+      const callHandler = this.#options.callHandler;
+      this.#tools = this.#options.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        fn: async (args) => {
+          let parsed;
+          try {
+            parsed = JSON.parse(args);
+          } catch {
+            parsed = { input: args };
+          }
+          const result = await callHandler(t.name, parsed);
+          return typeof result === "string" ? result : JSON.stringify(result);
+        }
+      }));
+      return this.#tools;
+    }
+    await import("@modelcontextprotocol/sdk/client/index.js").catch(() => {
+      throw new Error(
+        "The `@modelcontextprotocol/sdk` package is required for MCPToolAdapter.\nInstall it with: npm install @modelcontextprotocol/sdk"
+      );
+    });
+    throw new Error(
+      "Live MCP connection not yet implemented. Use tools+callHandler for now."
+    );
+  }
+};
+
+// src/mcp/DSTsxMCPServer.ts
+var DSTsxMCPServer = class {
+  #tools = /* @__PURE__ */ new Map();
+  registerModule(name, description, module, inputFields) {
+    const properties = {};
+    for (const field of inputFields) {
+      properties[field] = { type: "string" };
+    }
+    this.#tools.set(name, {
+      name,
+      description,
+      inputSchema: { type: "object", properties, required: inputFields },
+      handler: async (inputs) => {
+        const result = await module.forward(inputs);
+        return result.toJSON();
+      }
+    });
+    return this;
+  }
+  getToolDefinitions() {
+    return [...this.#tools.values()];
+  }
+  async callTool(name, inputs) {
+    const tool = this.#tools.get(name);
+    if (!tool) throw new Error(`Tool "${name}" not found.`);
+    return tool.handler(inputs);
+  }
+  async createStdioServer() {
+    await import("@modelcontextprotocol/sdk/server/index.js").catch(() => {
+      throw new Error(
+        "The `@modelcontextprotocol/sdk` package is required.\nInstall it with: npm install @modelcontextprotocol/sdk"
+      );
+    });
+    throw new Error(
+      "createStdioServer requires @modelcontextprotocol/sdk to be installed."
+    );
+  }
+};
+
+// src/tracking/Tracker.ts
+var Tracker = class {
+};
+
+// src/tracking/ConsoleTracker.ts
+var ConsoleTracker = class extends Tracker {
+  log(event) {
+    const parts = [`[${event.type.toUpperCase()}]`];
+    if (event.step !== void 0) parts.push(`step=${event.step}`);
+    if (event.score !== void 0) parts.push(`score=${event.score.toFixed(4)}`);
+    if (event.metadata) parts.push(JSON.stringify(event.metadata));
+    console.log(parts.join(" "));
+  }
+  async flush() {
+  }
+};
+
+// src/tracking/JsonFileTracker.ts
+import { mkdirSync as mkdirSync3 } from "fs";
+import { appendFile } from "fs/promises";
+import { dirname as dirname2 } from "path";
+var JsonFileTracker = class extends Tracker {
+  #path;
+  #buffer = [];
+  constructor(path) {
+    super();
+    this.#path = path;
+    mkdirSync3(dirname2(path), { recursive: true });
+  }
+  log(event) {
+    this.#buffer.push(JSON.stringify({ ...event, ts: (/* @__PURE__ */ new Date()).toISOString() }));
+  }
+  async flush() {
+    if (this.#buffer.length === 0) return;
+    const content = this.#buffer.join("\n") + "\n";
+    this.#buffer.length = 0;
+    await appendFile(this.#path, content, "utf8");
+  }
+};
+export {
+  Anthropic,
+  Assert,
+  AssertionError,
+  AvatarOptimizer,
+  BestOfN,
+  BootstrapFewShot,
+  BootstrapFewShotWithOptuna,
+  BootstrapFewShotWithRandomSearch,
+  BootstrapFinetune,
+  COPRO,
+  ChainOfThought,
+  ChainOfThoughtWithHint,
+  ChromadbRM,
+  Cohere,
+  ColBERTv2,
+  ConsoleTracker,
+  DSTsxMCPServer,
+  DiskCache,
+  Ensemble,
+  EnsembleOptimizer,
+  Example,
+  FaissRM,
+  GRPO,
+  GoogleAI,
+  HuggingFace,
+  Image,
+  InputField,
+  JsonFileTracker,
+  KNNFewShot,
+  LM,
+  LMStudio,
+  LRUCache,
+  LabeledFewShot,
+  MCPToolAdapter,
+  MIPRO,
+  MockLM,
+  MockRetriever,
+  Module,
+  MultiChainComparison,
+  NativeReAct,
+  Ollama,
+  OpenAI,
+  Optimizer,
+  OutputField,
+  Parallel,
+  PineconeRM,
+  Predict,
+  Prediction,
+  ProgramOfThought,
+  QdrantRM,
+  ReAct,
+  Refine,
+  Retrieve,
+  Retriever,
+  Retry,
+  SIMBA,
+  Settings,
+  Signature,
+  Suggest,
+  Tracker,
+  TypedChainOfThought,
+  TypedPrediction,
+  TypedPredictor,
+  WeaviateRM,
+  YouRM,
+  bleu,
+  evaluate,
+  exactMatch,
+  f1,
+  majority,
+  passAtK,
+  rouge,
+  settings
+};
+//# sourceMappingURL=index.js.map