Conform to the OpenFeature provider contract; require growthbook 3.x

[madhuchavva]

Summary

Brings the Python provider in line with the OpenFeature provider contract, fixes four evaluation bugs, and pins the dependency floors that fresh installs were already resolving past. Adds track() support. Releases as 0.1.0 (breaking).

Root cause

Verified by introspection against openfeature-sdk:

provider.initialize   : (self)                      | async: True
abstract.initialize   : (self, evaluation_context) -> None
provider defines shutdown? : False  -> inherits the no-op

Bug	Effect	Evidence
initialize() had the wrong signature and was async	The registry's initialize(evaluation_context) raised TypeError, was swallowed by its blanket except, and dispatched PROVIDER_ERROR on every set_provider()	openfeature/provider/_registry.py
close() defined instead of shutdown()	OpenFeature never closed the client; background refresh outlived the provider	inherited AbstractProvider.shutdown no-op
initialized assigned the first fetch result	A transient startup blip pinned the provider to PROVIDER_NOT_READY permanently, even after a successful background refresh	—
reason keyed off ruleId before experimentResult	GrowthBook sets both on experiment results, so every experiment reported TARGETING_MATCH and the experiment branch was unreachable	growthbook/core.py:686
Values coerced, not validated	bool("false") → True, str(123) → "123", list({"a":1}) → ["a"]	—
TARGETING_KEY_MISSING branch unreachable	A context with no bucketing id looked like a disabled flag; the README documented the error as real behaviour	provider.py:219 (old)
on_experiment_viewed typed as 1-positional-arg	growthbook 3.0.0 invokes it with keyword args experiment/result/user_context; following the annotation raised TypeError	growthbook_client.py:736-770

Behavioral change

• targeting_key still maps to id, but an explicit id attribute now wins.
• Missing bucketing id returns the default plus TARGETING_KEY_MISSING Reverted on review: that gate also broke plain flags (which need no subject) and experiments hashing on custom attributes such as deviceId. A missing id no longer blocks evaluation — GrowthBook itself skips only the rules whose hash attribute is absent.
• Type mismatches return the default plus TYPE_MISMATCH. One exception: an integer flag read via get_float_value widens losslessly, since GrowthBook (like JSON) has a single number type while OpenFeature splits the accessors.
• Unknown flags now return FLAG_NOT_FOUND (and a cyclic prerequisite returns PARSE_ERROR) instead of a plain DEFAULT with no error. The resolved value is still your default, so get_*_value is unaffected; only get_*_details gains the error. This matches the JavaScript provider and lets a typo be told apart from a flag that is deliberately off.
• Experiments now report SPLIT with the variation id; forced/override/prerequisite rules report TARGETING_MATCH with the rule id.

Dependencies

Both floors were unbounded, so fresh installs already crossed two major boundaries:

Package	Was	Now	Why
growthbook	>=1.2.1	>=3.0.0,<4.0.0	3.0.0 changed the tracking-callback contract
openfeature-sdk	>=0.8.1	>=0.10.0,<0.11.0	set_provider_and_wait and track() land here; requires Python 3.10+
pytest-asyncio	>=0.21.0	>=1.0.0,<1.1.0	1.1+ changes loop teardown in a way run_async_legacy does not survive

Python 3.9 is dropped (the openfeature floor requires 3.10+). CI matrix moves to 3.10–3.13.

Follow-ups

• The JavaScript providers emit PROVIDER_CONFIGURATION_CHANGED when the payload refreshes; the Python provider has no equivalent, so callers cannot react to flag changes. Deliberately left out of this PR to keep it reviewable.
• run_async_legacy relies on asyncio.get_event_loop() and is why pytest-asyncio is capped. Reworking it would lift the cap.
• Equivalent targetingKey and reason fixes are open for the JS providers ([growthbook] targetingKey is not mapped to GrowthBook's id attribute, silently disabling rollouts and experiments open-feature/js-sdk-contrib#1613, #1614) and Go (growthbook-openfeature-provider-go#4).

Test plan

• Full suite: pytest tests/ -q — 44 passed, 1 skipped
• With live CDN: GB_INTEGRATION_TESTS=1 pytest tests/ -q — 45 passed
• mypy src tests — clean (main had 4 pre-existing Liskov errors, also fixed)
• Clean install as CI does it: pip install -e ".[dev]" on Python 3.13 — 43 passed, 89% coverage
• New tests/test_provider_contract.py — 17 of its 21 tests fail against the pre-change provider, confirming they are real regression tests
• End-to-end against a real SDK connection: forced rule → TARGETING_MATCH, int flag widens to 1.0, boolean-as-string → TYPE_MISMATCH

test_provider_with_real_api is now opt-in behind GB_INTEGRATION_TESTS=1: it hits a shared demo project, and its previous assertions were wrong (it expected ff1 to be False while passing cloud: True, which a force: true rule matches).

Review pass

A second read of the diff surfaced and fixed:

• unknown flags silently reported as DEFAULT (above)
• close() discarded tracking events that were already scheduled
• the track() docstring claimed the call never blocks; true inside a running loop, false on the synchronous path
• the async doc examples called provider.resolve_*_details_async directly, bypassing the OpenFeature client's hooks and telemetry — the SDK dispatches to those resolvers itself, so client.get_*_async is the correct entry point

Checked and found fine, recorded so they are not re-litigated: decryption_key="" is falsy in GrowthBook so it is safely treated as "no decryption"; and constructing the client through the sync bridge from inside a running loop does not break evaluation or background refresh (verified against the live CDN).

Second review round

• id no longer required to evaluate. The TARGETING_KEY_MISSING gate rejected every context without an id, breaking plain flags and custom-hash experiments (deviceId). Removed; regression tests cover both.
• Shutdown is async-safe. shutdown() used to drive close() through a helper thread's fresh event loop, closing resources owned by the caller's loop. Inside a running loop it now schedules the close on that loop. Fixing this surfaced a second bug: the close task was initially parked in _tracking_tasks, which close() drains — it awaited itself. It lives in a separate lifecycle set.
• Shutdown/initialize race closed. A shutdown landing mid-boot returned before self.client was assigned; the completing initialize then resurrected an unclosed provider. _initialize now honours a _closed flag and closes the freshly built client.
• Reason map aligned with the JS and Go providers: override → STATIC, blocked prerequisite → DEFAULT; the force mapping is documented as lossy.
• Docs: the async example now evaluates through get_*_async (the sync methods block the loop per call); the failed-fetch example correctly shows READY + FLAG_NOT_FOUND; the tracking section no longer claims tracking never blocks (true in a running loop; plain sync callers drive the event inline).