wordulator 1.0.0

package/LISCENSE

@@ -0,0 +1,7 @@
+Copyright © 2026 Arlo Filley
+
+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,95 @@
+# WORDULATOR
+## An Automated Entropy Based Wordle Guessing Bot
+
+**Do you average 6 guesses at Wordle like I do?**
+**If so then this is the repository you've been looking for!**
+
+This is a Node.js implementation of a Wordle guessing bot. Uses entropy and several
+heuristics to average 3.83 guesses per answer with 99% accuracy! *Tested over 
+100 different cases, accuracy is defined as getting the answer within the 6 allowed
+guesses*
+
+This project was built over the course of 4 days so don't expect it to be fast
+or optimal. It was however an interesting dive into entropy, bitwise optimisation, 
+and implementing the Wordle ruleset!
+
+## Installation
+- Clone repo
+- Navigate to `./` in terminal
+- Run `npm run install-wordulator` - and wait to finish
+  - Installs base Wordle solutions and guesses
+  - Precomputes feedback matrix - This step might take a while
+  - Creates 5000 benchmark test cases from the solution list
+- All Done
+
+### Usage
+- Run in **user** mode using `node .`
+- Run a standard **benchmark** using `npm run benchmark`
+- Run a custom **benchmark** using `node . combo bench (# of tests)`
+- Enjoy
+
+### Example Usage
+![](./docs/Example%20Usage.png)
+
+### Example Benchmark
+![](./docs/Example%20Benchmark.png)
+
+## Features
+- Implements full Wordle ruleset - with automated feedback for efficient benchmarking
+- Entropy guess scoring with several adjusting heuristics including
+  - Positional letter frequencies
+  - Non-overlapping letters
+  - Guess being a possible remaining answer
+- Capable of using most\* 5 letter word lists (\*with A-Z charset)
+- Precomputation of feedback matrix
+- Memory mapping of feedback matrix allowing parallel program execution
+- Automated benchmarking for running up to thousands of tests
+  
+## Known Issues
+- Feedback matrix consumes significant disk and memory space
+- Limited to 5-letter Wordle variants
+- Missing many possible runtime performance optimisations
+- Assumes only ASCII characters a-z in wordlist
+
+## Ideas for Future Improvement
+- Weighting heuristics scores based on possible words left
+- Precomputed second guesses
+- Massive Performance optimisations
+- User-friendly web interface
+- Rewrite in rust?
+
+# How it Works
+## Feedback Modeling
+This program models Wordle feedback per letter as green, yellow or grey and encodes 
+that into an 8 bit integer, using ~2 bits per letter position. Because Wordle has 
+5 positions which each have 3 possibilities this means there are 243 possible feedbacks. 
+Each guess and answer pair is mapped into a deterministic feedback pattern represented 
+by the feedback matrix. The feedback matrix is precomputed before running the problem 
+as it significantly speeds up runtime performance at the cost of greater disk and 
+memory usage. The matrix allows simulating potential outcomes from each guess-answer 
+pair to model expected information gain
+
+## Scoring
+Each possible guess in the total word list is evaluate based on its entropy. This
+entropy in turn is based on simulating how the remaining possible answers would
+be partitioned be a given feedback. Guesses with higher entropy eliminate more potential
+answers than guesses with lower entropy\* (\*In the vast majority of cases). Each
+score is then adjusted based on the positional frequency of each letter in the guess
+based on the positional frequencies of remaining possible answers. The score is
+also adjusted based on whether letters in the guess have already been seen before
+in a previous guess. And finally the score is higher for guesses that are also contained
+in the possible answer set. These heuristics are great for picking more optimal
+guesses that still have high entropy.
+
+## Solving
+To solve a given Wordle problem, the program:
+  1. Makes a first predetermined guess (currently 'dares')
+  2. Receives user or simulated feedback
+  3. Create conditions the solution must fulfil
+  4. Filters possible answers based on currently known solution conditions
+  5. Makes another guess
+
+This loop repeats steps 2-5 until:
+- a) There is only one possible answer, the solution
+- b) The program has used up its 6 guesses
+- c) There is no possible answer that meets the solution conditions

