flagsmith-engine

flagsmith-flag-engine (the flag_engine package) is the core evaluation engine behind the Flagsmith feature-flag and remote-config platform. Given an evaluation context describing an identity and its traits, it resolves which segments match and returns the effective flag values, entirely in-process.

The library is deliberately small and dependency-light, exposing a single get_evaluation_result entry point along with typed EvaluationContext and EvaluationResult structures. It is used both inside the Flagsmith API and by SDKs that want to evaluate flags locally without a round trip to the server.

What You Get

• A single get_evaluation_result entry point for local flag evaluation
• Typed EvaluationContext and EvaluationResult structures with py.typed support
• A segment-rule evaluator supporting JSONPath and semantic-version comparisons
• A dependency-light core reusable across the Flagsmith API and its SDKs

Common Use Cases

• Evaluating Flagsmith feature flags locally inside an SDK to avoid per-request network calls
• Powering server-side flag resolution within the Flagsmith API
• Computing segment membership for an identity based on its traits

Under The Hood

Architecture - The public surface is tiny: flag_engine/engine.py re-exports get_evaluation_result plus the EvaluationContext, EvaluationResult, and ContextValue types. Evaluation flows from an EvaluationContext (identity and traits) into flag_engine/segments/evaluator.py, which walks segment rules and conditions to decide membership and resolve the effective flag values returned as an EvaluationResult. Supporting packages (context, result, segments, utils) keep the domain model separate from the evaluation logic.

Tech Stack - Plain Python targeting 3.10+ with only three runtime dependencies: jsonpath-rfc9535 for JSONPath condition lookups, semver for semantic-version comparisons, and typing-extensions. Tooling includes mypy, pytest, tox, and release-please for automated releases.

Code Quality - The project ships py.typed and enforces types via mypy.ini, has a dedicated tests/ suite driven by pinned engine-test-data, and keeps modules small and single-purpose. The clean split between context, segment evaluation, and result types makes the evaluation path easy to follow.

API Design - Consumers call a single function, get_evaluation_result, with a well-defined typed context and receive a typed result, which is about as low-boilerplate as a rules engine gets. The main learning curve is understanding the shape of the evaluation context and segment model rather than the API itself.