fireweave 0.1.0__py3-none-any.whl

fireweave/__init__.py

@@ -0,0 +1,126 @@
+"""Fireweave SDK for Python (spec v0.1.0).
+
+Core installs with zero runtime dependencies. Optional extras:
+
+- ``fireweave[posthog]`` — PostHog backend adapter (``fireweave.adapters.posthog``)
+- ``fireweave[openfeature]`` — OpenFeature provider (``fireweave.openfeature``)
+
+Quick start (in-memory, offline)::
+
+    from fireweave import FireweaveClient, FireweaveRuntime, InMemoryAdapter
+
+    adapter = InMemoryAdapter({"my-flag": {"type": "boolean", "enabled": True,
+                                           "variant": "on", "value": True}})
+    runtime = FireweaveRuntime(adapter)
+    runtime.initialize()
+    client = FireweaveClient(runtime)
+    client.control_points.get_boolean_value("my-flag", False)
+    client.shutdown()
+
+There are no hidden global clients: everything is constructed explicitly and
+injectable for tests.
+"""
+
+from ._version import SPEC_VERSION, __version__
+from .adapters import (
+    BackendAdapter,
+    FlagResolution,
+    FireweaveLocalAdapter,
+    FireweaveRemoteAdapter,
+    InMemoryAdapter,
+    RegisterTargetOptions,
+    RegisterTargetResult,
+)
+from .capabilities import CANONICAL_CAPABILITIES, CapabilityRegistry
+from .client import (
+    CapabilityResult,
+    ExposureResult,
+    FireweaveClient,
+    FlushResult,
+    ReleaseContext,
+    ReleaseResult,
+    SignalResult,
+)
+from .config import DEFAULT_ALLOWED_HOSTS, FireweaveConfig
+from .context import ContextLimits, EvaluationContext, merge_contexts, validate_context
+from .decision import Decision, Reason
+from .errors import (
+    AlreadyClosedError,
+    AuthenticationError,
+    AuthorizationError,
+    BackendUnavailableError,
+    ConfigurationError,
+    ErrorKind,
+    FireweaveError,
+    FlagNotFoundError,
+    InternalError,
+    InvalidContextError,
+    MalformedResponseError,
+    NetworkError,
+    NotReadyError,
+    RateLimitedError,
+    TargetingKeyMissingError,
+    TimeoutError_,
+    TypeMismatchError,
+    UnsupportedCapabilityError,
+)
+from .runtime import EvaluationOptions, FireweaveRuntime, LifecycleState
+from .types import FlagType, JsonValue
+
+__all__ = [
+    "__version__",
+    "SPEC_VERSION",
+    # runtime / client
+    "FireweaveClient",
+    "FireweaveRuntime",
+    "FireweaveConfig",
+    "DEFAULT_ALLOWED_HOSTS",
+    "LifecycleState",
+    "EvaluationOptions",
+    # adapters
+    "BackendAdapter",
+    "FlagResolution",
+    "InMemoryAdapter",
+    "FireweaveLocalAdapter",
+    "FireweaveRemoteAdapter",
+    "RegisterTargetOptions",
+    "RegisterTargetResult",
+    # context / decisions
+    "ContextLimits",
+    "EvaluationContext",
+    "merge_contexts",
+    "validate_context",
+    "Decision",
+    "Reason",
+    "FlagType",
+    "JsonValue",
+    # capabilities
+    "CANONICAL_CAPABILITIES",
+    "CapabilityRegistry",
+    # extension results
+    "ReleaseContext",
+    "ReleaseResult",
+    "ExposureResult",
+    "FlushResult",
+    "SignalResult",
+    "CapabilityResult",
+    # errors
+    "ErrorKind",
+    "FireweaveError",
+    "NotReadyError",
+    "FlagNotFoundError",
+    "TypeMismatchError",
+    "InvalidContextError",
+    "TargetingKeyMissingError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "RateLimitedError",
+    "TimeoutError_",
+    "NetworkError",
+    "BackendUnavailableError",
+    "MalformedResponseError",
+    "UnsupportedCapabilityError",
+    "ConfigurationError",
+    "AlreadyClosedError",
+    "InternalError",
+]

