@jaex/dstsx 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1597 @@
+/** Metadata describing a single field in a Signature. */
+interface FieldMeta {
+    /** Human-readable description used in the prompt. */
+    description?: string;
+    /** Optional prefix that precedes the field value in the prompt. */
+    prefix?: string;
+    /** Optional format hint (e.g. "json", "markdown", "list"). */
+    format?: string;
+    /** When true the field may be absent from a completion. */
+    optional?: boolean;
+    /**
+     * The JSON-schema-compatible type annotation for this field.
+     * Defaults to "string".
+     */
+    type?: "string" | "number" | "boolean" | "string[]" | "object";
+}
+/** Internal representation of a parsed Signature. */
+interface SignatureMeta {
+    /** Ordered list of input field names with their metadata. */
+    inputs: Map<string, FieldMeta>;
+    /** Ordered list of output field names with their metadata. */
+    outputs: Map<string, FieldMeta>;
+    /** Optional system-level instruction string. */
+    instructions?: string | undefined;
+}
+
+/**
+ * A Signature defines the typed interface (inputs and outputs) for a single
+ * language-model call.  It mirrors `dspy.Signature` in the Python library.
+ *
+ * Signatures can be created from a shorthand string:
+ * ```ts
+ * const sig = Signature.from("question -> answer");
+ * const sig2 = Signature.from("context, question -> answer, confidence");
+ * ```
+ *
+ * Or constructed explicitly:
+ * ```ts
+ * const sig = new Signature({
+ *   inputs:  new Map([["question", InputField({ description: "The question" })]]),
+ *   outputs: new Map([["answer",   OutputField({ description: "The answer"  })]]),
+ *   instructions: "Answer concisely.",
+ * });
+ * ```
+ */
+declare class Signature {
+    readonly inputs: ReadonlyMap<string, FieldMeta>;
+    readonly outputs: ReadonlyMap<string, FieldMeta>;
+    readonly instructions: string | undefined;
+    constructor(meta: SignatureMeta);
+    /**
+     * Parse a shorthand signature string of the form:
+     *   `"field1, field2? -> out1, out2"`
+     *
+     * A trailing `?` marks the field as optional.
+     */
+    static from(shorthand: string, instructions?: string): Signature;
+    /**
+     * Return a new Signature with additional or overridden fields / instructions.
+     */
+    with(overrides: Partial<SignatureMeta>): Signature;
+    /**
+     * Append an extra input field and return a new Signature.
+     */
+    withInput(name: string, meta?: FieldMeta): Signature;
+    /**
+     * Append an extra output field and return a new Signature.
+     */
+    withOutput(name: string, meta?: FieldMeta): Signature;
+    toJSON(): object;
+    static fromJSON(json: Record<string, unknown>): Signature;
+}
+
+/**
+ * Creates an input field descriptor for a {@link Signature}.
+ *
+ * @example
+ * ```ts
+ * const sig = new Signature({
+ *   inputs:  new Map([["question", InputField({ description: "The question to answer" })]]),
+ *   outputs: new Map([["answer",   OutputField({ description: "A concise answer" })]]),
+ * });
+ * ```
+ */
+declare function InputField(meta?: FieldMeta): FieldMeta;
+/**
+ * Creates an output field descriptor for a {@link Signature}.
+ */
+declare function OutputField(meta?: FieldMeta): FieldMeta;
+
+/**
+ * An immutable record of named values used as a training example or a module
+ * input.  Mirrors `dspy.Example` in Python.
+ *
+ * @example
+ * ```ts
+ * const ex = new Example({ question: "What is 2+2?", answer: "4" });
+ * const withLabel = ex.with({ answer: "four" });
+ * ```
+ */
+declare class Example {
+    #private;
+    constructor(data: Record<string, unknown>);
+    /** Return the value for `key`, or `undefined` if absent. */
+    get(key: string): unknown;
+    /** Return a shallow-frozen copy of the underlying data record. */
+    toDict(): Readonly<Record<string, unknown>>;
+    /**
+     * Return a new Example with the provided key-value pairs merged in.
+     */
+    with(overrides: Record<string, unknown>): Example;
+    /**
+     * Return a new Example containing only the keys listed in `keys`.
+     */
+    inputs(keys: string[]): Example;
+    /**
+     * Return a new Example containing only the keys NOT listed in `inputKeys`
+     * (i.e. the label / output keys).
+     */
+    labels(inputKeys: string[]): Example;
+    toJSON(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): Example;
+}
+
+/**
+ * The output of a {@link Predict} (or any module) call.
+ * Extends {@link Example} by adding `completions` for multi-output calls.
+ *
+ * Mirrors `dspy.Prediction` in Python.
+ */
+declare class Prediction extends Example {
+    /** All candidate completions when `n > 1` was requested. */
+    readonly completions: ReadonlyArray<Record<string, unknown>>;
+    constructor(data: Record<string, unknown>, completions?: Record<string, unknown>[]);
+    /** Typed accessor — casts the value to `T` (caller is responsible for type safety). */
+    getTyped<T>(key: string): T;
+    toJSON(): Record<string, unknown>;
+}
+
+/** Token-usage statistics returned by an LM call. */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * A single LM call record captured during program execution.
+ * Mirrors the trace entries in `dspy.settings.trace`.
+ */
+interface Trace {
+    /** The signature used for this call. */
+    signature: Signature;
+    /** The resolved input values passed to the LM. */
+    inputs: Record<string, unknown>;
+    /** The parsed output values returned by the LM. */
+    outputs: Record<string, unknown>;
+    /** Token usage for this call (if reported by the provider). */
+    usage: TokenUsage | null;
+    /** Wall-clock latency in milliseconds. */
+    latencyMs: number;
+    /** ISO-8601 timestamp of the call. */
+    timestamp: string;
+}
+
+/**
+ * Returns a reducer function that picks the Prediction whose `field` value
+ * appears most frequently.  Ties go to the first occurrence.
+ */
+declare function majority(field?: string): (predictions: Prediction[]) => Prediction;
+
+/** Supported image MIME types. */
+type ImageMimeType = "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+/**
+ * A multi-modal image value that can be passed as a field in Predict/TypedPredictor.
+ *
+ * @example
+ * ```ts
+ * const captioner = new Predict("image, question -> caption");
+ * const result = await captioner.forward({
+ *   image:    Image.fromURL("https://example.com/photo.jpg"),
+ *   question: "What is in this image?",
+ * });
+ * ```
+ */
+declare class Image {
+    readonly url: string | undefined;
+    readonly base64: string | undefined;
+    readonly mimeType: ImageMimeType | undefined;
+    private constructor();
+    /** Create an Image from a URL. */
+    static fromURL(url: string): Image;
+    /** Create an Image from base64-encoded data. */
+    static fromBase64(data: string, mimeType?: ImageMimeType): Image;
+    /** Create an Image by reading a local file synchronously. */
+    static fromFile(path: string, mimeType?: ImageMimeType): Image;
+    /** Serialize to an OpenAI-compatible image_url content part. */
+    toOpenAIContentPart(): {
+        type: "image_url";
+        image_url: {
+            url: string;
+        };
+    };
+    /** Serialize to an Anthropic-compatible image content block. */
+    toAnthropicContentBlock(): {
+        type: "image";
+        source: {
+            type: "base64" | "url";
+            media_type?: string;
+            data?: string;
+            url?: string;
+        };
+    };
+    /** Returns a string representation (used when Image is serialized in prompts). */
+    toString(): string;
+}
+
+/** A single chat message (role + content). */
+interface Message {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** Configuration passed to every LM call. */
+interface LMCallConfig {
+    /** Model identifier (e.g. "gpt-4o", "claude-3-opus-20240229"). */
+    model?: string;
+    /** Sampling temperature (0–2). */
+    temperature?: number;
+    /** Maximum tokens to generate. */
+    maxTokens?: number;
+    /** Stop sequences. */
+    stop?: string[];
+    /** Number of completions to generate (default 1). */
+    n?: number;
+    /**
+     * Optional cache key override.  When provided the cache uses this key
+     * instead of hashing the prompt.
+     */
+    cacheKey?: string;
+    /** Pass-through extra options to the underlying provider SDK. */
+    extra?: Record<string, unknown>;
+}
+/** The response returned by an LM adapter. */
+interface LMResponse {
+    /** The primary (first) completion text. */
+    text: string;
+    /** All completion texts when `n > 1`. */
+    texts: string[];
+    /** Token usage (null when the provider does not report it). */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    } | null;
+    /** Raw provider response (opaque). */
+    raw: unknown;
+}
+/** A single chunk emitted during token streaming. */
+interface StreamChunk {
+    /** The incremental text delta for this chunk. */
+    delta: string;
+    /** True on the final chunk. */
+    done: boolean;
+    /** Raw provider chunk (opaque). */
+    raw: unknown;
+}
+
+/**
+ * Abstract base class for all language model adapters.
+ *
+ * Subclasses must implement {@link LM._call} which performs the actual
+ * provider-specific API call.
+ *
+ * The base class handles:
+ * - LRU response caching
+ * - Request counting
+ * - Token usage aggregation
+ */
+declare abstract class LM {
+    #private;
+    /** Human-readable name / identifier for this model instance. */
+    readonly model: string;
+    constructor(model: string, cacheOptions?: {
+        maxSize?: number;
+        ttlMs?: number;
+        cacheDir?: string;
+    });
+    /**
+     * Call the language model with either a plain string prompt or a list of
+     * chat messages.
+     */
+    call(prompt: string | Message[], config?: LMCallConfig): Promise<LMResponse>;
+    /** Total number of (non-cached) API calls made. */
+    get requestCount(): number;
+    /** Accumulated token usage across all (non-cached) calls. */
+    get tokenUsage(): Readonly<{
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    }>;
+    /** Clear the in-memory response cache. */
+    clearCache(): void;
+    /**
+     * 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.
+     */
+    stream(prompt: string | Message[], config?: LMCallConfig): AsyncGenerator<StreamChunk>;
+    /**
+     * Perform the actual provider API call.  Subclasses must implement this.
+     */
+    protected abstract _call(prompt: string | Message[], config: LMCallConfig): Promise<LMResponse>;
+}
+
+/**
+ * A minimal LRU (Least Recently Used) cache used to memoize LM responses.
+ *
+ * Entries are evicted when `maxSize` is reached (oldest-first) or when their
+ * TTL has expired.
+ */
+declare class LRUCache<K, V> {
+    #private;
+    constructor(maxSize?: number, ttlMs?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    delete(key: K): void;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * Disk-persistent JSON cache for LM responses.
+ *
+ * Cache entries are stored as individual JSON files named by a truncated
+ * SHA-256 hash of the key.  Supports optional TTL and LRU eviction.
+ */
+declare class DiskCache {
+    #private;
+    constructor(cacheDir: string, maxSize?: number, ttlMs?: number);
+    get(key: string): LMResponse | undefined;
+    set(key: string, value: LMResponse): void;
+    clear(): void;
+}
+
+/** Options for the OpenAI adapter. */
+interface OpenAIOptions {
+    apiKey?: string;
+    baseURL?: string;
+    /** Default model, can be overridden per-call. */
+    model?: string;
+    maxRetries?: number;
+    stream?: boolean;
+}
+/**
+ * LM adapter for OpenAI chat-completion and text-completion models.
+ *
+ * Requires the `openai` package as a peer dependency:
+ * ```
+ * npm install openai
+ * ```
+ */
+declare class OpenAI extends LM {
+    #private;
+    constructor(options?: OpenAIOptions);
+    protected _call(prompt: string | Message[], config: LMCallConfig): Promise<LMResponse>;
+    stream(prompt: string | Message[], config?: LMCallConfig): AsyncGenerator<StreamChunk>;
+}
+
+/** Options for the Anthropic adapter. */
+interface AnthropicOptions {
+    apiKey?: string;
+    model?: string;
+    maxRetries?: number;
+}
+/**
+ * LM adapter for Anthropic Claude models.
+ *
+ * Requires the `@anthropic-ai/sdk` package as a peer dependency:
+ * ```
+ * npm install @anthropic-ai/sdk
+ * ```
+ */
+declare class Anthropic extends LM {
+    #private;
+    constructor(options?: AnthropicOptions);
+    protected _call(prompt: string | Message[], config: LMCallConfig): Promise<LMResponse>;
+    stream(prompt: string | Message[], config?: LMCallConfig): AsyncGenerator<StreamChunk>;
+}
+
+/** Options for the Cohere adapter. */
+interface CohereOptions {
+    apiKey?: string;
+    model?: string;
+}
+/**
+ * LM adapter for Cohere Command models.
+ *
+ * Requires the `cohere-ai` package as a peer dependency:
+ * ```
+ * npm install cohere-ai
+ * ```
+ */
+declare class Cohere extends LM {
+    #private;
+    constructor(options?: CohereOptions);
+    protected _call(prompt: string | Message[], config: LMCallConfig): Promise<LMResponse>;
+}
+
+/** Options for the Google Generative AI adapter. */
+interface GoogleAIOptions {
+    apiKey?: string;
+    model?: string;
+}
+/**
+ * LM adapter for Google Gemini models via `@google/generative-ai`.
+ *
+ * Requires the `@google/generative-ai` package as a peer dependency:
+ * ```
+ * npm install @google/generative-ai
+ * ```
+ */
+declare class GoogleAI extends LM {
+    #private;
+    constructor(options?: GoogleAIOptions);
+    protected _call(prompt: string | Message[], config: LMCallConfig): Promise<LMResponse>;
+}
+
+/** Options for the Ollama adapter. */
+interface OllamaOptions {
+    /** Base URL of the Ollama server (default: http://localhost:11434). */
+    baseURL?: string;
+    model?: string;
+}
+/**
+ * LM adapter for locally running Ollama models.
+ * Communicates via the Ollama REST API (OpenAI-compatible `/v1` endpoint).
+ */
+declare class Ollama extends LM {
+    #private;
+    constructor(options?: OllamaOptions);
+    protected _call(prompt: string | Message[], config: LMCallConfig): Promise<LMResponse>;
+}
+
+/** Options for the LM Studio adapter. */
+interface LMStudioOptions {
+    /** Base URL of the LM Studio server (default: http://localhost:1234/v1). */
+    baseURL?: string;
+    model?: string;
+}
+/**
+ * LM adapter for LM Studio's OpenAI-compatible REST endpoint.
+ */
+declare class LMStudio extends LM {
+    #private;
+    constructor(options?: LMStudioOptions);
+    protected _call(prompt: string | Message[], config: LMCallConfig): Promise<LMResponse>;
+}
+
+/** Options for the HuggingFace Inference API adapter. */
+interface HuggingFaceOptions {
+    apiKey?: string;
+    model?: string;
+    /** Override the inference endpoint URL (for dedicated endpoints). */
+    endpointURL?: string;
+}
+/**
+ * LM adapter for HuggingFace Inference API text-generation models.
+ *
+ * Uses the HuggingFace HTTP inference API directly (no SDK required).
+ */
+declare class HuggingFace extends LM {
+    #private;
+    constructor(options?: HuggingFaceOptions);
+    protected _call(prompt: string | Message[], config: LMCallConfig): Promise<LMResponse>;
+}
+
+/**
+ * A deterministic mock LM adapter for use in unit tests.
+ *
+ * Responses are resolved from a lookup map keyed on the exact prompt string
+ * (or the serialized messages array).  If no match is found the adapter falls
+ * back to `defaultResponse` (or throws if none is configured).
+ *
+ * @example
+ * ```ts
+ * const lm = new MockLM({
+ *   "What is 2+2?": "4",
+ * });
+ * settings.configure({ lm });
+ * ```
+ */
+declare class MockLM extends LM {
+    #private;
+    constructor(responses?: Record<string, string>, defaultResponse?: string);
+    protected _call(prompt: string | Message[], config: LMCallConfig): Promise<LMResponse>;
+    /** Register (or overwrite) a prompt → response mapping at runtime. */
+    addResponse(prompt: string, response: string): void;
+}
+
+/**
+ * Abstract base class for all DSTsx modules.
+ *
+ * A Module is a composable, serializable unit that encapsulates one or more
+ * language model calls.  Subclasses implement {@link Module.forward} to define
+ * their behaviour.
+ *
+ * Mirrors `dspy.Module` in Python.
+ *
+ * @example
+ * ```ts
+ * class MyRAG extends Module {
+ *   retrieve = new Retrieve(3);
+ *   generate = new ChainOfThought("context, question -> answer");
+ *
+ *   async forward(question: string): Promise<Prediction> {
+ *     const { passages } = await this.retrieve.forward(question);
+ *     return this.generate.forward({ context: passages.join("\n"), question });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class Module {
+    /**
+     * Execute the module.
+     *
+     * Subclasses define their own parameter signatures; the base type uses
+     * `unknown` so that TypeScript accepts any subclass override.
+     */
+    abstract forward(...args: unknown[]): Promise<Prediction>;
+    /**
+     * Recursively discover all {@link Predict} sub-modules by walking the own
+     * enumerable properties of this instance.
+     */
+    namedPredictors(): Array<[string, Module]>;
+    /**
+     * Serialize the module's learnable parameters (e.g. `Predict.demos`) to a
+     * plain JSON-compatible object.
+     */
+    dump(): Record<string, unknown>;
+    /**
+     * Restore learnable parameters from a plain object previously produced by
+     * {@link Module.dump}.
+     */
+    load(state: Record<string, unknown>): void;
+    /**
+     * 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(): this;
+}
+
+/**
+ * The fundamental DSTsx module — formats a prompt for the configured LM and
+ * parses the completion back into a typed {@link Prediction}.
+ *
+ * Mirrors `dspy.Predict` in Python.
+ *
+ * @example
+ * ```ts
+ * const qa = new Predict("question -> answer");
+ * const result = await qa.forward({ question: "What is 2 + 2?" });
+ * console.log(result.get("answer")); // "4"
+ * ```
+ */
+declare class Predict extends Module {
+    #private;
+    readonly signature: Signature;
+    /** Few-shot demonstration examples (learnable parameter). */
+    demos: Example[];
+    /** System instruction override (learnable parameter). */
+    instructions: string | undefined;
+    constructor(signature: string | Signature);
+    forward(inputs: Record<string, unknown>): Promise<Prediction>;
+    /**
+     * Stream the LM response token by token.
+     * Returns an `AsyncGenerator<StreamChunk>`.
+     */
+    stream(inputs: Record<string, unknown>): AsyncGenerator<StreamChunk>;
+    dump(): Record<string, unknown>;
+    load(state: Record<string, unknown>): void;
+}
+
+/**
+ * Chain-of-Thought module — extends {@link Predict} by prepending a hidden
+ * `rationale` output field so the LM reasons before producing the answer.
+ *
+ * Mirrors `dspy.ChainOfThought` in Python.
+ *
+ * @example
+ * ```ts
+ * const cot = new ChainOfThought("question -> answer");
+ * const result = await cot.forward({ question: "What is 9 * 8?" });
+ * console.log(result.get("answer")); // "72"
+ * ```
+ */
+declare class ChainOfThought extends Predict {
+    constructor(signature: string | Signature, options?: {
+        rationaleDescription?: string;
+    });
+    /** Returns the answer without the internal rationale. */
+    forward(inputs: Record<string, unknown>): Promise<Prediction>;
+}
+
+/**
+ * Chain-of-Thought with an optional user-supplied hint injected into the
+ * prompt at inference time.
+ *
+ * Mirrors `dspy.ChainOfThoughtWithHint` in Python.
+ *
+ * @example
+ * ```ts
+ * const cot = new ChainOfThoughtWithHint("question -> answer");
+ * const result = await cot.forward({
+ *   question: "What is the capital of France?",
+ *   hint: "Think about European countries.",
+ * });
+ * ```
+ */
+declare class ChainOfThoughtWithHint extends ChainOfThought {
+    constructor(signature: string | Signature, options?: {
+        rationaleDescription?: string;
+    });
+    forward(inputs: Record<string, unknown>): Promise<Prediction>;
+}
+
+/**
+ * Runs a signature `M` times and selects the best completion via a final
+ * aggregation call.
+ *
+ * Mirrors `dspy.MultiChainComparison` in Python.
+ */
+declare class MultiChainComparison extends Module {
+    #private;
+    readonly M: number;
+    constructor(signature: string | Signature, M?: number);
+    forward(inputs: Record<string, unknown>): Promise<Prediction>;
+}
+
+/** A callable tool that ReAct can invoke. */
+interface Tool {
+    /** Short unique name used in `Action: toolName[args]` syntax. */
+    name: string;
+    /** One-sentence description shown in the system prompt. */
+    description: string;
+    /** Async function that the tool executes. */
+    fn: (args: string) => Promise<string>;
+}
+/**
+ * ReAct (Reasoning + Acting) module that interleaves Thought, Action, and
+ * Observation steps in a loop until a `Finish` action is emitted.
+ *
+ * Mirrors `dspy.ReAct` in Python.
+ *
+ * @example
+ * ```ts
+ * const react = new ReAct("question -> answer", [searchTool]);
+ * const result = await react.forward({ question: "Who won the 2024 Olympics?" });
+ * ```
+ */
+declare class ReAct extends Module {
+    #private;
+    readonly tools: ReadonlyMap<string, Tool>;
+    readonly maxIter: number;
+    constructor(signature: string | Signature, tools: Tool[], maxIter?: number);
+    forward(inputs: Record<string, unknown>): Promise<Prediction>;
+}
+
+/**
+ * Generates JavaScript code to answer a question, executes it in a sandboxed
+ * manner, and returns the result.
+ *
+ * Mirrors `dspy.ProgramOfThought` in Python.
+ *
+ * ⚠️  Security: code runs inside the same process via `new Function()` with a
+ * configurable wall-clock timeout (default 5 s).  The timeout prevents
+ * indefinite hangs but does **not** prevent access to Node.js APIs or the
+ * global scope.  Do NOT use with untrusted inputs in production without
+ * an additional sandboxing layer (e.g. a Worker thread with a restricted
+ * `MessageChannel`).
+ */
+declare class ProgramOfThought extends Module {
+    #private;
+    readonly maxAttempts: number;
+    /** Wall-clock timeout (ms) for each code execution attempt. */
+    readonly timeoutMs: number;
+    readonly sandbox: "worker" | "function" | "none";
+    constructor(signature: string | Signature, maxAttempts?: number, timeoutMs?: number, sandbox?: "worker" | "function" | "none");
+    forward(inputs: Record<string, unknown>): Promise<Prediction>;
+}
+
+/**
+ * Retrieve module that calls the globally configured retriever.
+ *
+ * Mirrors `dspy.Retrieve` in Python.
+ *
+ * @example
+ * ```ts
+ * settings.configure({ rm: new ColBERTv2("http://colbert.host") });
+ * const retrieve = new Retrieve(3);
+ * const result = await retrieve.forward("What is DSPy?");
+ * console.log(result.get("passages")); // string[]
+ * ```
+ */
+declare class Retrieve extends Module {
+    readonly k: number;
+    constructor(k?: number);
+    forward(query: string): Promise<Prediction>;
+}
+
+/**
+ * Wraps any module and retries on {@link AssertionError} up to `maxAttempts`,
+ * feeding the failure message back into the next attempt.
+ *
+ * Mirrors `dspy.Retry` in Python.
+ */
+declare class Retry extends Module {
+    #private;
+    readonly maxAttempts: number;
+    constructor(inner: Module, maxAttempts?: number);
+    forward(...args: unknown[]): Promise<Prediction>;
+}
+
+/**
+ * Runs `N` copies of a module in parallel and selects the best output via a
+ * provided `reduceFunc` (defaults to returning the first result).
+ *
+ * Mirrors `dspy.BestOfN` in Python.
+ */
+declare class BestOfN extends Module {
+    #private;
+    readonly N: number;
+    constructor(inner: Module, N?: number, reduceFunc?: (predictions: Prediction[]) => Prediction);
+    forward(...args: unknown[]): Promise<Prediction>;
+}
+
+/**
+ * Combines multiple modules into one via a voting or custom reduce function.
+ *
+ * Mirrors `dspy.Ensemble` (optimizer version) when used as a module.
+ */
+declare class Ensemble extends Module {
+    #private;
+    constructor(modules: Module[], reduceFunc?: (predictions: Prediction[]) => Prediction);
+    forward(...args: unknown[]): Promise<Prediction>;
+}
+
+/**
+ * A Prediction that additionally carries a typed `.typed` field.
+ */
+declare class TypedPrediction<T = unknown> extends Prediction {
+    readonly typed: T;
+    constructor(data: Record<string, unknown>, typed: T, completions?: Record<string, unknown>[]);
+}
+/**
+ * TypedPredictor — like Predict but appends JSON formatting instructions and
+ * parses the completion as JSON.  If an optional schema is provided,
+ * validates and returns `.typed`.
+ */
+declare class TypedPredictor<T = unknown> extends Predict {
+    #private;
+    constructor(signature: string | Signature, schema?: {
+        parse: (v: unknown) => T;
+    }, options?: {
+        maxRetries?: number;
+    });
+    forward(inputs: Record<string, unknown>): Promise<TypedPrediction<T>>;
+}
+/**
+ * TypedChainOfThought — like TypedPredictor but adds a hidden rationale field
+ * so the LM reasons before producing the answer.
+ */
+declare class TypedChainOfThought<T = unknown> extends TypedPredictor<T> {
+    constructor(signature: string | Signature, schema?: {
+        parse: (v: unknown) => T;
+    }, options?: {
+        maxRetries?: number;
+    });
+    forward(inputs: Record<string, unknown>): Promise<TypedPrediction<T>>;
+}
+
+/**
+ * Runs multiple modules in parallel and returns all their results.
+ *
+ * Note: `forward()` returns the first prediction for Module interface
+ * compatibility.  Use `run()` to get all predictions.
+ */
+declare class Parallel extends Module {
+    #private;
+    constructor(modules: Module[], options?: {
+        timeoutMs?: number;
+    });
+    /** Run all modules in parallel and return all predictions. */
+    run(...args: unknown[]): Promise<Prediction[]>;
+    /** For Module interface compatibility — returns first prediction. */
+    forward(...args: unknown[]): Promise<Prediction>;
+}
+
+interface RefineOptions {
+    /** Maximum refinement iterations (default: 2). */
+    maxRefinements?: number;
+    /** Field name for feedback in the inner module re-run (default: "feedback"). */
+    feedbackField?: string;
+    /** If returns true, stop refining early. */
+    stopCondition?: (prediction: Prediction) => boolean;
+}
+/**
+ * Self-critique / iterative refinement loop.
+ *
+ * Runs the inner module, then uses a Predict critic to score the output.
+ * If the output is not satisfactory, feeds critique back and re-runs.
+ */
+declare class Refine extends Module {
+    #private;
+    constructor(inner: Module, options?: RefineOptions);
+    forward(...args: unknown[]): Promise<Prediction>;
+}
+
+/**
+ * ReAct variant that uses provider-native tool/function calling instead of
+ * text-based action parsing.
+ *
+ * For OpenAI models, this uses function calling (tools API). For Anthropic, it
+ * uses tool_use. Other adapters fall back to the text-based ReAct format.
+ *
+ * @example
+ * ```ts
+ * const tools: Tool[] = [{ name: "search", description: "Search", fn: search }];
+ * const agent = new NativeReAct("question -> answer", tools);
+ * const result = await agent.forward({ question: "What is the capital of France?" });
+ * ```
+ */
+declare class NativeReAct extends Module {
+    #private;
+    readonly tools: ReadonlyMap<string, Tool>;
+    readonly maxIter: number;
+    constructor(signatureStr: string, tools: Tool[], maxIter?: number);
+    forward(inputs: Record<string, unknown>): Promise<Prediction>;
+}
+
+/**
+ * Abstract base class for all retrieval backends.
+ *
+ * Mirrors `dspy.Retrieve`'s underlying retriever protocol in Python.
+ */
+declare abstract class Retriever {
+    /**
+     * Retrieve the top-`k` passages relevant to `query`.
+     *
+     * @param query - The search query string.
+     * @param k     - Number of passages to return.
+     * @returns     An ordered array of passage strings (most relevant first).
+     */
+    abstract retrieve(query: string, k: number): Promise<string[]>;
+}
+
+/** Options for the ColBERTv2 retriever. */
+interface ColBERTv2Options {
+    /** Base URL of the ColBERT server. */
+    url: string;
+    /** Number of passages to request from the server (defaults to k). */
+    passages?: number;
+}
+/**
+ * Retriever that queries a ColBERTv2 REST endpoint.
+ *
+ * Mirrors `dspy.ColBERTv2` in Python.
+ */
+declare class ColBERTv2 extends Retriever {
+    #private;
+    constructor(options: ColBERTv2Options | string);
+    retrieve(query: string, k: number): Promise<string[]>;
+}
+
+/** Options for the Pinecone retriever. */
+interface PineconeRMOptions {
+    apiKey?: string;
+    indexName: string;
+    namespace?: string;
+    embeddingFn: (text: string) => Promise<number[]>;
+}
+/**
+ * Retriever backed by Pinecone vector database.
+ *
+ * Requires the `@pinecone-database/pinecone` package:
+ * ```
+ * npm install @pinecone-database/pinecone
+ * ```
+ */
+declare class PineconeRM extends Retriever {
+    #private;
+    constructor(options: PineconeRMOptions);
+    retrieve(query: string, k: number): Promise<string[]>;
+}
+
+/** Options for the Weaviate retriever. */
+interface WeaviateRMOptions {
+    url: string;
+    apiKey?: string;
+    /** The Weaviate class/collection to query. */
+    className: string;
+    /** Property name that holds the passage text. */
+    textProperty?: string;
+    embeddingFn: (text: string) => Promise<number[]>;
+}
+/**
+ * Retriever backed by Weaviate vector database.
+ *
+ * Requires the `weaviate-client` package:
+ * ```
+ * npm install weaviate-client
+ * ```
+ */
+declare class WeaviateRM extends Retriever {
+    #private;
+    constructor(options: WeaviateRMOptions);
+    retrieve(query: string, k: number): Promise<string[]>;
+}
+
+/** Options for the ChromaDB retriever. */
+interface ChromadbRMOptions {
+    /** ChromaDB server URL (default: http://localhost:8000). */
+    url?: string;
+    collectionName: string;
+    embeddingFn?: (texts: string[]) => Promise<number[][]>;
+}
+/**
+ * Retriever backed by ChromaDB.
+ *
+ * Requires the `chromadb` package:
+ * ```
+ * npm install chromadb
+ * ```
+ */
+declare class ChromadbRM extends Retriever {
+    #private;
+    constructor(options: ChromadbRMOptions);
+    retrieve(query: string, k: number): Promise<string[]>;
+}
+
+/** Options for the Qdrant retriever. */
+interface QdrantRMOptions {
+    url?: string;
+    apiKey?: string;
+    collectionName: string;
+    /** Property name that holds the passage text in the payload. */
+    textField?: string;
+    embeddingFn: (text: string) => Promise<number[]>;
+}
+/**
+ * Retriever backed by Qdrant vector database.
+ *
+ * Requires the `@qdrant/js-client-rest` package:
+ * ```
+ * npm install @qdrant/js-client-rest
+ * ```
+ */
+declare class QdrantRM extends Retriever {
+    #private;
+    constructor(options: QdrantRMOptions);
+    retrieve(query: string, k: number): Promise<string[]>;
+}
+
+/** Options for the FAISS retriever. */
+interface FaissRMOptions {
+    /** Array of passage strings (the corpus). */
+    passages: string[];
+    /**
+     * Pre-computed embeddings (one per passage, in the same order as `passages`).
+     * When omitted, embeddings are computed lazily on the first `retrieve()` call
+     * using `embeddingFn` and cached for subsequent calls.
+     */
+    embeddings?: number[][];
+    /**
+     * Function that maps a text string to a dense embedding vector.
+     * Required for computing the query embedding (and passage embeddings when
+     * `embeddings` is not pre-supplied).
+     */
+    embeddingFn: (text: string) => Promise<number[]>;
+}
+/**
+ * In-process FAISS-style retriever using cosine similarity over dense
+ * embeddings.  No external server required.
+ *
+ * For large corpora, consider using the `faiss-node` package instead.
+ */
+declare class FaissRM extends Retriever {
+    #private;
+    constructor(options: FaissRMOptions);
+    retrieve(query: string, k: number): Promise<string[]>;
+}
+
+/** Options for the You.com retriever. */
+interface YouRMOptions {
+    apiKey?: string;
+    /** Number of snippets per web result to include (default: 1). */
+    numWeb?: number;
+}
+/**
+ * Retriever backed by the You.com search API.
+ */
+declare class YouRM extends Retriever {
+    #private;
+    constructor(options?: YouRMOptions);
+    retrieve(query: string, k: number): Promise<string[]>;
+}
+
+/**
+ * In-memory retriever for unit testing.
+ *
+ * Returns passages that contain the query string (case-insensitive), or the
+ * first `k` passages if no matches are found.
+ */
+declare class MockRetriever extends Retriever {
+    #private;
+    constructor(passages: string[]);
+    retrieve(query: string, k: number): Promise<string[]>;
+}
+
+/**
+ * A metric function receives an example, a prediction, and optionally the
+ * execution trace, and returns a score (number) or a pass/fail (boolean).
+ *
+ * Mirrors `dspy.Metric` in Python.
+ */
+type Metric = (example: Example, prediction: Prediction, trace?: Trace[]) => number | boolean;
+/** Per-example evaluation result. */
+interface ExampleResult {
+    example: Example;
+    prediction: Prediction;
+    score: number;
+    passed: boolean;
+}
+/** Aggregated result returned by {@link evaluate}. */
+interface EvaluationResult {
+    /** Average metric score across all examples. */
+    score: number;
+    /** Number of examples that passed (score > 0 / true). */
+    numPassed: number;
+    /** Total number of examples. */
+    total: number;
+    /** Per-example breakdown. */
+    results: ExampleResult[];
+}
+
+/** Options for the {@link evaluate} function. */
+interface EvaluateOptions {
+    /**
+     * Number of concurrent evaluations (default: 1 — sequential).
+     * Set > 1 to parallelise calls.
+     */
+    numThreads?: number;
+    /** When true, logs per-example results to the console. */
+    displayProgress?: boolean;
+}
+/**
+ * Evaluate a `program` (any {@link Module}) on a set of `examples` using a
+ * `metric` function.
+ *
+ * Mirrors `dspy.Evaluate` in Python.
+ *
+ * @example
+ * ```ts
+ * const result = await evaluate(rag, devset, exactMatch("answer"));
+ * console.log(`Score: ${result.score.toFixed(2)}`);
+ * ```
+ */
+declare function evaluate(program: Module, examples: Example[], metric: Metric, options?: EvaluateOptions): Promise<EvaluationResult>;
+
+/**
+ * Returns 1 if the prediction's `field` exactly matches the example's `field`
+ * (case-insensitive by default), 0 otherwise.
+ */
+declare function exactMatch(field?: string, caseSensitive?: boolean): Metric;
+/**
+ * Token-level F1 metric (word overlap), commonly used for SQuAD-style QA.
+ */
+declare function f1(field?: string): Metric;
+/**
+ * Returns 1 if at least one of the top-`k` completions passes the `innerMetric`.
+ */
+declare function passAtK(innerMetric: Metric, k: number): Metric;
+/**
+ * Simplified BLEU score (1-gram + 2-gram precision) for a single field.
+ */
+declare function bleu(field?: string): Metric;
+/**
+ * ROUGE-L metric (LCS-based recall/precision/F1) for a single field.
+ */
+declare function rouge(field?: string): Metric;
+
+/**
+ * Abstract base class for all DSTsx optimizers (teleprompters).
+ *
+ * An optimizer takes a student program and a training set, then returns a new
+ * (optimized) program with better prompts / few-shot examples.
+ *
+ * Mirrors `dspy.Teleprompter` in Python.
+ */
+declare abstract class Optimizer {
+    /**
+     * Compile (optimize) a `student` program.
+     *
+     * @param student  - The module to optimize (must not be mutated).
+     * @param trainset - Examples used to generate / score candidates.
+     * @param metric   - Function that scores a prediction.
+     * @returns        - A new, optimized copy of `student`.
+     */
+    abstract compile(student: Module, trainset: Example[], metric: Metric): Promise<Module>;
+}
+
+/**
+ * The simplest optimizer — directly assigns labeled examples as `demos` on
+ * every `Predict` sub-module without running the LM at all.
+ *
+ * Mirrors `dspy.LabeledFewShot` in Python.
+ */
+declare class LabeledFewShot extends Optimizer {
+    #private;
+    /**
+     * @param k - Maximum number of demos to assign per predictor (default: 16).
+     */
+    constructor(k?: number);
+    compile(student: Module, trainset: Example[], _metric: Metric): Promise<Module>;
+}
+
+/** Options for BootstrapFewShot. */
+interface BootstrapFewShotOptions {
+    /** Maximum number of bootstrapped demos per predictor (default: 4). */
+    maxBootstrappedDemos?: number;
+    /** Maximum number of labeled demos per predictor (default: 16). */
+    maxLabeledDemos?: number;
+    /** Optional teacher module; defaults to the student. */
+    teacher?: Module;
+}
+/**
+ * Collects successful execution traces by running the student (or a teacher)
+ * on the training set and uses them as few-shot demonstrations.
+ *
+ * Mirrors `dspy.BootstrapFewShot` in Python.
+ */
+declare class BootstrapFewShot extends Optimizer {
+    #private;
+    constructor(options?: BootstrapFewShotOptions);
+    compile(student: Module, trainset: Example[], metric: Metric): Promise<Module>;
+}
+
+/** Options for BootstrapFewShotWithRandomSearch. */
+interface BootstrapFewShotWithRandomSearchOptions extends BootstrapFewShotOptions {
+    /** Number of candidate demo subsets to evaluate (default: 8). */
+    numCandidatePrograms?: number;
+    /** Held-out validation set. If omitted, the trainset is used for scoring. */
+    valset?: Example[];
+}
+/**
+ * Extends {@link BootstrapFewShot} by trying multiple random demo subsets and
+ * selecting the combination with the highest validation score.
+ *
+ * Mirrors `dspy.BootstrapFewShotWithRandomSearch` in Python.
+ */
+declare class BootstrapFewShotWithRandomSearch extends BootstrapFewShot {
+    #private;
+    constructor(options?: BootstrapFewShotWithRandomSearchOptions);
+    compile(student: Module, trainset: Example[], metric: Metric): Promise<Module>;
+}
+
+interface BootstrapFewShotWithOptunaOptions {
+    maxBootstrappedDemos?: number;
+    maxLabeledDemos?: number;
+    /** Number of TPE trials (default: 20). */
+    numTrials?: number;
+    valset?: Example[];
+}
+/**
+ * Bayesian optimizer using a simplified TPE (Tree-structured Parzen Estimator).
+ *
+ * Extends BootstrapFewShot: first collects candidate demos via the parent,
+ * then runs `numTrials` iterations sampling demo subsets using TPE to find
+ * the best-scoring configuration.
+ */
+declare class BootstrapFewShotWithOptuna extends BootstrapFewShot {
+    #private;
+    constructor(options?: BootstrapFewShotWithOptunaOptions);
+    compile(student: Module, trainset: Example[], metric: Metric): Promise<Module>;
+}
+
+/** Options for COPRO. */
+interface COPROOptions {
+    /** Number of instruction candidates to generate per predictor (default: 5). */
+    breadth?: number;
+    /** Number of refinement rounds (default: 3). */
+    depth?: number;
+}
+/**
+ * Collaborative Prompt Optimizer (COPRO) — uses the LM to propose improved
+ * instructions for each `Predict` sub-module and selects the best via
+ * metric evaluation.
+ *
+ * Mirrors `dspy.COPRO` in Python.
+ */
+declare class COPRO extends Optimizer {
+    #private;
+    constructor(options?: COPROOptions);
+    compile(student: Module, trainset: Example[], metric: Metric): Promise<Module>;
+}
+
+/** Options for MIPRO. */
+interface MIPROOptions {
+    /** Number of instruction candidates per predictor (default: 5). */
+    numCandidates?: number;
+    /** Temperature for instruction generation (default: 0.9). */
+    initTemperature?: number;
+    /** Number of random bootstrap candidate programs to evaluate (default: 8). */
+    numCandidatePrograms?: number;
+    /** Emit verbose progress logs (default: false). */
+    verbose?: boolean;
+}
+/**
+ * Multi-stage Instruction Prompt Optimizer (MIPRO) — combines COPRO-style
+ * instruction proposal with BootstrapFewShotWithRandomSearch to jointly
+ * optimize instructions and demonstrations.
+ *
+ * Mirrors `dspy.MIPRO` in Python.
+ */
+declare class MIPRO extends Optimizer {
+    #private;
+    constructor(options?: MIPROOptions);
+    compile(student: Module, trainset: Example[], metric: Metric): Promise<Module>;
+}
+
+/** Options for KNNFewShot. */
+interface KNNFewShotOptions {
+    /** Number of nearest neighbors to use as demos (default: 3). */
+    k?: number;
+    /**
+     * Embedding function that maps a text string to a dense vector.
+     * Required for computing similarity between examples.
+     */
+    embeddingFn: (text: string) => Promise<number[]>;
+    /**
+     * Which field of each example to embed for similarity comparison
+     * (default: first input field of the signature).
+     */
+    keyField?: string;
+}
+/**
+ * Dynamic few-shot optimizer that selects demonstrations at inference time
+ * using k-nearest-neighbour search over the training set.
+ *
+ * Unlike static few-shot optimizers this one injects demos into a
+ * `Predict.forward` call by wrapping each predictor at compile time.
+ *
+ * Mirrors `dspy.KNNFewShot` in Python.
+ */
+declare class KNNFewShot extends Optimizer {
+    #private;
+    constructor(options: KNNFewShotOptions);
+    compile(student: Module, trainset: Example[], _metric: Metric): Promise<Module>;
+}
+
+/** Options for the Ensemble optimizer. */
+interface EnsembleOptimizerOptions {
+    /**
+     * Custom function to combine multiple predictions into one.
+     * Defaults to majority vote on the first output field.
+     */
+    reduceFunc?: (predictions: Prediction[]) => Prediction;
+}
+/**
+ * Combines multiple optimized programs into a single ensemble module.
+ *
+ * Mirrors `dspy.Ensemble` (optimizer version) in Python.
+ */
+declare class EnsembleOptimizer extends Optimizer {
+    #private;
+    constructor(options?: EnsembleOptimizerOptions);
+    compile(student: Module, _trainset: Example[], _metric: Metric): Promise<Module>;
+}
+
+/** Output format for the exported fine-tuning data. */
+type FinetuneFormat = "openai" | "generic";
+/** Options for BootstrapFinetune. */
+interface BootstrapFinetuneOptions {
+    /** Path to write the JSONL fine-tuning file (default: "./finetune_data.jsonl"). */
+    exportPath?: string | undefined;
+    /** Format of the exported data (default: "openai"). */
+    format?: FinetuneFormat | undefined;
+    /** Bootstrap options passed to BootstrapFewShot internally. */
+    maxBootstrappedDemos?: number | undefined;
+}
+/**
+ * Collects LM traces via BootstrapFewShot and exports them as a JSONL file
+ * suitable for fine-tuning.
+ *
+ * - `"openai"` format: `{ messages: [{role, content}, ...] }` per line
+ * - `"generic"` format: `{ prompt: string, completion: string }` per line
+ *
+ * @example
+ * ```ts
+ * const optimizer = new BootstrapFinetune({
+ *   exportPath: "./finetune_data.jsonl",
+ *   format: "openai",
+ * });
+ * const recipe = await optimizer.compile(program, trainset, metric);
+ * ```
+ */
+declare class BootstrapFinetune extends Optimizer {
+    #private;
+    constructor(options?: BootstrapFinetuneOptions);
+    compile(student: Module, trainset: Example[], metric: Metric): Promise<Module>;
+}
+
+/** Options for GRPO. */
+interface GRPOOptions {
+    /** Number of optimization steps (default: 20). */
+    numSteps?: number | undefined;
+    /** Number of candidates per group per step (default: 8). */
+    groupSize?: number | undefined;
+    /** Sampling temperature for candidate generation (default: 1.0). */
+    temperature?: number | undefined;
+    /** Max labeled demos (default: 16). */
+    maxLabeledDemos?: number | undefined;
+}
+/**
+ * Group Relative Policy Optimization optimizer.
+ *
+ * Mirrors `dspy.GRPO` in Python. Runs `numSteps` iterations where each step:
+ * 1. Samples `groupSize` candidate instruction variants via the LM.
+ * 2. Evaluates each against the training set.
+ * 3. Updates the best instruction using group-relative scoring.
+ *
+ * Pure TypeScript — no external dependencies beyond the configured LM.
+ */
+declare class GRPO extends Optimizer {
+    #private;
+    constructor(options?: GRPOOptions);
+    compile(student: Module, trainset: Example[], metric: Metric): Promise<Module>;
+}
+
+/** Options for SIMBA. */
+interface SIMBAOptions {
+    /** Number of optimization iterations (default: 10). */
+    numIter?: number | undefined;
+    /** Mini-batch size for each evaluation (default: 8). */
+    batchSize?: number | undefined;
+    /** Max bootstrapped demos (default: 4). */
+    maxBootstrappedDemos?: number | undefined;
+}
+/**
+ * SIMBA (Stochastic Introspective Mini-Batch Ascent) optimizer.
+ *
+ * A lightweight stochastic optimizer that:
+ * 1. Selects a random mini-batch from the training set each iteration.
+ * 2. Proposes a candidate (via demo subset sampling).
+ * 3. Accepts the candidate if it improves on the current best.
+ * 4. Returns the overall best module found.
+ */
+declare class SIMBA extends Optimizer {
+    #private;
+    constructor(options?: SIMBAOptions);
+    compile(student: Module, trainset: Example[], metric: Metric): Promise<Module>;
+}
+
+/** Options for AvatarOptimizer. */
+interface AvatarOptimizerOptions {
+    /** Number of avatar candidates to try per predictor (default: 4). */
+    numAvatars?: number | undefined;
+    /** Max labeled demos (default: 8). */
+    maxLabeledDemos?: number | undefined;
+}
+/**
+ * AvatarOptimizer iteratively proposes and evaluates "avatar" role descriptions
+ * (persona prefixes) for each Predict module.
+ *
+ * Mirrors `dspy.AvatarOptimizer` in Python.
+ *
+ * For each predictor, proposes `numAvatars` different role/persona descriptions
+ * and selects the one that scores highest on the training set.
+ */
+declare class AvatarOptimizer extends Optimizer {
+    #private;
+    constructor(options?: AvatarOptimizerOptions);
+    compile(student: Module, trainset: Example[], metric: Metric): Promise<Module>;
+}
+
+/**
+ * A typed error thrown by {@link Assert} when a condition is not met.
+ *
+ * {@link Retry} catches this error and feeds the message back into the next
+ * attempt as feedback.
+ */
+declare class AssertionError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Hard assertion — throws an {@link AssertionError} if `condition` is falsy.
+ * Caught and retried by the {@link Retry} module.
+ *
+ * Mirrors `dspy.Assert` in Python.
+ *
+ * @example
+ * ```ts
+ * Assert(result.get("answer") !== "", "Answer must not be empty");
+ * ```
+ */
+declare function Assert(condition: unknown, message?: string): asserts condition;
+
+/**
+ * Soft suggestion — logs a warning if `condition` is falsy but does NOT throw.
+ *
+ * Mirrors `dspy.Suggest` in Python.
+ *
+ * @example
+ * ```ts
+ * Suggest(result.get("confidence") === "high", "Low confidence in answer");
+ * ```
+ */
+declare function Suggest(condition: unknown, message?: string): void;
+
+/** Configuration options for the global DSTsx settings. */
+interface SettingsOptions {
+    /** Default language model used by all Predict modules. */
+    lm?: LM;
+    /** Default retrieval model used by the Retrieve module. */
+    rm?: Retriever;
+    /** Default LM call configuration (temperature, maxTokens, etc.). */
+    lmConfig?: LMCallConfig;
+    /** Log level for internal messages. */
+    logLevel?: "silent" | "error" | "warn" | "info" | "debug";
+    /** Directory for caching compiled programs (JSON). */
+    cacheDir?: string;
+}
+/**
+ * Global settings singleton for DSTsx.
+ *
+ * Configure the default LM and retriever before using any modules:
+ * ```ts
+ * import { settings } from "dstsx";
+ * import { OpenAI } from "dstsx";
+ *
+ * settings.configure({ lm: new OpenAI({ model: "gpt-4o" }) });
+ * ```
+ *
+ * Use {@link Settings.context} for per-request overrides in server environments.
+ * Each invocation gets an isolated async context via `AsyncLocalStorage`, so
+ * concurrent overlapping requests never interfere with each other:
+ * ```ts
+ * await settings.context({ lm: perRequestLM }, async () => {
+ *   return program.forward({ question });
+ * });
+ * ```
+ */
+declare class Settings {
+    #private;
+    get lm(): LM | undefined;
+    get rm(): Retriever | undefined;
+    get lmConfig(): LMCallConfig | undefined;
+    get logLevel(): SettingsOptions["logLevel"];
+    get cacheDir(): string | undefined;
+    /**
+     * 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: SettingsOptions): void;
+    /**
+     * Reset all global settings to their defaults.
+     */
+    reset(): void;
+    /**
+     * Return a deep-frozen snapshot of the currently effective settings
+     * (respects any active async-context overrides).
+     */
+    inspect(): Readonly<SettingsOptions>;
+    /**
+     * 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));
+     * ```
+     */
+    context<T>(overrides: SettingsOptions, fn: () => Promise<T>): Promise<T>;
+}
+/** The global DSTsx settings singleton. */
+declare const settings: Settings;
+
+interface MCPAdapterOptions {
+    serverUrl?: string;
+    tools?: Array<{
+        name: string;
+        description: string;
+        inputSchema: Record<string, unknown>;
+    }>;
+    callHandler?: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Wraps MCP server tools as DSTsx Tool objects.
+ *
+ * When `tools` + `callHandler` are provided, no network connection is needed.
+ * A live MCP connection (via `serverUrl`) requires the
+ * `@modelcontextprotocol/sdk` package to be installed.
+ */
+declare class MCPToolAdapter {
+    #private;
+    constructor(options?: MCPAdapterOptions);
+    getTools(): Promise<Tool[]>;
+}
+
+interface MCPTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description?: string;
+        }>;
+        required?: string[];
+    };
+    handler: (inputs: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Exposes DSTsx modules as MCP-compatible tool definitions.
+ *
+ * Registered modules can be called via `callTool()`.  To create a live stdio
+ * server the `@modelcontextprotocol/sdk` package must be installed.
+ */
+declare class DSTsxMCPServer {
+    #private;
+    registerModule(name: string, description: string, module: Module, inputFields: string[]): this;
+    getToolDefinitions(): MCPTool[];
+    callTool(name: string, inputs: Record<string, unknown>): Promise<unknown>;
+    createStdioServer(): Promise<unknown>;
+}
+
+/** Event types emitted during optimization. */
+interface TrackerEvent {
+    /** Type of event. */
+    type: "step" | "trial" | "best" | "done";
+    /** Current step number. */
+    step?: number | undefined;
+    /** Score at this event. */
+    score?: number | undefined;
+    /** Additional metadata. */
+    metadata?: Record<string, unknown> | undefined;
+}
+/**
+ * Abstract base class for experiment trackers.
+ *
+ * Implement this to log optimization events to console, files, or external
+ * experiment tracking services.
+ */
+declare abstract class Tracker {
+    /** Log a single event. */
+    abstract log(event: TrackerEvent): void;
+    /** Flush any buffered events (e.g. write to disk). */
+    abstract flush(): Promise<void>;
+}
+
+/**
+ * A simple tracker that logs events to the console.
+ */
+declare class ConsoleTracker extends Tracker {
+    log(event: TrackerEvent): void;
+    flush(): Promise<void>;
+}
+
+/**
+ * A tracker that appends JSON-encoded events as lines to a file.
+ *
+ * @example
+ * ```ts
+ * const tracker = new JsonFileTracker("./runs/experiment1.jsonl");
+ * const optimizer = new GRPO({ numSteps: 10 });
+ * ```
+ */
+declare class JsonFileTracker extends Tracker {
+    #private;
+    constructor(path: string);
+    log(event: TrackerEvent): void;
+    flush(): Promise<void>;
+}
+
+export { Anthropic, type AnthropicOptions, Assert, AssertionError, AvatarOptimizer, type AvatarOptimizerOptions, BestOfN, BootstrapFewShot, type BootstrapFewShotOptions, BootstrapFewShotWithOptuna, type BootstrapFewShotWithOptunaOptions, BootstrapFewShotWithRandomSearch, type BootstrapFewShotWithRandomSearchOptions, BootstrapFinetune, type BootstrapFinetuneOptions, COPRO, type COPROOptions, ChainOfThought, ChainOfThoughtWithHint, ChromadbRM, type ChromadbRMOptions, Cohere, type CohereOptions, ColBERTv2, type ColBERTv2Options, ConsoleTracker, DSTsxMCPServer, DiskCache, Ensemble, EnsembleOptimizer, type EnsembleOptimizerOptions, type EvaluateOptions, type EvaluationResult, Example, type ExampleResult, FaissRM, type FaissRMOptions, type FieldMeta, type FinetuneFormat, GRPO, type GRPOOptions, GoogleAI, type GoogleAIOptions, HuggingFace, type HuggingFaceOptions, Image, type ImageMimeType, InputField, JsonFileTracker, KNNFewShot, type KNNFewShotOptions, LM, type LMCallConfig, type LMResponse, LMStudio, type LMStudioOptions, LRUCache, LabeledFewShot, type MCPAdapterOptions, type MCPTool, MCPToolAdapter, MIPRO, type MIPROOptions, type Message, type Metric, MockLM, MockRetriever, Module, MultiChainComparison, NativeReAct, Ollama, type OllamaOptions, OpenAI, type OpenAIOptions, Optimizer, OutputField, Parallel, PineconeRM, type PineconeRMOptions, Predict, Prediction, ProgramOfThought, QdrantRM, type QdrantRMOptions, ReAct, Refine, type RefineOptions, Retrieve, Retriever, Retry, SIMBA, type SIMBAOptions, Settings, type SettingsOptions, Signature, type SignatureMeta, type StreamChunk, Suggest, type TokenUsage, type Tool, type Trace, Tracker, type TrackerEvent, TypedChainOfThought, TypedPrediction, TypedPredictor, WeaviateRM, type WeaviateRMOptions, YouRM, type YouRMOptions, bleu, evaluate, exactMatch, f1, majority, passAtK, rouge, settings };