`pip install flintai-cli` fails silently on Python < 3.13 — the error hides the real cause

[JackKXCO]

FlintAI is one of the sharpest takes on agent evaluation we've come across — the whitebox/blackbox split between scan and eval is exactly the right decomposition, and "understand context, not patterns" is the thesis this space has been missing. We've been putting it through its paces and came away impressed. One piece of adoption friction we hit in the first sixty seconds, though, is worth flagging, because it will quietly cost you installs.

Summary. On any Python older than 3.13, pip install flintai-cli fails with a "no matching distribution" error that is indistinguishable from a typo or an unpublished package — when the real cause is the Requires-Python: >=3.13 constraint.

Reproduce.

$ python --version
Python 3.12.10
$ pip install flintai-cli
ERROR: Could not find a version that satisfies the requirement flintai-cli (from versions: none)
ERROR: No matching distribution found for flintai-cli

The package is on PyPI and perfectly healthy — pip is simply filtering every release out because of the floor:

$ curl -s https://pypi.org/pypi/flintai-cli/json | python -c "import sys,json;print(json.load(sys.stdin)['info']['requires_python'])"
>=3.13

Why it matters. Python 3.13 only shipped in October 2024. A large share of the teams FlintAI is built for are still on 3.11 or 3.12 — it's the default in most cloud base images, CI runners, and the current Debian/Ubuntu LTS lines. And the failure mode is the unkind kind: it doesn't say "upgrade Python," it says "this package doesn't exist" — so an evaluator's very first impression is a dead end instead of a one-line version bump.

Two asks, in priority order:

1. Make the requirement legible. A single line on the quickstart ("requires Python 3.13+") plus, if feasible, a friendlier resolver message would turn a silent dead-end into a 30-second fix.
2. Consider lowering the floor to 3.11/3.12 if nothing 3.13-specific is load-bearing. If there's a hard dependency (a syntax feature, a typing construct, a transitive floor), that's completely fair — but if it's incidental, dropping to 3.11 roughly doubles the install surface for a tool that deserves to be everywhere.

Happy to test a pre-release against 3.11/3.12 if that would help.

---

Filed with genuine admiration from the KXCO team (kxco.ai) — building in the same neighbourhood (post-quantum security + AI trust) and rooting for FlintAI.

[p15r-sb]

Hey there! First off, thank you so much for taking the time to open this 🙏.

Here's where we're at on both points:

1. Python Requirement Visibility
   We currently specify the Python 3.13+ requirement in the following places:

   • Official Documentation: Listed at https://docs.flintai.dev/.
   • Repository Root: Noted in the README.md.
   • Package Configuration: Defined as a constraint within the pyproject.toml.

   Where else would you have expected this to be pointed out, so we know what to add?

2. Lowering the Floor to 3.11/3.12
   Increasing the potential install surface is a compelling argument. We need to audit our codebase to check whether we are leveraging any 3.13-specific features that act as a hard barrier. I have filed this as a feature request, and we will consider this internally during our next development cycle.

Thanks again for the feedback!

[JackKXCO]

Thanks mate,

1): to be clear, the gap isn't documentation coverage — docs, README, and pyproject.toml are all fine and I believe you that it's there.,

The problem is sequencing: the failure happens at pip install, which is before anyone reaches your docs or README. The error message itself is the only thing a first-time user sees, and it says "no matching distribution," which reads as "this package doesn't exist" rather than "wrong Python version." By the time someone's frustrated enough to go digging through docs to figure out why a seemingly real package won't install, you've already lost a chunk of evaluators.

Concretely, the fix has to live in the install path, not the docs.

Two options, roughly in order of effort:

Fast: add the Python requirement to the PyPI project description/summary itself, so it's visible on the package page if someone checks there before filing a bug.

Best: ship a compatibility shim — a tiny sdist that installs on any Python version but raises a clear RuntimeError/SystemExit at build/install time ("flintai-cli requires Python 3.13+, found 3.12.x") if the running interpreter is <3.13. This is a common pattern for exactly this failure mode, and it turns pip's generic "no matching distribution" into an actual, legible message at the exact moment someone needs it.

On (2): appreciate you filing it — happy to test a 3.11/3.12 build whenever.

Great work guys!!!

[p15r-sb]

Hi @JackKXCO

Thanks for the response.

The Python version requirement is already documented on the PyPI project page in multiple places:

I am a bit hesitant to introduce a compatibility shim for a few reasons:

• Following the Python packaging rules, we're defining the Python version requirement here.
• Adding a shim that matches the version requirement, but then fails at runtime confuses package resolution.
• While I agree that pip's error message at install time could be improved, it is better to fail as early in the install process as possible. Otherwise, the installation completes, but leaves it in a broken state requiring the user to clean it up (e.g. removing the package to get rid of the shim).

Thanks

[JackKXCO]

yeah good point mate,