fireweave/_version.py

@@ -0,0 +1,5 @@
+"""Package version constants."""
+
+__version__ = "0.1.0"
+SPEC_VERSION = "0.1.0"
+OPENFEATURE_SPEC_FLOOR = "0.8.0"

fireweave/adapters/__init__.py

@@ -0,0 +1,23 @@
+"""Backend adapters: protocol, in-memory, local, remote (default), PostHog (optional)."""
+
+from .base import (
+    BackendAdapter,
+    FlagResolution,
+    RegisterTargetOptions,
+    RegisterTargetResult,
+    TargetKind,
+)
+from .local import FireweaveLocalAdapter
+from .memory import InMemoryAdapter
+from .remote import FireweaveRemoteAdapter
+
+__all__ = [
+    "BackendAdapter",
+    "FlagResolution",
+    "RegisterTargetOptions",
+    "RegisterTargetResult",
+    "TargetKind",
+    "InMemoryAdapter",
+    "FireweaveLocalAdapter",
+    "FireweaveRemoteAdapter",
+]

fireweave/adapters/base.py

@@ -0,0 +1,117 @@
+"""BackendAdapter protocol and vendor-neutral resolution record.
+
+Adapters translate a vendor backend (PostHog, in-memory fixtures, ...) into
+:class:`FlagResolution` records. No vendor types cross this boundary — the
+runtime and public API only ever see Fireweave-owned shapes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, Optional, Protocol, runtime_checkable
+
+from ..context import EvaluationContext
+from ..errors import FireweaveError
+from ..types import JsonValue
+
+__all__ = [
+    "BackendAdapter",
+    "FlagResolution",
+    "TargetKind",
+    "RegisterTargetOptions",
+    "RegisterTargetResult",
+]
+
+TargetKind = Literal["user", "device"]
+
+
+@dataclass(frozen=True)
+class RegisterTargetOptions:
+    """Options for ``POST /v1/targets/register`` (spec/remote-register-target).
+
+    Omitted fields are left off the wire rather than sent as null/default —
+    the server defaults ``kind`` to ``user`` when absent.
+    """
+
+    kind: Optional[TargetKind] = None
+    properties: Optional[Dict[str, JsonValue]] = None
+    environment: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class RegisterTargetResult:
+    """Outcome of target registration.
+
+    ``ok=False`` means the target was NOT registered — rules that depend on its
+    properties will not match until a later attempt succeeds. Callers in a
+    login path normally ignore this; a careful caller logs it.
+    """
+
+    ok: bool
+    error: Optional[FireweaveError] = None
+
+
+@dataclass(frozen=True)
+class FlagResolution:
+    """Vendor-neutral outcome of resolving one flag.
+
+    ``matched`` is False when targeting conditions did not select the caller
+    (the runtime then serves the caller default with reason DEFAULT).
+    ``fireweave_reason`` lets adapters force a canonical reason (e.g. SPLIT).
+    """
+
+    value: JsonValue
+    variant: Optional[str] = None
+    enabled: bool = True
+    matched: bool = True
+    version: Optional[int] = None
+    vendor_flag_id: Optional[int] = None
+    reason_code: Optional[str] = None
+    condition_index: Optional[int] = None
+    payload: Optional[JsonValue] = None
+    fireweave_reason: Optional[str] = None
+    from_cache: bool = False
+    quota_limited: bool = False
+    extra_metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class BackendAdapter(Protocol):
+    """Protocol every Fireweave backend adapter implements.
+
+    ``resolve`` raises a :class:`fireweave.errors.FireweaveError` subtype on
+    failure (FlagNotFound, Network, Timeout, ...); the runtime converts errors
+    into default-valued decisions — evaluation APIs never propagate them.
+    """
+
+    def initialize(self) -> None:
+        """Bring the backend up; raise FireweaveError on fatal config."""
+
+    def resolve(self, flag_key: str, context: EvaluationContext) -> FlagResolution:
+        """Resolve one flag against a validated, merged context."""
+
+    def shutdown(self, timeout_ms: int) -> None:
+        """Deterministically flush and release resources within ``timeout_ms``.
+
+        Idempotent; must never block past the deadline.
+        """
+
+
+# Optional adapter surface (duck-typed, ruling 17 / capabilities matrix):
+#
+# - ``backend_name: str`` — "fireweave" | "posthog" | "inmemory" | "none" | "other"
+#   (spec/capabilities.schema.json runtime.backend).
+# - ``runtime_features() -> Dict[str, bool]`` — adapter-dependent runtime
+#   capability booleans merged into ``capabilities.get()``.
+# - ``register_target(targeting_key, options) -> RegisterTargetResult`` —
+#   durable identity registration (``POST /v1/targets/register``). Returns
+#   ``ok=False`` rather than raising — registration sits in login paths.
+# - ``send_exposures(events: list) -> None`` — telemetry sink for flushed
+#   exposure events.
+# - ``deliver_signal(signal: Dict) -> None`` — telemetry sink for recorded
+#   signals.
+# - ``deliver_release(event: Dict) -> None`` — telemetry sink for release
+#   transitions.
+#
+# All sink methods are best-effort: implementations swallow vendor errors —
+# telemetry loss must never affect callers.

fireweave/adapters/local.py

@@ -0,0 +1,76 @@
+"""Local development adapter — the DEV substrate for a scaffolded harness.
+
+Counterpart to :class:`FireweaveRemoteAdapter`: prod evaluates control points
+against fw-server; dev evaluates them here, in-process, with no network and no
+credentials. Because it satisfies the same :class:`BackendAdapter` port, the
+dev branch of a harness runs through the same :class:`FireweaveRuntime` as
+prod — inheriting identical lifecycle gating and context canonicalization.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Mapping, Optional
+
+from ..context import EvaluationContext
+from ..errors import FlagNotFoundError
+from .base import FlagResolution
+
+__all__ = ["FireweaveLocalAdapter"]
+
+
+class FireweaveLocalAdapter:
+    """In-process boolean overrides for local development.
+
+    Resolution policy:
+
+    - a key present in ``dev_flags`` resolves to its mapped value with reason
+      ``STATIC``;
+    - every other key raises :class:`FlagNotFoundError`, which the runtime
+      turns into an ERROR decision. :func:`make_fireweave_local_provider`
+      rewrites that single outcome to a clean DEFAULT for the OpenFeature path.
+    """
+
+    backend_name = "other"
+
+    def __init__(self, dev_flags: Optional[Mapping[str, bool]] = None) -> None:
+        self._dev_flags: Dict[str, bool] = dict(dev_flags or {})
+        self._closed = False
+
+    def initialize(self) -> None:
+        self._closed = False
+
+    def resolve(self, flag_key: str, context: EvaluationContext) -> FlagResolution:
+        # A ``dev_flags`` hit reports ``enabled=True`` alongside reason STATIC.
+        # Reporting ``enabled=False`` for an override of ``False`` would make
+        # the runtime label the decision DISABLED — "switched off upstream" —
+        # not what a local override expresses.
+        #
+        # Values are always boolean, so reading an overridden key as a string
+        # or number yields TYPE_MISMATCH rather than silently defaulting.
+        del context  # unused; kept for BackendAdapter signature parity
+        if flag_key not in self._dev_flags:
+            raise FlagNotFoundError()
+        override = self._dev_flags[flag_key]
+        return FlagResolution(
+            value=override,
+            variant="on" if override else "off",
+            enabled=True,
+            matched=True,
+            fireweave_reason="STATIC",
+        )
+
+    def shutdown(self, timeout_ms: int) -> None:
+        del timeout_ms
+        self._closed = True
+
+    def runtime_features(self) -> Dict[str, bool]:
+        return {
+            "remoteEvaluation": False,
+            "localEvaluation": True,
+            "localOnly": True,
+            # No exposure sink exists locally; claiming otherwise would make
+            # capabilities.get() advertise emission that silently goes nowhere.
+            "exposureEmission": False,
+            "sideEffectFreeReads": True,
+            "groupAnalytics": False,
+        }

