hot-dev 1.2.0__tar.gz → 1.4.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 (41) hide show
  1. hot_dev-1.4.0/PKG-INFO +409 -0
  2. hot_dev-1.4.0/README.md +378 -0
  3. hot_dev-1.4.0/pyproject.toml +79 -0
  4. hot_dev-1.4.0/src/hot/__init__.py +31 -0
  5. hot_dev-1.4.0/src/hot/_streaming.py +697 -0
  6. hot_dev-1.4.0/src/hot/_transport.py +439 -0
  7. hot_dev-1.4.0/src/hot/_version.py +1 -0
  8. {hot_dev-1.2.0 → hot_dev-1.4.0}/src/hot/client.py +48 -5
  9. hot_dev-1.4.0/src/hot/errors.py +185 -0
  10. hot_dev-1.4.0/src/hot/resources.py +2107 -0
  11. hot_dev-1.4.0/src/hot/sse.py +95 -0
  12. {hot_dev-1.2.0 → hot_dev-1.4.0}/src/hot/types.py +12 -1
  13. hot_dev-1.2.0/.github/workflows/ci.yml +0 -65
  14. hot_dev-1.2.0/.github/workflows/release.yml +0 -37
  15. hot_dev-1.2.0/AGENTS.md +0 -73
  16. hot_dev-1.2.0/PKG-INFO +0 -241
  17. hot_dev-1.2.0/README.md +0 -221
  18. hot_dev-1.2.0/integration/fixture/.env.example +0 -3
  19. hot_dev-1.2.0/integration/fixture/.gitignore +0 -5
  20. hot_dev-1.2.0/integration/fixture/hot/src/fixture/sdk.hot +0 -56
  21. hot_dev-1.2.0/integration/fixture/hot.hot +0 -22
  22. hot_dev-1.2.0/integration/mint_key.py +0 -42
  23. hot_dev-1.2.0/integration/run.sh +0 -44
  24. hot_dev-1.2.0/pyproject.toml +0 -47
  25. hot_dev-1.2.0/src/hot/__init__.py +0 -12
  26. hot_dev-1.2.0/src/hot/_transport.py +0 -200
  27. hot_dev-1.2.0/src/hot/errors.py +0 -104
  28. hot_dev-1.2.0/src/hot/resources.py +0 -1647
  29. hot_dev-1.2.0/src/hot/sse.py +0 -51
  30. hot_dev-1.2.0/tests/openapi_operations.json +0 -64
  31. hot_dev-1.2.0/tests/test_client.py +0 -248
  32. hot_dev-1.2.0/tests/test_integration.py +0 -120
  33. hot_dev-1.2.0/tests/test_openapi_coverage.py +0 -113
  34. hot_dev-1.2.0/tests/test_reconnect.py +0 -194
  35. hot_dev-1.2.0/tests/test_resources.py +0 -94
  36. hot_dev-1.2.0/tests/test_runs.py +0 -84
  37. hot_dev-1.2.0/tests/test_tasks.py +0 -79
  38. {hot_dev-1.2.0 → hot_dev-1.4.0}/.gitignore +0 -0
  39. {hot_dev-1.2.0 → hot_dev-1.4.0}/LICENSE +0 -0
  40. {hot_dev-1.2.0 → hot_dev-1.4.0}/NOTICE +0 -0
  41. {hot_dev-1.2.0 → hot_dev-1.4.0}/src/hot/py.typed +0 -0
