PF — Package Floor

English | 简体中文

Find verified lower bounds for a Python package's direct dependencies.

What it does

PF discovers candidate versions in isolated environments. search optionally captures a ty static baseline from the highest versions your declarations allow, then runs the project's full test command. Compatibility conclusions come only from that dynamic evidence; ty may choose a later probe but cannot reject a candidate. It records an explainable, verified exact dependency vector. smoke and check run the same verifier without ty.

The search unit is one installable package and one compatibility cell: exact uv target triple, CPython minor, and extra surface. On a frozen candidate snapshot, PF returns a coordinate-minimal vector that passed full tests. It does not claim a global minimum over the Cartesian product of dependencies, and it does not prove that unprobed versions or other combinations work. The product contract is D001.

For admitted resolution and installation requests, an unattributed normal nonzero exit rejects that attempt, including failures inside a build backend. It does not prove a dependency conflict or a repeatable failure. A backend can report network or permission problems this way, so false rejections may raise the reported floor, miss feasible vectors, or leave no result. Timeouts, abnormal terminals and directly observed external or consistency failures remain indeterminate. Final results still require actual resolution, installation, graph checks and a full verifier PASS; PF does not add retries or promise reproducibility from one observation.

Installation

uv tool install package-floor

pip install package-floor also works. The CLI name is pf. From a clone, uv run pf uses the local tree.

Quick Start

The target project needs static project.dependencies (and optional-dependencies, if used). Test dependency groups are optional: omitting test-group selects dev, then test, from the workspace root or selected member. If neither exists, the group is empty. An explicit name selects only that group; a missing name also means an empty group. The default test command is pytest; PF does not install it automatically. For example, provide the test tools with:

[dependency-groups]
test = ["pytest"]

Then:

pf smoke
pf search
pf apply

smoke checks a fresh install at the newest allowed versions. search writes package-floor.json. apply updates the project's requirement floors from that report when authorization succeeds. After apply, check is the everyday command: it verifies the current declarations and does not require a report or Git.

Commands

Onboarding: pf smoke → pf search → pf explain → pf apply. Steady state: pf check. Use pf minimize to search and apply in one step. After a failed check, or when you want new floors, run pf search → pf apply again.

Requirements

• Omit --package to select the installable workspace root. An explicit value is a canonical distribution name of one workspace member, not a path.
• Each process only runs the target that matches the current host. Merge other hosts with pf merge. When this host succeeds and the only gaps are other hosts, pf search exits 0 with an incomplete report so CI can collect artifacts.
• search writes package-floor.json. apply does not re-resolve dependencies or rerun ty or tests.

Configuration

Settings merge from the workspace root's [tool.pf] into the selected member's own [tool.pf]; explicit CLI flags override that run. For example:

[tool.pf]
test-command = ["pytest"]
search-resolution = "patch"
max-cells = 4

[tool.pf.search-space-defaults]
with-lower-bound = "majors[declaration-1:]"
without-lower-bound = "majors[baseline-2:]"

This is a configuration example, not a complete defaults table. See D001 configuration for groups, Cells, concurrency, timeouts and layer merging; see D037 candidate and search policy for spaces, conditional defaults, per-dependency overrides and exact baseline artifacts. search-resolution controls sampling within the chosen space; a verified floor remains an exact version.

A self-reference such as requests[socks] in the test group makes socks required in every Cell. Extra exploration is added to that required surface. A Cell without active external test dependencies installs the project plan directly and still runs the configured verifier. Changing the test command or harness changes the validation contract and can change the resulting floor; see D001 validation.

Pinned tools

Released PF pins uv 0.12.5 and ty 0.0.74. The resolver protocol accepts only that uv version; other versions fail closed. Upgrading either tool requires re-qualification before the pin changes.

Documentation

• D001 — product and command contract: floors, commands, configuration, reports, and exit codes
• Engineering docs index: contract ownership and layout
• This repository's own [tool.pf] test-command is a targeted-runtime contract: in-process public interfaces only. Real uv/ty/CLI and qualification runs live in CI test lanes. An existing package-floor.json produced under a wider historical C is not a floor relative to the current command; see tests/README.md.

License

Apache License 2.0. See LICENSE.