logic-puzzle-generator 1.0.0

package/dist/src/engine/BoundsCalculator.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundsCalculator = void 0;
+const Generator_1 = require("./Generator");
+const types_1 = require("../types");
+class BoundsCalculator {
+    static calculate(numCats, numItems, iterations = 20) {
+        // Construct standard config
+        const categories = [];
+        for (let i = 0; i < numCats; i++) {
+            categories.push({
+                id: `C${i}`,
+                type: types_1.CategoryType.NOMINAL,
+                values: Array.from({ length: numItems }, (_, j) => `V${j}`)
+            });
+        }
+        const target = {
+            category1Id: 'C0',
+            value1: 'V0',
+            category2Id: 'C1'
+        };
+        let globalMin = Infinity;
+        let globalMax = 0;
+        // Run batch
+        for (let i = 0; i < iterations; i++) {
+            // Seed
+            const seed = Date.now() + (i * 9999);
+            const gen = new Generator_1.Generator(seed);
+            const bounds = gen.getClueCountBounds(categories, target, 1); // 1 iteration of internal logic
+            if (bounds.min > 0) {
+                globalMin = Math.min(globalMin, bounds.min);
+                globalMax = Math.max(globalMax, bounds.max);
+            }
+        }
+        if (globalMin === Infinity)
+            globalMin = 0;
+        return { min: globalMin, max: globalMax };
+    }
+}
+exports.BoundsCalculator = BoundsCalculator;

package/dist/src/engine/Clue.d.ts

@@ -0,0 +1,75 @@
+import { ValueLabel, ClueType, BinaryOperator, OrdinalOperator, SuperlativeOperator, UnaryFilter, CrossOrdinalOperator } from '../types';
+export { ClueType, BinaryOperator, OrdinalOperator, SuperlativeOperator, UnaryFilter, CrossOrdinalOperator };
+/**
+ * A clue that establishes a direct link or separation between two specific values.
+ * Example: "Alice likes Horror movies." (IS)
+ * Example: "Bob does not like Comedy." (IS_NOT)
+ */
+export interface BinaryClue {
+    type: ClueType.BINARY;
+    operator: BinaryOperator;
+    cat1: string;
+    val1: ValueLabel;
+    cat2: string;
+    val2: ValueLabel;
+}
+/**
+ * A clue that compares two entities based on a third ordinal category.
+ * Example: "The person who likes Horror is older than Alice."
+ */
+export interface OrdinalClue {
+    type: ClueType.ORDINAL;
+    operator: OrdinalOperator;
+    item1Cat: string;
+    item1Val: ValueLabel;
+    item2Cat: string;
+    item2Val: ValueLabel;
+    /** The ordinal category used for comparison (e.g., "Age"). */
+    ordinalCat: string;
+}
+/**
+ * A clue that identifies an entity as having an extreme value in an ordinal category.
+ * Example: "The person who likes Popcorn is the oldest."
+ */
+export interface SuperlativeClue {
+    type: ClueType.SUPERLATIVE;
+    operator: SuperlativeOperator;
+    targetCat: string;
+    targetVal: ValueLabel;
+    /** The ordinal category (e.g., "Age") where the value is extreme. */
+    ordinalCat: string;
+}
+/**
+ * A clue that filters a value based on a property of its associated ordinal value.
+ * Example: "The person who likes Chips has an even age."
+ */
+export interface UnaryClue {
+    type: ClueType.UNARY;
+    filter: UnaryFilter;
+    targetCat: string;
+    targetVal: ValueLabel;
+    ordinalCat: string;
+}
+/**
+ * A clue that links relative positions across two ordinal categories.
+ * Example: "The person immediately before [Item A] in [Cat 1] is the same as the person immediately after [Item B] in [Cat 2]."
+ */
+export interface CrossOrdinalClue {
+    type: ClueType.CROSS_ORDINAL;
+    operator: CrossOrdinalOperator;
+    /** The first anchor entity */
+    item1Cat: string;
+    item1Val: ValueLabel;
+    /** The ordinal category for the first relation */
+    ordinal1: string;
+    /** The offset from the anchor (-1 = before, +1 = after) */
+    offset1: number;
+    /** The second anchor entity */
+    item2Cat: string;
+    item2Val: ValueLabel;
+    /** The ordinal category for the second relation */
+    ordinal2: string;
+    /** The offset from the anchor (-1 = before, +1 = after) */
+    offset2: number;
+}
+export type Clue = BinaryClue | OrdinalClue | SuperlativeClue | UnaryClue | CrossOrdinalClue;

