logic-puzzle-generator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# Logic Puzzle Generator
+
+![Version](https://img.shields.io/github/package-json/v/joshhills/logic-puzzle-generator)
+![Tests](https://github.com/joshhills/logic-puzzle-generator/actions/workflows/test.yml/badge.svg?label=Tests)
+![License](https://img.shields.io/badge/license-MIT-green)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)
+
+
+A TypeScript library for generating, solving, and verifying "Zebra Puzzle" style logic grid puzzles.
+
+Unlike standard generators, this library creates **goal-oriented puzzles**: you can specify a "Target Fact" (e.g., "What snack does David eat?") that will be the final deduction required to complete the puzzle. The generator ensures a step-by-step logical path exists to reach this conclusion when facts are presented in a specific order.
+
+The intention is for this library to empower narrative designers to create mysteries that are both solvable and engaging.
+
+## Features
+
+- **Goal-Oriented Generation**: Targeted generation ensures the puzzle builds towards a specific revelation. (Note: A target is naturally selected if none is provided, ensuring every puzzle behaves as a coherent mystery.)
+- **Rich Clue Types**: 
+    - **Binary**: IS / IS NOT
+    - **Ordinal**: Older/Younger + Negative (Not Before/After)
+    - **Cross-Ordinal**: Transitive relationships across different ordinal axes + Negated (Match/Not Match).
+    - **Superlative**: Extremes (Oldest/Youngest) + Negative (Not Oldest).
+    - **Unary**: Properties (Even/Odd). Requires at least one ordinal category that contains a mix of both odd and even numeric values.
+- **Complexity Variance**: The generator intelligently varies clue complexity to create a balanced puzzle flow.
+- **Clue Constraints**: Filter which clue types are allowed (e.g., disable Ordinal clues) for custom difficulty.
+- **Proof Chain**: Generates a full step-by-step solution path ("Proof Chain").
+- **Type-Safe**: Written in TypeScript with comprehensive type definitions.
+- **Configurable**: Define your own categories, values, and constraints.
+- **Reproducible**: Seed-based RNG ensures deterministic results. The seed controls:
+    - **Solution Generation**: The underlying logic grid truth.
+    - **Target Selection**: Which fact serves as the mystery focus.
+    - **Clue Template Variation**: Randomization of names, values, and sentence structures.
+    - **Search & Scoring**: The order in which candidates are evaluated.
+
+## Installation
+
+```bash
+npm install logic-puzzle-generator
+```
+
+## Quick Start
+
+Here's how to generate a simple puzzle where you want to find out what "David" is eating.
+
+```typescript
+import { Generator, CategoryType, Puzzle } from 'logic-puzzle-generator';
+
+// 1. Define your categories
+const categories = [
+    { id: 'Name', type: CategoryType.NOMINAL, values: ['Alice', 'Bob', 'David'] },
+    { id: 'Snack', type: CategoryType.NOMINAL, values: ['Chips', 'Popcorn', 'Candy'] },
+    { id: 'Age', type: CategoryType.ORDINAL, values: [20, 30, 40] }, // Ordinal allows for 'older/younger' clues
+];
+
+// 2. Define the target fact (The "Goal" of the puzzle)
+// We want the solver to deduce that 'Name: David' is linked to a specific value in 'Snack'.
+// Note: If you omit this, the generator will pick a random mystery for you.
+const targetFact = {
+    category1Id: 'Name',
+    value1: 'David',
+    category2Id: 'Snack',
+};
+
+// 3. Generate the puzzle
+const generator = new Generator(12345); // Seed controls solution generation, target selection, and clue variation.
+const puzzle: Puzzle = generator.generatePuzzle(categories, targetFact);
+
+// 4. View the results
+console.log('The Clues:');
+puzzle.clues.forEach((clue, i) => console.log(`${i + 1}.`, clue));
+
+// 5. Inspect the Logic
+console.log('\nThe Solution Path:');
+console.log(JSON.stringify(puzzle.proofChain[0], null, 2)); 
+// Example Output:
+// {
+//   "clue": { "type": "binary", "cat1": "Name", "val1": "Alice", "cat2": "Snack", "val2": "Popcorn", "operator": "is" },
+//   "deductions": 2
+// }
+```
+
+## Core Concepts
+
+### Categories
+- **Nominal**: Categories where order doesn't matter (e.g., Names, Colors, Snacks).
+- **Ordinal**: Categories that have an inherent order (e.g., Age, Price, Floor Number). These unlock special clues like "The person eating Chips is older than Alice".
+  > **Note**: Ordinal values must be numbers. ConfigurationError will be thrown if strings are provided.
+
+## Configuration
+
+The `generatePuzzle` method takes an array of `CategoryConfig` objects.
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `id` | `string` | Unique identifier for the category (e.g., "Color"). |
+| `type` | `CategoryType` | `NOMINAL` (unordered) or `ORDINAL` (ordered integers). |
+| `values` | `(string\|number)[]` | Array of possible values. Must be unique. If `ORDINAL`, must be sorted numbers. |
+
+### Error Handling
+
+The library provides strict validation. A `ConfigurationError` is thrown in the following scenarios:
+1.  **Invalid Ordinals**: Providing non-numeric values for a category marked as `ORDINAL`.
+2.  **Duplicate Values**: Categories contain duplicate value entries.
+3.  **Invalid Target**: The requested `Target Fact` refers to a category or value that does not exist.
+4.  **Impossible Constraints**: A custom constraint or seed results in immediate contradiction.
+5.  **Ambiguous Constraints**: Providing *only* "Weak" clue types (`UNARY`, `SUPERLATIVE`) results in an unsolvable puzzle. The configuration must include at least one "Strong" type (`BINARY`, `ORDINAL`, or `CROSS_ORDINAL`) to uniquely resolve identities.
+
+```typescript
+import { ConfigurationError } from 'logic-puzzle-generator';
+
+try {
+    const puzzle = generator.generatePuzzle(invalidConfig, target);
+} catch (err) {
+    if (err instanceof ConfigurationError) {
+        console.error("Config Error:", err.message);
+    }
+}
+```
+
+## How It Works
+
+### The Algorithm
+The generator uses a **Forward-Chaining Heuristic Search** to build the puzzle:
+
+1.  **Solution Seeding**: A valid, consistent solution grid is randomly generated based on the seed.
+2.  **Clue Generation**: Every possible true clue (Binary, Ordinal, etc.) is generated based on this solution.
+3.  **Heuristic Selection**: The solver iteratively selects the "best" clue to add to the puzzle. The "best" clue is determined by a scoring function that balances:
+    *   **Synergy**: Does it lead to new deductions when combined with existing clues?
+    *   **Completeness**: Does it help eliminate impossible options?
+    *   **Complexity**: Is it an interesting clue type (e.g., `Superlative` > `Binary`)?
+4.  **Penalties**: To ensure variety, the score is penalized if:
+    *   The clue refers to **Solution Groups** (specific entity combinations) that are already mentioned frequently.
+    *   The clue type is repeated (preventing boring lists of "IS/IS NOT" clues).
+    *   The clue is redundant (adds no new information).
+5.  **Termination**: The process repeats until the `Target Fact` is logically deducible from the selected clues alone.
+
+## Performance & Scalability
+
+The library is optimized for performance and uses heuristic sampling.
+
+| Dimensions | Approx Time | Notes |
+| :--- | :--- | :--- |
+| **3 cats, 4 vals** | ~20ms | Instant generation. |
+| **4 cats, 5 vals** | ~600ms | Standard logic puzzle size. |
+| **5 cats, 5 vals** | ~3s | Large, complex grid. |
+| **8 cats, 5 vals** | ~8s | Extreme. Use `maxCandidates: 50` for speed. |
+
+### Large Puzzles
+For puzzles with 6+ categories or high complexity, use the `maxCandidates` option in `generatePuzzle`. This limits the search space at each step (e.g. only check random 50 clues instead of 1000s) to keep generation fast while maintaining solvability.
+
+### Controlling Clue Count
+By default, the generator produces the most efficient puzzle it can find. To target a specific difficulty or length, you can request an exact number of clues.
+
+1.  **Estimate Feasibility**:
+    ```typescript
+    const bounds = generator.getClueCountBounds(categories, target); 
+    // -> { min: 4, max: 12 }
+    ```
+2.  **Generate**:
+    ```typescript
+    const puzzle = generator.generatePuzzle(categories, target, {
+        targetClueCount: 8, // Must be within feasible range
+        maxCandidates: 100,
+        timeoutMs: 180000 // Recommended: Give it time (3 mins) to find exact matches
+    });
+    ```
+
+    > **Note**: This uses a **Hybrid Iterative Correction** algorithm. If the generator detects it is falling behind or solving too fast, it switches strategies (Stall vs Speed) and commits to them ("Sticky Strategy") to navigate complex search spaces. This ensures effective pathfinding for hard targets (e.g., 26 clues on 4x4).
+
+### Clues
+The generator produces four types of clues:
+1.  **Binary**: Direct relationships. "Alice eats Chips" or "Bob does NOT eat Popcorn".
+2.  **Ordinal**: Comparisons. "The person eating Chips is younger than Bob" or "Alice is NOT older than Charlie".
+3.  **Cross-Ordinal**: Complex relativity. "The item before Alice (Age) is the item after Bob (Cost)".
+4.  **Superlative**: Extremes. "Alice is the oldest" or "Bob is NOT the youngest".
+5.  **Unary**: Properties. "The person eating Chips is an even age".
+
+### The Proof Chain
+The generator solves the puzzle as it builds it. The `puzzle.proofChain` array contains the optimal order of clues to solve the grid. This is useful for building hint systems or verify difficulty.
+
+## API Reference
+
+### `Generator`
+The main class. Use `new Generator(seed)` to initialize.
+
+- `generatePuzzle(categories, target, options)`: Returns a `Puzzle` object.
+    - `options.targetClueCount`: Attempt to find exact solution length.
+    - `options.maxCandidates`: Performance tuning (default 50).
+    - `options.onTrace`: **(Debug)** Callback `(msg: string) => void`. Receives real-time logs about the generation process (e.g., "Backtracking", "Pruning", "Solution Found"). Useful for debugging timeouts or understanding the generator's decision making.
+- `getClueCountBounds(categories, target)`: Returns plausible Min/Max clue counts.
+- `startSession(categories, target?)`: [Beta] Starts a `GenerativeSession` for step-by-step interactive generation (useful for "Builder Mode" UIs).
+
+### Extensibility
+The `Generator` class is designed to be extensible. Key methods like `calculateClueScore` are `public`, allowing you to extend the class and inject custom heuristics.
+
+### `LogicGrid`
+Manages the state of the puzzle grid (possibility matrix).
+- `isPossible(cat1, val1, cat2, val2)`: Returns true if a connection is possible.
+- `setPossibility(...)`: Manually set states (useful for custom solvers).
+
+### `Solver`
+The logical engine.
+- `applyClue(grid, clue)`: Applies a clue and cascades deductions.
+
+## AI Disclosure & Liability Policy
+
+### Transparency Statement
+This project utilizes artificial intelligence (AI) tools to assist in the generation of code, logic algorithms, and documentation. While human oversight is rigorously applied, portions of the codebase are AI-generated.
+
+### Copyright and Licensing
+- **Human Contribution**: The project structure, architectural decisions, core logic verification, and test suites are human-authored and covered by the standard project license.
+- **AI-Generated Content**: To the extent that AI-generated content is not eligible for copyright protection, it is dedicated to the public domain. Where copyrightable, it is licensed under the MIT license alongside human contributions.
+
+### "AS IS" and Liability Waiver
+This software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.
+
+### Accuracy Warning
+While all code is reviewed and tested, complete accuracy cannot be guaranteed. Users are responsible for verifying that the puzzle generation logic meets the strict requirements of their specific use cases.
+
+## License
+MIT

package/dist/Clue.d.ts

@@ -0,0 +1,81 @@
+import { ValueLabel } from './types';
+/**
+ * Enumeration of all supported clue types.
+ */
+export declare enum ClueType {
+    /** Expresses a direct relationship (IS or IS NOT) between two values. */
+    BINARY = 0,
+    /** Expresses a comparison (GREATER THAN or LESS THAN) between two values based on an ordinal category. */
+    ORDINAL = 1,
+    /** Expresses an extreme value relationship (MIN or MAX) within an ordinal category. */
+    SUPERLATIVE = 2,
+    /** Expresses a property of a single value (e.g., IS EVEN) relative to an ordinal category. */
+    UNARY = 3
+}
+export declare enum BinaryOperator {
+    IS = 0,
+    IS_NOT = 1
+}
+export declare enum OrdinalOperator {
+    GREATER_THAN = 0,
+    LESS_THAN = 1
+}
+export declare enum SuperlativeOperator {
+    MIN = 0,
+    MAX = 1
+}
+export declare enum UnaryFilter {
+    IS_ODD = 0,
+    IS_EVEN = 1
+}
+/**
+ * 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;
+}
+export type Clue = BinaryClue | OrdinalClue | SuperlativeClue | UnaryClue;

package/dist/Clue.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnaryFilter = exports.SuperlativeOperator = exports.OrdinalOperator = exports.BinaryOperator = exports.ClueType = void 0;
+/**
+ * Enumeration of all supported clue types.
+ */
+var ClueType;
+(function (ClueType) {
+    /** Expresses a direct relationship (IS or IS NOT) between two values. */
+    ClueType[ClueType["BINARY"] = 0] = "BINARY";
+    /** Expresses a comparison (GREATER THAN or LESS THAN) between two values based on an ordinal category. */
+    ClueType[ClueType["ORDINAL"] = 1] = "ORDINAL";
+    /** Expresses an extreme value relationship (MIN or MAX) within an ordinal category. */
+    ClueType[ClueType["SUPERLATIVE"] = 2] = "SUPERLATIVE";
+    /** Expresses a property of a single value (e.g., IS EVEN) relative to an ordinal category. */
+    ClueType[ClueType["UNARY"] = 3] = "UNARY";
+})(ClueType || (exports.ClueType = ClueType = {}));
+var BinaryOperator;
+(function (BinaryOperator) {
+    BinaryOperator[BinaryOperator["IS"] = 0] = "IS";
+    BinaryOperator[BinaryOperator["IS_NOT"] = 1] = "IS_NOT";
+})(BinaryOperator || (exports.BinaryOperator = BinaryOperator = {}));
+var OrdinalOperator;
+(function (OrdinalOperator) {
+    OrdinalOperator[OrdinalOperator["GREATER_THAN"] = 0] = "GREATER_THAN";
+    OrdinalOperator[OrdinalOperator["LESS_THAN"] = 1] = "LESS_THAN";
+})(OrdinalOperator || (exports.OrdinalOperator = OrdinalOperator = {}));
+var SuperlativeOperator;
+(function (SuperlativeOperator) {
+    SuperlativeOperator[SuperlativeOperator["MIN"] = 0] = "MIN";
+    SuperlativeOperator[SuperlativeOperator["MAX"] = 1] = "MAX";
+})(SuperlativeOperator || (exports.SuperlativeOperator = SuperlativeOperator = {}));
+var UnaryFilter;
+(function (UnaryFilter) {
+    UnaryFilter[UnaryFilter["IS_ODD"] = 0] = "IS_ODD";
+    UnaryFilter[UnaryFilter["IS_EVEN"] = 1] = "IS_EVEN";
+})(UnaryFilter || (exports.UnaryFilter = UnaryFilter = {}));

package/dist/Generator.d.ts

@@ -0,0 +1,58 @@
+import { CategoryConfig, Solution, TargetFact } from './types';
+import { Clue } from './Clue';
+/**
+ * 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;
+}
+/**
+ * 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.
+     *
+     * @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 complete Puzzle object containing the solution, clues, and proof chain.
+     */
+    generatePuzzle(categories: CategoryConfig[], target: TargetFact): Puzzle;
+    private createSolution;
+    private generateAllPossibleClues;
+    private calculateScore;
+    private isPuzzleSolved;
+}