@hmbown/kytchen-reasoning 0.1.0

package/dist/dialectic.js

@@ -0,0 +1,317 @@
+/**
+ * Valid state transitions. Used by the engine to enforce
+ * that the loop progresses through the correct sequence.
+ */
+const STATE_TRANSITIONS = {
+    idle: ["proposing"],
+    proposing: ["critiquing"],
+    critiquing: ["synthesizing"],
+    synthesizing: ["evaluating"],
+    evaluating: ["proposing", "done"],
+    done: [],
+};
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function now() {
+    return new Date().toISOString();
+}
+function emptySnapshot() {
+    return {
+        state: "idle",
+        currentRound: 0,
+        turns: [],
+        pendingThesis: null,
+        pendingAntithesis: null,
+        pendingSynthesis: null,
+        latestConfidence: 0,
+    };
+}
+/**
+ * Parse the evaluator's raw text response into a structured verdict.
+ * Accepts a JSON block (possibly wrapped in markdown fences).
+ * Falls back to a conservative rejection if parsing fails so the
+ * critic can never be bypassed by a malformed response.
+ */
+function parseEvaluatorVerdict(raw) {
+    // Strip optional markdown code fences
+    const stripped = raw
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```\s*$/, "")
+        .trim();
+    try {
+        const parsed = JSON.parse(stripped);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            "confidence" in parsed &&
+            "accept" in parsed) {
+            const obj = parsed;
+            const confidence = Number(obj["confidence"]);
+            const accept = Boolean(obj["accept"]);
+            const rationale = typeof obj["rationale"] === "string"
+                ? obj["rationale"]
+                : "No rationale provided.";
+            // Clamp confidence to [0, 1]
+            return {
+                confidence: Math.max(0, Math.min(1, confidence)),
+                accept,
+                rationale,
+            };
+        }
+    }
+    catch {
+        // fall through to conservative default
+    }
+    // Conservative fallback: never accept on parse failure.
+    // This ensures the critic cannot be bypassed by a proposer
+    // that crafts a malformed evaluator response.
+    return {
+        confidence: 0,
+        accept: false,
+        rationale: "Evaluator response could not be parsed; defaulting to rejection.",
+    };
+}
+// ---------------------------------------------------------------------------
+// System prompts per role
+// ---------------------------------------------------------------------------
+function proposerSystemPrompt() {
+    return [
+        "You are the PROPOSER in a dialectical reasoning process.",
+        "Your role is to formulate a clear, well-reasoned thesis that addresses the given goal.",
+        "If prior rounds exist, build upon the previous synthesis to strengthen the argument.",
+        "Be precise, structured, and evidence-oriented.",
+    ].join("\n");
+}
+function criticSystemPrompt() {
+    return [
+        "You are the CRITIC (antithesis) in a dialectical reasoning process.",
+        "Your role is to rigorously challenge the thesis.",
+        "Identify logical flaws, missing evidence, unstated assumptions, edge cases, and counter-arguments.",
+        "Do NOT accept the thesis at face value. Your job is adversarial scrutiny.",
+        "Be specific and constructive -- point to concrete weaknesses.",
+    ].join("\n");
+}
+function synthesizerSystemPrompt() {
+    return [
+        "You are the SYNTHESIZER in a dialectical reasoning process.",
+        "You receive a thesis and its antithesis (critique).",
+        "Your role is to produce a synthesis that resolves the tension between them.",
+        "Incorporate the strongest elements of the thesis while addressing the critique.",
+        "The synthesis should be strictly stronger than the original thesis.",
+    ].join("\n");
+}
+function evaluatorSystemPrompt() {
+    return [
+        "You are the EVALUATOR GATE in a dialectical reasoning process.",
+        "You assess whether the synthesis adequately resolves the tension between thesis and antithesis.",
+        "",
+        "Respond with a JSON object (no other text) with the following fields:",
+        '  "confidence": a number between 0 and 1 indicating your confidence in the synthesis,',
+        '  "accept": a boolean indicating whether to accept the synthesis as final,',
+        '  "rationale": a brief explanation of your verdict.',
+        "",
+        "Be rigorous. Only accept when the synthesis genuinely resolves the core objections.",
+        "A proposer claiming completeness is NOT sufficient -- evaluate on the merits.",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// DialecticalEngine
+// ---------------------------------------------------------------------------
+export class DialecticalEngine {
+    config;
+    generate;
+    constructor(config) {
+        this.config = config;
+        this.generate =
+            config.generate ??
+                (async (_sys, user) => `[stub] Response to: ${user.slice(0, 120)}`);
+    }
+    // -----------------------------------------------------------------------
+    // Public predicates
+    // -----------------------------------------------------------------------
+    shouldContinue(round, confidence) {
+        return (round < this.config.maxRounds &&
+            confidence < this.config.confidenceThreshold);
+    }
+    isApplicable(mode) {
+        return mode === "dialectical" || mode === "dialectical-recursive";
+    }
+    // -----------------------------------------------------------------------
+    // State machine helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Validate and execute a state transition.
+     * Throws if the transition is not allowed by the state machine.
+     */
+    transition(snapshot, to) {
+        const allowed = STATE_TRANSITIONS[snapshot.state];
+        if (!allowed.includes(to)) {
+            throw new Error(`Invalid dialectical state transition: ${snapshot.state} → ${to}. ` +
+                `Allowed: [${allowed.join(", ")}]`);
+        }
+        return { ...snapshot, state: to };
+    }
+    /**
+     * Return a fresh snapshot for a new run.
+     */
+    createSnapshot() {
+        return emptySnapshot();
+    }
+    // -----------------------------------------------------------------------
+    // Role execution
+    // -----------------------------------------------------------------------
+    async executeProposer(goal, context, previousSynthesis) {
+        const userPrompt = previousSynthesis
+            ? [
+                `Goal: ${goal}`,
+                "",
+                `Context: ${context}`,
+                "",
+                "Previous synthesis (build upon this):",
+                previousSynthesis,
+            ].join("\n")
+            : [`Goal: ${goal}`, "", `Context: ${context}`].join("\n");
+        const content = await this.generate(proposerSystemPrompt(), userPrompt);
+        return { role: "proposer", content, timestamp: now() };
+    }
+    async executeCritic(goal, thesis) {
+        const userPrompt = [
+            `Goal: ${goal}`,
+            "",
+            "Thesis to critique:",
+            thesis,
+        ].join("\n");
+        const content = await this.generate(criticSystemPrompt(), userPrompt);
+        return { role: "critic", content, timestamp: now() };
+    }
+    async executeSynthesizer(goal, thesis, antithesis) {
+        const userPrompt = [
+            `Goal: ${goal}`,
+            "",
+            "Thesis:",
+            thesis,
+            "",
+            "Antithesis (critique):",
+            antithesis,
+        ].join("\n");
+        const content = await this.generate(synthesizerSystemPrompt(), userPrompt);
+        return { role: "synthesizer", content, timestamp: now() };
+    }
+    async executeEvaluator(goal, thesis, antithesis, synthesis) {
+        const userPrompt = [
+            `Goal: ${goal}`,
+            "",
+            "Thesis:",
+            thesis,
+            "",
+            "Antithesis:",
+            antithesis,
+            "",
+            "Synthesis:",
+            synthesis,
+        ].join("\n");
+        const content = await this.generate(evaluatorSystemPrompt(), userPrompt);
+        const verdict = parseEvaluatorVerdict(content);
+        return {
+            artifact: { role: "evaluator", content, timestamp: now() },
+            verdict,
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Main loop
+    // -----------------------------------------------------------------------
+    /**
+     * Execute the full dialectical reasoning loop.
+     *
+     * Rounds: thesis → antithesis → synthesis → evaluation
+     * Stops when the evaluator's confidence meets the threshold,
+     * the evaluator explicitly accepts, or max rounds are exhausted.
+     *
+     * The effective max rounds is the lesser of `config.maxRounds`
+     * and `input.maxTurns` (when provided).
+     */
+    async run(input) {
+        const effectiveMaxRounds = Math.min(this.config.maxRounds, input.maxTurns > 0 ? input.maxTurns : this.config.maxRounds);
+        let snapshot = this.createSnapshot();
+        let previousSynthesis = null;
+        for (let round = 0; round < effectiveMaxRounds; round++) {
+            // ---- Proposing ----
+            snapshot = this.transition(snapshot.state === "idle" ? snapshot : { ...snapshot, state: "evaluating" }, "proposing");
+            const proposerArtifact = await this.executeProposer(input.goal, input.context, previousSynthesis);
+            snapshot = {
+                ...snapshot,
+                currentRound: round,
+                pendingThesis: proposerArtifact.content,
+            };
+            // ---- Critiquing ----
+            snapshot = this.transition(snapshot, "critiquing");
+            const criticArtifact = await this.executeCritic(input.goal, proposerArtifact.content);
+            snapshot = {
+                ...snapshot,
+                pendingAntithesis: criticArtifact.content,
+            };
+            // ---- Synthesizing ----
+            snapshot = this.transition(snapshot, "synthesizing");
+            const synthesizerArtifact = await this.executeSynthesizer(input.goal, proposerArtifact.content, criticArtifact.content);
+            snapshot = {
+                ...snapshot,
+                pendingSynthesis: synthesizerArtifact.content,
+            };
+            // ---- Evaluating ----
+            snapshot = this.transition(snapshot, "evaluating");
+            const { artifact: evaluatorArtifact, verdict } = await this.executeEvaluator(input.goal, proposerArtifact.content, criticArtifact.content, synthesizerArtifact.content);
+            // Build the turn record with all artifacts for auditability
+            const turn = {
+                round,
+                thesis: proposerArtifact.content,
+                antithesis: criticArtifact.content,
+                synthesis: synthesizerArtifact.content,
+                confidence: verdict.confidence,
+                artifacts: [
+                    proposerArtifact,
+                    criticArtifact,
+                    synthesizerArtifact,
+                    evaluatorArtifact,
+                ],
+            };
+            snapshot = {
+                ...snapshot,
+                turns: [...snapshot.turns, turn],
+                latestConfidence: verdict.confidence,
+                pendingThesis: null,
+                pendingAntithesis: null,
+                pendingSynthesis: null,
+            };
+            previousSynthesis = synthesizerArtifact.content;
+            // ---- Gate decision ----
+            // The evaluator gate is deterministic: accept only when both the
+            // confidence threshold is met AND the evaluator explicitly accepts.
+            // This prevents the proposer from bypassing the critic by claiming
+            // completeness in its own output.
+            if (verdict.accept &&
+                verdict.confidence >= this.config.confidenceThreshold) {
+                snapshot = this.transition(snapshot, "done");
+                break;
+            }
+            // If this was the last round, transition to done regardless
+            if (round === effectiveMaxRounds - 1) {
+                snapshot = this.transition(snapshot, "done");
+            }
+        }
+        // Ensure terminal state
+        if (snapshot.state !== "done") {
+            snapshot = { ...snapshot, state: "done" };
+        }
+        const finalSynthesis = previousSynthesis ?? `No synthesis produced for: ${input.goal}`;
+        const finalConfidence = snapshot.latestConfidence;
+        return {
+            artifact: {
+                synthesis: finalSynthesis,
+                rounds: snapshot.turns,
+                confidence: finalConfidence,
+            },
+            mode: "dialectical",
+        };
+    }
+}
+//# sourceMappingURL=dialectic.js.map

package/dist/dialectic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialectic.js","sourceRoot":"","sources":["../src/dialectic.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./dialectic.js";
+export * from "./recursive.js";
+export * from "./coherence.js";
+export * from "./router.js";
+export * from "./autocode.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./dialectic.js";
+export * from "./recursive.js";
+export * from "./coherence.js";
+export * from "./router.js";
+export * from "./autocode.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dist/recursive.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Unique identifier for a task node in the recursive tree.
+ * Format: `rq-<random>` for root tasks, `rq-<random>-<childIndex>` for children.
+ */
+export type TaskId = string;
+/** A single piece of evidence gathered during sub-query execution. */
+export interface EvidenceItem {
+    /** Stable identifier scoped to the task that produced it. */
+    id: string;
+    /** The task that produced this evidence. */
+    sourceTaskId: TaskId;
+    /** Human-readable content of the evidence. */
+    content: string;
+    /** Confidence score in [0, 1]. */
+    confidence: number;
+    /** ISO-8601 timestamp of when this evidence was recorded. */
+    timestamp: string;
+}
+/**
+ * Explicit completion state so that consumers can distinguish a fully
+ * resolved outcome from one that was cut short by a recursion guard.
+ */
+export type FinalizationStatus = "completed" | "depth_limit_reached" | "breadth_limit_reached" | "iteration_limit_reached" | "time_budget_exceeded" | "interrupted" | "execution_error" | "partial";
+/** A single node in the recursive task tree. */
+export interface RecursiveTask {
+    /** Stable, globally unique identifier. */
+    id: TaskId;
+    /** The prompt / sub-query to execute. */
+    prompt: string;
+    /** Zero-indexed depth in the tree (root = 0). */
+    depth: number;
+    /** Parent task ID, or `null` for root tasks. */
+    parentId: TaskId | null;
+    /** Ordered list of child task IDs. */
+    childIds: TaskId[];
+    /** Monotonically increasing index among siblings. */
+    siblingIndex: number;
+}
+/** Outcome produced when a single task finishes (or is cut short). */
+export interface RecursiveOutcome {
+    /** The task this outcome belongs to. */
+    taskId: TaskId;
+    /** Depth at which the task ran. */
+    depth: number;
+    /** Whether this outcome represents a fully resolved result. */
+    finalized: boolean;
+    /** Explicit marker describing how/why the task finished. */
+    finalizationStatus: FinalizationStatus;
+    /** Textual summary of the outcome. */
+    summary: string;
+    /** Evidence items accumulated during this task's execution. */
+    evidence: EvidenceItem[];
+    /** Outcomes of child sub-queries, in spawn order. */
+    childOutcomes: RecursiveOutcome[];
+}
+/** Tuning knobs for bounded recursive execution. */
+export interface RecursiveConfig {
+    /** Maximum depth of the task tree (root = depth 0). */
+    maxDepth: number;
+    /** Maximum total iterations (task executions) across the entire tree. */
+    maxIterations: number;
+    /**
+     * Maximum number of child sub-queries a single task may spawn.
+     * Defaults to `maxIterations` when not set (effectively unbounded
+     * within the iteration cap).
+     */
+    maxBreadth?: number;
+    /** Optional hard wall-clock budget for the full recursive execution. */
+    maxWallTimeMs?: number;
+}
+/**
+ * Result returned by the caller-supplied execution callback.
+ *
+ * The callback is intentionally provider-agnostic: the orchestrator does not
+ * care whether the work is done by an LLM, a tool pipeline, or a test stub.
+ */
+export interface SubQueryResult {
+    /** Textual summary produced by executing the sub-query. */
+    summary: string;
+    /** Evidence gathered during execution. */
+    evidence: EvidenceItem[];
+    /**
+     * Optional list of follow-up sub-queries the execution wants to spawn.
+     * The orchestrator will respect depth/breadth/iteration limits when
+     * deciding which (if any) of these are actually executed.
+     */
+    subQueries?: string[];
+}
+/**
+ * A provider-agnostic callback that executes a single sub-query.
+ *
+ * Receives the task to execute and its parent context (list of evidence
+ * accumulated so far in the parent scope). Returns the execution result
+ * including any follow-up sub-queries the task wants to spawn.
+ */
+export type ExecuteCallback = (task: Readonly<RecursiveTask>, parentEvidence: readonly EvidenceItem[], context: Readonly<SubAgentExecutionContext>) => Promise<SubQueryResult>;
+export interface SubAgentExecutionContext {
+    iteration: number;
+    maxIterations: number;
+    startedAt: string;
+    remainingMs?: number;
+    signal?: AbortSignal;
+}
+/** Full trace of the recursive decomposition for observability. */
+export interface RecursiveTrace {
+    /** Root outcome (contains the entire child tree). */
+    rootOutcome: RecursiveOutcome;
+    /** Flat map of every task node for random access. */
+    taskMap: ReadonlyMap<TaskId, RecursiveTask>;
+    /** Total number of task executions performed. */
+    totalIterations: number;
+    /** Maximum depth actually reached during execution. */
+    maxDepthReached: number;
+}
+export type RecursiveLifecycleEventType = "execution.started" | "execution.completed" | "task.spawned" | "task.started" | "task.completed" | "task.merged" | "task.limited" | "task.interrupted";
+export interface RecursiveLifecycleEvent {
+    type: RecursiveLifecycleEventType;
+    timestamp: string;
+    taskId?: TaskId;
+    parentTaskId?: TaskId | null;
+    depth?: number;
+    prompt?: string;
+    iteration?: number;
+    maxIterations?: number;
+    maxDepth?: number;
+    maxBreadth?: number;
+    maxWallTimeMs?: number;
+    maxDepthReached?: number;
+    remainingMs?: number;
+    finalizationStatus?: FinalizationStatus;
+    summary?: string;
+    childCount?: number;
+    evidenceCount?: number;
+    message?: string;
+}
+export interface RecursiveRunOptions {
+    maxDepth?: number;
+    maxIterations?: number;
+    maxBreadth?: number;
+    maxWallTimeMs?: number;
+    signal?: AbortSignal;
+    now?: () => number;
+    onLifecycleEvent?: (event: RecursiveLifecycleEvent) => void | Promise<void>;
+}
+/**
+ * Resets the internal ID counter. Intended for tests only.
+ * @internal
+ */
+export declare function _resetIdCounter(): void;
+/**
+ * Recursive reasoning orchestrator with bounded sub-query execution.
+ *
+ * The orchestrator manages a tree of sub-queries, enforcing hard limits
+ * on depth, breadth, and total iterations. It is provider-agnostic: the
+ * actual execution of each sub-query is delegated to a caller-supplied
+ * callback.
+ *
+ * ## Lifecycle
+ *
+ * 1. The caller invokes {@link run} with a root prompt and an execution
+ *    callback.
+ * 2. The orchestrator creates a root task and executes it via the callback.
+ * 3. If the callback returns follow-up sub-queries, the orchestrator
+ *    spawns child tasks (subject to limits) and recurses.
+ * 4. Child outcomes are merged back into the parent deterministically.
+ * 5. A full {@link RecursiveTrace} is returned for observability.
+ *
+ * ## Graceful degradation
+ *
+ * When any limit is reached, the orchestrator does **not** throw. Instead
+ * it produces a partial outcome with an appropriate
+ * {@link FinalizationStatus} and a fallback summary. Callers can inspect
+ * the trace to see which sub-queries were curtailed.
+ */
+export declare class RecursiveOrchestrator {
+    private readonly config;
+    constructor(config: RecursiveConfig);
+    /**
+     * Returns `true` if a new task can be spawned given the current depth
+     * and cumulative iteration count.
+     */
+    canSpawn(depth: number, iterations: number): boolean;
+    /**
+     * Produces a fallback outcome when a task cannot be fully executed.
+     * The outcome is explicitly marked as non-finalized with the
+     * appropriate status.
+     */
+    summarizeFallback(task: RecursiveTask, status?: FinalizationStatus): RecursiveOutcome;
+    /**
+     * Executes a recursive reasoning pass starting from the given root
+     * prompt.
+     *
+     * @param rootPrompt - The top-level query to reason about.
+     * @param execute    - Provider-agnostic callback for running a single
+     *                     sub-query. The orchestrator calls this for every
+     *                     task node in the tree.
+     * @returns A full trace of the recursive decomposition.
+     */
+    run(rootPrompt: string, execute: ExecuteCallback, options?: RecursiveRunOptions): Promise<RecursiveTrace>;
+    /**
+     * Recursively executes a single task and all of its spawned children.
+     */
+    private executeTask;
+    /**
+     * Builds a partial outcome when a task wants to spawn children but the
+     * depth limit has been reached.
+     */
+    private buildDepthLimitNote;
+    private isInterrupted;
+    private remainingMs;
+    private isTimeBudgetExceeded;
+    private emitLifecycle;
+}
+//# sourceMappingURL=recursive.d.ts.map

package/dist/recursive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recursive.d.ts","sourceRoot":"","sources":["../src/recursive.ts"],"names":[],"mappings":"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"}