mixpanel-openfeature 0.1.0__tar.gz

mixpanel_openfeature-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: mixpanel-openfeature
+Version: 0.1.0
+Summary: OpenFeature provider for the Mixpanel Python SDK
+Author-email: "Mixpanel, Inc." <dev@mixpanel.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Requires-Dist: mixpanel<6,>=5.1.0
+Requires-Dist: openfeature-sdk>=0.7.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.4.1; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Requires-Dist: pytest-cov>=6.0; extra == "test"

mixpanel_openfeature-0.1.0/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mixpanel-openfeature"
+version = "0.1.0"
+description = "OpenFeature provider for the Mixpanel Python SDK"
+license = "Apache-2.0"
+authors = [
+    {name = "Mixpanel, Inc.", email = "dev@mixpanel.com"},
+]
+requires-python = ">=3.9"
+dependencies = [
+    "mixpanel>=5.1.0,<6",
+    "openfeature-sdk>=0.7.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.4.1",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=6.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+# --- Ruff configuration (mirrors main project) ---
+
+[tool.ruff]
+target-version = "py39"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # --- Rule conflicts ---
+    "D203",    # conflicts with D211 (no-blank-line-before-class)
+    "D213",    # conflicts with D212 (multi-line-summary-first-line)
+    "COM812",  # conflicts with ruff formatter
+    "ISC001",  # conflicts with ruff formatter
+
+    # --- Type annotations (separate effort) ---
+    "ANN",     # all annotation rules
+
+    # --- Docstrings (separate effort) ---
+    "D100",    # undocumented-public-module
+    "D101",    # undocumented-public-class
+    "D102",    # undocumented-public-method
+    "D103",    # undocumented-public-function
+    "D104",    # undocumented-public-package
+    "D105",    # undocumented-magic-method
+    "D107",    # undocumented-public-init
+
+    # --- Boolean arguments (public API) ---
+    "FBT",     # boolean-type-hint / boolean-default / boolean-positional
+
+    # --- TODO/FIXME enforcement ---
+    "TD002",   # missing-todo-author
+    "TD003",   # missing-todo-link
+    "FIX001",  # line-contains-fixme
+    "FIX002",  # line-contains-todo
+
+    # --- Exception message style ---
+    "EM101",   # raw-string-in-exception
+    "EM103",   # dot-format-in-exception
+    "TRY003",  # raise-vanilla-args
+
+    # --- Other pragmatic exclusions ---
+    "PLR0913", # too-many-arguments
+    "PLR0911", # too-many-return-statements (_resolve has many type-check branches)
+    "E501",    # line-too-long (formatter handles code)
+    "FA100",   # future-rewritable-type-annotation
+    "BLE001",  # blind-exception (catching Exception in flag resolution is intentional)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = [
+    "S101",    # assert
+    "S105",    # hardcoded-password-string (test fixtures)
+    "S106",    # hardcoded-password-func-arg
+    "SLF001",  # private-member-access
+    "PLR2004", # magic-value-comparison
+    "D",       # all docstring rules
+    "PT018",   # pytest-composite-assertion
+    "INP001",  # implicit-namespace-package (no __init__.py in tests)
+    "ARG",     # unused arguments (lambda stubs in mocks)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["mixpanel", "mixpanel_openfeature"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

mixpanel_openfeature-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mixpanel_openfeature-0.1.0/src/mixpanel_openfeature/__init__.py

@@ -0,0 +1,3 @@
+from .provider import MixpanelProvider
+
+__all__ = ["MixpanelProvider"]

mixpanel_openfeature-0.1.0/src/mixpanel_openfeature/provider.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import math
+import typing
+from collections.abc import Mapping, Sequence
+from typing import Optional, Union
+
+from openfeature.evaluation_context import EvaluationContext
+from openfeature.exception import ErrorCode
+from openfeature.flag_evaluation import FlagResolutionDetails, Reason
+from openfeature.provider import AbstractProvider, Metadata
+
+from mixpanel import Mixpanel
+from mixpanel.flags.types import LocalFlagsConfig, RemoteFlagsConfig, SelectedVariant
+
+FlagValueType = Union[bool, str, int, float, list, dict, None]
+
+
+class MixpanelProvider(AbstractProvider):
+    """An OpenFeature provider backed by a Mixpanel feature flags provider."""
+
+    def __init__(
+        self,
+        flags_provider: typing.Any,
+        mixpanel_instance: Optional[Mixpanel] = None,
+    ) -> None:
+        super().__init__()
+        self._flags_provider = flags_provider
+        self._mixpanel = mixpanel_instance
+
+    @classmethod
+    def from_local_config(
+        cls, token: str, config: LocalFlagsConfig
+    ) -> MixpanelProvider:
+        """Create a MixpanelProvider backed by a local flags provider.
+
+        :param str token: your project's Mixpanel token
+        :param LocalFlagsConfig config: configuration for local feature flags
+        """
+        mp = Mixpanel(token, local_flags_config=config)
+        local_flags = mp.local_flags
+        local_flags.start_polling_for_definitions()
+        return cls(local_flags, mixpanel_instance=mp)
+
+    @classmethod
+    def from_remote_config(
+        cls, token: str, config: RemoteFlagsConfig
+    ) -> MixpanelProvider:
+        """Create a MixpanelProvider backed by a remote flags provider.
+
+        :param str token: your project's Mixpanel token
+        :param RemoteFlagsConfig config: configuration for remote feature flags
+        """
+        mp = Mixpanel(token, remote_flags_config=config)
+        remote_flags = mp.remote_flags
+        return cls(remote_flags, mixpanel_instance=mp)
+
+    @property
+    def mixpanel(self) -> Optional[Mixpanel]:
+        """The Mixpanel instance used by this provider, if created via a class method."""
+        return self._mixpanel
+
+    def get_metadata(self) -> Metadata:
+        return Metadata(name="mixpanel-provider")
+
+    def shutdown(self) -> None:
+        self._flags_provider.shutdown()
+
+    def resolve_boolean_details(
+        self,
+        flag_key: str,
+        default_value: bool,
+        evaluation_context: typing.Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[bool]:
+        return self._resolve(flag_key, default_value, bool, evaluation_context)
+
+    def resolve_string_details(
+        self,
+        flag_key: str,
+        default_value: str,
+        evaluation_context: typing.Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[str]:
+        return self._resolve(flag_key, default_value, str, evaluation_context)
+
+    def resolve_integer_details(
+        self,
+        flag_key: str,
+        default_value: int,
+        evaluation_context: typing.Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[int]:
+        return self._resolve(flag_key, default_value, int, evaluation_context)
+
+    def resolve_float_details(
+        self,
+        flag_key: str,
+        default_value: float,
+        evaluation_context: typing.Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[float]:
+        return self._resolve(flag_key, default_value, float, evaluation_context)
+
+    def resolve_object_details(
+        self,
+        flag_key: str,
+        default_value: Union[Sequence[FlagValueType], Mapping[str, FlagValueType]],
+        evaluation_context: typing.Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[
+        Union[Sequence[FlagValueType], Mapping[str, FlagValueType]]
+    ]:
+        return self._resolve(flag_key, default_value, None, evaluation_context)
+
+    @staticmethod
+    def _unwrap_value(value: typing.Any) -> typing.Any:
+        if isinstance(value, dict):
+            return {k: MixpanelProvider._unwrap_value(v) for k, v in value.items()}
+        if isinstance(value, list):
+            return [MixpanelProvider._unwrap_value(item) for item in value]
+        if isinstance(value, float) and value.is_integer():
+            return int(value)
+        return value
+
+    @staticmethod
+    def _build_user_context(
+        evaluation_context: typing.Optional[EvaluationContext],
+    ) -> dict:
+        user_context: dict = {}
+        if evaluation_context is not None:
+            if evaluation_context.attributes:
+                for k, v in evaluation_context.attributes.items():
+                    user_context[k] = MixpanelProvider._unwrap_value(v)
+            if evaluation_context.targeting_key:
+                user_context["targetingKey"] = evaluation_context.targeting_key
+        return user_context
+
+    def _resolve(
+        self,
+        flag_key: str,
+        default_value: typing.Any,
+        expected_type: typing.Optional[type],
+        evaluation_context: typing.Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails:
+        if not self._are_flags_ready():
+            return FlagResolutionDetails(
+                value=default_value,
+                error_code=ErrorCode.PROVIDER_NOT_READY,
+                reason=Reason.ERROR,
+            )
+
+        fallback = SelectedVariant(variant_value=default_value)
+        user_context = self._build_user_context(evaluation_context)
+        try:
+            result = self._flags_provider.get_variant(flag_key, fallback, user_context)
+        except Exception:
+            return FlagResolutionDetails(
+                value=default_value,
+                error_code=ErrorCode.GENERAL,
+                reason=Reason.ERROR,
+            )
+
+        if result is fallback:
+            return FlagResolutionDetails(
+                value=default_value,
+                error_code=ErrorCode.FLAG_NOT_FOUND,
+                reason=Reason.DEFAULT,
+            )
+
+        value = result.variant_value
+        variant_key = result.variant_key
+
+        if expected_type is None:
+            return FlagResolutionDetails(
+                value=value, variant=variant_key, reason=Reason.TARGETING_MATCH
+            )
+
+        # In Python, bool is a subclass of int, so isinstance(True, int)
+        # returns True. Reject bools early when expecting numeric types.
+        if expected_type in (int, float) and isinstance(value, bool):
+            return FlagResolutionDetails(
+                value=default_value,
+                error_code=ErrorCode.TYPE_MISMATCH,
+                error_message=f"Expected {expected_type.__name__}, got {type(value).__name__}",
+                reason=Reason.ERROR,
+            )
+
+        if expected_type is int and isinstance(value, float):
+            if math.isfinite(value) and value == math.floor(value):
+                return FlagResolutionDetails(
+                    value=int(value), variant=variant_key, reason=Reason.TARGETING_MATCH
+                )
+            return FlagResolutionDetails(
+                value=default_value,
+                error_code=ErrorCode.TYPE_MISMATCH,
+                error_message=f"Expected int, got float (value={value} is not a whole number)",
+                reason=Reason.ERROR,
+            )
+
+        if expected_type is float and isinstance(value, (int, float)):
+            return FlagResolutionDetails(
+                value=float(value), variant=variant_key, reason=Reason.TARGETING_MATCH
+            )
+
+        if not isinstance(value, expected_type):
+            return FlagResolutionDetails(
+                value=default_value,
+                error_code=ErrorCode.TYPE_MISMATCH,
+                error_message=f"Expected {expected_type.__name__}, got {type(value).__name__}",
+                reason=Reason.ERROR,
+            )
+
+        return FlagResolutionDetails(
+            value=value, variant=variant_key, reason=Reason.TARGETING_MATCH
+        )
+
+    def _are_flags_ready(self) -> bool:
+        if hasattr(self._flags_provider, "are_flags_ready"):
+            return self._flags_provider.are_flags_ready()
+        return True

mixpanel_openfeature-0.1.0/src/mixpanel_openfeature.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: mixpanel-openfeature
+Version: 0.1.0
+Summary: OpenFeature provider for the Mixpanel Python SDK
+Author-email: "Mixpanel, Inc." <dev@mixpanel.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Requires-Dist: mixpanel<6,>=5.1.0
+Requires-Dist: openfeature-sdk>=0.7.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.4.1; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Requires-Dist: pytest-cov>=6.0; extra == "test"

mixpanel_openfeature-0.1.0/src/mixpanel_openfeature.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+pyproject.toml
+src/mixpanel_openfeature/__init__.py
+src/mixpanel_openfeature/provider.py
+src/mixpanel_openfeature.egg-info/PKG-INFO
+src/mixpanel_openfeature.egg-info/SOURCES.txt
+src/mixpanel_openfeature.egg-info/dependency_links.txt
+src/mixpanel_openfeature.egg-info/requires.txt
+src/mixpanel_openfeature.egg-info/top_level.txt
+tests/test_provider.py

mixpanel_openfeature-0.1.0/src/mixpanel_openfeature.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mixpanel_openfeature-0.1.0/src/mixpanel_openfeature.egg-info/requires.txt

@@ -0,0 +1,7 @@
+mixpanel<6,>=5.1.0
+openfeature-sdk>=0.7.0
+
+[test]
+pytest>=8.4.1
+pytest-asyncio>=0.23.0
+pytest-cov>=6.0

mixpanel_openfeature-0.1.0/src/mixpanel_openfeature.egg-info/top_level.txt

@@ -0,0 +1 @@
+mixpanel_openfeature

mixpanel_openfeature-0.1.0/tests/test_provider.py

@@ -0,0 +1,452 @@
+from unittest.mock import MagicMock
+
+import pytest
+from openfeature.evaluation_context import EvaluationContext
+from openfeature.exception import ErrorCode
+from openfeature.flag_evaluation import Reason
+
+from mixpanel.flags.types import SelectedVariant
+from mixpanel_openfeature import MixpanelProvider
+
+
+@pytest.fixture
+def mock_flags():
+    flags = MagicMock()
+    flags.are_flags_ready.return_value = True
+    return flags
+
+
+@pytest.fixture
+def provider(mock_flags):
+    return MixpanelProvider(mock_flags)
+
+
+def setup_flag(mock_flags, flag_key, value, variant_key="variant-key"):
+    """Configure mock to return a SelectedVariant with the given value."""
+    mock_flags.get_variant.side_effect = lambda key, fallback, ctx: (
+        SelectedVariant(variant_key=variant_key, variant_value=value)
+        if key == flag_key
+        else fallback
+    )
+
+
+def setup_flag_not_found(mock_flags, flag_key):
+    """Configure mock to return the fallback (identity check triggers FLAG_NOT_FOUND)."""
+    mock_flags.get_variant.side_effect = lambda key, fallback, ctx: fallback
+
+
+# --- Metadata ---
+
+
+def test_metadata_name(provider):
+    assert provider.get_metadata().name == "mixpanel-provider"
+
+
+# --- Boolean evaluation ---
+
+
+def test_resolves_boolean_true(provider, mock_flags):
+    setup_flag(mock_flags, "bool-flag", True)
+    result = provider.resolve_boolean_details("bool-flag", False)
+    assert result.value is True
+    assert result.reason == Reason.TARGETING_MATCH
+    assert result.error_code is None
+
+
+def test_resolves_boolean_false(provider, mock_flags):
+    setup_flag(mock_flags, "bool-flag", False)
+    result = provider.resolve_boolean_details("bool-flag", True)
+    assert result.value is False
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+# --- String evaluation ---
+
+
+def test_resolves_string(provider, mock_flags):
+    setup_flag(mock_flags, "string-flag", "hello")
+    result = provider.resolve_string_details("string-flag", "default")
+    assert result.value == "hello"
+    assert result.reason == Reason.TARGETING_MATCH
+    assert result.error_code is None
+
+
+# --- Integer evaluation ---
+
+
+def test_resolves_integer(provider, mock_flags):
+    setup_flag(mock_flags, "int-flag", 42)
+    result = provider.resolve_integer_details("int-flag", 0)
+    assert result.value == 42
+    assert result.reason == Reason.TARGETING_MATCH
+    assert result.error_code is None
+
+
+def test_resolves_integer_from_float_no_fraction(provider, mock_flags):
+    setup_flag(mock_flags, "int-flag", 42.0)
+    result = provider.resolve_integer_details("int-flag", 0)
+    assert result.value == 42
+    assert isinstance(result.value, int)
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+# --- Float evaluation ---
+
+
+def test_resolves_float(provider, mock_flags):
+    setup_flag(mock_flags, "float-flag", 3.14)
+    result = provider.resolve_float_details("float-flag", 0.0)
+    assert result.value == pytest.approx(3.14)
+    assert result.reason == Reason.TARGETING_MATCH
+    assert result.error_code is None
+
+
+def test_resolves_float_from_integer(provider, mock_flags):
+    setup_flag(mock_flags, "float-flag", 42)
+    result = provider.resolve_float_details("float-flag", 0.0)
+    assert result.value == 42.0
+    assert isinstance(result.value, float)
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+# --- Object evaluation ---
+
+
+def test_resolves_object_with_dict(provider, mock_flags):
+    setup_flag(mock_flags, "obj-flag", {"key": "value"})
+    result = provider.resolve_object_details("obj-flag", {})
+    assert result.value == {"key": "value"}
+    assert result.reason == Reason.TARGETING_MATCH
+    assert result.error_code is None
+
+
+def test_resolves_object_with_list(provider, mock_flags):
+    setup_flag(mock_flags, "obj-flag", [1, 2, 3])
+    result = provider.resolve_object_details("obj-flag", [])
+    assert result.value == [1, 2, 3]
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+def test_resolves_object_with_string(provider, mock_flags):
+    setup_flag(mock_flags, "obj-flag", "hello")
+    result = provider.resolve_object_details("obj-flag", {})
+    assert result.value == "hello"
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+def test_resolves_object_with_bool(provider, mock_flags):
+    setup_flag(mock_flags, "obj-flag", True)
+    result = provider.resolve_object_details("obj-flag", {})
+    assert result.value is True
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+# --- Error: FLAG_NOT_FOUND ---
+
+
+def test_flag_not_found_boolean(provider, mock_flags):
+    setup_flag_not_found(mock_flags, "missing-flag")
+    result = provider.resolve_boolean_details("missing-flag", True)
+    assert result.value is True
+    assert result.error_code == ErrorCode.FLAG_NOT_FOUND
+    assert result.reason == Reason.DEFAULT
+
+
+def test_flag_not_found_string(provider, mock_flags):
+    setup_flag_not_found(mock_flags, "missing-flag")
+    result = provider.resolve_string_details("missing-flag", "fallback")
+    assert result.value == "fallback"
+    assert result.error_code == ErrorCode.FLAG_NOT_FOUND
+    assert result.reason == Reason.DEFAULT
+
+
+def test_flag_not_found_integer(provider, mock_flags):
+    setup_flag_not_found(mock_flags, "missing-flag")
+    result = provider.resolve_integer_details("missing-flag", 99)
+    assert result.value == 99
+    assert result.error_code == ErrorCode.FLAG_NOT_FOUND
+    assert result.reason == Reason.DEFAULT
+
+
+def test_flag_not_found_float(provider, mock_flags):
+    setup_flag_not_found(mock_flags, "missing-flag")
+    result = provider.resolve_float_details("missing-flag", 1.5)
+    assert result.value == 1.5
+    assert result.error_code == ErrorCode.FLAG_NOT_FOUND
+    assert result.reason == Reason.DEFAULT
+
+
+def test_flag_not_found_object(provider, mock_flags):
+    setup_flag_not_found(mock_flags, "missing-flag")
+    result = provider.resolve_object_details("missing-flag", {"default": True})
+    assert result.value == {"default": True}
+    assert result.error_code == ErrorCode.FLAG_NOT_FOUND
+    assert result.reason == Reason.DEFAULT
+
+
+# --- Error: TYPE_MISMATCH ---
+
+
+def test_type_mismatch_boolean_gets_string(provider, mock_flags):
+    setup_flag(mock_flags, "string-flag", "not-a-bool")
+    result = provider.resolve_boolean_details("string-flag", False)
+    assert result.value is False
+    assert result.error_code == ErrorCode.TYPE_MISMATCH
+    assert result.reason == Reason.ERROR
+
+
+def test_type_mismatch_string_gets_boolean(provider, mock_flags):
+    setup_flag(mock_flags, "bool-flag", True)
+    result = provider.resolve_string_details("bool-flag", "default")
+    assert result.value == "default"
+    assert result.error_code == ErrorCode.TYPE_MISMATCH
+    assert result.reason == Reason.ERROR
+
+
+def test_type_mismatch_integer_gets_string(provider, mock_flags):
+    setup_flag(mock_flags, "string-flag", "not-a-number")
+    result = provider.resolve_integer_details("string-flag", 0)
+    assert result.value == 0
+    assert result.error_code == ErrorCode.TYPE_MISMATCH
+    assert result.reason == Reason.ERROR
+
+
+def test_type_mismatch_float_gets_string(provider, mock_flags):
+    setup_flag(mock_flags, "string-flag", "not-a-number")
+    result = provider.resolve_float_details("string-flag", 0.0)
+    assert result.value == 0.0
+    assert result.error_code == ErrorCode.TYPE_MISMATCH
+    assert result.reason == Reason.ERROR
+
+
+def test_type_mismatch_integer_gets_float_with_fraction(provider, mock_flags):
+    setup_flag(mock_flags, "float-flag", 3.14)
+    result = provider.resolve_integer_details("float-flag", 0)
+    assert result.value == 0
+    assert result.error_code == ErrorCode.TYPE_MISMATCH
+    assert result.reason == Reason.ERROR
+
+
+def test_type_mismatch_integer_gets_boolean(provider, mock_flags):
+    setup_flag(mock_flags, "bool-flag", True)
+    result = provider.resolve_integer_details("bool-flag", 0)
+    assert result.value == 0
+    assert result.error_code == ErrorCode.TYPE_MISMATCH
+    assert result.reason == Reason.ERROR
+
+
+def test_type_mismatch_float_gets_boolean(provider, mock_flags):
+    setup_flag(mock_flags, "bool-flag", True)
+    result = provider.resolve_float_details("bool-flag", 0.0)
+    assert result.value == 0.0
+    assert result.error_code == ErrorCode.TYPE_MISMATCH
+    assert result.reason == Reason.ERROR
+
+
+# --- Error: PROVIDER_NOT_READY ---
+
+
+def test_provider_not_ready_boolean(mock_flags):
+    mock_flags.are_flags_ready.return_value = False
+    provider = MixpanelProvider(mock_flags)
+    result = provider.resolve_boolean_details("any-flag", True)
+    assert result.value is True
+    assert result.error_code == ErrorCode.PROVIDER_NOT_READY
+    assert result.reason == Reason.ERROR
+
+
+def test_provider_not_ready_string(mock_flags):
+    mock_flags.are_flags_ready.return_value = False
+    provider = MixpanelProvider(mock_flags)
+    result = provider.resolve_string_details("any-flag", "default")
+    assert result.value == "default"
+    assert result.error_code == ErrorCode.PROVIDER_NOT_READY
+    assert result.reason == Reason.ERROR
+
+
+def test_provider_not_ready_integer(mock_flags):
+    mock_flags.are_flags_ready.return_value = False
+    provider = MixpanelProvider(mock_flags)
+    result = provider.resolve_integer_details("any-flag", 5)
+    assert result.value == 5
+    assert result.error_code == ErrorCode.PROVIDER_NOT_READY
+    assert result.reason == Reason.ERROR
+
+
+def test_provider_not_ready_float(mock_flags):
+    mock_flags.are_flags_ready.return_value = False
+    provider = MixpanelProvider(mock_flags)
+    result = provider.resolve_float_details("any-flag", 2.5)
+    assert result.value == 2.5
+    assert result.error_code == ErrorCode.PROVIDER_NOT_READY
+    assert result.reason == Reason.ERROR
+
+
+def test_provider_not_ready_object(mock_flags):
+    mock_flags.are_flags_ready.return_value = False
+    provider = MixpanelProvider(mock_flags)
+    result = provider.resolve_object_details("any-flag", {"default": True})
+    assert result.value == {"default": True}
+    assert result.error_code == ErrorCode.PROVIDER_NOT_READY
+    assert result.reason == Reason.ERROR
+
+
+# --- Remote provider (no are_flags_ready) is always ready ---
+
+
+def test_remote_provider_always_ready():
+    remote_flags = MagicMock(spec=[])  # empty spec = no attributes
+    remote_flags.get_variant = MagicMock(
+        side_effect=lambda key, fallback, ctx: SelectedVariant(
+            variant_key="v1", variant_value=True
+        )
+    )
+    provider = MixpanelProvider(remote_flags)
+    result = provider.resolve_boolean_details("flag", False)
+    assert result.value is True
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+# --- Lifecycle ---
+
+
+def test_shutdown_is_noop(provider):
+    provider.shutdown()  # Should not raise
+
+
+# --- EvaluationContext forwarding ---
+
+
+def test_forwards_targeting_key(provider, mock_flags):
+    setup_flag(mock_flags, "flag", "val")
+    ctx = EvaluationContext(targeting_key="user-123")
+    provider.resolve_string_details("flag", "default", ctx)
+    _, _, user_context = mock_flags.get_variant.call_args[0]
+    assert user_context["targetingKey"] == "user-123"
+
+
+def test_forwards_attributes_flat(provider, mock_flags):
+    setup_flag(mock_flags, "flag", "val")
+    ctx = EvaluationContext(attributes={"plan": "pro", "beta": True})
+    provider.resolve_string_details("flag", "default", ctx)
+    _, _, user_context = mock_flags.get_variant.call_args[0]
+    assert user_context["plan"] == "pro"
+    assert user_context["beta"] is True
+
+
+def test_forwards_full_context(provider, mock_flags):
+    setup_flag(mock_flags, "flag", "val")
+    ctx = EvaluationContext(targeting_key="user-456", attributes={"tier": "enterprise"})
+    provider.resolve_string_details("flag", "default", ctx)
+    _, _, user_context = mock_flags.get_variant.call_args[0]
+    assert user_context == {
+        "targetingKey": "user-456",
+        "tier": "enterprise",
+    }
+
+
+def test_no_context_passes_empty_dict(provider, mock_flags):
+    setup_flag(mock_flags, "flag", "val")
+    provider.resolve_string_details("flag", "default")
+    _, _, user_context = mock_flags.get_variant.call_args[0]
+    assert user_context == {}
+
+
+# --- Variant key passthrough ---
+
+
+def test_variant_key_present_in_boolean_resolution(provider, mock_flags):
+    setup_flag(mock_flags, "bool-flag", True, variant_key="control")
+    result = provider.resolve_boolean_details("bool-flag", False)
+    assert result.value is True
+    assert result.variant == "control"
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+def test_variant_key_present_in_string_resolution(provider, mock_flags):
+    setup_flag(mock_flags, "string-flag", "hello", variant_key="treatment-a")
+    result = provider.resolve_string_details("string-flag", "default")
+    assert result.value == "hello"
+    assert result.variant == "treatment-a"
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+def test_variant_key_present_in_integer_resolution(provider, mock_flags):
+    setup_flag(mock_flags, "int-flag", 42, variant_key="v2")
+    result = provider.resolve_integer_details("int-flag", 0)
+    assert result.value == 42
+    assert result.variant == "v2"
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+def test_variant_key_present_in_float_resolution(provider, mock_flags):
+    setup_flag(mock_flags, "float-flag", 3.14, variant_key="v3")
+    result = provider.resolve_float_details("float-flag", 0.0)
+    assert result.value == pytest.approx(3.14)
+    assert result.variant == "v3"
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+def test_variant_key_present_in_object_resolution(provider, mock_flags):
+    setup_flag(mock_flags, "obj-flag", {"key": "value"}, variant_key="v4")
+    result = provider.resolve_object_details("obj-flag", {})
+    assert result.value == {"key": "value"}
+    assert result.variant == "v4"
+    assert result.reason == Reason.TARGETING_MATCH
+
+
+# --- SDK exception handling ---
+
+
+def test_sdk_exception_returns_default_boolean(provider, mock_flags):
+    mock_flags.get_variant.side_effect = RuntimeError("SDK failure")
+    result = provider.resolve_boolean_details("flag", True)
+    assert result.value is True
+    assert result.error_code == ErrorCode.GENERAL
+    assert result.reason == Reason.ERROR
+
+
+def test_sdk_exception_returns_default_string(provider, mock_flags):
+    mock_flags.get_variant.side_effect = RuntimeError("SDK failure")
+    result = provider.resolve_string_details("flag", "fallback")
+    assert result.value == "fallback"
+    assert result.error_code == ErrorCode.GENERAL
+    assert result.reason == Reason.ERROR
+
+
+def test_sdk_exception_returns_default_integer(provider, mock_flags):
+    mock_flags.get_variant.side_effect = RuntimeError("SDK failure")
+    result = provider.resolve_integer_details("flag", 99)
+    assert result.value == 99
+    assert result.error_code == ErrorCode.GENERAL
+    assert result.reason == Reason.ERROR
+
+
+# --- Null variant key ---
+
+
+def test_null_variant_key_boolean(provider, mock_flags):
+    setup_flag(mock_flags, "flag", True, variant_key=None)
+    result = provider.resolve_boolean_details("flag", False)
+    assert result.value is True
+    assert result.variant is None
+    assert result.reason == Reason.TARGETING_MATCH
+    assert result.error_code is None
+
+
+def test_null_variant_key_string(provider, mock_flags):
+    setup_flag(mock_flags, "flag", "hello", variant_key=None)
+    result = provider.resolve_string_details("flag", "default")
+    assert result.value == "hello"
+    assert result.variant is None
+    assert result.reason == Reason.TARGETING_MATCH
+    assert result.error_code is None
+
+
+def test_null_variant_key_object(provider, mock_flags):
+    setup_flag(mock_flags, "flag", {"key": "value"}, variant_key=None)
+    result = provider.resolve_object_details("flag", {})
+    assert result.value == {"key": "value"}
+    assert result.variant is None
+    assert result.reason == Reason.TARGETING_MATCH
+    assert result.error_code is None