{"id":4945,"library":"flagsmith-flag-engine","title":"Flagsmith Flag Engine","description":"The `flagsmith-flag-engine` is the core evaluation engine for the Flagsmith API, enabling feature flag and remote configuration management. It processes environment, feature, segment, and identity data to determine flag states locally. The library is actively maintained, with version 10.0.3 currently available, and frequent releases that often include minor and major updates with breaking changes.","status":"active","version":"10.0.3","language":"en","source_language":"en","source_url":"https://github.com/Flagsmith/flagsmith-engine","tags":["feature flags","feature management","AB testing","flagsmith","remote config","evaluation engine"],"install":[{"cmd":"pip install flagsmith-flag-engine","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for data models representing environments, features, and identities.","package":"pydantic"},{"reason":"Requires Python 3.9 or higher due to dependencies and SDK compatibility.","package":"python","version":">=3.9","optional":false}],"imports":[{"symbol":"EnvironmentModel","correct":"from flagsmith_engine.environments import EnvironmentModel"},{"symbol":"IdentityModel","correct":"from flagsmith_engine.identities import IdentityModel"},{"symbol":"TraitModel","correct":"from flagsmith_engine.features import TraitModel"},{"symbol":"evaluate_identity_flags","correct":"from flagsmith_engine.evaluator import evaluate_identity_flags"}],"quickstart":{"code":"import os\nfrom flagsmith_engine.environments import EnvironmentModel, FeatureStateModel, SegmentModel\nfrom flagsmith_engine.identities import IdentityModel, TraitModel\nfrom flagsmith_engine.evaluator import evaluate_identity_flags\nfrom flagsmith_engine.segments import SegmentCondition, SegmentRule, SEGMENT_CONDITION_OPERATORS\n\n# Simulate an Environment structure (typically fetched from Flagsmith API)\nenvironment_data = {\n    \"id\": 1,\n    \"api_key\": os.environ.get('FLAGSMITH_ENVIRONMENT_KEY', 'your_environment_key'),\n    \"project\": {\"id\": 1, \"name\": \"Test Project\", \"organisation\": {\"id\": 1, \"name\": \"Test Org\"}},\n    \"feature_states\": [\n        {\n            \"id\": 101,\n            \"feature\": {\"id\": 1, \"name\": \"my_test_feature\", \"type\": \"STANDARD\"},\n            \"enabled\": True,\n            \"feature_state_value\": \"default_value\"\n        },\n        {\n            \"id\": 102,\n            \"feature\": {\"id\": 2, \"name\": \"another_feature\", \"type\": \"STANDARD\"},\n            \"enabled\": False,\n            \"feature_state_value\": \"false_value\"\n        }\n    ],\n    \"segments\": [\n        {\n            \"id\": 201,\n            \"name\": \"Test Segment\",\n            \"rules\": [\n                {\n                    \"type\": \"ALL\",\n                    \"conditions\": [\n                        {\n                            \"operator\": SEGMENT_CONDITION_OPERATORS[\"EQUAL\"],\n                            \"property\": \"plan\",\n                            \"value\": \"premium\"\n                        }\n                    ]\n                }\n            ]\n        }\n    ]\n}\n\nenvironment = EnvironmentModel.parse_obj(environment_data)\n\n# Create an identity\nidentity_traits = [TraitModel(trait_key=\"plan\", trait_value=\"premium\")]\nidentity = IdentityModel(identifier=\"test_user_123\", environment_api_key=environment.api_key, traits=identity_traits)\n\n# Evaluate flags for the identity\nfeature_states, identities_segments = evaluate_identity_flags(identity, environment, None)\n\nprint(f\"Identity '{identity.identifier}' is in segments: {[s.name for s in identities_segments]}\")\nfor fs in feature_states:\n    print(f\"Feature '{fs.feature.name}': Enabled={fs.enabled}, Value='{fs.feature_state_value}'\")\n\n# Example with a user not in the segment\nidentity_traits_basic = [TraitModel(trait_key=\"plan\", trait_value=\"basic\")]\nidentity_basic = IdentityModel(identifier=\"basic_user_456\", environment_api_key=environment.api_key, traits=identity_traits_basic)\nfeature_states_basic, identities_segments_basic = evaluate_identity_flags(identity_basic, environment, None)\n\nprint(f\"\\nIdentity '{identity_basic.identifier}' is in segments: {[s.name for s in identities_segments_basic]}\")\nfor fs in feature_states_basic:\n    print(f\"Feature '{fs.feature.name}': Enabled={fs.enabled}, Value='{fs.feature_state_value}'\")\n","lang":"python","description":"This quickstart demonstrates how to use `flagsmith-flag-engine` directly to evaluate feature flags for a given identity. It simulates an `EnvironmentModel` with defined feature states and a segment rule, then creates an `IdentityModel` with traits. Finally, it uses `evaluate_identity_flags` to determine the active flags and segments for that identity based on the engine's logic. This is typically done within a server-side SDK which fetches the `EnvironmentModel` from the Flagsmith API."},"warnings":[{"fix":"Update any code directly referencing these attributes. They are no longer part of the evaluation context or segment result models.","message":"Version 10.0.0 removed `FeatureContext.feature_key` and `SegmentResult.key`.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"If implementing custom multivariate evaluation logic based on older versions of the engine, ensure it now correctly uses `FeatureValue.priority` as the determining factor.","message":"Version 9.0.0 changed multivariate evaluation to use `FeatureValue.priority`.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Review and update any custom code that interacts directly with the `EvaluationResult` object or relies on internal test data structures.","message":"Version 8.0.0 introduced a new `EvaluationResult` model and updated test data structures.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Upgrade Python to 3.9 or higher. Update code to use current API methods, replacing any deprecated functions or Pydantic models removed in this version.","message":"Version 7.0.0 dropped support for Python 3.8 and removed deprecated APIs and Pydantic models.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Always explicitly provide an `identity.identifier` when evaluating flags with 'PERCENTAGE_SPLIT' rules to ensure consistent and correct behavior. Upgrade to v10.0.1 or higher for the fix.","message":"Relying on implicit identity keys for 'PERCENTAGE_SPLIT' operator can lead to incorrect evaluations. This was a bug that was fixed in v10.0.1.","severity":"gotcha","affected_versions":"<10.0.1"},{"fix":"Regularly review and remove obsolete feature flags from both your codebase and the Flagsmith dashboard. Create new toggles for distinct features rather than reusing old ones.","message":"Not cleaning up unused feature flags can lead to cluttered codebases, technical debt, and potential system failures.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}