Metazooa Solver

Metazooa Solver is a terminal assistant for Metazooa. You enter the species you guessed in the game and the lowest-common-ancestor feedback Metazooa returned, and the solver ranks the best next guess using a minimax policy with expected remaining candidates as the tiebreak.

What It Does

• launches a full-screen Textual dashboard in your terminal
• tracks every guess and LCA clue you enter
• keeps only species consistent with the feedback seen so far
• recommends the next guess that best shrinks the remaining search space
• shows a Why <animal>? breakdown so you can inspect how each recommendation partitions the candidate set

Solver Efficiency

The current candidate-only minimax policy solves the March 27, 2026 project snapshot in at most 7 guesses, with 64.4% of species solved within 4 guesses and 88.1% solved within 5.

The full analysis and supporting plots live in docs/2026-03-27/current-policy-solve-paths.md.

Getting Started

Requirements

• Python 3.12 or newer
• uv

1. Clone the repository and install dependencies

git clone https://github.com/wmsci/metazooa-solver.git
cd metazooa-solver
uv sync

2. Start the solver

uv run metazooa-solver play

What happens on first run:

1. The app checks for a local runtime dataset cache.
2. If the cache is missing, it automatically downloads the current animals.json source and the NCBI new_taxdump archive.
3. It builds dataset.json and summary.json in the local cache.
4. The Textual dashboard launches.

The first run may be slower because it has to build the cache. Later runs reuse the cached dataset unless you refresh it.

play and refresh-data need internet access when they are using the default upstream data sources.

3. Use it during a Metazooa game

Typical flow:

1. Start a game in Metazooa.
2. Launch metazooa-solver play.
3. Use the recommended opening guess in the game.
4. In the solver, enter the species you guessed.
5. Enter the LCA taxon returned by Metazooa.
6. Press Enter or select Apply.
7. Repeat until the candidate set collapses to one species.

Keyboard Shortcuts

• q: quit the app
• u: undo the last feedback entry
• r: reset the session
• g: focus the guess input
• Tab: accept the active autocomplete suggestion
• Enter: submit feedback when both inputs are filled

Runtime Data

By default, the runtime cache is stored in:

• $XDG_CACHE_HOME/metazooa_solver when XDG_CACHE_HOME is set
• ~/.cache/metazooa_solver otherwise

You can override that location in either of these ways:

• set METAZOOA_SOLVER_DATA_DIR
• pass --data-dir to play or refresh-data

Refreshing data writes:

• dataset.json: the playable species snapshot with full and display lineages
• summary.json: metadata about the generated snapshot and sources used

Acknowledgements

• Metazooa for the game this solver is built around.
• NCBI Taxonomy for the taxonomy data used to compute LCA feedback and lineage structure.
• OpenAI's GPT-5.4 (via the Codex app) for AI-assisted development work on this project.