feat: add feature flags registry

Introduce a simple feature flags config module that allows flags
to be set programmatically via configure() and overridden locally
with UIPATH_FEATURE_<name> environment variables.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cotovanu-cristian

src/uipath/core/feature_flags/__init__.py

@@ -0,0 +1,13 @@
+"""UiPath Feature Flags.
+
+Local-only feature flag registry for the UiPath SDK.
+"""
+
+from .feature_flags import configure, get, is_enabled, reset
+
+__all__ = [
+    "configure",
+    "get",
+    "is_enabled",
+    "reset",
+]

src/uipath/core/feature_flags/feature_flags.py

@@ -0,0 +1,100 @@
+"""Feature flags configuration for UiPath SDK.
+
+A simple, local-only feature flag registry. Flags can be set
+programmatically via :func:`configure` or overridden per-flag with
+environment variables named ``UIPATH_FEATURE_<FlagName>``.
+
+Environment variables always take precedence over programmatic values.
+
+Example usage::
+
+    from uipath.core.feature_flags import configure, is_enabled, get
+
+    # Programmatic configuration (e.g. from an upstream layer)
+    configure({"NewSerialization": True, "ModelOverride": "gpt-4"})
+
+    # Check a boolean flag
+    if is_enabled("NewSerialization"):
+        ...
+
+    # Get an arbitrary value
+    model = get("ModelOverride", default="default-model")
+
+    # Local override via environment variable
+    # $ export UIPATH_FEATURE_NewSerialization=false
+"""
+
+import json
+import os
+from typing import Any
+
+_flags: dict[str, Any] = {}
+
+
+def configure(flags: dict[str, Any]) -> None:
+    """Merge feature flag values into the registry.
+
+    Args:
+        flags: Mapping of flag names to their values.  Existing flags
+            with the same name are overwritten.
+    """
+    _flags.update(flags)
+
+
+def reset() -> None:
+    """Clear all configured flags.  Mainly useful in tests."""
+    _flags.clear()
+
+
+def _parse_env_value(raw: str) -> Any:
+    """Convert an environment variable string to a Python value.
+
+    Booleans are matched first (case-insensitive). For all other values
+    JSON decoding is attempted so that dicts, lists and numbers survive
+    the env-var round-trip.  Plain strings that are not valid JSON are
+    returned as-is.
+    """
+    lower = raw.lower()
+    if lower == "true":
+        return True
+    if lower == "false":
+        return False
+    try:
+        parsed = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return raw
+    # Only promote structured types (dict/list); scalars stay as strings.
+    if isinstance(parsed, (dict, list)):
+        return parsed
+    return raw
+
+
+def get(name: str, *, default: Any = None) -> Any:
+    """Return a flag value.
+
+    Resolution order:
+
+    1. ``UIPATH_FEATURE_<name>`` environment variable (highest priority)
+    2. Value set via :func:`configure`
+    3. *default*
+
+    Args:
+        name: The feature flag name.
+        default: Fallback when the flag is not set anywhere.
+    """
+    env_val = os.environ.get(f"UIPATH_FEATURE_{name}")
+    if env_val is not None:
+        return _parse_env_value(env_val)
+    return _flags.get(name, default)
+
+
+def is_enabled(name: str, *, default: bool = False) -> bool:
+    """Check whether a boolean flag is enabled.
+
+    Uses the same resolution order as :func:`get`.
+
+    Args:
+        name: The feature flag name.
+        default: Fallback when the flag is not set anywhere.
+    """
+    return bool(get(name, default=default))

tests/feature_flags/__init__.py

