logic-puzzle-generator 1.1.9 → 1.2.0

package/README.md

@@ -192,8 +192,11 @@ The main class. Use `new Generator(seed)` to initialize.
     - `options.targetClueCount`: Attempt to find exact solution length. Avoids early termination.
     - `options.maxCandidates`: Performance tuning (default 50). Limits the heuristic search width.
     - `options.timeoutMs`: Abort generation if it exceeds this limit (default 10000ms).
-    - `options.constraints`: Filter allowed clue types.
-        - `allowedClueTypes`: `ClueType[]` (e.g. `[ClueType.BINARY, ClueType.ORDINAL]`).
+    - `options.constraints`: Filter/control generated clues.
+        - `allowedClueTypes`: `ClueType[]`.
+        - `includeSubjects`: `string[]` (New in v1.1.X). Restrict to clues involving these values.
+        - `excludeSubjects`: `string[]` (New in v1.1.X). Exclude clues involving these values.
+        - `minDeductions`: `number` (New in v1.1.X). Min new info required (default 1). Set to 0 for filler.
     - `options.onTrace`: **(Debug)** Callback `(msg: string) => void`. Receives real-time logs about the generation process.
 - `generatePuzzleAsync(...)`: **New in v1.1.0**. Non-blocking version of `generatePuzzle`. Returns `Promise<Puzzle>`.
 - `getClueCountBounds(categories, target)`: Returns plausible Min/Max clue counts.
@@ -233,7 +236,32 @@ The logical engine responsible for applying clues and performing deductions.
 Manages a stateful, step-by-step puzzle generation process.
 - `getNextClue(constraints?)`: Returns `{ clue: Clue | null, remaining: number, solved: boolean }`.
     - Generates and selects the next best clue based on the current grid state.
-    - `constraints`: Optional `ClueGenerationConstraints`.
+    -### `session.getNextClue(options?: ClueGenerationConstraints)`
+
+Generates the next step in the puzzle, returning the best available clue based on internal scoring and provided constraints.
+
+### `session.getTotalClueCount()`
+
+Returns the total number of valid clues remaining in the pool.
+
+### `session.getMatchingClueCount(options?: ClueGenerationConstraints)`
+
+Returns the number of clues that match the current filtering criteria.
+
+### `session.getScoredMatchingClues(options?: ClueGenerationConstraints, limit: number = 50)`
+
+Returns a list of clues matching the constraints, sorted by heuristic score.
+Each result object contains:
+- `clue`: The Clue object.
+- `score`: The calculated helpfulness score.
+- `deductions`: The number of new cell updates this clue provides.
+- `isDirectAnswer`: Boolean indicating if this clue directly reveals the puzzle's goal.
+
+### `session.useClue(clue: Clue)`
+
+Manually applies a specific clue to the board. Useful for interactive search features.
+
+### `session.rollbackLastClue()`: Returns `{ success: boolean, clue: Clue | null }`. Undoes the last step.
 - `getNextClueAsync(constraints?)`: **New in v1.1.1**. Non-blocking version. Returns `Promise<{ clue, remaining, solved }>`.
 - `rollbackLastClue()`: Returns `{ success: boolean, clue: Clue | null }`. Undoes the last step.
 - `getGrid()`: Returns the current `LogicGrid` state.
