Flagsmith Flag Engine

10.0.3 · active · verified Sun Apr 12

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.

Warnings

breaking Version 10.0.0 removed `FeatureContext.feature_key` and `SegmentResult.key`.
Fix: Update any code directly referencing these attributes. They are no longer part of the evaluation context or segment result models.
breaking Version 9.0.0 changed multivariate evaluation to use `FeatureValue.priority`.
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.
breaking Version 8.0.0 introduced a new `EvaluationResult` model and updated test data structures.
Fix: Review and update any custom code that interacts directly with the `EvaluationResult` object or relies on internal test data structures.
breaking Version 7.0.0 dropped support for Python 3.8 and removed deprecated APIs and Pydantic models.
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.
gotcha 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.
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.
gotcha Not cleaning up unused feature flags can lead to cluttered codebases, technical debt, and potential system failures.
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.

Install

pip install flagsmith-flag-engine Install latest version

Imports

EnvironmentModel

from flagsmith_engine.environments import EnvironmentModel

IdentityModel

from flagsmith_engine.identities import IdentityModel

TraitModel

from flagsmith_engine.features import TraitModel

evaluate_identity_flags

from flagsmith_engine.evaluator import evaluate_identity_flags

Quickstart

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.

import os
from flagsmith_engine.environments import EnvironmentModel, FeatureStateModel, SegmentModel
from flagsmith_engine.identities import IdentityModel, TraitModel
from flagsmith_engine.evaluator import evaluate_identity_flags
from flagsmith_engine.segments import SegmentCondition, SegmentRule, SEGMENT_CONDITION_OPERATORS

# Simulate an Environment structure (typically fetched from Flagsmith API)
environment_data = {
    "id": 1,
    "api_key": os.environ.get('FLAGSMITH_ENVIRONMENT_KEY', 'your_environment_key'),
    "project": {"id": 1, "name": "Test Project", "organisation": {"id": 1, "name": "Test Org"}},
    "feature_states": [
        {
            "id": 101,
            "feature": {"id": 1, "name": "my_test_feature", "type": "STANDARD"},
            "enabled": True,
            "feature_state_value": "default_value"
        },
        {
            "id": 102,
            "feature": {"id": 2, "name": "another_feature", "type": "STANDARD"},
            "enabled": False,
            "feature_state_value": "false_value"
        }
    ],
    "segments": [
        {
            "id": 201,
            "name": "Test Segment",
            "rules": [
                {
                    "type": "ALL",
                    "conditions": [
                        {
                            "operator": SEGMENT_CONDITION_OPERATORS["EQUAL"],
                            "property": "plan",
                            "value": "premium"
                        }
                    ]
                }
            ]
        }
    ]
}

environment = EnvironmentModel.parse_obj(environment_data)

# Create an identity
identity_traits = [TraitModel(trait_key="plan", trait_value="premium")]
identity = IdentityModel(identifier="test_user_123", environment_api_key=environment.api_key, traits=identity_traits)

# Evaluate flags for the identity
feature_states, identities_segments = evaluate_identity_flags(identity, environment, None)

print(f"Identity '{identity.identifier}' is in segments: {[s.name for s in identities_segments]}")
for fs in feature_states:
    print(f"Feature '{fs.feature.name}': Enabled={fs.enabled}, Value='{fs.feature_state_value}'")

# Example with a user not in the segment
identity_traits_basic = [TraitModel(trait_key="plan", trait_value="basic")]
identity_basic = IdentityModel(identifier="basic_user_456", environment_api_key=environment.api_key, traits=identity_traits_basic)
feature_states_basic, identities_segments_basic = evaluate_identity_flags(identity_basic, environment, None)

print(f"\nIdentity '{identity_basic.identifier}' is in segments: {[s.name for s in identities_segments_basic]}")
for fs in feature_states_basic:
    print(f"Feature '{fs.feature.name}': Enabled={fs.enabled}, Value='{fs.feature_state_value}'")

view raw JSON →