@@ -0,0 +1,162 @@
+"""Unit tests for the feature flags registry."""
+
+from typing import TYPE_CHECKING
+
+from uipath.core.feature_flags import configure, get, is_enabled, reset
+from uipath.core.feature_flags.feature_flags import _parse_env_value
+
+if TYPE_CHECKING:
+    from _pytest.monkeypatch import MonkeyPatch
+
+
+class TestParseEnvValue:
+    """Tests for _parse_env_value."""
+
+    def test_true_string(self) -> None:
+        assert _parse_env_value("true") is True
+
+    def test_true_uppercase(self) -> None:
+        assert _parse_env_value("TRUE") is True
+
+    def test_true_mixed_case(self) -> None:
+        assert _parse_env_value("True") is True
+
+    def test_false_string(self) -> None:
+        assert _parse_env_value("false") is False
+
+    def test_false_uppercase(self) -> None:
+        assert _parse_env_value("FALSE") is False
+
+    def test_string_passthrough(self) -> None:
+        assert _parse_env_value("gpt-4") == "gpt-4"
+
+    def test_empty_string(self) -> None:
+        assert _parse_env_value("") == ""
+
+    def test_numeric_string(self) -> None:
+        assert _parse_env_value("42") == "42"
+
+    def test_json_dict(self) -> None:
+        result = _parse_env_value('{"model": "gpt-4", "enabled": true}')
+        assert result == {"model": "gpt-4", "enabled": True}
+
+    def test_json_list(self) -> None:
+        result = _parse_env_value('["a", "b", "c"]')
+        assert result == ["a", "b", "c"]
+
+    def test_json_nested_dict(self) -> None:
+        result = _parse_env_value('{"outer": {"inner": 1}}')
+        assert result == {"outer": {"inner": 1}}
+
+    def test_float_string_stays_string(self) -> None:
+        assert _parse_env_value("3.14") == "3.14"
+
+    def test_plain_string_not_json(self) -> None:
+        assert _parse_env_value("gpt-4") == "gpt-4"
+
+
+class TestConfigure:
+    """Tests for configure / reset."""
+
+    def setup_method(self) -> None:
+        reset()
+
+    def test_configure_sets_flags(self) -> None:
+        configure({"FeatureA": True, "FeatureB": "value"})
+        assert get("FeatureA") is True
+        assert get("FeatureB") == "value"
+
+    def test_configure_merges(self) -> None:
+        configure({"FeatureA": True})
+        configure({"FeatureB": False})
+        assert get("FeatureA") is True
+        assert get("FeatureB") is False
+
+    def test_configure_overwrites(self) -> None:
+        configure({"FeatureA": True})
+        configure({"FeatureA": False})
+        assert get("FeatureA") is False
+
+    def test_reset_clears_all(self) -> None:
+        configure({"FeatureA": True})
+        reset()
+        assert get("FeatureA") is None
+
+
+class TestGet:
+    """Tests for get."""
+
+    def setup_method(self) -> None:
+        reset()
+
+    def test_returns_default_when_unset(self) -> None:
+        assert get("Missing") is None
+
+    def test_returns_custom_default(self) -> None:
+        assert get("Missing", default="fallback") == "fallback"
+
+    def test_returns_configured_value(self) -> None:
+        configure({"FeatureA": "hello"})
+        assert get("FeatureA") == "hello"
+
+    def test_env_var_overrides_configured(self, monkeypatch: "MonkeyPatch") -> None:
+        configure({"FeatureA": True})
+        monkeypatch.setenv("UIPATH_FEATURE_FeatureA", "false")
+        assert get("FeatureA") is False
+
+    def test_env_var_overrides_default(self, monkeypatch: "MonkeyPatch") -> None:
+        monkeypatch.setenv("UIPATH_FEATURE_X", "custom")
+        assert get("X", default="other") == "custom"
+
+    def test_env_var_string_value(self, monkeypatch: "MonkeyPatch") -> None:
+        monkeypatch.setenv("UIPATH_FEATURE_Model", "gpt-4-turbo")
+        assert get("Model") == "gpt-4-turbo"
+
+    def test_env_var_json_dict(self, monkeypatch: "MonkeyPatch") -> None:
+        monkeypatch.setenv(
+            "UIPATH_FEATURE_Models", '{"gpt-4": true, "claude": false}'
+        )
+        assert get("Models") == {"gpt-4": True, "claude": False}
+
+    def test_env_var_json_list(self, monkeypatch: "MonkeyPatch") -> None:
+        monkeypatch.setenv("UIPATH_FEATURE_AllowedModels", '["gpt-4", "claude"]')
+        assert get("AllowedModels") == ["gpt-4", "claude"]
+
+
+class TestIsEnabled:
+    """Tests for is_enabled."""
+
+    def setup_method(self) -> None:
+        reset()
+
+    def test_enabled_flag(self) -> None:
+        configure({"FeatureA": True})
+        assert is_enabled("FeatureA") is True
+
+    def test_disabled_flag(self) -> None:
+        configure({"FeatureA": False})
+        assert is_enabled("FeatureA") is False
+
+    def test_missing_flag_defaults_false(self) -> None:
+        assert is_enabled("Missing") is False
+
+    def test_missing_flag_custom_default(self) -> None:
+        assert is_enabled("Missing", default=True) is True
+
+    def test_truthy_string_is_enabled(self) -> None:
+        configure({"FeatureA": "some-value"})
+        assert is_enabled("FeatureA") is True
+
+    def test_none_is_disabled(self) -> None:
+        configure({"FeatureA": None})
+        assert is_enabled("FeatureA") is False
+
+    def test_env_override_disables(self, monkeypatch: "MonkeyPatch") -> None:
+        configure({"FeatureA": True})
+        monkeypatch.setenv("UIPATH_FEATURE_FeatureA", "false")
+        assert is_enabled("FeatureA") is False
+
+    def test_env_override_enables(self, monkeypatch: "MonkeyPatch") -> None:
+        configure({"FeatureA": False})
+        monkeypatch.setenv("UIPATH_FEATURE_FeatureA", "true")
+        assert is_enabled("FeatureA") is True