PuzzleTide Puzzle Generator

PuzzleTide CLI — gerador de caça-palavras, palavras cruzadas e sudoku

Gerador de caça-palavras, gerador de palavras cruzadas e gerador + solucionador de sudoku em uma única CLI de geração de puzzles local-first — com planilhas em PDF para imprimir, bancos de palavras iniciais, avaliações de LLM verificáveis e habilidades de agente integradas. Dos criadores do puzzletide.com.

Instalar

npm install -g puzzletide
ptide --version

O pacote instala ambos os binários:

• ptide
• puzzletide

Por que gerar puzzles com uma CLI

Peça a um modelo de linguagem para escrever um caça-palavras e você obtém uma grade onde metade das palavras estão quebradas; peça um sudoku e geralmente recebe um com várias soluções, ou nenhuma. Grades são exatamente o tipo de resultado em que LLMs são ruins e código determinístico é bom.

A PuzzleTide CLI é esse código determinístico:

• Cada palavra do caça-palavras é colocada e verificável — as coordenadas de colocação fazem parte da saída, e os geradores são testados por propriedade.
• Cada sudoku gerado é verificado para ter exatamente uma solução.
• Cada palavras cruzadas é validada contra suas próprias pistas antes de ser retornada.
• Mesmo --seed de entrada, mesmo puzzle de saída, em qualquer máquina.

O pacote também inclui habilidades de agente SKILL.md, para que agentes de codificação (Pi, Hermes, OpenClaw e outros sistemas baseados em SKILL.md) usem a CLI em vez de escrever grades manualmente.

Modelo de comando

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

Use comandos curtos interativamente e IDs de ferramenta canônicos em automação:

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

Gerador de caça-palavras

Oito direções de colocação com predefinições fácil/médio/difícil, grades de tamanho automático (6–30), normalização de acentos/espaços/hífens. As palavras vêm de flags, arquivos ou temas incluídos:

# 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

Gerador de palavras cruzadas

Colocação entrelaçada com numeração padrão de palavras cruzadas, validação de grade de pistas e pistas de fallback determinísticas para palavras temáticas. Palavras que não podem ser entrelaçadas são relatadas em vez de silenciosamente descartadas:

# 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"

Gerador e solucionador de sudoku

Sudoku fácil, médio, difícil e expert (17–21 dados) com garantia de unicidade, um solucionador instantâneo e um validador que relata conflitos, solubilidade e unicidade da solução:

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

Puzzles para imprimir: planilhas em PDF e SVG

Cada gerador aceita --pdf <file> para uma planilha pronta para impressão — página(s) do puzzle mais uma página de solução (--paper letter|a4, omita a chave de resposta com --no-solution-page) — e --svg <file> para imagens vetoriais. Planilhas de caça-palavras e sudoku para imprimir para um pacote de sala de aula estão a um loop de distância:

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

Prefere planilhas prontas? O caça-palavras para imprimir de mistério e assassinato é um favorito dos leitores, com centenas mais em puzzles para imprimir.

Bancos de palavras e ferramentas de palavras

30 temas iniciais (animais do oceano, frutas, espaço, halloween, ...) — navegue, pesquise, correspondência de padrões, anagramas, escolhas aleatórias. Traga suas próprias listas via --words/--file, ou jogue a coleção completa curada em puzzletide.com:

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

Há também um jogo da forca no terminal: ptide play hangman.

Habilidades do agente

O Pi pode carregar as habilidades incluídas diretamente deste pacote npm:

pi install npm:puzzletide

O manifesto do pacote declara:

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

Cinco habilidades estão incluídas: caça-palavras, palavras cruzadas, sudoku, puzzles para imprimir e avaliações de agente. Cada uma prefere a CLI local e verifica ptide, puzzletide, então npx puzzletide. As habilidades nunca instalam nada automaticamente; os agentes devem perguntar ao usuário antes de instalar.

Servidor MCP para Claude Desktop, Cursor e qualquer cliente MCP

