feat-sdk 0.1.0__tar.gz

feat_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish feathq-python-sdk to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI via OIDC
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi-publish
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

feat_sdk-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+dist/
+build/
+.DS_Store

feat_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 feat HQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

feat_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: feat-sdk
+Version: 0.1.0
+Summary: feat feature-flag SDK for Python (server-side, local evaluation)
+Project-URL: Homepage, https://feat.so
+Project-URL: Repository, https://github.com/feathq/python-sdk
+Project-URL: Issues, https://github.com/feathq/python-sdk/issues
+Author-email: feat HQ <engineering@feat.so>
+License: MIT
+License-File: LICENSE
+Keywords: feat,feature-flags,feature-management,feature-toggles,openfeature
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# feat-sdk
+
+Server-side Python SDK for [feat](https://feat.so) feature flags. Local flag evaluation against a polled datafile. Zero runtime dependencies (stdlib only).
+
+## Install
+
+```bash
+pip install feat-sdk
+```
+
+Python 3.10+.
+
+## Usage
+
+```python
+from feat import Client, ClientConfig, EvalContext
+
+client = Client(ClientConfig(
+    api_key="feat_sdk_...",
+    data_plane_url="https://data.feat.so",
+))
+client.ready()
+
+ctx = EvalContext(
+    targeting_key="user-123",
+    kinds={"user": {"plan": "pro", "email": "alice@example.com"}},
+)
+
+if client.get_boolean_value("checkout-v2", False, ctx):
+    # ...
+    pass
+
+client.close()
+```
+
+Use a **server** API key (`feat_sdk_...`).
+
+## How it works
+
+- Fetches a per-environment datafile and keeps it in memory.
+- Polls every 30 seconds by default (configurable). ETag-aware via `If-None-Match`.
+- Evaluation runs in-process: no per-flag network call.
+- A background daemon thread handles polling; `close()` stops it cleanly.
+
+## License
+
+MIT

feat_sdk-0.1.0/README.md

@@ -0,0 +1,47 @@
+# feat-sdk
+
+Server-side Python SDK for [feat](https://feat.so) feature flags. Local flag evaluation against a polled datafile. Zero runtime dependencies (stdlib only).
+
+## Install
+
+```bash
+pip install feat-sdk
+```
+
+Python 3.10+.
+
+## Usage
+
+```python
+from feat import Client, ClientConfig, EvalContext
+
+client = Client(ClientConfig(
+    api_key="feat_sdk_...",
+    data_plane_url="https://data.feat.so",
+))
+client.ready()
+
+ctx = EvalContext(
+    targeting_key="user-123",
+    kinds={"user": {"plan": "pro", "email": "alice@example.com"}},
+)
+
+if client.get_boolean_value("checkout-v2", False, ctx):
+    # ...
+    pass
+
+client.close()
+```
+
+Use a **server** API key (`feat_sdk_...`).
+
+## How it works
+
+- Fetches a per-environment datafile and keeps it in memory.
+- Polls every 30 seconds by default (configurable). ETag-aware via `If-None-Match`.
+- Evaluation runs in-process: no per-flag network call.
+- A background daemon thread handles polling; `close()` stops it cleanly.
+
+## License
+
+MIT

feat_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "feat-sdk"
+version = "0.1.0"
+description = "feat feature-flag SDK for Python (server-side, local evaluation)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "feat HQ", email = "engineering@feat.so" },
+]
+keywords = ["feature-flags", "feature-toggles", "feature-management", "feat", "openfeature"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://feat.so"
+Repository = "https://github.com/feathq/python-sdk"
+Issues = "https://github.com/feathq/python-sdk/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/feat"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

feat_sdk-0.1.0/src/feat/__init__.py

@@ -0,0 +1,31 @@
+"""feat feature-flag SDK for Python.
+
+Server-side evaluation against a locally-cached datafile.
+"""
+
+from .client import Client, ClientConfig
+from .datafile import (
+    ConditionSpec,
+    ContextKindSpec,
+    Datafile,
+    FlagSpec,
+    Rollout,
+    SegmentSpec,
+)
+from .eval import EvaluationResult, Reason, evaluate
+from .types import EvalContext
+
+__all__ = [
+    "Client",
+    "ClientConfig",
+    "ConditionSpec",
+    "ContextKindSpec",
+    "Datafile",
+    "EvalContext",
+    "EvaluationResult",
+    "FlagSpec",
+    "Reason",
+    "Rollout",
+    "SegmentSpec",
+    "evaluate",
+]

feat_sdk-0.1.0/src/feat/bucketing.py

@@ -0,0 +1,41 @@
+"""Deterministic bucketing for percentage rollouts.
+
+Algorithm matches @feathq/feat-eval and feat-go-sdk bit-for-bit so the
+same context lands in the same variation regardless of which SDK does
+the evaluation:
+
+    sha1(salt + "." + flag_key + "." + context_key)
+    -> first 8 bytes as big-endian uint64
+    -> shift right 4 (drop low bits) for exactly 60 bits
+    -> modulo 100_000
+
+Uses SHA-1 for the algorithm (not security); shrugs off Python's hash
+randomization since the digest is purely a function of the inputs.
+"""
+
+import hashlib
+
+BUCKET_SCALE = 100_000
+
+
+def bucket(salt: str, flag_key: str, context_key: str) -> int:
+    data = f"{salt}.{flag_key}.{context_key}".encode()
+    digest = hashlib.sha1(data, usedforsecurity=False).digest()
+    first8 = int.from_bytes(digest[:8], "big", signed=False)
+    sixty = first8 >> 4
+    return sixty % BUCKET_SCALE
+
+
+def pick_by_weight(bucket_value: int, variations: list) -> str | None:
+    """Walk cumulative weights and return the variation whose range
+    contains bucket_value. Falls back to the last variation defensively
+    if upstream weights underflow the scale.
+    """
+    cumulative = 0
+    for v in variations:
+        cumulative += v.weight
+        if bucket_value < cumulative:
+            return v.variationId
+    if variations:
+        return variations[-1].variationId
+    return None

feat_sdk-0.1.0/src/feat/client.py

@@ -0,0 +1,146 @@
+"""Polling HTTP client. Uses stdlib only (urllib + threading) - zero deps."""
+
+import json
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+from .datafile import Datafile, from_json
+from .eval import EvaluationResult, Reason, evaluate
+from .types import EvalContext
+
+MIN_POLL_INTERVAL_SECONDS = 5.0
+MAX_DATAFILE_BYTES = 10 * 1024 * 1024
+
+
+@dataclass
+class ClientConfig:
+    api_key: str
+    data_plane_url: str
+    poll_interval_seconds: float = 30.0
+    # If True, start() spawns a background daemon thread that polls
+    # on the configured cadence. Tests typically set this False and
+    # drive refresh() manually.
+    poll_in_background: bool = True
+
+
+def _validate_https(url: str) -> None:
+    """Reject non-https URLs (allow http://localhost / 127.0.0.1 for tests)."""
+    try:
+        parsed = urllib.parse.urlparse(url)
+    except ValueError as exc:  # pragma: no cover - urlparse rarely raises
+        raise ValueError("dataPlaneUrl is not a valid URL") from exc
+    if parsed.scheme == "https":
+        return
+    if parsed.scheme == "http" and parsed.hostname in ("localhost", "127.0.0.1"):
+        return
+    raise ValueError(
+        "data_plane_url must use https:// (http://localhost allowed for tests)"
+    )
+
+
+class Client:
+    """In-memory datafile cache with background polling.
+
+    Construct, call ready() once (blocks for the first fetch), then
+    evaluate(). Thread-safe: the datafile pointer is swapped atomically.
+    """
+
+    def __init__(self, config: ClientConfig) -> None:
+        _validate_https(config.data_plane_url)
+        if config.poll_interval_seconds < MIN_POLL_INTERVAL_SECONDS:
+            config.poll_interval_seconds = MIN_POLL_INTERVAL_SECONDS
+        self.config = config
+        self._datafile: Datafile | None = None
+        self._etag: str | None = None
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+
+    def ready(self) -> None:
+        """Blocking initial fetch + start the background poller (if enabled)."""
+        self._fetch_once()
+        if self.config.poll_in_background and self._thread is None:
+            self._thread = threading.Thread(target=self._poll_loop, daemon=True)
+            self._thread.start()
+
+    def close(self) -> None:
+        self._stop.set()
+
+    def refresh(self) -> bool:
+        """Fetch once. Returns True if the datafile changed."""
+        return self._fetch_once()
+
+    def evaluate(
+        self,
+        flag_key: str,
+        default_value: Any,
+        context: EvalContext,
+    ) -> EvaluationResult:
+        df = self._datafile
+        if df is None:
+            return EvaluationResult(
+                value=default_value,
+                variation_id=None,
+                reason=Reason.ERROR,
+                error_message="client not ready: call ready() before evaluate",
+            )
+        return evaluate(flag_key, default_value, context, df)
+
+    def get_boolean_value(self, flag_key: str, default: bool, context: EvalContext) -> bool:
+        r = self.evaluate(flag_key, default, context)
+        return r.value if isinstance(r.value, bool) else default
+
+    def get_string_value(self, flag_key: str, default: str, context: EvalContext) -> str:
+        r = self.evaluate(flag_key, default, context)
+        return r.value if isinstance(r.value, str) else default
+
+    def get_number_value(self, flag_key: str, default: float, context: EvalContext) -> float:
+        r = self.evaluate(flag_key, default, context)
+        if isinstance(r.value, bool):  # bool isinstance of int - exclude
+            return default
+        return r.value if isinstance(r.value, (int, float)) else default
+
+    def get_object_value(self, flag_key: str, default: Any, context: EvalContext) -> Any:
+        r = self.evaluate(flag_key, default, context)
+        return r.value
+
+    def _poll_loop(self) -> None:
+        while not self._stop.wait(self.config.poll_interval_seconds):
+            try:
+                self._fetch_once()
+            except Exception:  # noqa: BLE001 - defensive: keep polling on any error
+                pass
+
+    def _fetch_once(self) -> bool:
+        url = self.config.data_plane_url.rstrip("/") + "/sdk/v1/datafile"
+        req = urllib.request.Request(url)
+        req.add_header("Authorization", f"Bearer {self.config.api_key}")
+        with self._lock:
+            if self._etag:
+                req.add_header("If-None-Match", self._etag)
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:  # noqa: S310 - trusted endpoint
+                status = resp.status
+                if status in (304, 404):
+                    return False
+                length_header = resp.headers.get("Content-Length")
+                if length_header and int(length_header) > MAX_DATAFILE_BYTES:
+                    raise RuntimeError("datafile exceeds maximum allowed size")
+                body = resp.read(MAX_DATAFILE_BYTES + 1)
+                if len(body) > MAX_DATAFILE_BYTES:
+                    raise RuntimeError("datafile exceeds maximum allowed size")
+                data = json.loads(body.decode("utf-8"))
+                new_etag = resp.headers.get("ETag")
+        except urllib.error.HTTPError as e:
+            if e.code in (304, 404):
+                return False
+            raise
+        with self._lock:
+            self._datafile = from_json(data)
+            if new_etag:
+                self._etag = new_etag
+        return True

feat_sdk-0.1.0/src/feat/context.py

@@ -0,0 +1,57 @@
+"""Attribute resolution against an EvalContext."""
+
+from typing import Any
+
+from .types import EvalContext
+
+
+def resolve_attribute(ctx: EvalContext, attribute_path: str) -> Any:
+    """Walk an attribute path like "user.email" or "user.address.city".
+
+    Returns None if any segment is missing — operators treat None as a
+    non-match rather than throw.
+    """
+    if not attribute_path:
+        return None
+    parts = attribute_path.split(".", 1)
+    kind_key = parts[0]
+    kind_obj = _read_kind(ctx, kind_key)
+    if kind_obj is None:
+        return None
+    if len(parts) == 1:
+        return kind_obj.get("key")
+
+    rest = parts[1]
+    cur: Any = kind_obj
+    for p in rest.split("."):
+        if not isinstance(cur, dict):
+            return None
+        # Defensive: never traverse dunder / class-internal keys.
+        if p.startswith("__") and p.endswith("__"):
+            return None
+        if p not in cur:
+            return None
+        cur = cur[p]
+    return cur
+
+
+def read_context_key(ctx: EvalContext, kind_key: str) -> str | None:
+    """Pull just the `.key` for a context kind. Falls back to
+    targeting_key for "user", matching OpenFeature semantics."""
+    obj = _read_kind(ctx, kind_key)
+    if obj is None:
+        return None
+    key = obj.get("key")
+    return key if isinstance(key, str) else None
+
+
+def _read_kind(ctx: EvalContext, kind_key: str) -> dict[str, Any] | None:
+    if kind_key == "user":
+        obj = ctx.kinds.get("user")
+        if isinstance(obj, dict):
+            return obj
+        if ctx.targeting_key:
+            return {"key": ctx.targeting_key}
+        return None
+    obj = ctx.kinds.get(kind_key)
+    return obj if isinstance(obj, dict) else None

feat_sdk-0.1.0/src/feat/datafile.py

@@ -0,0 +1,170 @@
+"""Wire-format types. JSON field names mirror @feathq/datafile-schema."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class VariationSpec:
+    id: str
+    name: str
+    value: Any
+
+
+@dataclass
+class TargetSpec:
+    contextKindKey: str
+    contextKey: str
+    variationId: str
+
+
+@dataclass
+class ConditionSpec:
+    attributePath: str
+    operator: str
+    values: list[Any]
+
+
+@dataclass
+class ConditionGroupSpec:
+    conditions: list[ConditionSpec]
+
+
+@dataclass
+class RolloutVariation:
+    variationId: str
+    weight: int
+
+
+@dataclass
+class Rollout:
+    bucketingContextKindKey: str
+    variations: list[RolloutVariation]
+
+
+@dataclass
+class RuleSpec:
+    id: str
+    bucketingContextKindKey: str | None
+    variationId: str | None
+    rollout: Rollout | None
+    groups: list[ConditionGroupSpec]
+
+
+@dataclass
+class FlagSpec:
+    id: str
+    key: str
+    valueType: str
+    salt: str
+    archived: bool
+    isEnabled: bool
+    offVariationId: str
+    defaultVariationId: str | None
+    defaultRollout: Rollout | None
+    defaultBucketingContextKindKey: str | None
+    variations: list[VariationSpec]
+    targets: list[TargetSpec]
+    rules: list[RuleSpec]
+
+
+@dataclass
+class SegmentRuleSpec:
+    conditions: list[ConditionSpec]
+
+
+@dataclass
+class SegmentSpec:
+    key: str
+    rules: list[SegmentRuleSpec]
+
+
+@dataclass
+class ContextKindSpec:
+    key: str
+    availableForRules: bool
+    availableForExperiments: bool
+
+
+@dataclass
+class Datafile:
+    schemaVersion: int
+    envId: str
+    envKey: str
+    projectId: str
+    version: int
+    etag: str
+    generatedAt: str
+    flags: dict[str, FlagSpec]
+    segments: dict[str, SegmentSpec] = field(default_factory=dict)
+    contextKinds: dict[str, ContextKindSpec] = field(default_factory=dict)
+
+
+def from_json(data: dict[str, Any]) -> Datafile:
+    """Parse the wire-format dict (typically from response.json()) into a Datafile."""
+    return Datafile(
+        schemaVersion=data["schemaVersion"],
+        envId=data["envId"],
+        envKey=data["envKey"],
+        projectId=data["projectId"],
+        version=data["version"],
+        etag=data["etag"],
+        generatedAt=data["generatedAt"],
+        flags={k: _flag(v) for k, v in data["flags"].items()},
+        segments={k: _segment(v) for k, v in data.get("segments", {}).items()},
+        contextKinds={
+            k: ContextKindSpec(**v) for k, v in data.get("contextKinds", {}).items()
+        },
+    )
+
+
+def _flag(d: dict[str, Any]) -> FlagSpec:
+    return FlagSpec(
+        id=d["id"],
+        key=d["key"],
+        valueType=d["valueType"],
+        salt=d["salt"],
+        archived=d["archived"],
+        isEnabled=d["isEnabled"],
+        offVariationId=d["offVariationId"],
+        defaultVariationId=d.get("defaultVariationId"),
+        defaultRollout=_rollout(d.get("defaultRollout")),
+        defaultBucketingContextKindKey=d.get("defaultBucketingContextKindKey"),
+        variations=[VariationSpec(**v) for v in d["variations"]],
+        targets=[TargetSpec(**t) for t in d["targets"]],
+        rules=[_rule(r) for r in d["rules"]],
+    )
+
+
+def _rule(d: dict[str, Any]) -> RuleSpec:
+    return RuleSpec(
+        id=d["id"],
+        bucketingContextKindKey=d.get("bucketingContextKindKey"),
+        variationId=d.get("variationId"),
+        rollout=_rollout(d.get("rollout")),
+        groups=[
+            ConditionGroupSpec(
+                conditions=[ConditionSpec(**c) for c in g["conditions"]]
+            )
+            for g in d["groups"]
+        ],
+    )
+
+
+def _rollout(d: dict[str, Any] | None) -> Rollout | None:
+    if d is None:
+        return None
+    return Rollout(
+        bucketingContextKindKey=d["bucketingContextKindKey"],
+        variations=[RolloutVariation(**v) for v in d["variations"]],
+    )
+
+
+def _segment(d: dict[str, Any]) -> SegmentSpec:
+    return SegmentSpec(
+        key=d["key"],
+        rules=[
+            SegmentRuleSpec(conditions=[ConditionSpec(**c) for c in r["conditions"]])
+            for r in d["rules"]
+        ],
+    )

feat_sdk-0.1.0/src/feat/eval.py

@@ -0,0 +1,115 @@
+"""Evaluation precedence pipeline. Mirrors @feathq/feat-eval bit-for-bit."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from .bucketing import bucket, pick_by_weight
+from .context import read_context_key
+from .datafile import Datafile, FlagSpec, RuleSpec
+from .segments import match_condition
+from .types import EvalContext
+
+
+class Reason(str, Enum):
+    TARGETING_MATCH = "TARGETING_MATCH"
+    SPLIT = "SPLIT"
+    FALLTHROUGH = "FALLTHROUGH"
+    DEFAULT = "DEFAULT"
+    DISABLED = "DISABLED"
+    ERROR = "ERROR"
+    STATIC = "STATIC"
+
+
+@dataclass
+class EvaluationResult:
+    value: Any
+    variation_id: str | None
+    reason: Reason
+    error_message: str | None = None
+
+
+def evaluate(
+    flag_key: str,
+    default_value: Any,
+    ctx: EvalContext,
+    df: Datafile,
+) -> EvaluationResult:
+    """Run the evaluation pipeline:
+
+    1. archived flag        -> off variation        DISABLED
+    2. !isEnabled           -> off variation        DISABLED
+    3. individual target    -> target variation     TARGETING_MATCH
+    4. first matching rule  -> rule variation/rollout TARGETING_MATCH / SPLIT
+    5. default              -> default variation/rollout FALLTHROUGH / SPLIT
+    6. nothing matched      -> off variation        DEFAULT
+
+    Errors (missing flag, missing variation) return default_value with
+    reason ERROR.
+    """
+    flag = df.flags.get(flag_key)
+    if flag is None:
+        return EvaluationResult(
+            value=default_value,
+            variation_id=None,
+            reason=Reason.ERROR,
+            error_message="flag could not be evaluated",
+        )
+
+    if flag.archived or not flag.isEnabled:
+        return _resolve_variation(flag, flag.offVariationId, Reason.DISABLED, default_value)
+
+    for target in flag.targets:
+        ctx_key = read_context_key(ctx, target.contextKindKey)
+        if ctx_key is not None and ctx_key == target.contextKey:
+            return _resolve_variation(flag, target.variationId, Reason.TARGETING_MATCH, default_value)
+
+    for rule in flag.rules:
+        if not _match_rule(rule, ctx, df):
+            continue
+        if rule.variationId is not None:
+            return _resolve_variation(flag, rule.variationId, Reason.TARGETING_MATCH, default_value)
+        if rule.rollout is not None:
+            picked = _pick_rollout(flag, rule.rollout, ctx)
+            if picked is not None:
+                return _resolve_variation(flag, picked, Reason.SPLIT, default_value)
+
+    if flag.defaultVariationId is not None:
+        return _resolve_variation(flag, flag.defaultVariationId, Reason.FALLTHROUGH, default_value)
+    if flag.defaultRollout is not None:
+        picked = _pick_rollout(flag, flag.defaultRollout, ctx)
+        if picked is not None:
+            return _resolve_variation(flag, picked, Reason.SPLIT, default_value)
+
+    return _resolve_variation(flag, flag.offVariationId, Reason.DEFAULT, default_value)
+
+
+def _match_rule(rule: RuleSpec, ctx: EvalContext, df: Datafile) -> bool:
+    if not rule.groups:
+        return False
+    return any(
+        all(match_condition(cond, ctx, df) for cond in group.conditions)
+        and len(group.conditions) > 0
+        for group in rule.groups
+    )
+
+
+def _pick_rollout(flag: FlagSpec, rollout, ctx: EvalContext) -> str | None:
+    ctx_key = read_context_key(ctx, rollout.bucketingContextKindKey)
+    if ctx_key is None:
+        return None
+    return pick_by_weight(bucket(flag.salt, flag.key, ctx_key), rollout.variations)
+
+
+def _resolve_variation(
+    flag: FlagSpec, variation_id: str, reason: Reason, default_value: Any
+) -> EvaluationResult:
+    for v in flag.variations:
+        if v.id == variation_id:
+            return EvaluationResult(value=v.value, variation_id=variation_id, reason=reason)
+    return EvaluationResult(
+        value=default_value,
+        variation_id=None,
+        reason=Reason.ERROR,
+        error_message="flag could not be evaluated",
+    )

feat_sdk-0.1.0/src/feat/operators.py

@@ -0,0 +1,226 @@
+"""Per-operator predicates. Defensive: type-mismatch / parse-failure
+returns False rather than raising — matches the JS engine's posture
+against malformed contexts at the edge.
+
+segment_match / segment_not_match are dispatched by the rule evaluator
+(they recurse into the datafile's segments map), not here.
+"""
+
+import re
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+
+def match_operator(operator: str, lhs: Any, values: list[Any]) -> bool:
+    fn = _OPS.get(operator)
+    if fn is None:
+        return False
+    return fn(lhs, values)
+
+
+def _is_one_of(lhs: Any, values: list[Any]) -> bool:
+    return any(_deep_eq(lhs, v) for v in values)
+
+
+def _is_not_one_of(lhs: Any, values: list[Any]) -> bool:
+    return not _is_one_of(lhs, values)
+
+
+def _is_empty(lhs: Any, _: list[Any]) -> bool:
+    return lhs is None or lhs == ""
+
+
+def _is_not_empty(lhs: Any, _: list[Any]) -> bool:
+    return not _is_empty(lhs, _)
+
+
+def _contains(lhs: Any, values: list[Any]) -> bool:
+    if not isinstance(lhs, str):
+        return False
+    return any(isinstance(v, str) and v in lhs for v in values)
+
+
+def _does_not_contain(lhs: Any, values: list[Any]) -> bool:
+    if not isinstance(lhs, str):
+        return True
+    return not any(isinstance(v, str) and v in lhs for v in values)
+
+
+def _starts_with(lhs: Any, values: list[Any]) -> bool:
+    if not isinstance(lhs, str):
+        return False
+    return any(isinstance(v, str) and lhs.startswith(v) for v in values)
+
+
+def _ends_with(lhs: Any, values: list[Any]) -> bool:
+    if not isinstance(lhs, str):
+        return False
+    return any(isinstance(v, str) and lhs.endswith(v) for v in values)
+
+
+# ReDoS guard: cap pattern length and reject the most common catastrophic-
+# backtracking shapes (nested unbounded quantifiers, alternation inside a
+# starred group). False positives just turn the rule into a non-match,
+# which is the safe default.
+_REDOS_SHAPES = re.compile(r"\([^)]*[+*][^)]*\)\s*[+*]|\([^)]*\|[^)]*\)\s*[+*]")
+
+
+def _is_safe_regex(pattern: str) -> bool:
+    if len(pattern) > 512:
+        return False
+    if _REDOS_SHAPES.search(pattern):
+        return False
+    return True
+
+
+def _matches_regex(lhs: Any, values: list[Any]) -> bool:
+    if not isinstance(lhs, str):
+        return False
+    for v in values:
+        if not isinstance(v, str):
+            continue
+        if not _is_safe_regex(v):
+            continue
+        try:
+            if re.search(v, lhs) is not None:
+                return True
+        except re.error:
+            continue
+    return False
+
+
+def _deep_eq(a: Any, b: Any) -> bool:
+    if a == b:
+        return True
+    # String/number coercion — matches JS engine.
+    if isinstance(a, (int, float)) and isinstance(b, str):
+        return str(a) == b or _num_str_eq(a, b)
+    if isinstance(a, str) and isinstance(b, (int, float)):
+        return a == str(b) or _num_str_eq(b, a)
+    return False
+
+
+def _num_str_eq(num: Any, s: str) -> bool:
+    try:
+        return float(num) == float(s)
+    except (TypeError, ValueError):
+        return False
+
+
+def _to_number(x: Any) -> float | None:
+    if isinstance(x, bool):
+        return None  # bool isinstance of int — exclude explicitly
+    if isinstance(x, (int, float)):
+        return float(x)
+    if isinstance(x, str):
+        try:
+            return float(x)
+        except ValueError:
+            return None
+    return None
+
+
+def _numeric_cmp(cmp: Callable[[float, float], bool]) -> Callable[[Any, list[Any]], bool]:
+    def fn(lhs: Any, values: list[Any]) -> bool:
+        a = _to_number(lhs)
+        if a is None:
+            return False
+        for v in values:
+            b = _to_number(v)
+            if b is not None and cmp(a, b):
+                return True
+        return False
+    return fn
+
+
+def _to_datetime(x: Any) -> datetime | None:
+    if isinstance(x, str):
+        try:
+            # Support ISO-8601 with or without "Z" / offset.
+            s = x.replace("Z", "+00:00")
+            return datetime.fromisoformat(s)
+        except ValueError:
+            return None
+    if isinstance(x, (int, float)) and not isinstance(x, bool):
+        return datetime.fromtimestamp(float(x) / 1000.0, tz=timezone.utc)
+    return None
+
+
+def _date_cmp(cmp: Callable[[datetime, datetime], bool]) -> Callable[[Any, list[Any]], bool]:
+    def fn(lhs: Any, values: list[Any]) -> bool:
+        a = _to_datetime(lhs)
+        if a is None:
+            return False
+        for v in values:
+            b = _to_datetime(v)
+            if b is not None and cmp(a, b):
+                return True
+        return False
+    return fn
+
+
+_SEMVER_RE = re.compile(
+    r"^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$"
+)
+
+
+def _parse_semver(x: Any) -> tuple[int, int, int, str | None] | None:
+    if not isinstance(x, str):
+        return None
+    m = _SEMVER_RE.match(x.strip())
+    if m is None:
+        return None
+    return int(m.group(1)), int(m.group(2)), int(m.group(3)), m.group(4)
+
+
+def _compare_semver(a: tuple[int, int, int, str | None], b: tuple[int, int, int, str | None]) -> int:
+    for i in range(3):
+        if a[i] != b[i]:
+            return a[i] - b[i]
+    ap, bp = a[3], b[3]
+    if ap == bp:
+        return 0
+    if ap is None:
+        return 1
+    if bp is None:
+        return -1
+    return (ap > bp) - (ap < bp)
+
+
+def _semver_cmp(pred: Callable[[int], bool]) -> Callable[[Any, list[Any]], bool]:
+    def fn(lhs: Any, values: list[Any]) -> bool:
+        a = _parse_semver(lhs)
+        if a is None:
+            return False
+        for v in values:
+            b = _parse_semver(v)
+            if b is not None and pred(_compare_semver(a, b)):
+                return True
+        return False
+    return fn
+
+
+_OPS: dict[str, Callable[[Any, list[Any]], bool]] = {
+    "is_one_of": _is_one_of,
+    "is_not_one_of": _is_not_one_of,
+    "is_empty": _is_empty,
+    "is_not_empty": _is_not_empty,
+    "contains": _contains,
+    "does_not_contain": _does_not_contain,
+    "starts_with": _starts_with,
+    "ends_with": _ends_with,
+    "matches_regex": _matches_regex,
+    "gt": _numeric_cmp(lambda a, b: a > b),
+    "gte": _numeric_cmp(lambda a, b: a >= b),
+    "lt": _numeric_cmp(lambda a, b: a < b),
+    "lte": _numeric_cmp(lambda a, b: a <= b),
+    "before": _date_cmp(lambda a, b: a < b),
+    "after": _date_cmp(lambda a, b: a > b),
+    "semver_eq": _semver_cmp(lambda c: c == 0),
+    "semver_gt": _semver_cmp(lambda c: c > 0),
+    "semver_gte": _semver_cmp(lambda c: c >= 0),
+    "semver_lt": _semver_cmp(lambda c: c < 0),
+    "semver_lte": _semver_cmp(lambda c: c <= 0),
+    "segment_match": lambda lhs, values: False,
+    "segment_not_match": lambda lhs, values: False,
+}

feat_sdk-0.1.0/src/feat/segments.py

@@ -0,0 +1,30 @@
+"""Segment matching with recursion for segment_match / segment_not_match."""
+
+from .context import resolve_attribute
+from .datafile import ConditionSpec, Datafile
+from .operators import match_operator
+from .types import EvalContext
+
+
+def match_segment(segment_key: str, ctx: EvalContext, df: Datafile) -> bool:
+    seg = df.segments.get(segment_key)
+    if seg is None:
+        return False
+    return any(_match_segment_rule(rule.conditions, ctx, df) for rule in seg.rules)
+
+
+def _match_segment_rule(conds: list[ConditionSpec], ctx: EvalContext, df: Datafile) -> bool:
+    if not conds:
+        return False
+    return all(match_condition(c, ctx, df) for c in conds)
+
+
+def match_condition(cond: ConditionSpec, ctx: EvalContext, df: Datafile) -> bool:
+    if cond.operator == "segment_match":
+        keys = [v for v in cond.values if isinstance(v, str)]
+        return any(match_segment(k, ctx, df) for k in keys)
+    if cond.operator == "segment_not_match":
+        keys = [v for v in cond.values if isinstance(v, str)]
+        return not any(match_segment(k, ctx, df) for k in keys)
+    lhs = resolve_attribute(ctx, cond.attributePath)
+    return match_operator(cond.operator, lhs, cond.values)

feat_sdk-0.1.0/src/feat/types.py

@@ -0,0 +1,23 @@
+"""SDK-consumer-facing types.
+
+EvalContext mirrors OpenFeature's pattern: a `targeting_key` shorthand
+for `user.key`, and a kinds dict matching the datafile's `contextKinds`
+map. Example:
+
+    EvalContext(
+        targeting_key="user-123",
+        kinds={
+            "user": {"key": "user-123", "email": "u@example.com"},
+            "organization": {"key": "acme", "plan": "pro"},
+        },
+    )
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class EvalContext:
+    targeting_key: str | None = None
+    kinds: dict[str, dict[str, Any]] = field(default_factory=dict)

feat_sdk-0.1.0/tests/test_eval.py

@@ -0,0 +1,301 @@
+"""Parity suite — mirrors test/eval.test.ts (JS SDK) and feat/eval_test.go.
+
+New cases should land in all three so we keep eval semantics aligned
+across languages. Long-term these should become shared JSON fixtures.
+"""
+
+from typing import Any
+
+from feat import EvalContext, evaluate
+from feat.datafile import (
+    ConditionGroupSpec,
+    ConditionSpec,
+    ContextKindSpec,
+    Datafile,
+    FlagSpec,
+    Rollout,
+    RolloutVariation,
+    RuleSpec,
+    SegmentRuleSpec,
+    SegmentSpec,
+    TargetSpec,
+    VariationSpec,
+)
+from feat.eval import Reason
+
+TRUE_VAR = VariationSpec(id="var-true", name="true", value=True)
+FALSE_VAR = VariationSpec(id="var-false", name="false", value=False)
+
+
+def make_df(flags=None, segments=None) -> Datafile:
+    return Datafile(
+        schemaVersion=1,
+        envId="env-1",
+        envKey="staging",
+        projectId="proj-1",
+        version=1,
+        etag="etag",
+        generatedAt="2026-05-17T00:00:00Z",
+        flags=flags or {},
+        segments=segments or {},
+        contextKinds={
+            "user": ContextKindSpec(
+                key="user", availableForRules=True, availableForExperiments=True
+            ),
+        },
+    )
+
+
+def bool_flag(**overrides: Any) -> FlagSpec:
+    defaults = dict(
+        id="flag-1",
+        key="checkout",
+        valueType="boolean",
+        salt="abcdef0123456789",
+        archived=False,
+        isEnabled=True,
+        offVariationId=FALSE_VAR.id,
+        defaultVariationId=FALSE_VAR.id,
+        defaultRollout=None,
+        defaultBucketingContextKindKey=None,
+        variations=[TRUE_VAR, FALSE_VAR],
+        targets=[],
+        rules=[],
+    )
+    defaults.update(overrides)
+    return FlagSpec(**defaults)
+
+
+def user_ctx(key: str, **attrs: Any) -> EvalContext:
+    obj: dict[str, Any] = {"key": key, **attrs}
+    return EvalContext(kinds={"user": obj})
+
+
+def test_archived_returns_off():
+    df = make_df(flags={"checkout": bool_flag(archived=True)})
+    r = evaluate("checkout", False, user_ctx("u1"), df)
+    assert r.value is False
+    assert r.reason == Reason.DISABLED
+
+
+def test_disabled_returns_off():
+    df = make_df(flags={"checkout": bool_flag(isEnabled=False)})
+    r = evaluate("checkout", True, user_ctx("u1"), df)
+    assert r.value is False
+    assert r.reason == Reason.DISABLED
+
+
+def test_default_when_no_targeting():
+    df = make_df(flags={"checkout": bool_flag()})
+    r = evaluate("checkout", True, user_ctx("u1"), df)
+    assert r.value is False
+    assert r.reason == Reason.FALLTHROUGH
+
+
+def test_individual_target_beats_rules():
+    flag = bool_flag(
+        targets=[TargetSpec(contextKindKey="user", contextKey="u-vip", variationId=TRUE_VAR.id)],
+        rules=[
+            RuleSpec(
+                id="r1",
+                bucketingContextKindKey=None,
+                variationId=FALSE_VAR.id,
+                rollout=None,
+                groups=[
+                    ConditionGroupSpec(
+                        conditions=[
+                            ConditionSpec(
+                                attributePath="user.key",
+                                operator="is_one_of",
+                                values=["u-vip"],
+                            )
+                        ]
+                    )
+                ],
+            )
+        ],
+    )
+    df = make_df(flags={"checkout": flag})
+    r = evaluate("checkout", False, user_ctx("u-vip"), df)
+    assert r.value is True
+    assert r.reason == Reason.TARGETING_MATCH
+
+
+def test_rule_ends_with_email():
+    flag = bool_flag(
+        rules=[
+            RuleSpec(
+                id="r1",
+                bucketingContextKindKey=None,
+                variationId=TRUE_VAR.id,
+                rollout=None,
+                groups=[
+                    ConditionGroupSpec(
+                        conditions=[
+                            ConditionSpec(
+                                attributePath="user.email",
+                                operator="ends_with",
+                                values=["@example.com"],
+                            )
+                        ]
+                    )
+                ],
+            )
+        ]
+    )
+    df = make_df(flags={"checkout": flag})
+    r = evaluate("checkout", False, user_ctx("u1", email="alice@example.com"), df)
+    assert r.value is True
+    assert r.reason == Reason.TARGETING_MATCH
+
+
+def test_rule_or_groups():
+    flag = bool_flag(
+        rules=[
+            RuleSpec(
+                id="r1",
+                bucketingContextKindKey=None,
+                variationId=TRUE_VAR.id,
+                rollout=None,
+                groups=[
+                    ConditionGroupSpec(
+                        conditions=[
+                            ConditionSpec(
+                                attributePath="user.email",
+                                operator="ends_with",
+                                values=["@nope.com"],
+                            )
+                        ]
+                    ),
+                    ConditionGroupSpec(
+                        conditions=[
+                            ConditionSpec(
+                                attributePath="user.plan",
+                                operator="is_one_of",
+                                values=["pro", "enterprise"],
+                            )
+                        ]
+                    ),
+                ],
+            )
+        ]
+    )
+    df = make_df(flags={"checkout": flag})
+    r = evaluate(
+        "checkout", False, user_ctx("u1", email="x@elsewhere.com", plan="pro"), df
+    )
+    assert r.value is True
+
+
+def test_rollout_deterministic():
+    flag = bool_flag(
+        defaultVariationId=None,
+        defaultRollout=Rollout(
+            bucketingContextKindKey="user",
+            variations=[
+                RolloutVariation(variationId=TRUE_VAR.id, weight=50_000),
+                RolloutVariation(variationId=FALSE_VAR.id, weight=50_000),
+            ],
+        ),
+    )
+    df = make_df(flags={"checkout": flag})
+    r1 = evaluate("checkout", False, user_ctx("stable-key"), df)
+    r2 = evaluate("checkout", False, user_ctx("stable-key"), df)
+    assert r1.value == r2.value
+    assert r1.reason == Reason.SPLIT
+
+
+def test_rollout_100_percent():
+    flag = bool_flag(
+        defaultVariationId=None,
+        defaultRollout=Rollout(
+            bucketingContextKindKey="user",
+            variations=[RolloutVariation(variationId=TRUE_VAR.id, weight=100_000)],
+        ),
+    )
+    df = make_df(flags={"checkout": flag})
+    for key in ["u1", "u2", "u3", "u4", "u5"]:
+        r = evaluate("checkout", False, user_ctx(key), df)
+        assert r.value is True
+
+
+def test_segment_match():
+    flag = bool_flag(
+        rules=[
+            RuleSpec(
+                id="r1",
+                bucketingContextKindKey=None,
+                variationId=TRUE_VAR.id,
+                rollout=None,
+                groups=[
+                    ConditionGroupSpec(
+                        conditions=[
+                            ConditionSpec(
+                                attributePath="",
+                                operator="segment_match",
+                                values=["internal-users"],
+                            )
+                        ]
+                    )
+                ],
+            )
+        ]
+    )
+    segs = {
+        "internal-users": SegmentSpec(
+            key="internal-users",
+            rules=[
+                SegmentRuleSpec(
+                    conditions=[
+                        ConditionSpec(
+                            attributePath="user.email",
+                            operator="ends_with",
+                            values=["@feathq.com"],
+                        )
+                    ]
+                )
+            ],
+        )
+    }
+    df = make_df(flags={"checkout": flag}, segments=segs)
+
+    hit = evaluate("checkout", False, user_ctx("u1", email="bob@feathq.com"), df)
+    assert hit.value is True
+    miss = evaluate("checkout", False, user_ctx("u2", email="bob@other.com"), df)
+    assert miss.value is False
+
+
+def test_semver_gte():
+    flag = bool_flag(
+        rules=[
+            RuleSpec(
+                id="r1",
+                bucketingContextKindKey=None,
+                variationId=TRUE_VAR.id,
+                rollout=None,
+                groups=[
+                    ConditionGroupSpec(
+                        conditions=[
+                            ConditionSpec(
+                                attributePath="user.app_version",
+                                operator="semver_gte",
+                                values=["1.2.0"],
+                            )
+                        ]
+                    )
+                ],
+            )
+        ]
+    )
+    df = make_df(flags={"checkout": flag})
+    newer = evaluate("checkout", False, user_ctx("u1", app_version="1.5.0"), df)
+    assert newer.value is True
+    older = evaluate("checkout", False, user_ctx("u2", app_version="1.1.5"), df)
+    assert older.value is False
+
+
+def test_missing_flag_returns_error():
+    df = make_df()
+    r = evaluate("missing", "fallback", user_ctx("u1"), df)
+    assert r.reason == Reason.ERROR
+    assert r.value == "fallback"