reasonix 0.0.3 → 0.0.5

package/dist/index.d.ts

@@ -172,6 +172,58 @@ declare function emptyPlanState(): TypedPlanState;
 declare function isPlanStateEmpty(s: TypedPlanState | null | undefined): boolean;
 declare function harvest(reasoningContent: string | null | undefined, client?: DeepSeekClient, options?: HarvestOptions): Promise<TypedPlanState>;
 
+/**
+ * Self-consistency branching.
+ *
+ * When enabled, the loop fans out into N parallel samples per turn (varied
+ * temperatures), runs Pillar 2 harvest on each, and selects the sample with
+ * the fewest flagged uncertainties (ties broken by answer length — a crude
+ * Occam prior).
+ *
+ * The unique opportunity here: because DeepSeek is ~20× cheaper than Claude,
+ * running N=3–5 samples per turn is still cheaper than a single Claude call,
+ * while the majority-confidence selection tends to dominate single-sample
+ * answers on fuzzy multi-step reasoning tasks.
+ */
+
+interface BranchSample {
+    index: number;
+    temperature: number;
+    response: ChatResponse;
+    planState: TypedPlanState;
+}
+type BranchSelector = (samples: BranchSample[]) => BranchSample;
+interface BranchOptions {
+    /** Number of parallel samples. 1 disables branching. Default 1. */
+    budget?: number;
+    /** Temperatures for each branch. Default spreads across [0, 1]. */
+    temperatures?: readonly number[];
+    /** Harvest options; the selector needs harvest to score samples. */
+    harvestOptions?: HarvestOptions;
+    /** Custom selector. Default: min uncertainties, tie-break shortest answer. */
+    selector?: BranchSelector;
+    /**
+     * Fires as each sample finishes (main call + harvest both complete).
+     * Useful for progress UI. Not awaited; exceptions are swallowed.
+     */
+    onSampleDone?: (sample: BranchSample) => void;
+}
+interface BranchResult {
+    chosen: BranchSample;
+    samples: BranchSample[];
+}
+/** Default: fewest uncertainties wins, ties broken by shorter answer content. */
+declare const defaultSelector: BranchSelector;
+declare function runBranches(client: DeepSeekClient, request: ChatRequestOptions, opts?: BranchOptions): Promise<BranchResult>;
+/** Sum usage across branch samples for telemetry purposes. */
+declare function aggregateBranchUsage(samples: readonly BranchSample[]): {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    promptCacheHitTokens: number;
+    promptCacheMissTokens: number;
+};
+
 interface ImmutablePrefixOptions {
     system: string;
     toolSpecs?: readonly ToolSpec[];
@@ -342,17 +394,42 @@ interface ToolDefinition<A = any, R = any> {
     parameters?: JSONSchema;
     fn: (args: A) => R | Promise<R>;
 }
+interface ToolRegistryOptions {
+    /**
+     * Auto-flatten schemas that exceed depth/width thresholds before sending
+     * them to the model. Re-nests arguments transparently on dispatch.
+     * Default: true. Pass false to opt out.
+     */
+    autoFlatten?: boolean;
+}
 declare class ToolRegistry {
     private readonly _tools;
+    private readonly _autoFlatten;
+    constructor(opts?: ToolRegistryOptions);
     register<A, R>(def: ToolDefinition<A, R>): this;
     has(name: string): boolean;
     get(name: string): ToolDefinition | undefined;
     get size(): number;
+    /** True if a registered tool's schema was flattened for the model. */
+    wasFlattened(name: string): boolean;
     specs(): ToolSpec[];
     dispatch(name: string, argumentsRaw: string | Record<string, unknown>): Promise<string>;
 }
 
-type EventRole = "assistant_delta" | "assistant_final" | "tool" | "done" | "error";
+type EventRole = "assistant_delta" | "assistant_final" | "tool" | "done" | "error" | "branch_start" | "branch_progress" | "branch_done";
+interface BranchSummary {
+    budget: number;
+    chosenIndex: number;
+    uncertainties: number[];
+    temperatures: number[];
+}
+interface BranchProgress {
+    completed: number;
+    total: number;
+    latestIndex: number;
+    latestTemperature: number;
+    latestUncertainties: number;
+}
 interface LoopEvent {
     turn: number;
     role: EventRole;
@@ -362,6 +439,8 @@ interface LoopEvent {
     stats?: TurnStats;
     planState?: TypedPlanState;
     repair?: RepairReport;
+    branch?: BranchSummary;
+    branchProgress?: BranchProgress;
     error?: string;
 }
 interface CacheFirstLoopOptions {
@@ -377,6 +456,13 @@ interface CacheFirstLoopOptions {
      * cheap but non-zero V3 call per turn).
      */
     harvest?: boolean | HarvestOptions;
+    /**
+     * Self-consistency branching. Pass a number for just a budget (e.g. 3) or
+     * a full `BranchOptions` object. Disables streaming for the branched turn
+     * because all samples must complete before selection. Auto-enables harvest
+     * since the default selector scores samples by plan-state uncertainty.
+     */
+    branch?: number | BranchOptions;
 }
 /**
  * Pillar 1 — Cache-First Loop.
@@ -387,21 +473,37 @@ interface CacheFirstLoopOptions {
  *
  * Yields a stream of events so a TUI can render progressively.
  */
+interface ReconfigurableOptions {
+    model?: string;
+    harvest?: boolean | HarvestOptions;
+    branch?: number | BranchOptions;
+    stream?: boolean;
+}
 declare class CacheFirstLoop {
     readonly client: DeepSeekClient;
     readonly prefix: ImmutablePrefix;
     readonly tools: ToolRegistry;
-    readonly model: string;
     readonly maxToolIters: number;
-    readonly stream: boolean;
-    readonly harvestEnabled: boolean;
-    readonly harvestOptions: HarvestOptions;
     readonly log: AppendOnlyLog;
     readonly scratch: VolatileScratch;
     readonly stats: SessionStats;
     readonly repair: ToolCallRepair;
+    model: string;
+    stream: boolean;
+    harvestEnabled: boolean;
+    harvestOptions: HarvestOptions;
+    branchEnabled: boolean;
+    branchOptions: BranchOptions;
     private _turn;
+    private _streamPreference;
     constructor(opts: CacheFirstLoopOptions);
+    /**
+     * Reconfigure model/harvest/branch/stream mid-session. The loop's log,
+     * scratch, and stats are preserved — only the per-turn behavior changes.
+     * Used by the TUI's slash commands and by library callers who want to
+     * flip a knob between turns.
+     */
+    configure(opts: ReconfigurableOptions): void;
     private buildMessages;
     step(userInput: string): AsyncGenerator<LoopEvent>;
     run(userInput: string, onEvent?: (ev: LoopEvent) => void): Promise<string>;
@@ -446,4 +548,4 @@ declare function redactKey(key: string): string;
 
 declare const VERSION = "0.0.1";
 
-export { AppendOnlyLog, CacheFirstLoop, type CacheFirstLoopOptions, type ChatMessage, type ChatResponse, DeepSeekClient, type DeepSeekClientOptions, type EventRole, type FlattenDecision, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type JSONSchema, type LoopEvent, type ReasonixConfig, type RepairReport, type RetryInfo, type RetryOptions, type Role, type ScavengeOptions, type ScavengeResult, SessionStats, type SessionSummary, StormBreaker, type StreamChunk, type ToolCall, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TruncationRepairResult, type TurnStats, type TypedPlanState, Usage, VERSION, VolatileScratch, analyzeSchema, claudeEquivalentCost, costUsd, defaultConfigPath, emptyPlanState, fetchWithRetry, flattenSchema, harvest, isPlanStateEmpty, isPlausibleKey, loadApiKey, loadDotenv, nestArguments, readConfig, redactKey, repairTruncatedJson, saveApiKey, scavengeToolCalls, writeConfig };
+export { AppendOnlyLog, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, CacheFirstLoop, type CacheFirstLoopOptions, type ChatMessage, type ChatResponse, DeepSeekClient, type DeepSeekClientOptions, type EventRole, type FlattenDecision, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type JSONSchema, type LoopEvent, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type RetryInfo, type RetryOptions, type Role, type ScavengeOptions, type ScavengeResult, SessionStats, type SessionSummary, StormBreaker, type StreamChunk, type ToolCall, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TruncationRepairResult, type TurnStats, type TypedPlanState, Usage, VERSION, VolatileScratch, aggregateBranchUsage, analyzeSchema, claudeEquivalentCost, costUsd, defaultConfigPath, defaultSelector, emptyPlanState, fetchWithRetry, flattenSchema, harvest, isPlanStateEmpty, isPlausibleKey, loadApiKey, loadDotenv, nestArguments, readConfig, redactKey, repairTruncatedJson, runBranches, saveApiKey, scavengeToolCalls, writeConfig };