O pacote complementar puzzletide-mcp expõe todas as ferramentas não interativas através do Model Context Protocol — o mesmo gerador de caça-palavras, gerador de palavras cruzadas, gerador/solucionador de sudoku, ferramentas de palavras e avaliações, acessíveis a partir do Claude Desktop, Cursor, Windsurf ou qualquer cliente MCP:

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

Veja docs/mcp.md para nomes de ferramentas, argumentos e configuração por cliente.

Ferramentas

O servidor MCP (e ptide run <tool-id>) expõe 15 ferramentas:

• puzzle_wordsearch_generate: Gera uma grade de caça-palavras a partir de palavras personalizadas, arquivos ou bancos de palavras temáticos — cada colocação verificável, imprimível via PDF/SVG.
• puzzle_crossword_generate: Gera palavras cruzadas entrelaçadas com numeração padrão e pistas validadas.
• puzzle_sudoku_generate: Gera sudoku fácil, médio, difícil ou expert com uma solução única garantida.
• puzzle_sudoku_solve: Resolve um sudoku a partir de sua string de 81 caracteres e relata se a solução é única.
• puzzle_sudoku_validate: Valida uma grade de sudoku — conflitos, solubilidade e unicidade da solução.
• words_categories: Lista categorias de banco de palavras.
• words_themes: Lista ou pesquisa as listas de palavras temáticas incluídas.
• words_list: Lista as palavras em um tema, filtradas por comprimento ou contagem.
• words_match: Encontra palavras que correspondem a um padrão estilo palavras cruzadas (c_r_l).
• words_anagram: Encontra anagramas das letras fornecidas no banco de palavras.
• words_random: Escolhe uma palavra aleatória, opcionalmente de um tema.
• words_stats: Estatísticas do banco de palavras.
• eval_generate: Gera tarefas de puzzle reproduzíveis e objetivamente avaliáveis para benchmarking de LLMs e agentes.
• eval_check: Avalia respostas para tarefas de avaliação geradas por construção — nenhuma chave de resposta é confiável.
• play_daily: Imprime o sudoku diário de hoje (o mesmo para todos em um dia UTC).

Avaliações de LLM verificáveis

As respostas de puzzles são verificáveis sem uma chave de resposta: uma resposta de sudoku ou satisfaz as regras e preserva os dados fornecidos ou não; uma resposta de caça-palavras ou soletra a palavra ao longo de uma linha reta na grade ou não. Isso torna os puzzles tarefas de benchmark limpas para avaliações de LLM — nenhum juiz LLM necessário:

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

A tupla (tipo, dificuldade, n, semente) determina totalmente o conjunto de tarefas, portanto, nomeia um benchmark reproduzível.

Uso da biblioteca

Os motores são importáveis em TypeScript sem envolvimento da CLI:

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' });

Mais documentos:

• Comandos da CLI
• Registro de ferramentas
• Habilidades do agente

Versões online

Prefere um navegador?

• PuzzleTide caça-palavras
• PuzzleTide palavras cruzadas
• PuzzleTide sudoku
• PuzzleTide forca
• Puzzles para imprimir
• Crie seu próprio puzzle
• Fontes e configurações de caça-palavras amigáveis para dislexia

Privacidade

Tudo é executado localmente. Sem conta, sem chave de API, sem telemetria, sem acesso à rede.

Desenvolvimento

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

Os bancos de palavras iniciais são listas genéricas e originais escritas para este pacote (scripts/wordbanks-source.json, compilado com npm run build:wordbanks). Contribuições de temas são bem-vindas — adicione uma entrada ao arquivo de origem e execute a compilação. A coleção completa e curada do banco de palavras PuzzleTide é proprietária do puzzletide.com e não faz parte deste repositório.

Citando a PuzzleTide CLI

Se você usar a PuzzleTide CLI em seu trabalho — por exemplo, as avaliações de puzzle verificáveis em um benchmark de modelo — por favor, cite-a (ou use o botão "Cite this repository" do GitHub):

@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}}
}

Texto simples: "PuzzleTide CLI (Caravaca Labs, 2026), https://github.com/Caravaca-Labs/puzzletide-cli — dos criadores de https://puzzletide.com."

Licença

MIT © Caravaca Labs