package/dist/src/engine/Clue.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrossOrdinalOperator = exports.UnaryFilter = exports.SuperlativeOperator = exports.OrdinalOperator = exports.BinaryOperator = exports.ClueType = void 0;
+const types_1 = require("../types");
+Object.defineProperty(exports, "ClueType", { enumerable: true, get: function () { return types_1.ClueType; } });
+Object.defineProperty(exports, "BinaryOperator", { enumerable: true, get: function () { return types_1.BinaryOperator; } });
+Object.defineProperty(exports, "OrdinalOperator", { enumerable: true, get: function () { return types_1.OrdinalOperator; } });
+Object.defineProperty(exports, "SuperlativeOperator", { enumerable: true, get: function () { return types_1.SuperlativeOperator; } });
+Object.defineProperty(exports, "UnaryFilter", { enumerable: true, get: function () { return types_1.UnaryFilter; } });
+Object.defineProperty(exports, "CrossOrdinalOperator", { enumerable: true, get: function () { return types_1.CrossOrdinalOperator; } });

package/dist/src/engine/DifficultyBounds.d.ts

@@ -0,0 +1,12 @@
+export declare const DIFFICULTY_BOUNDS: Record<string, {
+    min: number;
+    max: number;
+}>;
+export declare const getRecommendedBounds: (numCats: number, numItems: number) => {
+    min: number;
+    max: number;
+};
+export declare const getRecommendedSweetSpot: (numCats: number, numItems: number) => {
+    min: number;
+    max: number;
+};

package/dist/src/engine/DifficultyBounds.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRecommendedSweetSpot = exports.getRecommendedBounds = exports.DIFFICULTY_BOUNDS = void 0;
+// Precomputed via Monte Carlo simulation (src/scripts/GenerateBounds.test.ts)
+// Key format: "${numCats}x${numItems}"
+// Updated after banning Direct Target Clues to ensure puzzle quality.
+exports.DIFFICULTY_BOUNDS = {
+    // 2 Categories
+    "2x3": { "min": 2, "max": 2 },
+    "2x4": { "min": 3, "max": 10 },
+    "2x5": { "min": 4, "max": 17 },
+    "2x6": { "min": 5, "max": 26 },
+    "2x7": { "min": 6, "max": 37 },
+    "2x8": { "min": 7, "max": 50 },
+    "2x9": { "min": 8, "max": 65 },
+    "2x10": { "min": 9, "max": 82 },
+    // 3 Categories
+    "3x3": { "min": 3, "max": 9 },
+    "3x4": { "min": 5, "max": 26 },
+    "3x5": { "min": 7, "max": 47 },
+    "3x6": { "min": 9, "max": 72 },
+    "3x7": { "min": 11, "max": 100 },
+    "3x8": { "min": 13, "max": 130 },
+    "3x9": { "min": 15, "max": 160 },
+    "3x10": { "min": 17, "max": 200 },
+    // 4 Categories
+    "4x3": { "min": 5, "max": 16 },
+    "4x4": { "min": 8, "max": 44 },
+    "4x5": { "min": 11, "max": 87 },
+    "4x6": { "min": 14, "max": 140 },
+    "4x7": { "min": 17, "max": 200 },
+    "4x8": { "min": 20, "max": 260 },
+    "4x9": { "min": 23, "max": 330 },
+    "4x10": { "min": 26, "max": 400 },
+    // 5 Categories
+    "5x3": { "min": 7, "max": 25 },
+    "5x4": { "min": 11, "max": 70 },
+    "5x5": { "min": 15, "max": 130 },
+    "5x6": { "min": 19, "max": 200 },
+    "5x7": { "min": 23, "max": 280 },
+    "5x8": { "min": 27, "max": 370 },
+    "5x9": { "min": 31, "max": 470 },
+    "5x10": { "min": 35, "max": 580 }
+};
+const getRecommendedBounds = (numCats, numItems) => {
+    const key = `${numCats}x${numItems}`;
+    if (exports.DIFFICULTY_BOUNDS[key])
+        return exports.DIFFICULTY_BOUNDS[key];
+    // Dynamic Fallback for large grids
+    // Based on regression from smaller grids:
+    // Min ~ 0.8 * (Cats-1) * Items
+    // Max ~ 6.0 * (Cats-1) * Items (loose upper bound)
+    const factor = (numCats - 1) * numItems;
+    const min = Math.max(5, Math.floor(factor * 0.7));
+    const max = Math.floor(factor * 5.0);
+    return { min, max };
+};
+exports.getRecommendedBounds = getRecommendedBounds;
+const getRecommendedSweetSpot = (numCats, numItems) => {
+    const bounds = (0, exports.getRecommendedBounds)(numCats, numItems);
+    // Sweet spot: 1.0x to 1.5x of minimum required clues for parity/solvability
+    return {
+        min: bounds.min,
+        max: Math.min(bounds.max, Math.ceil(bounds.min * 1.5))
+    };
+};
+exports.getRecommendedSweetSpot = getRecommendedSweetSpot;

