feat(flagd): extract evaluator into api, core, and testkit packages

[aepfli]

Summary

Mirrors the Java SDK contrib architecture (PR #1696, PR #1742) by extracting the flagd evaluation logic into three independent packages:

• openfeature-flagd-api (tools/openfeature-flagd-api/): Evaluator Protocol defining the contract for flag evaluation, so others can implement their own evaluator
• openfeature-flagd-core (tools/openfeature-flagd-core/): Reference implementation (FlagdCore) with targeting engine and custom operators (fractional v2, sem_ver, starts_with, ends_with)
• openfeature-flagd-api-testkit (tools/openfeature-flagd-api-testkit/): Compliance test suite bundling gherkin feature files from the test-harness evaluator/ directory, with pytest-bdd step definitions — installable as a package so custom evaluator implementations can run the same compliance suite

Provider refactoring

• InProcessResolver now delegates evaluation to FlagdCore via an adapter pattern
• Old modules (flags.py, targeting.py, custom_ops.py) are thin re-exports from core for backward compatibility
• Connectors (FileWatcher, GrpcWatcher) remain unchanged
• No changes to gRPC resolvers, config, or other provider functionality

Fractional bucketing

• flagd-core implements the v2 fractional algorithm (unsigned hash, integer arithmetic with (hash * totalWeight) >> 32)
• Includes MAX_WEIGHT_SUM overflow guard, negative weight clamping, explicit bool-as-weight rejection
• v1 fractional tests are deselected since the implementation is v2

CI & release

• Added tools/* packages to the build workflow matrix (lint, mypy, tests on Python 3.10–3.14)
• Added py.typed marker files for PEP 561 compliance
• Replaced project.scripts with poethepoet tasks to match CI conventions
• Added release-please config for all 3 new packages
• Added tools/* to UV workspace members

Other changes

• Updated test-harness submodule to v3.5.0 (adds evaluator/ directory with gherkin feature files)
• Dropped Python 3.9 support for tools packages (aligned with rest of project)
• Schemas and spec submodules kept at main (no changes)

Test plan

• openfeature-flagd-api unit tests: 10 passed
• openfeature-flagd-api-testkit smoke tests: 2 passed, mypy clean
• openfeature-flagd-core unit tests: 27 passed
• openfeature-flagd-core e2e (testkit compliance): 85 passed, 15 deselected (fractional-v1), 0 failures
• Provider unit tests: no regressions
• Lint: ruff check + ruff format clean
• Type checking: mypy strict clean for all 3 tools packages

How to use the testkit (for custom evaluator implementations)

# conftest.py
from openfeature.contrib.tools.flagd.testkit import load_testkit_flags
from openfeature.contrib.tools.flagd.testkit.steps import *  # noqa: F403

@pytest.fixture
def evaluator():
    core = MyCustomEvaluator()
    core.set_flags(load_testkit_flags())
    return core

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a modular architecture for the flagd provider by extracting core evaluation logic and API definitions into separate tools packages. It replaces the internal FlagStore with a new FlagdCore implementation and adds a testkit for compliance testing. I have no feedback to provide on the changes.

[codecov]

Codecov Report

❌ Patch coverage is 96.77419% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.09%. Comparing base (564eb68) to head (65f4052).

Files with missing lines	Patch %	Lines
...openfeature/contrib/tools/flagd/core/flagd_core.py	93.26%	7 Missing ⚠️
...trib/tools/flagd/testkit/steps/evaluation_steps.py	93.44%	4 Missing ⚠️
...openfeature/contrib/tools/flagd/core/model/flag.py	94.73%	3 Missing ⚠️
...ature/contrib/tools/flagd/core/model/flag_store.py	97.05%	1 Missing ⚠️
...e/contrib/tools/flagd/core/targeting/custom_ops.py	99.21%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #377      +/-   ##
==========================================
+ Coverage   95.91%   96.09%   +0.18%     
==========================================
  Files          30       42      +12     
  Lines        1517     1563      +46     
==========================================
+ Hits         1455     1502      +47     
+ Misses         62       61       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[aepfli]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the openfeature-flagd-api and openfeature-flagd-core packages to provide a modular evaluator implementation for flagd. It also refactors the existing openfeature-provider-flagd to utilize these new core components. I have provided feedback to improve performance by allowing flag configuration to be passed as a dictionary, avoiding redundant serialization, and suggested fixes for regex escaping and exception handling in the core implementation.

[aepfli]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors the flagd provider by extracting its core evaluation logic into three new standalone packages: openfeature-flagd-api (protocol definition), openfeature-flagd-core (reference implementation), and openfeature-flagd-api-testkit (compliance suite). The InProcessResolver has been updated to use the new FlagdCore evaluator, and existing modules have been refactored to re-export logic for backward compatibility. Review feedback highlights a potential breaking change in the FlagStore.update method signature and suggests a correction for JSON parsing in the testkit utilities.