@@ -277,7 +305,13 @@ let solved = false;
 while (!solved) {
     // 1. Get the next best clue (optionally force a specific type)
     const result = session.getNextClue({ 
-        allowedClueTypes: [ClueType.BINARY, ClueType.ORDINAL] 
+    // 1. Get the next best clue (optionally force a specific type)
+    const result = session.getNextClue({ 
+        allowedClueTypes: [ClueType.BINARY, ClueType.ORDINAL],
+        includeSubjects: ['Mustard', 'Plum'],     // Only clues about these entities
+        excludeSubjects: ['Revolver'],            // No clues dealing with Revolvers
+        minDeductions: 0                          // Allow "useless" clues (flavor text)
+    });
     });
 
     if (result.clue) {
@@ -294,8 +328,6 @@ while (!solved) {
 
 The library uses specific error types to help you debug configuration issues.
 
-| Method | Throws | Reason |
-| :--- | :--- | :--- |
 | Method | Throws | Reason |
 | :--- | :--- | :--- |
 | `new Generator()` | `Error` | If `seed` is invalid (NaN). |

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

@@ -15,6 +15,21 @@ export declare class GenerativeSession {
     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);
+    getTotalClueCount(): number;
+    getMatchingClueCount(constraints?: ClueGenerationConstraints): number;
+    getMatchingClues(constraints?: ClueGenerationConstraints, limit?: number): Clue[];
+    getScoredMatchingClues(constraints?: ClueGenerationConstraints, limit?: number): {
+        clue: Clue;
+        score: number;
+        deductions: number;
+        isDirectAnswer: boolean;
+    }[];
+    useClue(clue: Clue): {
+        remaining: number;
+        solved: boolean;
+    };
+    private filterClues;
+    private applyAndSave;
     getNextClue(constraints?: ClueGenerationConstraints): {
         clue: Clue | null;
         remaining: number;
@@ -38,4 +53,5 @@ export declare class GenerativeSession {
     getProofChain(): Clue[];
     getSolution(): Solution;
     getValueMap(): Map<ValueLabel, Record<string, ValueLabel>>;
+    private extractValuesFromClue;
 }

package/dist/src/engine/GenerativeSession.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GenerativeSession = void 0;
+const types_1 = require("../types");
 const LogicGrid_1 = require("./LogicGrid");
 const Solver_1 = require("./Solver");
 class GenerativeSession {
@@ -21,41 +22,116 @@ class GenerativeSession {
         // 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.
+    getTotalClueCount() {
+        return this.availableClues.length;
+    }
+    getMatchingClueCount(constraints) {
+        return this.filterClues(constraints).length;
+    }
+    getMatchingClues(constraints, limit = 50) {
+        const clues = this.filterClues(constraints);
+        return clues.slice(0, limit);
+    }
+    getScoredMatchingClues(constraints, limit = 50) {
+        const clues = this.filterClues(constraints);
+        // Score all (or up to a reasonable hard limit to avoid perf issues, say 200)
+        // Then sort and take top 'limit'
+        const candidateLimit = 200;
+        const candidates = clues.slice(0, candidateLimit);
+        const scored = candidates.map(clue => {
+            // Score Logic - similar to getNextClue but without the constraints checks (already done)
+            const tempGrid = this.grid.clone();
+            const { deductions } = this.solver.applyClue(tempGrid, clue);
+            // Calculate real score
+            const score = this.generator.calculateClueScore(this.grid, this.targetFact, deductions, clue, this.proofChain, this.solution, this.reverseSolution);
+            // Check if this is the "Direct Answer" (Positive link for the target fact)
+            let isDirectAnswer = false;
+            if (clue.type === types_1.ClueType.BINARY) {
+                // Check if it links the target subject to the target category
+                // Positive operators: IS (0). Assuming enum values.
+                const isPositive = clue.operator === types_1.BinaryOperator.IS;
+                if (isPositive) {
+                    const c = clue;
+                    const matchForward = c.cat1 === this.targetFact.category1Id && c.val1 === this.targetFact.value1 && c.cat2 === this.targetFact.category2Id;
+                    const matchReverse = c.cat2 === this.targetFact.category1Id && c.val2 === this.targetFact.value1 && c.cat1 === this.targetFact.category2Id;
+                    if (matchForward || matchReverse) {
+                        isDirectAnswer = true;
+                    }
+                }
+            }
+            return { clue, score, deductions, isDirectAnswer };
+        });
+        // Sort by score descending
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, limit);
+    }
+    useClue(clue) {
+        // Ensure the clue is removed from available if it was there
+        // (If searching, the UI passes a Clue object that should exist in our availableClues)
+        this.applyAndSave(clue);
+        return { remaining: this.availableClues.length, solved: this.generator.isPuzzleSolved(this.grid, this.solution, this.reverseSolution) };
+    }
+    filterClues(constraints) {
+        return this.availableClues.filter(clue => {
             // 2. Constraints
             if (constraints?.allowedClueTypes && !constraints.allowedClueTypes.includes(clue.type))
                 return false;
+            // Validation: Check for intersection
+            if (constraints?.includeSubjects && constraints?.excludeSubjects) {
+                const intersection = constraints.includeSubjects.filter(s => constraints.excludeSubjects.includes(s));
+                if (intersection.length > 0) {
+                    throw new Error(`Constraint Error: The following subjects are both included and excluded: ${intersection.join(', ')}`);
+                }
+            }
+            // Subject Constraints
+            if (constraints?.includeSubjects || constraints?.excludeSubjects) {
+                const valuesInClue = this.extractValuesFromClue(clue);
+                if (constraints.includeSubjects) {
+                    const hasMatch = constraints.includeSubjects.some(s => valuesInClue.includes(s));
+                    if (!hasMatch)
+                        return false;
+                }
+                if (constraints.excludeSubjects) {
+                    const hasMatch = constraints.excludeSubjects.some(s => valuesInClue.includes(s));
+                    if (hasMatch)
+                        return false;
+                }
+            }
             return true;
         });
+    }
+    applyAndSave(clue) {
+        // Save state
+        this.historyStack.push(this.grid.clone());
+        // Apply it
+        this.solver.applyClue(this.grid, clue);
+        this.proofChain.push(clue);
+        // Remove from available
+        const idx = this.availableClues.indexOf(clue);
+        if (idx > -1)
+            this.availableClues.splice(idx, 1);
+    }
+    getNextClue(constraints) {
+        const validClues = this.filterClues(constraints);
         // 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
+        // Shuffle validClues first to ensure variety.
         const candidates = [...validClues].sort(() => Math.random() - 0.5);
         // Take top N candidates?
         const searchLimit = 50;
         let checked = 0;
+        const minDeductions = constraints?.minDeductions ?? 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.
+            // Score Logic
+            // We must clone grid and apply to see deductions.
             const tempGrid = this.grid.clone();
             const { deductions } = this.solver.applyClue(tempGrid, clue);
-            if (deductions === 0 && !this.isUseful(tempGrid)) {
-                // Useless clue
+            // Check Deduction Floor
+            if (deductions < minDeductions) {
                 continue;
             }
             // Re-calc score with deductions
@@ -66,15 +142,7 @@ class GenerativeSession {
             }
         }
         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);
+            this.applyAndSave(bestClue);
             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) };
@@ -122,5 +190,24 @@ class GenerativeSession {
     getProofChain() { return this.proofChain; }
     getSolution() { return this.solution; }
     getValueMap() { return this.valueMap; }
+    extractValuesFromClue(clue) {
+        const values = [];
+        // Extract based on type (simpler than full traversal)
+        // We cast values to string for easy comparison
+        const add = (v) => { if (v !== undefined)
+            values.push(String(v)); };
+        // Common fields
+        // @ts-ignore
+        add(clue.val1);
+        // @ts-ignore
+        add(clue.val2);
+        // @ts-ignore
+        add(clue.item1Val);
+        // @ts-ignore
+        add(clue.item2Val);
+        // @ts-ignore
+        add(clue.targetVal);
+        return values;
+    }
 }
 exports.GenerativeSession = GenerativeSession;

package/dist/src/types.d.ts

@@ -83,4 +83,18 @@ export interface ClueGenerationConstraints {
      * Use this to control difficulty or puzzle attributes.
      */
     allowedClueTypes?: ClueType[];
+    /**
+     * If provided, only clues that refer to these specific values (as subjects or objects) will be generated.
+     * Useful for "Ask this suspect" mechanics.
+     */
+    includeSubjects?: string[];
+    /**
+     * If provided, clues referring to these values will be excluded.
+     */
+    excludeSubjects?: string[];
+    /**
+     * Minimum number of new deductions this clue must provide to be considered valid.
+     * Default is 0 (allow all clues). Set to 1 to ensure progress.
+     */
+    minDeductions?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logic-puzzle-generator",
-  "version": "1.1.9",
+  "version": "1.2.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"