package/main.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+let { solve : combinedSolver   } = require('./src/solvers/combined.js')
+let { randomInt } = require('./src/lib/lib.js')
+
+let words = require('./data/filter/words.json');
+let test_data = require('./data/test/tests.json')
+
+main();
+async function main() {
+    try {
+        const args          = process.argv.slice(2);
+        const type          = typeof(args[0]) === 'string'  ? args[0] : 'user';
+        const num           = args[1] > 0                   ? Number.parseInt(args[1]) : 100;
+    
+        let solve = combinedSolver;
+
+        switch (type) {
+            case 'bench'     : await benchmark(solve, num, test_data, console.log);                  break;
+            case 'benchmark' : await benchmark(solve, num, test_data, console.log);                  break;                                          break;
+            case 'user'      : await solve({ type: "user", rand: true, log: console.log }); break;
+            default: throw `Invalid Mode Selected ${type}`
+        }
+    
+        process.exit(0);
+    } catch (err) {
+        console.error(err);
+        process.exit(1)
+    }
+}
+
+/**
+ * 
+ * @param {function} solve 
+ * @param {num} benchmark_num 
+ * @param {object} weights 
+ * @param {string[]} tests 
+ * @param {function} log
+ */
+async function benchmark(solve, benchmark_num = 100, tests, log) {
+    const results = [];
+    let total_guesses = 0;
+    let correct = 0;
+    let no_of_guesses = [0, 0, 0, 0, 0, 0];
+    let avg = 0;
+
+    for (let i=0; i < benchmark_num; i++) {
+        let ans = words[randomInt(words.length)];
+        let result;
+
+        if (tests !== undefined) ans = tests[i];
+        result = await solve({ type: 'benchmark', answer: ans, log: () => {} });
+
+        if (result.solved === true) {
+            total_guesses += result.guesses;
+            correct++;
+            no_of_guesses[result.guesses-1]++;
+            avg = total_guesses/(i+1);
+        } else {
+            avg = total_guesses/(i+1);
+            total_guesses += 8;
+        }
+
+        if (/*i % 20 === 0 &&*/ result.solved) {
+            log(`Solved ${correct}/${i+1} | guesses:  ${result.guesses} | accuracy ${(correct / (i+1) * 100).toFixed(1)} | running avg: ${avg.toFixed(2)}`);
+        } else /*if (i % 20 === 0)*/ {
+            log(`Solved ${correct}/${i+1} | guesses: >6 | accuracy ${(correct / (i+1) * 100).toFixed(1)} | running avg: ${avg.toFixed(2)}`);
+        }
+
+        results.push(result);
+    }
+
+    log(`Correct   - ${correct}/${benchmark_num} - ${correct / benchmark_num * 100}%`);
+    log(`Avg Guess - ${avg.toFixed(3)}`);
+    log('Guess Breakdown:')
+    for (let i=0; i<no_of_guesses.length; i++) {
+        if (i === 0) {
+            log(`\t${i+1} guess   - ${no_of_guesses[0]}`);
+        } else {
+            log(`\t${i+1} guesses - ${no_of_guesses[i]}`);
+        }
+    }
+
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "wordulator",
+  "version": "1.0.0",
+  "description": "An Entropy Based Wordle Solver",
+  "keywords": ["wordle", "entropy"],
+  "license": "MIT",
+  "author": "Arlo Filley",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ArloFilley/Wordulator"
+  },
+  "type": "commonjs",
+  "main": "main.js",
+  "bin": {
+    "wordulator": "node ./main.js"
+  },
+  "scripts": {
+    "test": "echo \"What the hell is a test???? YALL TESTING UR CODE??? GETTOUTAHEER!!!\" && exit 1",
+    "install-wordulator": "chmod u+x run/install.bash && run/install.bash && chmod u+x run/benchmark.bash",
+    "benchmark": "run/benchmark.bash",
+    "bench": "run/benchmark.bash"
+  },
+  "dependencies": {
+    "@luminati-io/mmap-io": "^1.1.7-lum.6",
+    "i": "^0.3.7",
+    "npm": "^11.8.0"
+  }
+}

package/run/benchmark.bash

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+echo "Running benchmark, results saved to ./bench/benchmark.txt"
+time node . bench 100 | tee "./bench/benchmark.txt"

package/run/install.bash

@@ -0,0 +1,61 @@
+#!/bin/bash
+echo "installing node modules"
+npm i
+wait
+sleep 5
+
+echo "Creating Directory Structure"
+sleep 0.2
+echo "Created ./data"
+sleep 0.2
+mkdir data
+echo "Created ./data/filter"
+mkdir data/filter
+sleep 0.2
+echo "Created ./data/proc"
+mkdir data/proc
+sleep 0.2
+echo "Created ./data/raw"
+mkdir data/raw
+sleep 0.2
+echo "Created ./data/test"
+mkdir data/test
+sleep 0.2
+echo "Created ./bench"
+mkdir bench
+
+wait
+sleep 5
+
+echo "Copying Files Into Correct Places"
+cp run/wordle.txt data/raw/wordle.txt
+sleep 0.2
+echo "Copied ./run/wordle.txt -> ./data/raw/wordle.txt"
+cp run/solutions.txt data/raw/solutions.txt
+sleep 0.2
+echo "Copied ./run/solutions.txt -> ./data/raw/solutions.txt"
+
+wait
+sleep 1
+
+echo "Filtering List For Valid Words"
+node src/pre/filter_words.js data/raw/wordle.txt data/filter/words.json 5
+node src/pre/filter_words.js data/raw/solutions.txt data/filter/solutions.json 5
+
+wait
+sleep 1
+
+echo "Generating Feedback Matrix"
+echo "This Step Might Take a While"
+echo "The Feedback Matrix Can Be Found at data/proc/feedback_matrix.bin It Takes Up Roughly 200mb For 12k Words"
+node ./src/pre/feedback_matrix.js data/filter/words.json data/proc/feedback_matrix.bin
+
+wait
+sleep 1
+
+echo "Generating Benchmark Tests"
+node src/pre/test.js data/filter/solutions.json data/test/tests.json 5000
+
+wait
+sleep 1
+echo "Everything installed correctly :>"