flow-forecast: two release tags named after branches, and requirements.txt is the runtime manifest

Two of the three release tags are named after branches

The release list reads like a filing cabinet of working states. The newest tag is a beta marker for version one, published in January 2024. The one before it is named for a branch that collects fixes, and its release name is a different string again, a three-part version in the older style. The third is named for a bug branch. So of three published releases, two are named after branches rather than versions, and only one tag looks like a version. Meanwhile the last commit on the default branch is dated late September 2026, which places roughly two years and eight months between the newest published release and the newest source. The source file carries its own version, and it is a five character string that ends in a development marker with the digits packed as one point zero zero one rather than one point zero point one. Written out, it does not read as a version anyone would type, and a build tool has to normalise it before it can be published. For anyone pinning this library, the practical consequence is that the tag you would want to pin to is the one that looks least like a version.

The runtime manifest is the requirements file, and it lists the documentation

The setup file does not declare its dependencies. It computes the path to the requirements file, and if that file exists it reads it and splits it into the install list:

requirementPath = f'{library_folder}/requirements.txt'
install_requires = []
if os.path.isfile(requirementPath):
    with open(requirementPath) as f:
        install_requires = f.read().splitlines()

Whatever is in that text file becomes a hard runtime requirement, with one dependency per line and no environment markers and no extras. And the file it reads contains the documentation toolchain, twice over: a documentation generator listed once, then again after its theme and type-hint extension, so the same package is requested twice on consecutive lines. Also in that runtime list are a nightly-only experiment tracking package, two Google Cloud client packages, a weights and biases tracker at an exact version, a plotting library with a version range, an interactive plotting helper, a terminal emulator library from the future framework, a compatibility layer, a time zone database, and a language extension package. A development extras group exists and contains exactly two entries, a formatter and a linter. So a user who installs this library installs Sphinx, its theme, its type-hint extension, nightly experiment tracking, two cloud clients, a plotting stack and a terminal emulator, and the only things separated out are the two tools you need to contribute.

A compiler-backed library carries a floor below its own first release

One line in that same file is worth pulling out on its own. The just-in-time compiler library is given a floor of version zero point five zero, which is a lower bound rather than an exact version. That library was not released in the zero point five zero series until well after this project's first tagged release, so on a modern install the floor is satisfied by something many years newer, and the lower bound is doing no work at all. The floor was almost certainly written against a different packaging era, where the version scheme differed, and it was carried forward. That matters more here than in most dependencies, because this one compiles code at run time. Its version determines the machine code your models execute, and a different major release of a compiler can produce different floating point behaviour. So the same model, the same data and the same seed can give slightly different numbers depending on which version of the compiler library resolved, and the page nowhere mentions reproducibility or seeds. For a research library whose entire value is reproducing a published result, an unpinned compiler backend is a quiet source of drift.

The numeric library is pinned exactly and the tracker is a nightly build

Two more lines from the runtime file pull in opposite directions. The numeric library is pinned to an exact version with an equality operator and three decimal places, which is the opposite of the compiler floor. Meanwhile the experiment tracking package is requested as a nightly build, meaning the version is whatever the nightly channel happens to publish, and nightly channels move. Pinning one library exactly and taking another from a moving channel in the same file is a strange combination, and it is a real constraint: an exact pin on the numeric library means a project that needs a different major version cannot have both in one environment, which is a common enough situation that a numeric major bump will break co-installation with anything that already resolved this package. The torch requirement itself is unbounded, as are the dataframe library, the requests library and the image library, so the file mixes exact pins, range floors and no constraints at all. There is no lock file in the tree, so nothing here is reproduced for you.

The package list is hand written, so a new module ships broken

The setup file lists its packages explicitly, nine subpackages named as string literals rather than discovered. That is a defensible choice for a library that wants to exclude test modules, and it is the modern approach to not shipping tests. The cost is that the list is now a second place to maintain. Add a module to the source tree, forget the setup file, and the library installs and then fails at import with a missing module, for the user, on their machine, rather than at build time. Nothing in the repository checks the two against each other, and the test suite in the tree would not catch it because tests run from the source checkout where the module is plainly present. The project has a separate tutorials repository linked from the page, so there is at least one place where a package could be added without a corresponding entry. For anyone vendoring this into a build pipeline, the list is worth reading before you trust the install, and worth comparing against the source directory afterwards.

The page says first and only and substantiates neither

The introduction makes two priority claims. It says the project was the first time series framework to feature support for transformer based models, and that it remains the only true end-to-end deep learning for time series framework. There is no citation, no comparison table, no benchmark and no date attached to either. The first claim is the kind that is checkable in principle and would need evidence. The second is not checkable as phrased, because the qualifier doing the work is the word true inside a sentence whose other words, end-to-end deep learning for time series framework, describe a category several projects could occupy. The rest of the introduction is more careful. It says the project provides state of the art models and interpretability metrics, and it distinguishes what the project is now from what it was: currently a different organisation primarily maintains the repository, and historically it provided benchmark code for flash flood and river flow forecasting. That last sentence is the most useful line on the page, and it should be the first one.

Seventeen models, three naming conventions, and one link to a personal site

The model list is seventeen numbered entries and it is the most useful thing on the page, because most entries give you the paper to read and the registry name to ask for. It is also inconsistent in three ways. Six entries state a code name in parentheses, for example that the full transformer is registered under one name, that a particular linear-decoder variant is registered under another, and that one paper's model is registered under a third. Nine entries give a paper or a name with no code name at all, so a reader has to guess the string to pass. And the citations themselves are inconsistent: most are paper identifiers, one is a conference paper page, and one is a PDF hosted on an individual's personal site domain rather than on a paper repository. That last one will rot. The list also notes where a model has a real constraint, such as the full transformer requiring the target to be supplied at inference, and a separate section for models planned but not released points at a project board. The pattern to adopt when using this list is to read the paper and then find the name in the code.

A broken link with a doubled letter, and a homepage that is a wiki space

Two small things round out the documentation. The contributing section links to a project board on the hosting site, and the organisation in that path has one letter too many: it is spelled with a doubled final consonant where the actual organisation is spelled with one. The link therefore points at an account that does not exist. The rest of the contributing section points to a wiki page, so a reader who tries the project board hits a dead end while the page they came from is fine. Separately, the repository's homepage field is a wiki space on a project-management service rather than a documentation site, and the documentation itself is hosted separately on a read-the-docs service with its own configuration file in the tree. Two documentation locations and a wiki space as the canonical homepage is an unusual arrangement, and it means the page a reader is sent to first is the least likely one to be current. The root of the repository is also cluttered in a way that suggests notebook work left in place: a committed notebook with a generated name, a script that builds that notebook, a script whose name begins with a separator character, an editor configuration directory, and a linter configuration file with no accompanying linter extras in the runtime list.

Editorial conclusion

Flow Forecast suits a hydrology or forecasting researcher who wants a maintained implementation of a specific paper, recognises that the name on the index still says flood, and can point pip at a build rather than installing it. It is a poor fit for a production service, because the install path drags in nightly builds, two documentation toolchains and a plotting stack as hard runtime requirements, and because a compiler-backed library carries a numeric floor that predates the package's first release. Before you install it, read the requirements file as a runtime manifest rather than a convenience list, expect the exact numeric pin to constrain what you can build alongside it, and treat the model registry as a menu to be verified rather than a catalogue, since its naming conventions are not consistent and two of the seventeen entries never say what to ask for. And if you want the framework itself cited, the page only offers a dataset paper.

Frequently asked questions

Official sources

1. AIStream-Peelout/flow-forecast on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases