PuzzleTide Puzzle Generator

PuzzleTide CLI — kelime avı, bulmaca & sudoku üretici

Kelime avı üretici, bulmaca üretici ve sudoku üretici + çözücü, hepsi bir arada yerel öncelikli bulmaca üretim CLI'sı — yazdırılabilir PDF çalışma kağıtları, başlangıç kelime bankaları, doğrulanabilir LLM değerlendirmeleri ve paketlenmiş ajan becerileri ile. puzzletide.com yapımcılarından.

Kurulum

npm install -g puzzletide
ptide --version

Paket her iki ikili dosyayı da kurar:

• ptide
• puzzletide

Neden bir CLI ile bulmaca üretmeli

Bir dil modelinden kelime avı yazmasını isteyin, kelimelerin yarısının bozuk olduğu bir ızgara alırsınız; ondan bir sudoku isteyin, genellikle birden fazla çözümü olan veya hiç çözümü olmayan bir tane alırsınız. Izgaralar, LLM'lerin kötü olduğu ve deterministik kodun iyi olduğu türden çıktılardır.

PuzzleTide CLI işte bu deterministik koddur:

• Her kelime avı kelimesi yerleştirilir ve doğrulanabilir — yerleştirme koordinatları çıktının bir parçasıdır ve üreticiler özellik testlerinden geçmiştir.
• Üretilen her sudoku'nun tam olarak bir çözümü olduğu kontrol edilir.
• Her bulmaca, döndürülmeden önce kendi ipuçlarına göre doğrulanır.
• Aynı --seed girdi, herhangi bir makinede aynı bulmaca çıktısını verir.

Paket ayrıca SKILL.md ajan becerileri ile birlikte gelir, böylece kodlama ajanları (Pi, Hermes, OpenClaw ve diğer SKILL.md tabanlı sistemler) ızgaraları elle yazmak yerine CLI'ye başvurur.

Komut modeli

ptide <namespace> <operation> [input] [options]   # for humans
ptide run <tool-id> [input] [options] --json      # canonical, for scripts/agents
ptide tools list | search <q> | info <id> | docs <id>
ptide agent manifest

Etkileşimli olarak kısa komutları, otomasyonda ise kanonik araç kimliklerini kullanın:

ptide sudoku generate --difficulty hard
ptide run puzzle.sudoku.generate --difficulty hard --json

Kelime avı üretici

Kolay/orta/zor ön ayarlarıyla sekiz yerleştirme yönü, otomatik boyutlandırılmış ızgaralar (6–30), aksan/boşluk/tire normalizasyonu. Kelimeler bayraklardan, dosyalardan veya paketlenmiş temalardan gelir:

# Word search from your own words, printed in the terminal
ptide wordsearch generate --words "coral,shark,kelp,wave,tide"

# Themed printable word search (puzzle page + solution page)
ptide wordsearch generate --theme animals/ocean-animals --pdf ocean.pdf

# Kids mode: easy = forward-only words
ptide wordsearch generate --theme seasonal/halloween --difficulty easy

Bulmaca üretici

Standart bulmaca numaralandırması, ipucu-ızgara doğrulaması ve tema kelimeleri için deterministik yedek ipuçları ile kenetlenen yerleştirme. Kenetlenemeyen kelimeler sessizce düşürülmek yerine raporlanır:

# Crossword with your clues
ptide crossword generate --words "PARIS: Capital of France; TOKYO: Capital of Japan"

# From a JSON file, as a printable PDF
ptide crossword generate --file words.json --pdf review.pdf --title "Unit 4 Review"

Sudoku üretici ve çözücü

Teklik garantisi, anlık çözücü ve çakışmaları, çözülebilirliği ve çözüm tekliğini raporlayan bir doğrulayıcı ile kolay, orta, zor ve uzman sudoku (17–21 verili hücre):

ptide sudoku generate --difficulty expert --seed 42
ptide sudoku solve "53..7....6..195....98....6.8...6...34..8.3..17...2...6.6....28....419..5....8..79"
ptide sudoku validate --file puzzle.txt
ptide daily        # today's daily sudoku, same for everyone on a given UTC day

Yazdırılabilir bulmacalar: PDF çalışma kağıtları ve SVG

Her üretici, yazdırmaya hazır bir çalışma kağıdı için --pdf <file> — bulmaca sayfa(lar)ı artı bir çözüm sayfası (--paper letter|a4, cevap anahtarını --no-solution-page ile atlayın) — ve vektör görüntüler için --svg <file> alır. Bir sınıf paketi için yazdırılabilir kelime avı ve yazdırılabilir sudoku sayfaları bir döngü uzağınızdadır:

for i in 1 2 3 4 5; do
  ptide sudoku generate --difficulty medium --seed "$i" --pdf "sudoku-$i.pdf" --title "Sudoku #$i"
done

Hazır sayfaları mı tercih edersiniz? gizem ve cinayet yazdırılabilir kelime avı okuyucuların favorisidir, yazdırılabilir bulmacalar adresinde yüzlercesi daha bulunur.

Kelime bankaları ve kelime araçları

30 başlangıç teması (okyanus hayvanları, meyveler, uzay, cadılar bayramı, ...) — göz atın, arayın, desen eşleştirin, anagramlar, rastgele seçimler. --words/--file aracılığıyla kendi listelerinizi getirin veya puzzletide.com adresindeki tam küratörlü koleksiyonu oynayın:

ptide words themes --search dinosaur
ptide words match "c_r_l"        # crossword-style pattern matching
ptide words anagram coral

Terminalde bir de adam asmaca oyunu var: ptide play hangman.

Ajan becerileri

Pi, paketlenmiş becerileri doğrudan bu npm paketinden yükleyebilir:

pi install npm:puzzletide

Paket manifestosu şunları bildirir:

{
  "pi": {
    "skills": ["./skills"]
  }
}

Beş beceri dahildir: kelime avı, bulmaca, sudoku, yazdırılabilir bulmacalar ve ajan değerlendirmeleri. Her biri yerel CLI'yi tercih eder ve ptide, puzzletide, ardından npx puzzletide'ü kontrol eder. Beceriler asla otomatik olarak hiçbir şey yüklemez; ajanlar yüklemeden önce kullanıcıya sormalıdır.

Claude Desktop, Cursor ve herhangi bir MCP istemcisi için MCP sunucusu

Yardımcı paket puzzletide-mcp, etkileşimli olmayan her aracı Model Bağlam Protokolü üzerinden sunar — aynı kelime avı üretici, bulmaca üretici, sudoku üretici/çözücü, kelime araçları ve değerlendirmeler, Claude Desktop, Cursor, Windsurf veya herhangi bir MCP istemcisinden çağrılabilir:

{
  "mcpServers": {
    "puzzletide": {
      "command": "npx",
      "args": ["-y", "puzzletide-mcp"]
    }
  }
}

Araç adları, argümanlar ve istemci başına kurulum için docs/mcp.md dosyasına bakın.

Araçlar

MCP sunucusu (ve ptide run <tool-id>) 15 araç sunar:

• puzzle_wordsearch_generate: Özel kelimelerden, dosyalardan veya temalı kelime bankalarından bir kelime avı ızgarası oluşturun — her yerleştirme doğrulanabilir, PDF/SVG ile yazdırılabilir.
• puzzle_crossword_generate: Standart numaralandırma ve doğrulanmış ipuçları ile kenetlenen bir bulmaca oluşturun.
• puzzle_sudoku_generate: Garantili benzersiz çözümü olan kolay, orta, zor veya uzman sudoku oluşturun.
• puzzle_sudoku_solve: 81 karakterlik dizgisinden bir sudoku çözün ve çözümün benzersiz olup olmadığını raporlayın.
• puzzle_sudoku_validate: Bir sudoku ızgarasını doğrulayın — çakışmalar, çözülebilirlik ve çözüm tekliği.
• words_categories: Kelime bankası kategorilerini listeleyin.
• words_themes: Paketlenmiş temalı kelime listelerini listeleyin veya arayın.
• words_list: Bir temadaki kelimeleri uzunluğa veya sayıya göre filtreleyerek listeleyin.
• words_match: Bulmaca tarzı bir desenle eşleşen kelimeleri bulun (c_r_l).
• words_anagram: Kelime bankasında verilen harflerin anagramlarını bulun.
• words_random: İsteğe bağlı olarak bir temadan rastgele bir kelime seçin.
• words_stats: Kelime bankası istatistikleri.
• eval_generate: LLM'leri ve ajanları kıyaslamak için tekrarlanabilir, nesnel olarak derecelendirilebilir bulmaca görevleri oluşturun.
• eval_check: Oluşturulan değerlendirme görevlerine verilen cevapları yapısal olarak derecelendirin — hiçbir cevap anahtarına güvenilmez.
• play_daily: Bugünün günlük sudokusunu yazdırın (bir UTC gününde herkes için aynı).