package/dist/src/engine/GenerativeSession.d.ts

@@ -0,0 +1,32 @@
+import { CategoryConfig, ClueGenerationConstraints, Solution, TargetFact, ValueLabel } from '../types';
+import { Clue } from './Clue';
+import { LogicGrid } from './LogicGrid';
+import type { Generator } from './Generator';
+export declare class GenerativeSession {
+    private generator;
+    private categories;
+    private solution;
+    private reverseSolution;
+    private valueMap;
+    targetFact: TargetFact;
+    private grid;
+    private availableClues;
+    private proofChain;
+    private solver;
+    private historyStack;
+    constructor(generator: Generator, categories: CategoryConfig[], solution: Solution, reverseSolution: Map<string, Map<ValueLabel, ValueLabel>>, valueMap: Map<ValueLabel, Record<string, ValueLabel>>, targetFact: TargetFact);
+    getNextClue(constraints?: ClueGenerationConstraints): {
+        clue: Clue | null;
+        remaining: number;
+        solved: boolean;
+    };
+    rollbackLastClue(): {
+        success: boolean;
+        clue: Clue | null;
+    };
+    private isUseful;
+    getGrid(): LogicGrid;
+    getProofChain(): Clue[];
+    getSolution(): Solution;
+    getValueMap(): Map<ValueLabel, Record<string, ValueLabel>>;
+}

