libauc, sixteen unpinned dependencies and a flagship example that cannot run

The training example in the readme cannot run as written

The usage section has one code block, and it is formatted as an interactive session transcript. Every statement after the two imports is prefixed with a prompt marker.

That is the first problem. A transcript implies you can paste lines into a prompt, and three of the lines cannot be: the call that switches the model to training mode, a loop, and a loop body. Nobody types a for loop into a prompt.

The second is indentation. The line that moves the batch to the accelerator is indented with a tab. The three lines inside the loop body are indented with a tab in one case and with spaces in the others. Mixed tabs and spaces in the same block is the classic Python indentation error, and the block has both.

The third is the optimiser. It is constructed two lines above the loop and then never used. The last line of the block is a bare word with no call and no parentheses, which is a leftover from a line that got truncated or redacted.

So the single piece of executable documentation in the readme has a broken indentation, a format that cannot work, and an unused optimiser. Everything else in the file is prose or links. The tutorials section is where working code actually lives, and it is twelve links to a documentation site rather than anything inline.

The packaging script is one patch ahead of the newest tag

The repository has no declarative project metadata. Packaging is a single script that calls the setuptools function directly with keyword arguments, rather than a declarative table of metadata.

That script declares version two point zero point one. The newest published tag is two point zero zero, cut at the end of May 2026. The default branch was last pushed in late August 2026, so there are roughly three months of commits on the branch that no tag contains and no release describes.

So a user who installs from the index gets a version number one higher than the newest release, on a code base the maintainers have not cut a tag for. The readme's news section announces the two point zero release and links out for the details, so the announcement and the artefact disagree by one patch number.

There is a second detail in the same file. The package list is discovered by searching from the repository root with no restriction. The root contains the library directory, an examples directory of notebooks, an images directory, and a bibliography file. Whether the discovery picks up anything it should not depends on which of those contain an init file, and the script does not say.

Sixteen unpinned dependencies including a graph stack and a medical benchmark

The install commands are two lines:

$ pip install -U libauc

The install list has sixteen entries and not one of them has a version bound.

Five are unremarkable: an array library, a progress bar, a scientific computing library, a dataframe library, an image library, a configuration library, and a YAML parser. Two are the deep learning framework and its vision sibling, unpinned.

The rest are where it gets interesting. There is a graph neural network library, a graph benchmark library, a large-scale web dataset loader, a transformer library, and a medical imaging benchmark collection. A user who wants a partial area-under-the-curve surrogate loss on a tabular credit fraud dataset installs a graph learning stack and a medical imaging package.

That is the signature of a dependency list assembled from what the examples touch rather than from what the core needs. The examples directory does contain graph neural network notebooks, a medical imaging benchmark notebook, and a federated learning script, so the dependencies are justified by the repository and unjustified by the library.

None of it is pinned, and the documented install command upgrades the package itself, which means the sixteen resolve to whatever is current on the day you run it. For a library whose pitch is that you should optimise the metric you care about precisely, installing a moving set of sixteen transitive dependencies is a strange amount of variance to accept at the point where you are trying to control numerics.

The news section is a bug log and it admits the paper code shipped broken

Most project readmes use a news section for features. This one uses it for defects, and two of its five entries are bug reports.

The first says a dataset helper was returning the wrong thing so that a contrastive learning method could not use it, and that a collective operation in a loss was communicating incorrectly, with a parameter reset to its original value in one branch. It then adds a sentence that is unusual in a changelog: none of this was in the experimental code that came with the paper.

The second says the calculation of two losses was missing a margin parameter, which could make the loss negative, and then adds that it does not affect learning because the updates are unaffected. Both the source and the installed package were updated.

That second entry is worth sitting with. A loss that can go negative is a serious defect in a numerical library, and the mitigation offered is that the optimiser step happened to be unaffected anyway. That is a correct observation and not a reassurance.

The disclosure is to the project's credit. The pattern it establishes is that this library ships code from its own papers quickly, that the code has bugs, that the bugs are found and fixed, and that the maintainers tell you which parts were experimental. A user deciding whether to trust a loss should read these two entries before the feature list.

Three generations of the same notebook live side by side

The examples directory contains the same notebooks more than once, distinguished only by a version suffix in the filename.

There is a pair for the area-under-the-curve example, a pair for the precision-recall example, a group of four for the partial area example covering two optimisers in two versions, and three files for the contrastive learning example with and without a schedule. There is also a subdirectory named for a version from two major releases ago.