hot_dev-1.4.0/PKG-INFO ADDED
@@ -0,0 +1,409 @@
1
+ Metadata-Version: 2.5
2
+ Name: hot-dev
3
+ Version: 1.4.0
4
+ Summary: Python SDK for the Hot Dev API
5
+ Project-URL: Homepage, https://hot.dev
6
+ Project-URL: Repository, https://github.com/hot-dev/hot-python
7
+ Project-URL: Issues, https://github.com/hot-dev/hot-python/issues
8
+ Author: Hot Dev, LLC
9
+ License-Expression: Apache-2.0
10
+ License-File: LICENSE
11
+ License-File: NOTICE
12
+ Keywords: agents,api,hot,hot-dev,sdk,streaming
13
+ Classifier: Development Status :: 5 - Production/Stable
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: Apache Software License
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
+ Requires-Dist: httpx<1.0,>=0.28
25
+ Provides-Extra: dev
26
+ Requires-Dist: build==1.6.1; extra == 'dev'
27
+ Requires-Dist: mypy==1.15.0; extra == 'dev'
28
+ Requires-Dist: pytest==9.2.0; extra == 'dev'
29
+ Requires-Dist: ruff==0.17.6; extra == 'dev'
30
+ Description-Content-Type: text/markdown
31
+
32
+ # hot-dev
33
+
34
+ Official Python SDK for the [Hot Dev](https://hot.dev) API.
35
+
36
+ - PyPI distribution: `hot-dev`
37
+ - Import package: `hot`
38
+ - Tested on Python 3.10 through 3.15
39
+
40
+ ## Install
41
+
42
+ ```bash
43
+ pip install hot-dev
44
+ ```
45
+
46
+ ## Quick Start
47
+
48
+ ```python
49
+ import os
50
+
51
+ from hot import HotClient
52
+
53
+ hot = HotClient(token=os.environ["HOT_API_KEY"])
54
+
55
+ # base_url defaults to https://api.hot.dev.
56
+ # For local development with `hot dev`, pass base_url="http://localhost:4681".
57
+
58
+ for event in hot.streams.subscribe_with_event(
59
+ {
60
+ "event_type": "team-agent:ask",
61
+ "event_data": {
62
+ "session_id": "web:chat:demo",
63
+ "user_id": "web:user:demo",
64
+ "user_name": "Demo User",
65
+ "question": "what is blocking launch?",
66
+ },
67
+ }
68
+ ):
69
+ if event["type"] == "stream:data":
70
+ print(event["data_type"], event.get("payload"))
71
+
72
+ if event["type"] == "run:stop":
73
+ print(event.get("run", {}).get("result"))
74
+ break
75
+ ```
76
+
77
+ The client closes its underlying HTTP connection cleanly when used as a context
78
+ manager:
79
+
80
+ ```python
81
+ with HotClient(token=os.environ["HOT_API_KEY"]) as hot:
82
+ event = hot.events.publish(
83
+ {
84
+ "event_type": "team-agent:ask",
85
+ "event_data": {"question": "what changed?"},
86
+ }
87
+ )
88
+ print(event["stream_id"])
89
+ ```
90
+
91
+ Authenticated clients should run server-side. Browser apps and public notebooks
92
+ should call your own backend route instead of exposing a Hot API key.
93
+ Administrative runtime endpoints require an API key with appropriate grants. Sessions and service keys are
94
+ permission-scoped and are mainly for event publishing and stream reads.
95
+
96
+ When code has a run id but does not need the full stream, wait on its durable
97
+ terminal snapshot. `timeout` bounds the whole wait, including reconnects:
98
+
99
+ ```python
100
+ run = hot.runs.wait(run_id, timeout=300)
101
+ print(run["result"])
102
+ ```
103
+
104
+ When a run returns a background task id, wait through the durable task resource:
105
+
106
+ ```python
107
+ task = hot.tasks.wait(task_id, timeout=300)
108
+ print(task["result"])
109
+ ```
110
+
111
+ The task waiter receives the latest persisted state first and reconnects, so it
112
+ cannot miss a task that completed before subscription. A failed, cancelled, or
113
+ timed-out task raises `HotTaskError` with the final task record.
114
+ To coordinate several tasks, wait on each one (`hot.tasks.wait`), for example
115
+ from a thread pool or with `asyncio.gather` on `AsyncHotClient`. The task's
116
+ parent stream also emits durable `task:update` events, but a plain
117
+ `streams.subscribe` ends at the API's 5-minute subscription limit.
118
+
119
+ ### Waiters and reconnects
120
+
121
+ `runs.wait`, `tasks.wait`, `streams.wait_for_run_result`, `events.call_hot`
122
+ and `streams.subscribe_with_event` share one reconnect policy:
123
+
124
+ - `timeout` is an absolute deadline over connecting, reading, and backoff. It
125
+ fires even while the server keeps sending keepalives. `subscribe_with_event`
126
+ takes an optional `timeout`; without one it has no deadline.
127
+ - Permanent errors (any 4xx except 408 and 429, including `HotKeyScopeError`)
128
+ raise at once.
129
+ - Transport errors, 408, 429 and 5xx reconnect with jittered exponential
130
+ backoff (0.25 s up to 10 s), honouring `retry_after`. A backoff that would
131
+ cross the deadline raises `TimeoutError` instead.
132
+ - `max_attempts` (default 5) counts consecutive failed connections. The API
133
+ closes every subscription 5 minutes after it opens, with `stream:complete`;
134
+ explicit `stream:complete` rollovers reconnect at once and do not count, so
135
+ long runs can be awaited for as long as `timeout` allows. Unexpected premature
136
+ stream closes without `stream:complete` back off and count against
137
+ `max_attempts`.
138
+ - A run with status `pending_retry` is not final, whatever the event: the
139
+ waiter follows the handler's retry run (linked by `retry_run_id` or
140
+ `origin_run_id`). Hot can replay a retried attempt as `run:fail` with status
141
+ `failed` before the retry run exists; when its `retry_attempt` shows a
142
+ scheduled retry, the waiter holds that failure for 5 seconds (or until
143
+ `timeout`) and raises `HotRunError` (a `RuntimeError` subclass) only if no
144
+ retry run appears. `subscribe_with_event` yields that `run:fail` and ends
145
+ after the same grace.
146
+ - `on_chunk` receives `stream:data` text in order, including chunks the server
147
+ delivers before `run:start`.
148
+
149
+ ## Async Usage
150
+
151
+ ```python
152
+ import os
153
+
154
+ from hot import AsyncHotClient
155
+
156
+ async with AsyncHotClient(token=os.environ["HOT_API_KEY"]) as hot:
157
+ event = await hot.events.publish(
158
+ {
159
+ "event_type": "team-agent:ask",
160
+ "event_data": {"question": "what changed?"},
161
+ }
162
+ )
163
+ print(event["stream_id"])
164
+ ```
165
+
166
+ Async streaming is supported the same way:
167
+
168
+ ```python
169
+ async with AsyncHotClient(token=os.environ["HOT_API_KEY"]) as hot:
170
+ async for event in hot.streams.subscribe_with_event(
171
+ {
172
+ "event_type": "team-agent:ask",
173
+ "event_data": {"question": "what changed?"},
174
+ }
175
+ ):
176
+ print(event["type"], event)
177
+ ```
178
+
179
+ `AsyncHotClient` exposes the same resource namespaces as `HotClient`.
180
+
181
+ ## Errors
182
+
183
+ Non-2xx API responses raise `HotApiError` with structured fields:
184
+
185
+ ```python
186
+ from hot import HotApiError
187
+
188
+ try:
189
+ hot.projects.get("missing-project")
190
+ except HotApiError as error:
191
+ print(error.status_code, error.code, error.request_id, error.retry_after)
192
+ ```
193
+
194
+ A call made with the wrong kind of key raises `HotKeyScopeError` (a
195
+ `HotApiError` with status 403 and code `key_scope_mismatch`). Its
196
+ `required_scope` is `"org"` for `hot.orgs` and `hot.api_keys`, and `"env"` for
197
+ every runtime resource.
198
+
199
+ ### Retries
200
+
201
+ JSON requests are retried automatically (at most twice, bounded by the client's
202
+ configured read timeout) when the API responds:
203
+
204
+ - `429` with a `retry_after` (including `0`, integer seconds, or HTTP-date),
205
+ - `502`, `503`, or `504` on idempotent requests (`GET`, `HEAD`, `PUT`, `DELETE`),
206
+ - `503` with error code `event_publish_in_progress` on `POST` (for example,
207
+ concurrent retries of `events.publish` with the same client-supplied
208
+ `event_id`).
209
+
210
+ Other errors (including `409 event_id_conflict` when an `event_id` is reused
211
+ with different parameters) are raised as-is. Raw requests (`request_raw`,
212
+ uploads, downloads) are never retried; waiters follow the reconnect policy
213
+ above.
214
+
215
+ ## Resources
216
+
217
+ `HotClient` mirrors the Hot API resources:
218
+
219
+ - `hot.status()` — public, unauthenticated server health check (`GET /status`; does not send `Authorization`)
220
+ - `hot.events` — publish (pass an optional `event_id` for idempotent retries; conflicting reuse returns `409 event_id_conflict`), list, get, inspect event runs, and call Hot functions with `call_hot(fn, args)`
221
+ - `hot.streams` — subscribe to run and task updates, wait for run results, and publish events atomically (reconnects automatically across the 5-minute SSE timeout; pass `reconnect=False` to opt out)
222
+ - `hot.runs` — list (filter by `status`, `type`, `time_range`, `project_id`, `stream_id`, `function`, `limit`, `offset`), inspect, subscribe to, and wait for durable runs
223
+ - `hot.tasks` — get, subscribe to, and wait for durable background tasks
224
+ - `hot.files` — upload, download (`download_stream` for large files), list, and delete files (including multipart uploads)
225
+ - `hot.projects` — create, list, update, activate, deactivate, and delete projects
226
+ - `hot.builds` — upload, download (`download_stream`), deploy, and look up live/deployed builds
227
+ - `hot.blobs` — download large payloads spilled to blob storage (`download_stream` streams them); needs an environment API key
228
+ - `hot.context` — manage encrypted project context variables
229
+ - `hot.domains` — register, verify, list, and delete custom domains
230
+ - `hot.sessions` — create and revoke scoped sessions
231
+ - `hot.service_keys` — create and revoke scoped service keys
232
+ - `hot.org` — view the environment's usage and limits
233
+ - `hot.env` — read environment info, subscribe to environment events, and purge call traces
234
+ - `hot.orgs` — with an org API key: sub-organizations, their environments and API keys, account usage, and `orgs.env(org_id, env_id)` for projects, builds and context in an environment
235
+ - `hot.api_keys` — with an org API key: get, narrow, rotate, and revoke API keys it issued (`status` can be `active`, `revoked`, `disabled`, `expired`, `issuer_inactive`, or `suspended`)
236
+
237
+ Use `hot.request(...)` or `hot.request_raw(...)` as an escape hatch for `/v1`
238
+ API endpoints that do not yet have a resource helper. Paths are resolved under
239
+ `/v1` automatically (pass `"/runs"` or `"runs"`, not `"/v1/runs"`); use
240
+ `hot.status()` for the unversioned `GET /status` route.
241
+
242
+ `hot.env.subscribe()` requires API key credentials and a live API pub/sub
243
+ backend; local API servers without pub/sub return a 503. `subscribe_with_event`
244
+ reconnects across the API's 5-minute SSE timeout and stops after the terminal
245
+ run correlated to the event it published. Unrelated runs on the same stream do
246
+ not end the iterator.
247
+
248
+ ## Customizing the HTTP Client
249
+
250
+ Without `timeout` or `client`, requests time out after 60 s per read and 10 s
251
+ to connect; pass `timeout=httpx.Timeout(None)` to disable that. Streams and
252
+ waiters set their own timeouts. Note that `timeout=` is ignored when you pass a
253
+ custom `client=` — configure timeouts on your `httpx.Client` /
254
+ `httpx.AsyncClient` instead.
255
+
256
+ `HotClient` and `AsyncHotClient` accept an `httpx.Client` (or
257
+ `httpx.AsyncClient`) via the `client=` argument. Use this to configure retries,
258
+ proxies, or custom transports:
259
+
260
+ ```python
261
+ import httpx
262
+
263
+ from hot import HotClient
264
+
265
+ http_client = httpx.Client(
266
+ timeout=httpx.Timeout(connect=5.0, read=60.0, write=30.0, pool=5.0),
267
+ transport=httpx.HTTPTransport(retries=3),
268
+ )
269
+
270
+ hot = HotClient(token=os.environ["HOT_API_KEY"], client=http_client)
271
+ ```
272
+
273
+ When you pass your own client, the SDK does not close it on exit.
274
+
275
+ ## Downloads
276
+
277
+ `files.download`, `builds.download` and `blobs.download` read the whole body into
278
+ memory. For large files, stream instead:
279
+
280
+ ```python
281
+ with hot.files.download_stream(file_id) as response, open("out.bin", "wb") as out:
282
+ for chunk in response.iter_bytes():
283
+ out.write(chunk)
284
+ ```
285
+
286
+ `blobs.download_stream(blob_ref_id)` works the same way.
287
+ `AsyncHotClient` offers the same with `async with` and `response.aiter_bytes()`.
288
+
289
+ ## Casing Policy
290
+
291
+ Core API request and response payloads use the Hot API wire format:
292
+ `event_type`, `event_data`, `stream_id`, and so on. SDK-only options use Python
293
+ style names such as `base_url` and `timeout`.
294
+
295
+ The SDK never transforms user-owned payloads such as `event_data`.
296
+
297
+ ## Type Hints
298
+
299
+ The package ships with `py.typed`, so editors and type checkers will pick up
300
+ the public API. Request and response payloads are currently typed as plain
301
+ `dict[str, Any]` — keys follow the Hot API wire format documented above. Strict
302
+ `TypedDict` shapes generated from the Hot API OpenAPI spec are planned for a
303
+ future release.
304
+
305
+ ## Org API
306
+
307
+ Requires Hot 3.0.1 or later. An org API key (created by an administrator of the parent organization in the
308
+ App) provisions sub-organizations, their environments, and environment API
309
+ keys. Org keys only call `hot.orgs` and `hot.api_keys`; environment keys,
310
+ service keys, and sessions only call runtime resources. Either kind of key on
311
+ the wrong routes raises `HotKeyScopeError`.
312
+
313
+ ```python
314
+ import os
315
+ import uuid
316
+
317
+ from hot import HotClient
318
+
319
+ with HotClient(token=os.environ["HOT_ORG_API_KEY"]) as org:
320
+ request_id = uuid.uuid4().hex[:24]
321
+ sub_org = org.orgs.create(
322
+ {
323
+ "name": "Customer",
324
+ "slug": f"customer-{request_id}", # 32 characters or fewer
325
+ "external_id": "customer-123",
326
+ "idempotency_key": request_id, # reuse it when retrying this request
327
+ }
328
+ )
329
+ org_id, env_id = sub_org["org"]["org_id"], sub_org["env_id"]
330
+ key = org.orgs.create_env_api_key(
331
+ org_id,
332
+ env_id,
333
+ {"description": "Customer backend", "permissions": {"*:*": ["*"]}},
334
+ )
335
+ # Projects, builds and context in the sub-organization's environment, with the org key.
336
+ org.orgs.env(org_id, env_id).projects.create({"name": "agent"})
337
+
338
+ with HotClient(token=key["token"]) as customer:
339
+ print(customer.env.get())
340
+ ```
341
+
342
+ | Method | Route |
343
+ | --- | --- |
344
+ | `orgs.list(limit=, offset=)` | `GET /v1/orgs` (list envelope) |
345
+ | `orgs.create(body)` | `POST /v1/orgs`: returns `org`, `env_id`, `created` |
346
+ | `orgs.get(org_id)` / `orgs.update(org_id, {"state": ...})` | `GET`/`PATCH /v1/orgs/{org_id}` (`active`, `suspended`, `archived`) |
347
+ | `orgs.usage(parent_org_id)` | `GET /v1/orgs/{org_id}/usage` (account usage; parent organization only) |
348
+ | `orgs.purge_calls(org_id, include_sub_orgs=False)` | `DELETE /v1/orgs/{org_id}/calls` |
349
+ | `orgs.list_envs` / `create_env` / `get_env` | `/v1/orgs/{org_id}/envs[/{env_id}]` (create is idempotent by name) |
350
+ | `orgs.list_api_keys` / `create_api_key` | `/v1/orgs/{org_id}/api-keys` (org keys) |
351
+ | `orgs.list_env_api_keys` / `create_env_api_key` | `/v1/orgs/{org_id}/envs/{env_id}/api-keys` |
352
+ | `api_keys.get` / `update` / `revoke` / `rotate(overlap_seconds=)` | `/v1/api-keys/{key_id}[/rotate]` |
353
+ | `orgs.env(org_id, env_id).projects` / `.builds` / `.context` | `/v1/orgs/{org_id}/envs/{env_id}/...` |
354
+
355
+ A minted or rotated key's `token` is returned only once. Minted grants must fit
356
+ inside the org key's own grants for that environment. Revoking or narrowing an
357
+ org key restricts every key, service key, and session issued under it.
358
+
359
+ `hot.org.usage()` (runtime) reports one environment's consumption, with
360
+ `env_id` and `usage_scope: "environment"`; its limits come from the billing
361
+ account. Use `orgs.usage(parent_org_id)` with an org key for the account total.
362
+
363
+ ## Local Development
364
+
365
+ ```bash
366
+ python -m venv .venv
367
+ source .venv/bin/activate
368
+ python -m pip install -e ".[dev]"
369
+ ruff check .
370
+ pytest
371
+ python -m build
372
+ ```
373
+
374
+ ## Org API integration tests
375
+
376
+ `integration/suborg_fixture.py` creates an owned disposable database and
377
+ loopback API server, seeds an org API key and a root environment key, checks
378
+ the live OpenAPI operations against `tests/openapi_operations.json`, and runs
379
+ the given test command. It removes only its own resources and never uses
380
+ deployed credentials. It needs Python 3 and a Hot CLI built from the revision
381
+ in `integration/hot-server.ref`. For PostgreSQL, also install Docker and `psql`
382
+ and provide that hot checkout (default: sibling `hot`). Migrations use a
383
+ non-superuser schema owner; the API uses a distinct non-owner
384
+ `NOSUPERUSER NOBYPASSRLS` login with RLS enforcement.
385
+
386
+ ```bash
387
+ python3 integration/suborg_fixture.py --hot ../hot/target/debug/hot --backend postgres -- \
388
+ .venv/bin/python -m pytest tests/test_suborg_integration.py -v
389
+ # For SQLite, use --backend sqlite.
390
+ ```
391
+
392
+ Coverage includes sub-organization and environment provisioning and idempotency, identical
393
+ project names in siblings, foreign-ID and stream denial, root runtime
394
+ isolation, org/environment key separation (`HotKeyScopeError`), account and
395
+ environment usage, provisioning projects and context through `orgs.env`,
396
+ restricted keys, key rotation, narrowing and revocation, service/session
397
+ issuance and revocation, descendants of a revoked or narrowed org key, and sub-organization
398
+ suspension and resumption. See [the validation record](integration/VALIDATION.md).
399
+
400
+ ## Related
401
+
402
+ - [Hot Dev documentation](https://hot.dev/docs)
403
+ - [SDK docs](https://hot.dev/docs/api/sdks)
404
+ - [JavaScript / TypeScript SDK](https://www.npmjs.com/package/@hot-dev/sdk)
405
+ - [Hot Chat demo](https://github.com/hot-dev/hot-demos/tree/main/hot-chat)
406
+
407
+ ## License
408
+
409
+ Apache-2.0