package/dist/src/engine/GenerativeSession.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenerativeSession = void 0;
+const LogicGrid_1 = require("./LogicGrid");
+const Solver_1 = require("./Solver");
+class GenerativeSession {
+    constructor(generator, categories, solution, reverseSolution, valueMap, targetFact) {
+        this.generator = generator;
+        this.categories = categories;
+        this.solution = solution;
+        this.reverseSolution = reverseSolution;
+        this.valueMap = valueMap;
+        this.targetFact = targetFact;
+        this.availableClues = [];
+        this.proofChain = [];
+        this.historyStack = [];
+        this.grid = new LogicGrid_1.LogicGrid(categories);
+        this.solver = new Solver_1.Solver();
+        // Initial Generation of ALL possibilities (we filter later)
+        // We need access to the generator's clue generation logic.
+        // We will call a public method on generator.
+        this.availableClues = this.generator.generateAllPossibleClues(categories, undefined, reverseSolution, valueMap);
+    }
+    getNextClue(constraints) {
+        // Filter available clues based on constraints & current relevance
+        // Use the same heuristic logic as Generator?
+        const validClues = this.availableClues.filter(clue => {
+            // 1. Must not define something already known (Solver.applyClue check basically)
+            // Actually, redundancy check happens in scoring.
+            // 2. Constraints
+            if (constraints?.allowedClueTypes && !constraints.allowedClueTypes.includes(clue.type))
+                return false;
+            return true;
+        });
+        // Score them
+        let bestClue = null;
+        let bestScore = -Infinity;
+        // We should shuffle validClues to limit search space or just search all?
+        // For interactive session, speed is less critical than quality, but we want variety.
+        // Shuffle validClues first.
+        // In-place shuffle copy
+        const candidates = [...validClues].sort(() => Math.random() - 0.5);
+        // Take top N candidates?
+        const searchLimit = 50;
+        let checked = 0;
+        for (const clue of candidates) {
+            checked++;
+            if (checked > searchLimit && bestClue)
+                break; // found something good enough?
+            const score = this.generator.calculateClueScore(this.grid, this.targetFact, 0, clue, this.proofChain, this.solution, this.reverseSolution
+            // Note: we need to actually apply it to get deductions count for scoring to work well
+            );
+            // Wait, publicCalculateScore needs `deductions`.
+            // So we must clone grid and apply.
+            const tempGrid = this.grid.clone();
+            const { deductions } = this.solver.applyClue(tempGrid, clue);
+            if (deductions === 0 && !this.isUseful(tempGrid)) {
+                // Useless clue
+                continue;
+            }
+            // Re-calc score with deductions
+            const realScore = this.generator.calculateClueScore(this.grid, this.targetFact, deductions, clue, this.proofChain, this.solution, this.reverseSolution);
+            if (realScore > bestScore) {
+                bestScore = realScore;
+                bestClue = clue;
+            }
+        }
+        if (bestClue) {
+            // Save state
+            this.historyStack.push(this.grid.clone());
+            // Apply it
+            this.solver.applyClue(this.grid, bestClue);
+            this.proofChain.push(bestClue);
+            // Remove from available
+            const idx = this.availableClues.indexOf(bestClue);
+            if (idx > -1)
+                this.availableClues.splice(idx, 1);
+            return { clue: bestClue, remaining: this.availableClues.length, solved: this.generator.isPuzzleSolved(this.grid, this.solution, this.reverseSolution) };
+        }
+        return { clue: null, remaining: validClues.length, solved: this.generator.isPuzzleSolved(this.grid, this.solution, this.reverseSolution) };
+    }
+    rollbackLastClue() {
+        if (this.historyStack.length === 0)
+            return { success: false, clue: null };
+        const prevGrid = this.historyStack.pop();
+        if (prevGrid)
+            this.grid = prevGrid;
+        const lastClue = this.proofChain.pop();
+        if (lastClue) {
+            this.availableClues.push(lastClue);
+            return { success: true, clue: lastClue };
+        }
+        return { success: false, clue: null };
+    }
+    isUseful(grid) {
+        // Did it eliminate anything? 
+        // LogicGrid could report this.
+        // We compare clone vs original?
+        // Actually Solver returns deductions count.
+        // If deductions > 0, it's useful.
+        return true;
+    }
+    // Getters for UI
+    getGrid() { return this.grid; }
+    getProofChain() { return this.proofChain; }
+    getSolution() { return this.solution; }
+    getValueMap() { return this.valueMap; }
+}
+exports.GenerativeSession = GenerativeSession;

package/dist/src/engine/Generator.d.ts

