NYT Connections Solver

Solves NYT Connections puzzles. Given 16 words, finds the 4 groups of 4 that belong together.

Best approach: Zero-shot Claude prompting achieves ~90%+ group accuracy. An algorithmic beam-search solver (GloVe + WordNet + wordplay detection) is also included, reaching 16.5% group accuracy without any LLM.

See RESULTS.md for detailed research findings.

Quick Start

LLM Solver (recommended)

Requires the Claude CLI (claude).

python -m connections.solve -w "SKATE,KEY,CARD,WHITE,EAGLE,TIGER,WHALE,SHARK,CRIMSON,AZURE,EMERALD,IVORY,GOLD,SILVER,BRONZE,COPPER"

Programmatic Use

from connections.solve import solve

groups = solve([
    "SKATE", "KEY", "CARD", "WHITE",
    "EAGLE", "TIGER", "WHALE", "SHARK",
    "CRIMSON", "AZURE", "EMERALD", "IVORY",
    "GOLD", "SILVER", "BRONZE", "COPPER",
])

for category, words in groups.items():
    print(f"{category}: {', '.join(words)}")

Algorithmic Solver

The beam-search solver works without any external API:

from connections.solver import solve

words = ["SKATE", "KEY", "CARD", "WHITE",
         "EAGLE", "TIGER", "WHALE", "SHARK",
         "CRIMSON", "AZURE", "EMERALD", "IVORY",
         "GOLD", "SILVER", "BRONZE", "COPPER"]

partitions = solve(words, beam_width=50, num_results=3)
for partition in partitions:
    for group in partition.groups:
        print(f"  {group.label or group.strategy}: {', '.join(group.words)}")

Evaluation

Run the solver against the test set (148 puzzles):

# Evaluate on 20 puzzles (quick check)
python -m connections.evaluate_final --num-puzzles 20

# Evaluate on full test set
python -m connections.evaluate_final --num-puzzles 0

# Save results to file
python -m connections.evaluate_final --num-puzzles 0 --output results.json

Project Structure

connections/
  solve.py              # LLM solver (Claude zero-shot) -- recommended
  solver.py             # Algorithmic beam-search solver
  evaluate_final.py     # Evaluation script
  models.py             # Data models (GroupCandidate, Partition)
  data_pipeline.py      # Dataset loading and splitting
  strategies/
    wordplay.py         # Compound word, hidden word, anagram detection
    embeddings.py       # GloVe embedding similarity
    wordnet_sim.py      # WordNet Wu-Palmer similarity
data/
  test.json             # 148 test puzzles
  train.json            # 707 training puzzles
  validate.json         # 159 validation puzzles
  connections_raw.json  # Raw puzzle corpus
  models/               # GloVe embeddings (50d, 100d)

Requirements

• Python 3.10+
• For the LLM solver: Claude CLI
• For the algorithmic solver: no external dependencies (wordplay only) or numpy (for GloVe embeddings)
• For evaluation: Claude CLI

Install development dependencies:

pip install -e ".[dev]"

License

MIT