fireweave 2.3.0__tar.gz → 3.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. fireweave-3.0.0/PKG-INFO +234 -0
  2. fireweave-3.0.0/README.md +205 -0
  3. {fireweave-2.3.0 → fireweave-3.0.0}/pyproject.toml +1 -1
  4. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/__init__.py +2 -2
  5. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/application/client.py +23 -48
  6. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/application/ports.py +6 -6
  7. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/application/runtime.py +61 -18
  8. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/decision.py +2 -2
  9. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/errors.py +51 -15
  10. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/types.py +3 -3
  11. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/validation.py +13 -8
  12. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/adapters/local.py +5 -5
  13. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/adapters/memory.py +6 -6
  14. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/adapters/remote.py +42 -13
  15. fireweave-3.0.0/src/fireweave/start/__init__.py +46 -0
  16. fireweave-3.0.0/src/fireweave/start/_build_info.py +64 -0
  17. fireweave-3.0.0/src/fireweave/start/_control_points.py +107 -0
  18. fireweave-3.0.0/src/fireweave/start/_env.py +43 -0
  19. fireweave-3.0.0/src/fireweave/start/_facade.py +228 -0
  20. fireweave-3.0.0/src/fireweave/start/_instance.py +54 -0
  21. fireweave-3.0.0/src/fireweave/start/_names.py +48 -0
  22. fireweave-3.0.0/src/fireweave/start/_resolve.py +242 -0
  23. fireweave-3.0.0/src/fireweave/start/_state.py +624 -0
  24. fireweave-3.0.0/src/fireweave.egg-info/PKG-INFO +234 -0
  25. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave.egg-info/SOURCES.txt +19 -1
  26. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_architecture_layers.py +19 -5
  27. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_concurrency.py +2 -2
  28. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_control_points.py +3 -23
  29. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_control_points_surface.py +5 -5
  30. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_errors.py +7 -7
  31. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_init_fireweave.py +4 -4
  32. fireweave-3.0.0/tests/test_input_guards.py +153 -0
  33. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_lifecycle.py +1 -1
  34. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_local_register_target.py +2 -2
  35. fireweave-3.0.0/tests/test_redaction_contract.py +57 -0
  36. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_remote_adapter.py +10 -10
  37. fireweave-3.0.0/tests/test_remote_no_redirects.py +128 -0
  38. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_runtime_evaluation.py +9 -9
  39. fireweave-3.0.0/tests/test_start_contracts.py +217 -0
  40. fireweave-3.0.0/tests/test_start_facade.py +504 -0
  41. fireweave-3.0.0/tests/test_start_guards.py +182 -0
  42. fireweave-3.0.0/tests/test_start_remote.py +103 -0
  43. fireweave-3.0.0/tests/test_start_remote_failures.py +149 -0
  44. fireweave-3.0.0/tests/test_start_resolve.py +270 -0
  45. fireweave-2.3.0/PKG-INFO +0 -139
  46. fireweave-2.3.0/README.md +0 -110
  47. fireweave-2.3.0/src/fireweave.egg-info/PKG-INFO +0 -139
  48. {fireweave-2.3.0 → fireweave-3.0.0}/LICENSE +0 -0
  49. {fireweave-2.3.0 → fireweave-3.0.0}/setup.cfg +0 -0
  50. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/_version.py +0 -0
  51. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/application/__init__.py +0 -0
  52. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/application/mode.py +0 -0
  53. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/__init__.py +0 -0
  54. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/context.py +0 -0
  55. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/target.py +0 -0
  56. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/__init__.py +0 -0
  57. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/adapters/__init__.py +0 -0
  58. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/hosts.py +0 -0
  59. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/py.typed +0 -0
  60. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave.egg-info/dependency_links.txt +0 -0
  61. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave.egg-info/requires.txt +0 -0
  62. {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave.egg-info/top_level.txt +0 -0
  63. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_conformance.py +0 -0
  64. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_context.py +0 -0
  65. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_hosts.py +0 -0
  66. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_no_vendor_leak.py +0 -0
  67. {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_register_target.py +0 -0
@@ -0,0 +1,234 @@
1
+ Metadata-Version: 2.4
2
+ Name: fireweave
3
+ Version: 3.0.0
4
+ Summary: Fireweave polyglot SDK for Python — server-first control-point evaluation and target registration (spec v0.1.0).
5
+ Author: Fireweave AI, Inc.
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/FireWeave-HQ/fireweave-sdk
8
+ Project-URL: Documentation, https://github.com/FireWeave-HQ/fireweave-sdk/tree/master/docs
9
+ Project-URL: Repository, https://github.com/FireWeave-HQ/fireweave-sdk
10
+ Project-URL: Issues, https://github.com/FireWeave-HQ/fireweave-sdk/issues
11
+ Project-URL: Changelog, https://github.com/FireWeave-HQ/fireweave-sdk/blob/master/CHANGELOG.md
12
+ Project-URL: Source, https://github.com/FireWeave-HQ/fireweave-sdk/tree/master/sdks/python
13
+ Keywords: feature-flags,rollout,release,control-points
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: >=3.10
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest>=8; extra == "dev"
28
+ Dynamic: license-file
29
+
30
+ # fireweave (Python SDK)
31
+
32
+ Fireweave release-engineering SDK for Python — **control points** and target
33
+ registration, the two v1 capabilities (spec/control-points.md "Scope of v1").
34
+
35
+ - **Zero runtime dependencies.**
36
+ - **The core SDK reads no environment variables** — every option is an explicit
37
+ argument to `init_fireweave` (spec/modes.md). The opt-in start profile,
38
+ `fireweave.start`, is the one documented exception
39
+ ([ADR-0012](../../docs/adr/0012-start-profile.md)).
40
+ - **No vendor SDK, key, or hostname in your process.** Applications hold a
41
+ Fireweave project key and talk to fw-server; which backend fw-server
42
+ forwards to is fw-server's concern.
43
+
44
+ ## Quick start (one line: the start profile)
45
+
46
+ Most apps need only this ([ADR-0012](../../docs/adr/0012-start-profile.md)). One small module and one call:
47
+
48
+ ```python
49
+ # src/fireweave_setup/control_points.py: every control point the app reads, with its local value
50
+ from fireweave.start import define_control_points
51
+
52
+ control_points = define_control_points({
53
+ "new-checkout": {"local": True, "description": "One-page checkout"}, # served only in local mode
54
+ })
55
+ ```
56
+
57
+ ```python
58
+ # the process entrypoint, FIRST thing: main.py, wsgi.py + asgi.py, create_app(), the Celery app module
59
+ from fireweave.start import start
60
+ from fireweave_setup.control_points import control_points
61
+
62
+ start(control_points=control_points)
63
+ ```
64
+
65
+ ```python
66
+ # any call site
67
+ from fireweave import EvaluationContext
68
+ from fireweave.start import fw
69
+
70
+ # @fireweave-controlpoint new-checkout
71
+ if fw.control_points.get_boolean_value("new-checkout", False, EvaluationContext(user_id)):
72
+ ...
73
+ fw.identify(user_id, {"plan": user.plan}) # at sign-in
74
+ fw.control_points.get_boolean_value("nightly-reindex", False, EvaluationContext(fw.instance_key())) # server as subject
75
+ ```
76
+
77
+ Deployed environments set one variable, `FIREWEAVE_KEY` (the project key, `project-api-key_…`).
78
+ Local development needs nothing when `FIREWEAVE_ENV` (or `APP_ENV`) is `development`, `dev`,
79
+ `local` or `test`.
80
+
81
+ `fw.control_points` has exactly the core's nine methods, with the same names and arguments;
82
+ contexts are `EvaluationContext` as everywhere else. Reads are synchronous (one blocking HTTP call
83
+ each in remote mode); in an `async def` handler use
84
+ `await asyncio.to_thread(lambda: fw.control_points.get_boolean_value("new-checkout", False, ctx))`.
85
+ Never pass an unguarded `str(user.id)`: Django's `AnonymousUser.id` is `None`, and `"None"` would
86
+ be one targeting key shared by every anonymous visitor.
87
+
88
+ ### Options and overrides
89
+
90
+ Every value resolves as: `start()` keyword option, then env var, then legacy name (warns once),
91
+ then default. Empty and whitespace-only values count as unset.
92
+
93
+ | Option | Env var | Default | What it does |
94
+ | --- | --- | --- | --- |
95
+ | `control_points` | — | `{}` | Local values per control point. Ignored in remote mode. |
96
+ | `mode` | — | inferred | `'remote'` or `'local'`. Overrides inference. `'remote'` without a key is a start error; `'local'` ignores a key, with one warning. |
97
+ | `environment` | `FIREWEAVE_ENV`, `APP_ENV` | — | Environment name used for inference when there is no key and no `mode`. Pass your own, e.g. `environment=settings.DEPLOY_STAGE`. `ENVIRONMENT`, `ENV`, `NODE_ENV` and the retired `FW_ENV` are not read. |
98
+ | `url` | `FIREWEAVE_URL` (legacy `FW_API_URL`, `FW_ATTEST_URL`) | from the installed version | A pre-release or dev release calls `staging-app-server.fireweave.ai`; any other calls `app-server.fireweave.ai`. Staging builds are `X.Y.ZrcN` on PyPI: install one with `pip install fireweave==X.Y.ZrcN` (no extra index; pip skips pre-releases unless pinned). Set it for a self-hosted or local fw-server: https is required except on localhost, and the host allowlist follows it. |
99
+ | `key` | `FIREWEAVE_KEY` (legacy `FW_PROJECT_API_KEY`) | — | Project key. Pass it to read from your own secret store. Browser keys (`fw_public_…`), analytics vendor keys and org or CLI tokens are rejected at start. |
100
+ | `instance_id` | `FIREWEAVE_INSTANCE_ID` | `inst_` + hash of the host name | Value of `fw.instance_key()`. Nothing is written to disk. |
101
+ | `env` | — | `os.environ` | Read values from this mapping instead of the environment (tests). |
102
+ | `log` | — | the `fireweave.start` logger | A callable taking one line, or a `logging.Logger`. Where `[fireweave]` lines go. |
103
+
104
+ `fireweave.start.SDK_VERSION` and `SDK_CHANNEL` show which version and channel are installed.
105
+
106
+ **Mode rule.** `mode` wins. Otherwise: a key means remote. No key and a development environment
107
+ name means local. Anything else (including no environment name at all) raises
108
+ `ConfigurationError` at `start()`, naming `FIREWEAVE_KEY` and where the environment name was
109
+ looked for, so a deploy that forgot its key fails instead of silently serving defaults.
110
+
111
+ **One per process.** `start()` is idempotent: a second call with the same configuration does
112
+ nothing, a different one raises `ConfigurationError`. It does no network I/O and starts no
113
+ thread, so it is ready when it returns. Call it in every process entrypoint; a forked worker
114
+ (gunicorn `--preload`, Celery prefork) rebuilds its client on its own. A read before any `start()`
115
+ starts FireWeave immediately from the environment alone (one warning); the first explicit
116
+ `start()` afterwards replaces that once, with a warning, and shuts the provisional client down
117
+ (reads in flight move to the new one). Processes that never run your entrypoint
118
+ (`manage.py`, spawned children) get the environment-only start, so prefer `FIREWEAVE_*`
119
+ variables to options for anything every process needs.
120
+
121
+ **Reads never raise.** If start fails, reads return your default (`evaluate` and the `*_details`
122
+ forms return an `ERROR` decision with the `Configuration` error) and `fw.identify()` returns
123
+ `ok=False`. In local mode, reading a key that is not in your control points returns the default and
124
+ warns once, naming the file that declared them.
125
+
126
+ **Debugging.** `fw.status()` reports what start decided: `state`, `started_by`, `mode` and
127
+ `mode_source`, `channel`, `sdk_version`, `host`, `endpoint_source`, `key_source`, `environment`,
128
+ `flag_count`, `error` and `last_error_kind`. It never includes the key. When fw-server refuses the
129
+ key (401/403), rate-limits it (429) or cannot be reached (network error, timeout, 5xx or a
130
+ redirect, which is never followed), reads serve their defaults, so a revoked key would otherwise
131
+ look like a rollout at 0%. Each of those kinds logs **one** line per process through your `log`
132
+ sink (default: the `fireweave.start` logger), naming the key's source (`FIREWEAVE_KEY`,
133
+ `start(key=...)`) or the endpoint's, and the host, never the key; `last_error_kind` keeps the
134
+ latest kind (`Authentication`, `Authorization`, `RateLimited`, `Network`, `Timeout`,
135
+ `BackendUnavailable`). `fw.client()` is the core `FireweaveClient` for anything the facade does not
136
+ cover (do not cache it: the first explicit `start()` after a read-triggered one shuts the
137
+ provisional client down); `fw.shutdown()` flushes and closes, and a later `start()` begins fresh.
138
+ Tests call `fireweave.start.reset_for_tests()` between cases.
139
+
140
+ ## Quick start (production path)
141
+
142
+ ```python
143
+ from fireweave import RegisterTargetOptions, init_fireweave, EvaluationContext
144
+
145
+ # mode is required and never inferred (spec/modes.md); api_key/api_url are
146
+ # explicit options — the SDK reads no environment variables.
147
+ client = init_fireweave(
148
+ mode="remote",
149
+ api_key="project-api-key_...",
150
+ api_url="https://app-server.fireweave.ai",
151
+ )
152
+
153
+ # Once per login: the durable facts your targeting rules match on.
154
+ client.register_target(
155
+ "user_42", RegisterTargetOptions(kind="user", properties={"plan": "pro"})
156
+ )
157
+
158
+ # Per request.
159
+ enabled = client.control_points.get_boolean_value(
160
+ "new-checkout", False, EvaluationContext("user_42")
161
+ )
162
+
163
+ client.shutdown()
164
+ ```
165
+
166
+ ## Quick start (offline, in-memory)
167
+
168
+ ```python
169
+ from fireweave import FireweaveClient, FireweaveRuntime, InMemoryAdapter
170
+
171
+ adapter = InMemoryAdapter({
172
+ "new-checkout": {"enabled": True, "variant": "on", "value": True},
173
+ })
174
+ runtime = FireweaveRuntime(adapter)
175
+ runtime.initialize()
176
+ client = FireweaveClient(runtime)
177
+
178
+ assert client.control_points.get_boolean_value("new-checkout", False) is True
179
+ client.shutdown()
180
+ ```
181
+
182
+ ## Quick start (local dev — no network, no credentials)
183
+
184
+ ```python
185
+ from fireweave import init_fireweave
186
+
187
+ client = init_fireweave(mode="local", local={"control_points": {"new-checkout": True}})
188
+ client.control_points.get_boolean_value("new-checkout", False) # -> True
189
+ client.register_target("user_42") # recorded in-process + traced; nothing sent
190
+ client.shutdown()
191
+ ```
192
+
193
+ ## The nine methods
194
+
195
+ `get_boolean_value` / `get_string_value` / `get_number_value` /
196
+ `get_object_value`, their `*_details` counterparts (return the whole
197
+ `Decision` — `reason`, `error_kind`, `control_point_metadata`, ... — instead of
198
+ just the value), and the general-form `evaluate`. All nine live under
199
+ `client.control_points`; the `client.flags` alias was removed in 3.0.0
200
+ (ADR-0013).
201
+
202
+ `get_integer_value` is a deprecated alias of `get_number_value` — spec fixes
203
+ the method as **number**, not integer (`Decision.value` is `jsonValue`). It
204
+ still works and delegates straight through; it logs one `DeprecationWarning`
205
+ per process the first time it's called.
206
+
207
+ ## Module layout
208
+
209
+ | Module | Responsibility |
210
+ | --- | --- |
211
+ | `domain/` | Pure types + validation: `errors.py`, `types.py`, `context.py`, `decision.py`, `target.py`, `validation.py`. No I/O, no imports from `application/`/`infrastructure/`. |
212
+ | `application/runtime.py` | Lifecycle state machine, context layering, the evaluation pipeline. Evaluation never raises. |
213
+ | `application/client.py` | `FireweaveClient` — `control_points`, `register_target`, `invoke_capability` (degrades; v1 has no supported capabilities). |
214
+ | `application/mode.py` | `init_fireweave` — the single entry point and sanctioned composition root (the only file allowed to import concrete adapters). |
215
+ | `application/ports.py` | The `BackendAdapter` boundary. |
216
+ | `infrastructure/adapters/remote.py` | `FireweaveRemoteAdapter` — the production backend (`POST /v1/control-points/evaluate`, `POST /v1/targets/register`). |
217
+ | `infrastructure/adapters/local.py` | `FireweaveLocalAdapter` — the dev substrate: seeded boolean overrides, no network. `register_target` records in-process and traces the call. |
218
+ | `infrastructure/adapters/memory.py` | Deterministic fixture-driven adapter for tests. |
219
+ | `infrastructure/hosts.py` | SSRF allowlist (on by default; https required off-loopback). |
220
+ | `start/` | The opt-in start profile (`from fireweave.start import start, fw, define_control_points`). Built on the public `fireweave` API only; `start/_env.py` is the one file that reads the environment or the host name. The core never imports it. |
221
+
222
+ ## Development
223
+
224
+ ```bash
225
+ python -m venv .venv && .venv/bin/pip install -e '.[dev]'
226
+ # or: uv sync
227
+ .venv/bin/pytest # unit tests
228
+ ```
229
+
230
+ `conformance/surface/control-points.surface.json` is the parity gate this package satisfies.
231
+
232
+ ## License
233
+
234
+ [MIT](./LICENSE).
@@ -0,0 +1,205 @@
1
+ # fireweave (Python SDK)
2
+
3
+ Fireweave release-engineering SDK for Python — **control points** and target
4
+ registration, the two v1 capabilities (spec/control-points.md "Scope of v1").
5
+
6
+ - **Zero runtime dependencies.**
7
+ - **The core SDK reads no environment variables** — every option is an explicit
8
+ argument to `init_fireweave` (spec/modes.md). The opt-in start profile,
9
+ `fireweave.start`, is the one documented exception
10
+ ([ADR-0012](../../docs/adr/0012-start-profile.md)).
11
+ - **No vendor SDK, key, or hostname in your process.** Applications hold a
12
+ Fireweave project key and talk to fw-server; which backend fw-server
13
+ forwards to is fw-server's concern.
14
+
15
+ ## Quick start (one line: the start profile)
16
+
17
+ Most apps need only this ([ADR-0012](../../docs/adr/0012-start-profile.md)). One small module and one call:
18
+
19
+ ```python
20
+ # src/fireweave_setup/control_points.py: every control point the app reads, with its local value
21
+ from fireweave.start import define_control_points
22
+
23
+ control_points = define_control_points({
24
+ "new-checkout": {"local": True, "description": "One-page checkout"}, # served only in local mode
25
+ })
26
+ ```
27
+
28
+ ```python
29
+ # the process entrypoint, FIRST thing: main.py, wsgi.py + asgi.py, create_app(), the Celery app module
30
+ from fireweave.start import start
31
+ from fireweave_setup.control_points import control_points
32
+
33
+ start(control_points=control_points)
34
+ ```
35
+
36
+ ```python
37
+ # any call site
38
+ from fireweave import EvaluationContext
39
+ from fireweave.start import fw
40
+
41
+ # @fireweave-controlpoint new-checkout
42
+ if fw.control_points.get_boolean_value("new-checkout", False, EvaluationContext(user_id)):
43
+ ...
44
+ fw.identify(user_id, {"plan": user.plan}) # at sign-in
45
+ fw.control_points.get_boolean_value("nightly-reindex", False, EvaluationContext(fw.instance_key())) # server as subject
46
+ ```
47
+
48
+ Deployed environments set one variable, `FIREWEAVE_KEY` (the project key, `project-api-key_…`).
49
+ Local development needs nothing when `FIREWEAVE_ENV` (or `APP_ENV`) is `development`, `dev`,
50
+ `local` or `test`.
51
+
52
+ `fw.control_points` has exactly the core's nine methods, with the same names and arguments;
53
+ contexts are `EvaluationContext` as everywhere else. Reads are synchronous (one blocking HTTP call
54
+ each in remote mode); in an `async def` handler use
55
+ `await asyncio.to_thread(lambda: fw.control_points.get_boolean_value("new-checkout", False, ctx))`.
56
+ Never pass an unguarded `str(user.id)`: Django's `AnonymousUser.id` is `None`, and `"None"` would
57
+ be one targeting key shared by every anonymous visitor.
58
+
59
+ ### Options and overrides
60
+
61
+ Every value resolves as: `start()` keyword option, then env var, then legacy name (warns once),
62
+ then default. Empty and whitespace-only values count as unset.
63
+
64
+ | Option | Env var | Default | What it does |
65
+ | --- | --- | --- | --- |
66
+ | `control_points` | — | `{}` | Local values per control point. Ignored in remote mode. |
67
+ | `mode` | — | inferred | `'remote'` or `'local'`. Overrides inference. `'remote'` without a key is a start error; `'local'` ignores a key, with one warning. |
68
+ | `environment` | `FIREWEAVE_ENV`, `APP_ENV` | — | Environment name used for inference when there is no key and no `mode`. Pass your own, e.g. `environment=settings.DEPLOY_STAGE`. `ENVIRONMENT`, `ENV`, `NODE_ENV` and the retired `FW_ENV` are not read. |
69
+ | `url` | `FIREWEAVE_URL` (legacy `FW_API_URL`, `FW_ATTEST_URL`) | from the installed version | A pre-release or dev release calls `staging-app-server.fireweave.ai`; any other calls `app-server.fireweave.ai`. Staging builds are `X.Y.ZrcN` on PyPI: install one with `pip install fireweave==X.Y.ZrcN` (no extra index; pip skips pre-releases unless pinned). Set it for a self-hosted or local fw-server: https is required except on localhost, and the host allowlist follows it. |
70
+ | `key` | `FIREWEAVE_KEY` (legacy `FW_PROJECT_API_KEY`) | — | Project key. Pass it to read from your own secret store. Browser keys (`fw_public_…`), analytics vendor keys and org or CLI tokens are rejected at start. |
71
+ | `instance_id` | `FIREWEAVE_INSTANCE_ID` | `inst_` + hash of the host name | Value of `fw.instance_key()`. Nothing is written to disk. |
72
+ | `env` | — | `os.environ` | Read values from this mapping instead of the environment (tests). |
73
+ | `log` | — | the `fireweave.start` logger | A callable taking one line, or a `logging.Logger`. Where `[fireweave]` lines go. |
74
+
75
+ `fireweave.start.SDK_VERSION` and `SDK_CHANNEL` show which version and channel are installed.
76
+
77
+ **Mode rule.** `mode` wins. Otherwise: a key means remote. No key and a development environment
78
+ name means local. Anything else (including no environment name at all) raises
79
+ `ConfigurationError` at `start()`, naming `FIREWEAVE_KEY` and where the environment name was
80
+ looked for, so a deploy that forgot its key fails instead of silently serving defaults.
81
+
82
+ **One per process.** `start()` is idempotent: a second call with the same configuration does
83
+ nothing, a different one raises `ConfigurationError`. It does no network I/O and starts no
84
+ thread, so it is ready when it returns. Call it in every process entrypoint; a forked worker
85
+ (gunicorn `--preload`, Celery prefork) rebuilds its client on its own. A read before any `start()`
86
+ starts FireWeave immediately from the environment alone (one warning); the first explicit
87
+ `start()` afterwards replaces that once, with a warning, and shuts the provisional client down
88
+ (reads in flight move to the new one). Processes that never run your entrypoint
89
+ (`manage.py`, spawned children) get the environment-only start, so prefer `FIREWEAVE_*`
90
+ variables to options for anything every process needs.
91
+
92
+ **Reads never raise.** If start fails, reads return your default (`evaluate` and the `*_details`
93
+ forms return an `ERROR` decision with the `Configuration` error) and `fw.identify()` returns
94
+ `ok=False`. In local mode, reading a key that is not in your control points returns the default and
95
+ warns once, naming the file that declared them.
96
+
97
+ **Debugging.** `fw.status()` reports what start decided: `state`, `started_by`, `mode` and
98
+ `mode_source`, `channel`, `sdk_version`, `host`, `endpoint_source`, `key_source`, `environment`,
99
+ `flag_count`, `error` and `last_error_kind`. It never includes the key. When fw-server refuses the
100
+ key (401/403), rate-limits it (429) or cannot be reached (network error, timeout, 5xx or a
101
+ redirect, which is never followed), reads serve their defaults, so a revoked key would otherwise
102
+ look like a rollout at 0%. Each of those kinds logs **one** line per process through your `log`
103
+ sink (default: the `fireweave.start` logger), naming the key's source (`FIREWEAVE_KEY`,
104
+ `start(key=...)`) or the endpoint's, and the host, never the key; `last_error_kind` keeps the
105
+ latest kind (`Authentication`, `Authorization`, `RateLimited`, `Network`, `Timeout`,
106
+ `BackendUnavailable`). `fw.client()` is the core `FireweaveClient` for anything the facade does not
107
+ cover (do not cache it: the first explicit `start()` after a read-triggered one shuts the
108
+ provisional client down); `fw.shutdown()` flushes and closes, and a later `start()` begins fresh.
109
+ Tests call `fireweave.start.reset_for_tests()` between cases.
110
+
111
+ ## Quick start (production path)
112
+
113
+ ```python
114
+ from fireweave import RegisterTargetOptions, init_fireweave, EvaluationContext
115
+
116
+ # mode is required and never inferred (spec/modes.md); api_key/api_url are
117
+ # explicit options — the SDK reads no environment variables.
118
+ client = init_fireweave(
119
+ mode="remote",
120
+ api_key="project-api-key_...",
121
+ api_url="https://app-server.fireweave.ai",
122
+ )
123
+
124
+ # Once per login: the durable facts your targeting rules match on.
125
+ client.register_target(
126
+ "user_42", RegisterTargetOptions(kind="user", properties={"plan": "pro"})
127
+ )
128
+
129
+ # Per request.
130
+ enabled = client.control_points.get_boolean_value(
131
+ "new-checkout", False, EvaluationContext("user_42")
132
+ )
133
+
134
+ client.shutdown()
135
+ ```
136
+
137
+ ## Quick start (offline, in-memory)
138
+
139
+ ```python
140
+ from fireweave import FireweaveClient, FireweaveRuntime, InMemoryAdapter
141
+
142
+ adapter = InMemoryAdapter({
143
+ "new-checkout": {"enabled": True, "variant": "on", "value": True},
144
+ })
145
+ runtime = FireweaveRuntime(adapter)
146
+ runtime.initialize()
147
+ client = FireweaveClient(runtime)
148
+
149
+ assert client.control_points.get_boolean_value("new-checkout", False) is True
150
+ client.shutdown()
151
+ ```
152
+
153
+ ## Quick start (local dev — no network, no credentials)
154
+
155
+ ```python
156
+ from fireweave import init_fireweave
157
+
158
+ client = init_fireweave(mode="local", local={"control_points": {"new-checkout": True}})
159
+ client.control_points.get_boolean_value("new-checkout", False) # -> True
160
+ client.register_target("user_42") # recorded in-process + traced; nothing sent
161
+ client.shutdown()
162
+ ```
163
+
164
+ ## The nine methods
165
+
166
+ `get_boolean_value` / `get_string_value` / `get_number_value` /
167
+ `get_object_value`, their `*_details` counterparts (return the whole
168
+ `Decision` — `reason`, `error_kind`, `control_point_metadata`, ... — instead of
169
+ just the value), and the general-form `evaluate`. All nine live under
170
+ `client.control_points`; the `client.flags` alias was removed in 3.0.0
171
+ (ADR-0013).
172
+
173
+ `get_integer_value` is a deprecated alias of `get_number_value` — spec fixes
174
+ the method as **number**, not integer (`Decision.value` is `jsonValue`). It
175
+ still works and delegates straight through; it logs one `DeprecationWarning`
176
+ per process the first time it's called.
177
+
178
+ ## Module layout
179
+
180
+ | Module | Responsibility |
181
+ | --- | --- |
182
+ | `domain/` | Pure types + validation: `errors.py`, `types.py`, `context.py`, `decision.py`, `target.py`, `validation.py`. No I/O, no imports from `application/`/`infrastructure/`. |
183
+ | `application/runtime.py` | Lifecycle state machine, context layering, the evaluation pipeline. Evaluation never raises. |
184
+ | `application/client.py` | `FireweaveClient` — `control_points`, `register_target`, `invoke_capability` (degrades; v1 has no supported capabilities). |
185
+ | `application/mode.py` | `init_fireweave` — the single entry point and sanctioned composition root (the only file allowed to import concrete adapters). |
186
+ | `application/ports.py` | The `BackendAdapter` boundary. |
187
+ | `infrastructure/adapters/remote.py` | `FireweaveRemoteAdapter` — the production backend (`POST /v1/control-points/evaluate`, `POST /v1/targets/register`). |
188
+ | `infrastructure/adapters/local.py` | `FireweaveLocalAdapter` — the dev substrate: seeded boolean overrides, no network. `register_target` records in-process and traces the call. |
189
+ | `infrastructure/adapters/memory.py` | Deterministic fixture-driven adapter for tests. |
190
+ | `infrastructure/hosts.py` | SSRF allowlist (on by default; https required off-loopback). |
191
+ | `start/` | The opt-in start profile (`from fireweave.start import start, fw, define_control_points`). Built on the public `fireweave` API only; `start/_env.py` is the one file that reads the environment or the host name. The core never imports it. |
192
+
193
+ ## Development
194
+
195
+ ```bash
196
+ python -m venv .venv && .venv/bin/pip install -e '.[dev]'
197
+ # or: uv sync
198
+ .venv/bin/pytest # unit tests
199
+ ```
200
+
201
+ `conformance/surface/control-points.surface.json` is the parity gate this package satisfies.
202
+
203
+ ## License
204
+
205
+ [MIT](./LICENSE).
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "fireweave"
7
- version = "2.3.0"
7
+ version = "3.0.0"
8
8
  description = "Fireweave polyglot SDK for Python — server-first control-point evaluation and target registration (spec v0.1.0)."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -44,7 +44,7 @@ from .domain.errors import (
44
44
  ConfigurationError,
45
45
  ErrorKind,
46
46
  FireweaveError,
47
- FlagNotFoundError,
47
+ ControlPointNotFoundError,
48
48
  InternalError,
49
49
  InvalidContextError,
50
50
  MalformedResponseError,
@@ -133,7 +133,7 @@ __all__ = [
133
133
  "ErrorKind",
134
134
  "FireweaveError",
135
135
  "NotReadyError",
136
- "FlagNotFoundError",
136
+ "ControlPointNotFoundError",
137
137
  "TypeMismatchError",
138
138
  "InvalidContextError",
139
139
  "TargetingKeyMissingError",
@@ -42,8 +42,8 @@ def _failure(err: FireweaveError, degraded: bool = False) -> ExtensionResult:
42
42
 
43
43
  class _ControlPointsNamespace:
44
44
  """Typed evaluation helpers — the nine methods (spec/control-points.md
45
- "The nine methods"). Documented as ``client.control_points``;
46
- ``client.flags`` is an identical alias retained for compatibility.
45
+ "The nine methods"), as ``client.control_points``. The ``client.flags``
46
+ alias was removed in 3.0.0 (ADR-0013).
47
47
  """
48
48
 
49
49
  def __init__(self, runtime: FireweaveRuntime) -> None:
@@ -51,7 +51,7 @@ class _ControlPointsNamespace:
51
51
 
52
52
  def evaluate(
53
53
  self,
54
- flag_key: str,
54
+ control_point_key: str,
55
55
  flag_type: FlagType,
56
56
  default: Any,
57
57
  context: Optional[EvaluationContext] = None,
@@ -65,50 +65,50 @@ class _ControlPointsNamespace:
65
65
  ``evaluate(key, type, default, context?, options?)`` across every
66
66
  language). ``options.include_payload`` (task-10b item 5) is the one
67
67
  real field: it attaches the resolved flag's payload, when any, to
68
- ``flag_metadata['fireweave.payload']`` — a deterministic sorted-key
68
+ ``control_point_metadata['fireweave.payload']`` — a deterministic sorted-key
69
69
  JSON string, matching node's ``EvaluateOptions.includePayload``. The
70
70
  python control-point surface is synchronous (server SDK — blocking
71
71
  I/O like node's ``await`` is fine), so there is no in-flight-call
72
72
  `signal` to carry, and v1 reads are side-effect-free by design (no
73
73
  per-call exposure opt-in to carry either) — those two remain N/A.
74
74
  """
75
- return self._runtime.evaluate(flag_key, flag_type, default, context, options)
75
+ return self._runtime.evaluate(control_point_key, flag_type, default, context, options)
76
76
 
77
- def get_boolean_value(self, flag_key: str, default: bool, context: Optional[EvaluationContext] = None) -> bool:
78
- return self.evaluate(flag_key, FlagType.BOOLEAN, default, context).value
77
+ def get_boolean_value(self, control_point_key: str, default: bool, context: Optional[EvaluationContext] = None) -> bool:
78
+ return self.evaluate(control_point_key, FlagType.BOOLEAN, default, context).value
79
79
 
80
- def get_string_value(self, flag_key: str, default: str, context: Optional[EvaluationContext] = None) -> str:
81
- return self.evaluate(flag_key, FlagType.STRING, default, context).value
80
+ def get_string_value(self, control_point_key: str, default: str, context: Optional[EvaluationContext] = None) -> str:
81
+ return self.evaluate(control_point_key, FlagType.STRING, default, context).value
82
82
 
83
- def get_number_value(self, flag_key: str, default: Any, context: Optional[EvaluationContext] = None) -> Any:
84
- return self.evaluate(flag_key, FlagType.NUMBER, default, context).value
83
+ def get_number_value(self, control_point_key: str, default: Any, context: Optional[EvaluationContext] = None) -> Any:
84
+ return self.evaluate(control_point_key, FlagType.NUMBER, default, context).value
85
85
 
86
86
  def get_object_value(
87
- self, flag_key: str, default: JsonValue, context: Optional[EvaluationContext] = None
87
+ self, control_point_key: str, default: JsonValue, context: Optional[EvaluationContext] = None
88
88
  ) -> JsonValue:
89
- return self.evaluate(flag_key, FlagType.OBJECT, default, context).value
89
+ return self.evaluate(control_point_key, FlagType.OBJECT, default, context).value
90
90
 
91
91
  def get_boolean_details(
92
- self, flag_key: str, default: bool, context: Optional[EvaluationContext] = None
92
+ self, control_point_key: str, default: bool, context: Optional[EvaluationContext] = None
93
93
  ) -> Decision:
94
- return self.evaluate(flag_key, FlagType.BOOLEAN, default, context)
94
+ return self.evaluate(control_point_key, FlagType.BOOLEAN, default, context)
95
95
 
96
96
  def get_string_details(
97
- self, flag_key: str, default: str, context: Optional[EvaluationContext] = None
97
+ self, control_point_key: str, default: str, context: Optional[EvaluationContext] = None
98
98
  ) -> Decision:
99
- return self.evaluate(flag_key, FlagType.STRING, default, context)
99
+ return self.evaluate(control_point_key, FlagType.STRING, default, context)
100
100
 
101
101
  def get_number_details(
102
- self, flag_key: str, default: Any, context: Optional[EvaluationContext] = None
102
+ self, control_point_key: str, default: Any, context: Optional[EvaluationContext] = None
103
103
  ) -> Decision:
104
- return self.evaluate(flag_key, FlagType.NUMBER, default, context)
104
+ return self.evaluate(control_point_key, FlagType.NUMBER, default, context)
105
105
 
106
106
  def get_object_details(
107
- self, flag_key: str, default: JsonValue, context: Optional[EvaluationContext] = None
107
+ self, control_point_key: str, default: JsonValue, context: Optional[EvaluationContext] = None
108
108
  ) -> Decision:
109
- return self.evaluate(flag_key, FlagType.OBJECT, default, context)
109
+ return self.evaluate(control_point_key, FlagType.OBJECT, default, context)
110
110
 
111
- def get_integer_value(self, flag_key: str, default: int, context: Optional[EvaluationContext] = None) -> int:
111
+ def get_integer_value(self, control_point_key: str, default: int, context: Optional[EvaluationContext] = None) -> int:
112
112
  """Deprecated alias of :meth:`get_number_value`.
113
113
 
114
114
  spec/control-points.md fixed the method as **number**, not integer
@@ -121,7 +121,7 @@ class _ControlPointsNamespace:
121
121
  warning.
122
122
  """
123
123
  _note_deprecated_get_integer_value()
124
- return self.get_number_value(flag_key, default, context)
124
+ return self.get_number_value(control_point_key, default, context)
125
125
 
126
126
 
127
127
  # Names invoke_capability will dispatch instead of degrading with
@@ -136,23 +136,9 @@ SUPPORTED_CAPABILITIES: FrozenSet[str] = frozenset()
136
136
  # wholesale and then ignored. Unconditional (no env gate): the SDK reads no
137
137
  # environment variables (spec/modes.md "The SDK reads no environment
138
138
  # variables", unscoped).
139
- _flags_alias_warned = False
140
139
  _get_integer_value_warned = False
141
140
 
142
141
 
143
- def _note_deprecated_flags_alias() -> None:
144
- global _flags_alias_warned
145
- if _flags_alias_warned:
146
- return
147
- _flags_alias_warned = True
148
- warnings.warn(
149
- "client.flags has been renamed to client.control_points. "
150
- "The old name remains fully supported — no migration is required.",
151
- DeprecationWarning,
152
- stacklevel=3,
153
- )
154
-
155
-
156
142
  def _note_deprecated_get_integer_value() -> None:
157
143
  global _get_integer_value_warned
158
144
  if _get_integer_value_warned:
@@ -179,17 +165,6 @@ class FireweaveClient:
179
165
  self._runtime = runtime
180
166
  self.control_points = _ControlPointsNamespace(runtime)
181
167
 
182
- @property
183
- def flags(self) -> _ControlPointsNamespace:
184
- """Control-point evaluation under its former name.
185
-
186
- Identical to :attr:`control_points` — ``client.flags is
187
- client.control_points``. Not scheduled for removal. Logs one notice
188
- per process the first time this getter is used.
189
- """
190
- _note_deprecated_flags_alias()
191
- return self.control_points
192
-
193
168
  @property
194
169
  def runtime(self) -> FireweaveRuntime:
195
170
  return self._runtime
@@ -34,7 +34,7 @@ class EvaluateOptions:
34
34
  ``include_payload`` (task-10b item 5, contracts/evaluation/eval-payload-
35
35
  attached.json): when True and the resolved flag carries a payload
36
36
  (:attr:`FlagResolution.payload`), it is attached to
37
- ``flag_metadata['fireweave.payload']`` as a deterministic (sorted-key)
37
+ ``control_point_metadata['fireweave.payload']`` as a deterministic (sorted-key)
38
38
  JSON string — matching node's ``EvaluateOptions.includePayload``. Before
39
39
  task-10b this was entirely absent (``evaluate()`` had no ``options``
40
40
  concept whatsoever; the parameter existed but was always discarded).
@@ -80,8 +80,8 @@ class FlagResolution:
80
80
  :meth:`FireweaveRuntime.evaluate` reads to produce reason ``DEFAULT``
81
81
  (spec/modes.md "Behaviour per mode": local mode's unknown-key row).
82
82
  Contrast a genuinely-unknown key at a real backend (remote's "key unknown
83
- to the backend" row), which resolves to reason ``ERROR``/``FlagNotFound``
84
- by *raising* :class:`~fireweave.domain.errors.FlagNotFoundError` instead
83
+ to the backend" row), which resolves to reason ``ERROR``/``ControlPointNotFound``
84
+ by *raising* :class:`~fireweave.domain.errors.ControlPointNotFoundError` instead
85
85
  of returning ``matched=False`` — see `FireweaveRemoteAdapter.resolve` and
86
86
  `FireweaveLocalAdapter.resolve`.
87
87
 
@@ -94,7 +94,7 @@ class FlagResolution:
94
94
  enabled: bool = True
95
95
  matched: bool = True
96
96
  version: Optional[int] = None
97
- vendor_flag_id: Optional[int] = None
97
+ vendor_control_point_id: Optional[int] = None
98
98
  reason_code: Optional[str] = None
99
99
  condition_index: Optional[int] = None
100
100
  payload: Optional[JsonValue] = None
@@ -108,7 +108,7 @@ class BackendAdapter(Protocol):
108
108
  """Protocol every Fireweave backend adapter implements.
109
109
 
110
110
  ``resolve`` raises a :class:`fireweave.domain.errors.FireweaveError`
111
- subtype for a genuine backend failure (FlagNotFound, Network, Timeout,
111
+ subtype for a genuine backend failure (ControlPointNotFound, Network, Timeout,
112
112
  ...); the runtime converts those into default-valued decisions —
113
113
  evaluation APIs never propagate them to the caller.
114
114
 
@@ -122,7 +122,7 @@ class BackendAdapter(Protocol):
122
122
  def initialize(self) -> None:
123
123
  """Bring the backend up; raise FireweaveError on fatal config."""
124
124
 
125
- def resolve(self, flag_key: str, context: EvaluationContext) -> FlagResolution:
125
+ def resolve(self, control_point_key: str, context: EvaluationContext) -> FlagResolution:
126
126
  """Resolve one flag against a validated, merged context."""
127
127
 
128
128
  def shutdown(self, timeout_ms: int) -> None: