@jaex/dstsx 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -231,6 +231,8 @@ interface LMCallConfig {
     stop?: string[];
     /** Number of completions to generate (default 1). */
     n?: number;
+    /** Opt-in to prompt caching API if the provider supports it (e.g. Anthropic `cache_control`). */
+    promptCaching?: boolean;
     /**
      * Optional cache key override.  When provided the cache uses this key
      * instead of hashing the prompt.
@@ -250,6 +252,8 @@ interface LMResponse {
         promptTokens: number;
         completionTokens: number;
         totalTokens: number;
+        /** Cached input tokens read by the provider (e.g. OpenAI cached_tokens, Anthropic cache_read_input_tokens). */
+        cachedPromptTokens?: number;
     } | null;
     /** Raw provider response (opaque). */
     raw: unknown;
@@ -296,6 +300,7 @@ declare abstract class LM {
         promptTokens: number;
         completionTokens: number;
         totalTokens: number;
+        cachedPromptTokens: number;
     }>;
     /** Clear the in-memory response cache. */
     clearCache(): void;
@@ -374,6 +379,8 @@ interface AnthropicOptions {
     apiKey?: string;
     model?: string;
     maxRetries?: number;
+    /** Whether to enable prompt caching up-front. */
+    promptCaching?: boolean;
 }
 /**
  * LM adapter for Anthropic Claude models.
@@ -500,11 +507,24 @@ declare class MockLM extends LM {
     addResponse(prompt: string, response: string): void;
 }
 
+/**
+ * The return type of {@link Module.forward} — either a single prediction or
+ * an array of predictions for modules that produce multiple outputs (e.g.
+ * {@link Parallel}).
+ */
+type ModuleOutput = Prediction | Prediction[];
+/**
+ * Extracts the first {@link Prediction} from a {@link ModuleOutput}.
+ *
+ * Useful when consuming an unknown module whose `forward()` may return either
+ * a single prediction or an array.
+ */
+declare function firstPrediction(result: ModuleOutput): Prediction;
 /**
  * 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
+ * language model calls.  Subclasses implement {@link Module["forward"]} to define
  * their behaviour.
  *
  * Mirrors `dspy.Module` in Python.
@@ -528,8 +548,13 @@ declare abstract class Module {
      *
      * Subclasses define their own parameter signatures; the base type uses
      * `unknown` so that TypeScript accepts any subclass override.
+     *
+     * The return value is {@link ModuleOutput} — a single {@link Prediction} for
+     * most modules, or a `Prediction[]` for multi-output modules such as
+     * {@link Parallel}.  Use {@link firstPrediction} to safely extract the first
+     * result when consuming an unknown module.
      */
-    abstract forward(...args: unknown[]): Promise<Prediction>;
+    abstract forward(...args: unknown[]): Promise<ModuleOutput>;
     /**
      * Recursively discover all {@link Predict} sub-modules by walking the own
      * enumerable properties of this instance.
@@ -628,7 +653,6 @@ declare class ChainOfThoughtWithHint extends ChainOfThought {
     constructor(signature: string | Signature, options?: {
         rationaleDescription?: string;
     });
-    forward(inputs: Record<string, unknown>): Promise<Prediction>;
 }
 
 /**
@@ -787,20 +811,28 @@ declare class TypedChainOfThought<T = unknown> extends TypedPredictor<T> {
 }
 
 /**
- * Runs multiple modules in parallel and returns all their results.
+ * Runs multiple modules in parallel and returns all their results as a
+ * `Prediction[]`.
  *
- * Note: `forward()` returns the first prediction for Module interface
- * compatibility.  Use `run()` to get all predictions.
+ * Because `forward()` now returns `Prediction[]`, consumers can use the
+ * results directly without needing the separate `run()` method.  `run()` is
+ * retained as a more explicit, named alternative.
  */
 declare class Parallel extends Module {
     #private;
     constructor(modules: Module[], options?: {
         timeoutMs?: number;
     });
-    /** Run all modules in parallel and return all predictions. */
+    /**
+     * Run all modules in parallel and return one {@link Prediction} per module.
+     * If a module's `forward()` returns multiple predictions, the first is used.
+     */
     run(...args: unknown[]): Promise<Prediction[]>;
-    /** For Module interface compatibility — returns first prediction. */
-    forward(...args: unknown[]): Promise<Prediction>;
+    /**
+     * Execute all modules in parallel and return all predictions as an array
+     * (one entry per module).
+     */
+    forward(...args: unknown[]): Promise<Prediction[]>;
 }
 
 interface RefineOptions {
@@ -1594,4 +1626,4 @@ declare class JsonFileTracker extends Tracker {
     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 };
+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, type ModuleOutput, 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, firstPrediction, majority, passAtK, rouge, settings };

package/dist/index.d.ts

@@ -231,6 +231,8 @@ interface LMCallConfig {
     stop?: string[];
     /** Number of completions to generate (default 1). */
     n?: number;
+    /** Opt-in to prompt caching API if the provider supports it (e.g. Anthropic `cache_control`). */
+    promptCaching?: boolean;
     /**
      * Optional cache key override.  When provided the cache uses this key
      * instead of hashing the prompt.
@@ -250,6 +252,8 @@ interface LMResponse {
         promptTokens: number;
         completionTokens: number;
         totalTokens: number;
+        /** Cached input tokens read by the provider (e.g. OpenAI cached_tokens, Anthropic cache_read_input_tokens). */
+        cachedPromptTokens?: number;
     } | null;
     /** Raw provider response (opaque). */
     raw: unknown;
@@ -296,6 +300,7 @@ declare abstract class LM {
         promptTokens: number;
         completionTokens: number;
         totalTokens: number;
+        cachedPromptTokens: number;
     }>;
     /** Clear the in-memory response cache. */
     clearCache(): void;
@@ -374,6 +379,8 @@ interface AnthropicOptions {
     apiKey?: string;
     model?: string;
     maxRetries?: number;
+    /** Whether to enable prompt caching up-front. */
+    promptCaching?: boolean;
 }
 /**
  * LM adapter for Anthropic Claude models.
@@ -500,11 +507,24 @@ declare class MockLM extends LM {
     addResponse(prompt: string, response: string): void;
 }
 
+/**
+ * The return type of {@link Module.forward} — either a single prediction or
+ * an array of predictions for modules that produce multiple outputs (e.g.
+ * {@link Parallel}).
+ */
+type ModuleOutput = Prediction | Prediction[];
+/**
+ * Extracts the first {@link Prediction} from a {@link ModuleOutput}.
+ *
+ * Useful when consuming an unknown module whose `forward()` may return either
+ * a single prediction or an array.
+ */
+declare function firstPrediction(result: ModuleOutput): Prediction;
 /**
  * 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
+ * language model calls.  Subclasses implement {@link Module["forward"]} to define
  * their behaviour.
  *
  * Mirrors `dspy.Module` in Python.
@@ -528,8 +548,13 @@ declare abstract class Module {
      *
      * Subclasses define their own parameter signatures; the base type uses
      * `unknown` so that TypeScript accepts any subclass override.
+     *
+     * The return value is {@link ModuleOutput} — a single {@link Prediction} for
+     * most modules, or a `Prediction[]` for multi-output modules such as
+     * {@link Parallel}.  Use {@link firstPrediction} to safely extract the first
+     * result when consuming an unknown module.
      */
-    abstract forward(...args: unknown[]): Promise<Prediction>;
+    abstract forward(...args: unknown[]): Promise<ModuleOutput>;
     /**
      * Recursively discover all {@link Predict} sub-modules by walking the own
      * enumerable properties of this instance.
@@ -628,7 +653,6 @@ declare class ChainOfThoughtWithHint extends ChainOfThought {
     constructor(signature: string | Signature, options?: {
         rationaleDescription?: string;
     });
-    forward(inputs: Record<string, unknown>): Promise<Prediction>;
 }
 
 /**
@@ -787,20 +811,28 @@ declare class TypedChainOfThought<T = unknown> extends TypedPredictor<T> {
 }
 
 /**
- * Runs multiple modules in parallel and returns all their results.
+ * Runs multiple modules in parallel and returns all their results as a
+ * `Prediction[]`.
  *
- * Note: `forward()` returns the first prediction for Module interface
- * compatibility.  Use `run()` to get all predictions.
+ * Because `forward()` now returns `Prediction[]`, consumers can use the
+ * results directly without needing the separate `run()` method.  `run()` is
+ * retained as a more explicit, named alternative.
  */
 declare class Parallel extends Module {
     #private;
     constructor(modules: Module[], options?: {
         timeoutMs?: number;
     });
-    /** Run all modules in parallel and return all predictions. */
+    /**
+     * Run all modules in parallel and return one {@link Prediction} per module.
+     * If a module's `forward()` returns multiple predictions, the first is used.
+     */
     run(...args: unknown[]): Promise<Prediction[]>;
-    /** For Module interface compatibility — returns first prediction. */
-    forward(...args: unknown[]): Promise<Prediction>;
+    /**
+     * Execute all modules in parallel and return all predictions as an array
+     * (one entry per module).
+     */
+    forward(...args: unknown[]): Promise<Prediction[]>;
 }
 
 interface RefineOptions {
@@ -1594,4 +1626,4 @@ declare class JsonFileTracker extends Tracker {
     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 };
+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, type ModuleOutput, 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, firstPrediction, majority, passAtK, rouge, settings };