johnypuzzles

A puzzle you play in the terminal. You connect over SSH, and a small language model embroiders poems about the Portuguese flag for you. One of her poems is hiding something.

Inspired by terminal puzzles like Augusta Labs' Ode Triunfal. There is no website to click through and nothing to install: an SSH client, a bit of curiosity, and some thinking about how a language model writes, not only what it writes.

How to play

Open a terminal and connect to the box. It runs on demand, so the address is shared when it's open.
Press enter at the coat of arms and read the riddle.
Talk to the Bordadeira, the embroiderer. Type anything and she stitches a poem.
You can take her home: the box lets you copy her model with scp.
When you think you know, submit with code <answer>. You get three tries.

$ ssh <box address>
  johnypuzzles: o bordado

  A bordadeira borda em ponto de cruz: lê-se a linha, não o pano.
  ...
  talk     type anything and she embroiders for you
  take     scp -r <box address>:bordado-lora .
  submit   code <resposta>   (3 tries)
  leave    sair
>

The riddle is in Portuguese. The answer is not in this repository.

How it's made

The Bordadeira: Qwen2.5-0.5B-Instruct with a LoRA adapter (PEFT), fine-tuned on Camões (Os Lusíadas and the lyric poems, public domain) plus poems about the flag. Small enough to run on a laptop CPU, which is the point: players can take her home and study her.
Training on a supercomputer: Trained on TU Delft's DelftBlue cluster with Slurm jobs on an A100, deterministic seeds and an evaluation run that checks the behaviour the puzzle depends on before the adapter is shipped.
The box: An asyncssh server: no password, a welcome screen that redraws the coat of arms to fit any terminal size, per-IP limits on sessions and guesses, and the adapter served read-only over SCP.
Hosting: A small Azure VM running the box as a systemd service, with on and off scripts so it only costs money while people are playing.
The coat of arms: Rendered from text glyphs, in ANSI for the terminal and as the canvas at the top of this page. Move your mouse over it, or click it to watch it reassemble.

Run your own box

You'll need Python 3.10 or newer. The answers are read from environment variables, so pick your own.

$ git clone https://github.com/joaofilipe5/johnypuzzles && cd johnypuzzles
$ python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
$ export JP_CODE=YOURWORD JP_ANSWER=YOURANSWER JP_SEED=42
$ .venv/bin/python -m server.ssh_server --port 2222
$ ssh -p 2222 localhost          # in another terminal

Without a trained adapter the box still runs and the Bordadeira says she's resting. To train one, see docs/DELFTBLUE.md. To host it, see infra/DEPLOY.md.

What's in the repository

server/   the SSH box players connect to
model/    bordado: dataset, LoRA training and evaluation
          vexnet: a small character-level model trained on flag descriptions
render/   the coat of arms as ANSI text and as a web canvas
co/       an earlier optimisation-based version of the puzzle (max-cut)
hpc/      Slurm job scripts for DelftBlue
infra/    create, deploy, start and stop the Azure VM
docs/     this page and the DelftBlue guide