Doğrulanabilir LLM değerlendirmeleri

Bulmaca cevapları bir cevap anahtarı olmadan kontrol edilebilir: bir sudoku cevabı ya kuralları karşılar ve verilenleri korur ya da karşılamaz; bir kelime avı cevabı ya kelimeyi ızgarada düz bir çizgi boyunca heceler ya da hecelemez. Bu, bulmacaları LLM değerlendirmeleri için temiz kıyaslama görevleri haline getirir — LLM yargıcına gerek yoktur:

ptide eval generate --type sudoku --n 20 --difficulty hard --seed 1 --out tasks.json
# ...run your model on tasks.json, collect [{id, answer}] ...
ptide eval check --tasks tasks.json --answers answers.json --json

(tür, zorluk, n, seed) demeti görev setini tamamen belirler, bu nedenle tekrarlanabilir bir kıyaslama adlandırır.

Kütüphane kullanımı

Motorlar, CLI dahil olmadan içe aktarılabilir TypeScript'tir:

import { generateSudoku, generateWordSearch, wordSearchPdf } from 'puzzletide';

const sudoku = generateSudoku({ difficulty: 'hard', seed: 42 });
const search = generateWordSearch({
  words: ['coral', 'shark', 'kelp'],
  directions: ['E', 'S', 'SE'],
  seed: 7,
});
const pdfBytes = await wordSearchPdf(search, { title: 'Ocean Animals' });

Daha fazla belge:

• CLI komutları
• Araç kaydı
• Ajan becerileri

Çevrimiçi sürümler

Tarayıcıyı mı tercih edersiniz?

• PuzzleTide kelime avı
• PuzzleTide bulmaca
• PuzzleTide sudoku
• PuzzleTide adam asmaca
• Yazdırılabilir bulmacalar
• Kendi bulmacanı yap
• Disleksi dostu kelime avı yazı tipleri ve ayarları

Gizlilik

Her şey yerel olarak çalışır. Hesap yok, API anahtarı yok, telemetri yok, ağ erişimi yok.

Geliştirme

npm install
npm run build     # tsc → dist/
npm test          # vitest + fast-check property tests (build first: CLI tests run dist/)

Başlangıç kelime bankaları, bu paket için yazılmış genel, orijinal listelerdir (scripts/wordbanks-source.json, npm run build:wordbanks ile derlenmiştir). Tema katkıları memnuniyetle karşılanır — kaynak dosyaya bir giriş ekleyin ve derlemeyi çalıştırın. Tam küratörlü PuzzleTide kelime bankası koleksiyonu puzzletide.com'a özeldir ve bu deponun bir parçası değildir.

PuzzleTide CLI'ye Atıf Yapma

Çalışmanızda PuzzleTide CLI kullanıyorsanız — örneğin bir model kıyaslamasındaki doğrulanabilir bulmaca değerlendirmeleri — lütfen atıfta bulunun (veya GitHub'ın "Bu depoya atıfta bulun" düğmesini kullanın):

@software{puzzletide_cli,
  author  = {{Caravaca Labs}},
  title   = {PuzzleTide CLI: word search, crossword \& sudoku generator with verifiable LLM evals},
  year    = {2026},
  url     = {https://github.com/Caravaca-Labs/puzzletide-cli},
  note    = {From the makers of \url{https://puzzletide.com}}
}

Düz metin: "PuzzleTide CLI (Caravaca Labs, 2026), https://github.com/Caravaca-Labs/puzzletide-cli — https://puzzletide.com. yapımcılarından"

Lisans

MIT © Caravaca Labs