logic-grid

Generate and solve logic grid puzzles (zebra puzzles / Einstein's riddles) in TypeScript. Zero-dependency core with optional AI-themed category generation.

→ Try the live demo

Quick start

npm install logic-grid

import { generate, solve } from "logic-grid";

const puzzle = generate({ size: 4, difficulty: "medium" });

console.log(puzzle.clues.map((c) => c.text));
// ["Alice owns the dog.", "The fish owner lives in the red house.", ...]

const solution = solve(puzzle.constraints, puzzle.grid);

For AI-generated themed puzzles (requires an Anthropic API key):

npm install logic-grid-ai logic-grid

import { generateTheme } from "logic-grid-ai";
import { generate } from "logic-grid";

const theme = await generateTheme({
  theme: "pirate adventure",
  size: 4,
  categories: 4,
});

const puzzle = generate({
  size: 4,
  categoryNames: theme.categories,
});
// Clues like: "Blackbeard commands the Revenge."

Features

• SAT-based — DPLL solver with watched literals, puzzles encoded as CNF
• Zero dependencies — ~15kb gzipped (core)
• Step-by-step deduction — explain solutions in human terms with named techniques (naked single, hidden pair, contradiction, …)
• Multi-axis ordered categories — comparators (before, next_to, between, exact_distance, …) on any ordered axis
• Custom categories — bring your own values, nouns, and verb phrases
• AI-themed generation — describe a theme, get fully structured puzzle categories with consistent comparator phrasing (via logic-grid-ai)
• Difficulty classification — easy / medium / hard / expert
• Sizes 3–8 — generate up to 8×8 grids in <100ms

See the logic-grid README for the full API.

Packages

• logic-grid — Generator, SAT solver, and step-by-step deduction. Zero dependencies. (npm)
• logic-grid-ai — AI-themed category generation backed by the Anthropic API. (npm)
• logic-grid-demo — SvelteKit browser demo exercising both packages, deployed at the live demo.

Development

npm install
npm run check    # typecheck + lint + format + test
npm run build    # build all packages

License

MIT