@@ -0,0 +1,119 @@
+import { CategoryConfig, ValueLabel, Solution, TargetFact, ClueGenerationConstraints } from '../types';
+import { Clue } from './Clue';
+import { LogicGrid } from './LogicGrid';
+import { GenerativeSession } from './GenerativeSession';
+/**
+ * Represents a single step in the logical deduction path.
+ */
+export interface ProofStep {
+    /** The clue applied at this step. */
+    clue: Clue;
+    /** The number of logical eliminations that resulted immediately from this clue. */
+    deductions: number;
+}
+/**
+ * The complete result of the puzzle generation process.
+ */
+export interface Puzzle {
+    /** The solution grid (Category -> Value -> Corresponding Value). */
+    solution: Solution;
+    /** The list of clues needed to solve the puzzle, in no particular order. */
+    clues: Clue[];
+    /** An ordered list of clues that demonstrates a step-by-step logical solution. */
+    proofChain: ProofStep[];
+    /** The configuration used to generate this puzzle. */
+    categories: CategoryConfig[];
+    /** The specific fact that the puzzle is designed to reveal at the end. */
+    targetFact: TargetFact;
+}
+/**
+ * Configuration options for the puzzle generation process.
+ */
+export interface GeneratorOptions {
+    /**
+     * The maximum number of candidate clues to evaluate at each step.
+     * Lower values improve performance for large grids but may slightly reduce puzzle quality.
+     * Default: Infinity (Exhaustive search).
+     */
+    maxCandidates?: number;
+    /**
+     * Attempt to generate a puzzle with exactly this many clues.
+     * The generator will use backtracking to find a path of this length.
+     * May throw an error if the count is infeasible.
+     */
+    targetClueCount?: number;
+    /**
+     * Timeout in milliseconds for the generation process.
+     * Default: 10000ms (10s).
+     */
+    timeoutMs?: number;
+    /**
+     * Constraints to filter the types of clues generated.
+     */
+    constraints?: ClueGenerationConstraints;
+    /**
+     * Callback for trace logs execution details.
+     */
+    onTrace?: (message: string) => void;
+}
+/**
+ * The main class responsible for generating logic puzzles.
+ *
+ * It handles the creation of a consistent solution, the generation of all possible clues,
+ * and the selection of an optimal set of clues to form a solvable puzzle with a specific target.
+ */
+export declare class Generator {
+    private seed;
+    private random;
+    private solver;
+    private solution;
+    private valueMap;
+    private reverseSolution;
+    /**
+     * Creates a new Generator instance.
+     *
+     * @param seed - A numeric seed for the random number generator to ensure reproducibility.
+     */
+    constructor(seed: number);
+    /**
+     * Generates a fully solvable logic puzzle based on the provided configuration.
+     * Estimates the minimum and maximum number of clues required to solve a puzzle
+     * for the given configuration and target, by running several simulations.
+     * This is a computationally intensive operation.
+     *
+     * @param categories - The categories and values to include in the puzzle.
+     * @param target - The specific fact that should be the final deduction of the puzzle.
+     * @returns A promise resolving to an object containing the estimated min and max clue counts.
+     */
+    getClueCountBounds(categories: CategoryConfig[], target: TargetFact, maxIterations?: number): {
+        min: number;
+        max: number;
+    };
+    /**
+     * Generates a fully solvable logic puzzle.
+     * @param categories - The categories config.
+     * @param target - Optional target fact. If missing, a random one is synthesized.
+     * @param config - Generation options.
+     */
+    generatePuzzle(categories: CategoryConfig[], target?: TargetFact, config?: GeneratorOptions): Puzzle;
+    /**
+     * Starts an interactive generative session.
+     * @param categories
+     * @param target Optional target fact.
+     */
+    startSession(categories: CategoryConfig[], target?: TargetFact): GenerativeSession;
+    /**
+     * Internal generation method exposed for simulations.
+     * @param strategy 'standard' | 'min' | 'max'
+     */
+    internalGenerate(categories: CategoryConfig[], target: TargetFact, strategy: 'standard' | 'min' | 'max', options?: GeneratorOptions): Puzzle;
+    private generateWithBacktracking;
+    private createSolution;
+    generateAllPossibleClues(categories: CategoryConfig[], constraints: ClueGenerationConstraints | undefined, reverseSolution: Map<string, Map<ValueLabel, ValueLabel>>, valueMap: Map<ValueLabel, Record<string, ValueLabel>>): Clue[];
+    /**
+     * Calculates the heuristic score for a candidate clue.
+     * Higher scores represent better clues according to the current strategy.
+     */
+    calculateClueScore(grid: LogicGrid, target: TargetFact, deductions: number, clue: Clue, previouslySelectedClues: Clue[], solution: Solution, reverseSolution: Map<string, Map<ValueLabel, ValueLabel>>): number;
+    isPuzzleSolved(grid: LogicGrid, solution: Solution, reverseSolution: Map<string, Map<ValueLabel, ValueLabel>>): boolean;
+}