fireweave/adapters/memory.py

@@ -0,0 +1,115 @@
+"""Deterministic in-memory adapter (fixture-shaped flag definitions).
+
+Resolution is purely definition-driven — no hashing, no percentage bucketing.
+A flag definition is a dict in the shape used by ``contracts/`` fixtures:
+
+.. code-block:: python
+
+    {
+        "type": "boolean",            # boolean|string|integer|float|object
+        "enabled": True,
+        "variant": "on",
+        "value": True,
+        "payload": {...},              # optional
+        "reason": {"code": "condition_match", "condition_index": 0, ...},
+        "metadata": {"version": 1, "id": 42},
+        "fireweaveReason": "SPLIT",   # optional canonical reason override
+        "fromCache": False,            # optional stale-cache marker
+        "matchTargetingKey": "...",   # optional deterministic conditions
+        "matchAttribute": {...},
+        "matchPerson": {...},
+        "matchGroups": {...},
+    }
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Dict, Mapping, Optional
+
+from ..context import EvaluationContext
+from ..errors import FlagNotFoundError
+from .base import FlagResolution
+
+__all__ = ["InMemoryAdapter"]
+
+
+class InMemoryAdapter:
+    """Fixture-driven adapter; thread-safe; supports live flag replacement."""
+
+    backend_name = "inmemory"
+
+    def __init__(self, flags: Optional[Mapping[str, Dict[str, Any]]] = None) -> None:
+        self._lock = threading.Lock()
+        self._flags: Dict[str, Dict[str, Any]] = dict(flags or {})
+        self._closed = False
+
+    def initialize(self) -> None:
+        with self._lock:
+            self._closed = False
+
+    def set_flags(self, flags: Mapping[str, Dict[str, Any]]) -> None:
+        with self._lock:
+            self._flags = dict(flags)
+
+    def resolve(self, flag_key: str, context: EvaluationContext) -> FlagResolution:
+        with self._lock:
+            definition = self._flags.get(flag_key)
+        if definition is None:
+            raise FlagNotFoundError()
+
+        matched = self._conditions_match(definition, context)
+        reason = definition.get("reason") or {}
+        metadata = definition.get("metadata") or {}
+        return FlagResolution(
+            value=definition.get("value"),
+            variant=definition.get("variant"),
+            enabled=bool(definition.get("enabled", True)),
+            matched=matched,
+            version=metadata.get("version"),
+            vendor_flag_id=metadata.get("id"),
+            reason_code=reason.get("code"),
+            condition_index=reason.get("condition_index"),
+            payload=definition.get("payload"),
+            fireweave_reason=definition.get("fireweaveReason"),
+            from_cache=bool(definition.get("fromCache", False)),
+        )
+
+    @staticmethod
+    def _conditions_match(
+        definition: Mapping[str, Any], context: EvaluationContext
+    ) -> bool:
+        """All present match* conditions must hold (deterministic equality)."""
+        expected_key = definition.get("matchTargetingKey")
+        if expected_key is not None and context.targeting_key != expected_key:
+            return False
+
+        attrs = dict(context.attributes)
+
+        for cond_field in ("matchAttribute", "matchPerson"):
+            conditions = definition.get(cond_field)
+            if conditions:
+                for key, expected in conditions.items():
+                    if attrs.get(key) != expected:
+                        return False
+
+        match_groups = definition.get("matchGroups")
+        if match_groups:
+            groups = context.groups
+            for group_type, expected in match_groups.items():
+                if groups.get(group_type) != expected:
+                    return False
+        return True
+
+    def shutdown(self, timeout_ms: int) -> None:
+        with self._lock:
+            self._closed = True
+
+    def runtime_features(self) -> Dict[str, bool]:
+        """Adapter runtime features merged into ``capabilities.get()``."""
+        return {
+            "remoteEvaluation": False,
+            "localEvaluation": True,
+            "exposureEmission": False,
+            "sideEffectFreeReads": True,
+        }