Science is always in motion. Most online taxonomy or phylogeny databases attempt to show a consensus or accepted view, with each site having its own editorial policy for what gets included. Some include historical information, but do not make it a central or easily-accessible part of the sysetm.
The phylohist project instead provides access to trees as published,
over time, while leaving the judgement of what to accept or reject to
the researcher. An LLM-driven interface supports complex queries over
a curated corpus stored as YAML data. This uses a model where one is
needed, and prioritizes reliability, reproducibility, speed,
and lower costs where one is not.
The current corpus holds over 200 papers entered in whole or in part, from the mid-1700s to the present, mostly focusing on Paleozoic echinoderms. A coverage system tracks how much of the information from a paper has been entered and reviewed.
This repository began as a place to store my notes, and gradually evolved into a software package, featuring more and more modern software engineering best practices as I have found time to add them. However, it remains a solo, unfunded project that I work on whenever I can.
The package is published on PyPI as phylohist from version 0.1.0.
Next steps include writing human-user-friendly documentation,
continuing to improve the software development methodology, curating
additional data and adding more features.
A data model for capturing specimen information has recenlty been designed but data entry for this area is in its infancy. Additional areas of fuure work are proper support for cladograms (currently allowed in the data but treated more-or-less like systematic trees) and data visualization.
Because phylohist relies on manual validation and a human-in-the-loop
workflow, data ingestion proceeds slowly to prioritize high fidelity
over unchecked volume.
No data is entered purely by AI. The data model has grown from my experience of manually reading papers and figuring out how to work with the data as it was published. Current LLMs are too eager to make things "work" rather than step back and consider the user experience.
Data entry is guided by the target research scope, currently focusing primarily on Paleozoic echinoderms and their relatives in the Ambulacrarian stem group.
- Partial Ingestion: For vast foundational texts such as Linnaeus’s Systema Naturae, only the specific branches of interest to the active dataset are entered.
- Closed-World Boundaries: The data model is being enhanced with ways to indicate when data is complete by some metric. However, updating the data with these fields is itself a large, ongoing project.
Tracking archaic, text-heavy literature (particularly pre-19th-century sources written in informal prose) presents a unique archival challenge.
- Philosophy: The core directive of this corpus is to capture the published
author's opinions as they published them. However, no data model is
perfect, so
phylohistattempts to get as close as possible while capturing literal text and editorial reasoning to inform users of possible discrepancies and inferences. Only ICZN-mandated textual normalizations are performed. In more recently-entered data, the original textual form is also captured (e.g. "Asterias caputmedusae" vs "Aſterias Caput meduſæ"). The common use of only non-Latin names for higher taxa in earlier publications introduces further difficulty, as does the uneven introduction of ranks other than those first used by Linnaeus. - Continuous Ingestion: Determining how to translate loose, informal prose into deterministic YAML schemas without breaking historical context is an ongoing design effort. Often, a paper will inspire a revision to the data model, meaning that data entered at different times shows different levels of completion. Older data may use less precise structures that will eventually brought in line with the current design so that the older structures can be dropped.
The project welcomes feedback or additions to schemas and coverage maps via GitHub issues. Please open an issue prior to working on a pull request to ensure that the request will be well-received.
The internet has made a tremendous amount of information available, but finding what you need and verifying its accuracy is a lot of work. Humans have the deepest judgement for data curation, while models handle flexible querying beyond what fixed database queries can provide. Underneath it all, deterministic code ensures fast, repeatable, and accurate outcomes.
This diagram shows the roles of humans (the top row), models (the middle) and code. The third column shows the expected typical interactive usage, where the model interprets the questions and chooses the tools to call and output shapes to render, but leaves the querying and output construction to code.
This avoids verbose or hallucinated output while spending tokens only on the work that really requires a model's reasoning and flexibility.
- The data. The curator records each publication's opinions as
printed: who published what systematic information in which paper.
That is names and nomenclatural acts, placements, usages and
synonymies, the specimens they rest on with their geological context,
and the page, plate and figure numbers that locate each of these. It
is not diagnoses, descriptions or a narration of the paper; a
researcher who wants those follows the citation to the paper itself.
The model's part is optional and reviewable: it reads a
paper against its tree and writes a review (
notes/reviews/), or drafts a tree (drafts/) that code validates and the researcher audits before it entersdata/. The human and the model review each other's work; code checks both against the schema and regenerates the claim table, which CI keeps current. - The CLI. A question goes from the researcher to the tools with no
model in the lane:
phylohist history rhenopyrgusrenders the block. - Chat. Claude asks the MCP server. The model resolves the names and papers the question mentions and states a plan, the blocks the answer is made of; code builds and renders them. The model chooses; code answers. The only words of the model's own that reach a reader are a one-line header stating the parameters it chose.
- The eval. The runner drives the model over the committed
questions in compose or planner mode, the grader is code, and a model
judges only the header. The researcher writes the questions and
reviews the grades and write-ups (
eval/).
The project's evolution can be seen through the evaluation metrics.
Moving from AI-written prose answers to planned queries with modular output blocks improved key measurements across complete evaluation runs:
- The measured pass rate rose from 61% to 87% on the original question set, with several failure modes eliminated entirely; the latest run (2026-11-02, the run version 0.1.0 ships with) passes 80% of those questions and 80% of the expanded set of 56.
- Wall clock time was cut from around 25 minutes to around 10 minutes, over a quarter more questions.
- Token usage dropped from 2.25 million to 0.60 million.
Future improvements to how the model selects blocks are expected to raise the correctness score.
The phylohist CLI runs queries over the claims table generated from
the curated YAML data. These result in output data blocks rendered
as text, Markdown, or JSON based on the --style argument.
The CLI has one subcommand per tool:
poetry run phylohist resolve "Palæaster"
poetry run phylohist contents 1994_guensburg_sprinkle astrocystitidae --synonymy
poetry run phylohist descendants edrioblastoidea
poetry run phylohist ancestors astrocystitidae cyathocystidae rhenopyrgidae
poetry run phylohist history rhenopyrgus --style markdown
poetry run phylohist history "Rhenopyrgus grayae"
poetry run phylohist under rhenopyrgus edrioblastoidina
poetry run phylohist statements "Rhenopyrgus viviani"
poetry run phylohist gap "Holloway & Jell 1983" material
poetry run phylohist source "Lamarck 1816"
poetry run phylohist plan my-plan.yaml
poetry run python scripts/eval_run.py --mode planner --ask "Who first placed Rhenopyrgus under Edrioblastoidina?"
The same tools are served over MCP by the phylohist-mcp command
(phylohist/mcp.py), which .mcp.json registers for Claude Code:
a chat model can read blocks or state a plan and get the rendered answer.
The "Reading the table" section of docs/claims.md describes the blocks
and the tools.
What one paper places in a family, showing only what the paper included:
$ poetry run phylohist contents 1994_guensburg_sprinkle astrocystitidae
Guensburg & Sprinkle 1994
Family Astrocystitidae emend.
Genus Astrocystites
Genus Cambroblastus
Genus Lampteroblastus gen. nov.
Type species. Lampteroblastus hintzei
Lampteroblastus hintzei sp. nov.
The emendation, the new genus and species, and the type species are the paper's own statements; nothing here is inferred, and a source whose listing is not yet entered says so instead.
See docs/walkthrough.md for additional examples.
The eval_run.py script can be used to ask a question without using the
chat interface to see how the model plans the queries and selects the output
blocks. It requires an Anthropic API key to be configured.
poetry run python scripts/eval_run.py --ask "Who first placed Rhenopyrgus under Edrioblastoidina?"
Rhenopyrgus (including its subgenus rank variant) placed under Edrioblastoidina (= Edrioblastoidea); taxonomy tree, all years
Rhenopyrgus Dehm 1961 under Edrioblastoidina Fay 1962: 4 papers, 4 co-author sets, 1994–2020
first Guensburg & Sprinkle 1994, last Ewin et al. 2020
1994 Guensburg & Sprinkle Cyathocystidae › Rhenopyrginae › Rhenopyrgus
2000 Grigo Cyathocystidae › Rhenopyrginae › Rhenopyrgus
2013 Sumrall et al. Rhenopyrgidae › Rhenopyrgus
2020 Ewin et al. Rhenopyrgidae › Rhenopyrgus
--- trail
resolve_name {"query": "Rhenopyrgus"} -> 2 candidate(s)
resolve_name {"query": "Edrioblastoidina"} -> 1 candidate(s)
placed_under {"record": "rhenopyrgus", "parent": "edrioblastoidina", "include_variants": true} -> 1 block(s)
header: Rhenopyrgus (including its subgenus rank variant) placed under Edrioblastoidina (= Edrioblastoidea); taxonomy tree, all years
21227+375 tokens, 6.9s, tool_use
From PyPI, for the tools and the MCP server over the claim table as of the release (Python 3.12 or later):
pip install phylohist
phylohist history rhenopyrgus
phylohist-mcp
The second command is the server over stdio, which any MCP client runs by name. For Claude Desktop or Claude Code the entry is
{"mcpServers": {"phylohist": {"command": "phylohist-mcp"}}}
or, with nothing installed, uvx --from phylohist phylohist-mcp as the
command and its arguments.
From a checkout, for the loader, the generator and the eval, Poetry:
poetry install
The claim table the tools read is generated into phylohist/table/, so
a built package carries the table as of its build and a clone answers
from the table as poetry run regenerate last wrote it.
PHYLOHIST_CLAIMS names another table to read.
Only scripts/eval_run.py and the grader's --judge call a model;
their client is the eval dependency group, and they read
ANTHROPIC_API_KEY from the environment or from a git-ignored .env at
the repository root. Nothing else needs a key.
CI runs these on Python 3.12 and 3.14 and fails if the generated
schema census, the claim table or the expected-warnings file is stale;
after editing data/ or the schema, poetry run regenerate rewrites all
three (a warning the load no longer produces leaves the file; a new one
is added with scripts/expected_warnings.py --add):
poetry run ruff check .
poetry run ruff format --check .
poetry run pytest --cov=phylohist --cov-fail-under=90
poetry run regenerate
git diff --exit-code scripts/schema-usage.md phylohist/table/ tests/expected-warnings.txt
poetry run python scripts/check_draft.py drafts/<file>.yaml
The tests run over the frozen copy of the data under tests/corpus/;
only those marked production load data/ itself, so improving the
data cannot break a test of the code. poetry run pytest --demo adds the
eval questions and the walkthrough over the committed phylohist/table/, which
hold for the data they were last refreshed against.
docs/will contain user documentation; for now it explains how recorded tree data is converted to the claims that the tools use, as well as the tools and the answer formats.notes/contains project development information from both the human and LLM developers; some of this information might be out-of-date.eval/holds the evaluation questions, results, write-ups, and metrics.drafts/holds AI-drafted trees awaiting a human audit.
LICENSE (MIT) covers everything in the repository and in the released
package: the code; the YAML under data/, which is the owner's
compilation of published opinions, recorded as printed; the claim table
generated from it; and notes/, the owner's and the assistant's writing.
If the corpus is useful in published work, please cite it
(CITATION.cff).