So a reader browsing the directory sees the same file four times with different names and no way to tell from the listing which one matches the current API. The tutorials section of the readme links to the documentation site rather than to these files, which means the disambiguation happens somewhere else, and the readme does not say where.

The version suffixes do imply something useful. They suggest the library's API changed between the older and newer releases in a way that broke the examples, which is consistent with the two point zero release, which the news item describes as introducing a trainer, distributed training, and integrations.

Carrying two generations of notebooks is a defensible choice for a research library whose users are often reproducing a paper from a specific year. It is also a directory in which a reader has to guess, and the filenames do not help.

The overview paragraph and the tutorial list are different inventories

The section explaining why the library exists names three problem domains: classifying imbalanced data, learning to rank, and contrastive representation learning.

It then names the surrogates for each. For imbalance: area under the curve, average precision, and the partial variant. For ranking: a ranking coefficient, its top-truncated form, and listwise losses. For contrastive: global contrastive losses. That is seven named surrogates in one sentence.

The tutorial list has twelve entries, and they are not the same seven. It includes a trainer, distributed training, an extreme classification loss, a contrastive-clip variant, a compositional area loss, and a method that appears twice under different gamma settings. So the paragraph and the list are two inventories of the same library, of different sizes, with different members.

The practical consequence is small but real. A user arrives knowing they want to optimise a particular metric, scans the paragraph for it, and if it is one of the two or three that the tutorial list covers and the paragraph does not mention, they conclude the library cannot do it.

The tutorial list is the accurate one, because a tutorial implies a working loss. The paragraph is the one that reads as a specification of scope.

The readme duplicates an installation page that lives on a second domain

The project runs a marketing site and a separate documentation site on two subdomains of one domain. The installation instructions live on the first, the tutorials on the second, and the readme contains a third copy of the installation instructions.

That copy is short. Install from the index with one command, or clone and install from source with three.

It is also a duplicate that can drift, and the readme gives no indication of which copy is authoritative. The installation page could gain a platform note, a version constraint, or a troubleshooting step that the readme never sees.

The badge row is a third case. Alongside the two project links and a licence link, one badge points at an external package-statistics site. A readme badge is scraped by registries and rendered in package pages, so a badge pointing at somebody else's database is a small piece of the project's front page that lives outside its control and that nobody on the project reviews.

None of this is a problem to fix today. It is the ordinary accumulation of a research library that grew a website, a documentation site, and a set of badges over several years, and the readme is the artefact that has to be kept in step with all of them by hand.

Ten of the twelve tutorials optimise one loss each

Reading the tutorial list as a set tells you what the library actually is: a wide collection of small, independent optimisations, each with its own page.

Ten of the twelve entries are one loss each. There is a page for the area-under-the-curve surrogate, one for the precision-recall surrogate, one for the compositional version, one for the partial version, one for a method that appears twice with different settings for a parameter, one for the ranking coefficient, two for the contrastive loss, and one for a method applied to extreme classification.

The two that are not about a single loss are the two that are about the framework. One is the trainer, which is a higher-level thing than an optimiser, and one is distributed training, which is about running the optimisers across machines.

That ratio is the library in miniature. The contribution is not a new training loop or a new architecture. It is a set of optimisers for metrics that do not have convenient surrogates, collected under one import path with one interface, so that a practitioner can swap a metric without rewriting the training code.

The citation request at the end of the readme, which asks users to cite the paper, is the other thing worth noting. The library and the paper are the same artefact, and the version-suffixed example directories are the practical consequence of that: the notebooks are the paper's code, kept runnable across releases.

Editorial conclusion

Use libauc if you are training a model where the metric you care about is not the loss you can conveniently write, which is exactly the imbalance and ranking case the library targets. Four things to check. That your environment can resolve sixteen unpinned dependencies, two of which are a graph learning stack and a medical imaging benchmark that a tabular classification user has no use for. That you pin libauc yourself, because the packaging script declares a version one patch ahead of the newest tag. That you read the tutorial for your loss rather than the readme, since the overview paragraph and the tutorial list are different inventories. And that you do not copy the readme's training snippet, which will not run as written.

Frequently asked questions

Official sources

1. License: MIT
2. Optimization-AI/LibAUC on GitHub
3. Project website
4. README
5. Releases