fireweave 0.1.0__tar.gz

fireweave-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fireweave AI, Inc.
+
+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.

fireweave-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: fireweave
+Version: 0.1.0
+Summary: Fireweave polyglot SDK for Python — OpenFeature-compatible, server-first flag evaluation and release-safety extensions (spec v0.1.0).
+Author: Fireweave AI, Inc.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/FireWeave-HQ/fireweave-sdk
+Project-URL: Documentation, https://github.com/FireWeave-HQ/fireweave-sdk/tree/master/docs
+Project-URL: Repository, https://github.com/FireWeave-HQ/fireweave-sdk
+Project-URL: Issues, https://github.com/FireWeave-HQ/fireweave-sdk/issues
+Project-URL: Changelog, https://github.com/FireWeave-HQ/fireweave-sdk/blob/master/CHANGELOG.md
+Project-URL: Source, https://github.com/FireWeave-HQ/fireweave-sdk/tree/master/sdks/python
+Keywords: feature-flags,openfeature,posthog,rollout,release
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: posthog
+Requires-Dist: posthog==7.31.0; extra == "posthog"
+Provides-Extra: openfeature
+Requires-Dist: openfeature-sdk<0.11,>=0.10.0; extra == "openfeature"
+Provides-Extra: dev
+Requires-Dist: posthog==7.31.0; extra == "dev"
+Requires-Dist: openfeature-sdk<0.11,>=0.10.0; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# fireweave (Python SDK)
+
+Fireweave polyglot SDK for Python — OpenFeature-compatible, server-first flag
+evaluation with release-safety extensions (spec v0.1.0).
+
+- **Core**: zero runtime dependencies (`fireweave` + `InMemoryAdapter`).
+- **Extras**: `fireweave[posthog]` (PostHog backend, `posthog==7.31.0`),
+  `fireweave[openfeature]` (OpenFeature provider, `openfeature-sdk>=0.10,<0.11`).
+
+## Quick start (offline, in-memory)
+
+```python
+from fireweave import FireweaveClient, FireweaveRuntime, InMemoryAdapter
+
+adapter = InMemoryAdapter({
+    "new-checkout": {"type": "boolean", "enabled": True, "variant": "on", "value": True},
+})
+runtime = FireweaveRuntime(adapter)
+runtime.initialize()
+client = FireweaveClient(runtime)
+
+assert client.flags.get_boolean_value("new-checkout", False) is True
+client.shutdown()
+```
+
+## OpenFeature
+
+```python
+from openfeature import api
+from fireweave import FireweaveRuntime, InMemoryAdapter
+from fireweave.openfeature import FireweaveProvider
+
+api.set_provider(FireweaveProvider(FireweaveRuntime(InMemoryAdapter({...}))))
+client = api.get_client()
+client.get_boolean_value("new-checkout", False)
+```
+
+## PostHog backend
+
+```python
+from fireweave import FireweaveConfig, FireweaveRuntime, FireweaveClient
+from fireweave.adapters.posthog import PostHogAdapter
+
+config = FireweaveConfig(project_api_key="phc_...", host="https://us.i.posthog.com")
+runtime = FireweaveRuntime(PostHogAdapter(config=config), config)
+runtime.initialize(backend_required=True)
+client = FireweaveClient(runtime)
+```
+
+## Sync / async
+
+The core is a thread-safe **sync** runtime; asyncio servers use
+`fireweave.aio.AsyncFireweaveClient`, which offloads calls via
+`asyncio.to_thread`. See `docs/adr/0004` and the module docstring.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest                                   # unit + conformance tests
+.venv/bin/python conformance/run_conformance.py    # normalized results JSON
+```

fireweave-0.1.0/README.md

@@ -0,0 +1,62 @@
+# fireweave (Python SDK)
+
+Fireweave polyglot SDK for Python — OpenFeature-compatible, server-first flag
+evaluation with release-safety extensions (spec v0.1.0).
+
+- **Core**: zero runtime dependencies (`fireweave` + `InMemoryAdapter`).
+- **Extras**: `fireweave[posthog]` (PostHog backend, `posthog==7.31.0`),
+  `fireweave[openfeature]` (OpenFeature provider, `openfeature-sdk>=0.10,<0.11`).
+
+## Quick start (offline, in-memory)
+
+```python
+from fireweave import FireweaveClient, FireweaveRuntime, InMemoryAdapter
+
+adapter = InMemoryAdapter({
+    "new-checkout": {"type": "boolean", "enabled": True, "variant": "on", "value": True},
+})
+runtime = FireweaveRuntime(adapter)
+runtime.initialize()
+client = FireweaveClient(runtime)
+
+assert client.flags.get_boolean_value("new-checkout", False) is True
+client.shutdown()
+```
+
+## OpenFeature
+
+```python
+from openfeature import api
+from fireweave import FireweaveRuntime, InMemoryAdapter
+from fireweave.openfeature import FireweaveProvider
+
+api.set_provider(FireweaveProvider(FireweaveRuntime(InMemoryAdapter({...}))))
+client = api.get_client()
+client.get_boolean_value("new-checkout", False)
+```
+
+## PostHog backend
+
+```python
+from fireweave import FireweaveConfig, FireweaveRuntime, FireweaveClient
+from fireweave.adapters.posthog import PostHogAdapter
+
+config = FireweaveConfig(project_api_key="phc_...", host="https://us.i.posthog.com")
+runtime = FireweaveRuntime(PostHogAdapter(config=config), config)
+runtime.initialize(backend_required=True)
+client = FireweaveClient(runtime)
+```
+
+## Sync / async
+
+The core is a thread-safe **sync** runtime; asyncio servers use
+`fireweave.aio.AsyncFireweaveClient`, which offloads calls via
+`asyncio.to_thread`. See `docs/adr/0004` and the module docstring.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest                                   # unit + conformance tests
+.venv/bin/python conformance/run_conformance.py    # normalized results JSON
+```

fireweave-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fireweave"
+version = "0.1.0"
+description = "Fireweave polyglot SDK for Python — OpenFeature-compatible, server-first flag evaluation and release-safety extensions (spec v0.1.0)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Fireweave AI, Inc." }]
+keywords = ["feature-flags", "openfeature", "posthog", "rollout", "release"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "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",
+    "Typing :: Typed",
+]
+# Core has NO runtime dependencies: the OpenFeature provider and the PostHog
+# adapter are optional integrations behind extras. `import fireweave` plus the
+# InMemory adapter work with the standard library only.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/FireWeave-HQ/fireweave-sdk"
+Documentation = "https://github.com/FireWeave-HQ/fireweave-sdk/tree/master/docs"
+Repository = "https://github.com/FireWeave-HQ/fireweave-sdk"
+Issues = "https://github.com/FireWeave-HQ/fireweave-sdk/issues"
+Changelog = "https://github.com/FireWeave-HQ/fireweave-sdk/blob/master/CHANGELOG.md"
+"Source" = "https://github.com/FireWeave-HQ/fireweave-sdk/tree/master/sdks/python"
+
+[project.optional-dependencies]
+# ADR-0002 pin: PostHog snapshot API (`evaluate_flags`) — exact pin to absorb
+# the in-flight /flags migration.
+posthog = ["posthog==7.31.0"]
+# Pre-1.0 OpenFeature SDK: pin below 0.11 (decision brief §3 / ADR-0003).
+openfeature = ["openfeature-sdk>=0.10.0,<0.11"]
+dev = [
+    "posthog==7.31.0",
+    "openfeature-sdk>=0.10.0,<0.11",
+    "pytest>=8",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+fireweave = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

fireweave-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fireweave-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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,
+        }