hot-dev 1.2.0__tar.gz → 1.3.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 (46) hide show
  1. hot_dev-1.3.0/.github/dependabot.yml +10 -0
  2. hot_dev-1.3.0/.github/workflows/ci.yml +163 -0
  3. {hot_dev-1.2.0 → hot_dev-1.3.0}/.github/workflows/release.yml +4 -4
  4. {hot_dev-1.2.0 → hot_dev-1.3.0}/AGENTS.md +11 -4
  5. hot_dev-1.3.0/PKG-INFO +381 -0
  6. hot_dev-1.3.0/README.md +361 -0
  7. hot_dev-1.3.0/integration/VALIDATION.md +51 -0
  8. {hot_dev-1.2.0 → hot_dev-1.3.0}/integration/fixture/hot/src/fixture/sdk.hot +23 -0
  9. hot_dev-1.3.0/integration/hot-server.ref +1 -0
  10. {hot_dev-1.2.0 → hot_dev-1.3.0}/integration/run.sh +3 -10
  11. hot_dev-1.3.0/integration/suborg_fixture.py +473 -0
  12. {hot_dev-1.2.0 → hot_dev-1.3.0}/pyproject.toml +6 -5
  13. {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/__init__.py +2 -1
  14. hot_dev-1.3.0/src/hot/_streaming.py +565 -0
  15. {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/_transport.py +90 -13
  16. {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/client.py +20 -1
  17. {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/errors.py +54 -2
  18. hot_dev-1.3.0/src/hot/resources.py +2075 -0
  19. {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/openapi_operations.json +57 -34
  20. hot_dev-1.3.0/tests/test_deadlines.py +228 -0
  21. {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_integration.py +54 -0
  22. {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_openapi_coverage.py +31 -1
  23. hot_dev-1.3.0/tests/test_orgs.py +215 -0
  24. hot_dev-1.3.0/tests/test_reconnect_policy.py +295 -0
  25. {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_resources.py +60 -1
  26. hot_dev-1.3.0/tests/test_run_correlation.py +346 -0
  27. {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_runs.py +2 -6
  28. hot_dev-1.3.0/tests/test_suborg_integration.py +244 -0
  29. hot_dev-1.3.0/tests/test_transport.py +132 -0
  30. hot_dev-1.2.0/.github/workflows/ci.yml +0 -65
  31. hot_dev-1.2.0/PKG-INFO +0 -241
  32. hot_dev-1.2.0/README.md +0 -221
  33. hot_dev-1.2.0/integration/mint_key.py +0 -42
  34. hot_dev-1.2.0/src/hot/resources.py +0 -1647
  35. {hot_dev-1.2.0 → hot_dev-1.3.0}/.gitignore +0 -0
  36. {hot_dev-1.2.0 → hot_dev-1.3.0}/LICENSE +0 -0
  37. {hot_dev-1.2.0 → hot_dev-1.3.0}/NOTICE +0 -0
  38. {hot_dev-1.2.0 → hot_dev-1.3.0}/integration/fixture/.env.example +0 -0
  39. {hot_dev-1.2.0 → hot_dev-1.3.0}/integration/fixture/.gitignore +0 -0
  40. {hot_dev-1.2.0 → hot_dev-1.3.0}/integration/fixture/hot.hot +0 -0
  41. {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/py.typed +0 -0
  42. {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/sse.py +0 -0
  43. {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/types.py +0 -0
  44. {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_client.py +0 -0
  45. {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_reconnect.py +0 -0
  46. {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_tasks.py +0 -0
@@ -0,0 +1,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: pip
4
+ directory: /
5
+ schedule:
6
+ interval: weekly
7
+ - package-ecosystem: github-actions
8
+ directory: /
9
+ schedule:
10
+ interval: weekly
@@ -0,0 +1,163 @@
1
+ name: CI
2
+
3
+ on:
4
+ pull_request:
5
+ push:
6
+ branches:
7
+ - main
8
+ # Weekly: run the org API isolation job against hot main, so drift in the
9
+ # API or its OpenAPI operations shows up before the pin is moved.
10
+ schedule:
11
+ - cron: "23 6 * * 1"
12
+
13
+ permissions:
14
+ contents: read
15
+
16
+ jobs:
17
+ test:
18
+ name: Python ${{ matrix.python-version }}
19
+ runs-on: ubuntu-latest
20
+ strategy:
21
+ fail-fast: false
22
+ matrix:
23
+ python-version:
24
+ - "3.10"
25
+ - "3.11"
26
+ - "3.12"
27
+ - "3.13"
28
+ - "3.14"
29
+ - "3.15"
30
+
31
+ steps:
32
+ - name: Checkout
33
+ uses: actions/checkout@v7
34
+
35
+ - name: Set up Python
36
+ uses: actions/setup-python@v7
37
+ with:
38
+ python-version: ${{ matrix.python-version }}
39
+ allow-prereleases: true
40
+ cache: pip
41
+
42
+ - name: Install
43
+ run: python -m pip install -e ".[dev]"
44
+
45
+ - name: Lint
46
+ run: |
47
+ ruff check .
48
+ ruff format --check src tests
49
+
50
+ - name: Test
51
+ run: pytest
52
+
53
+ - name: Build
54
+ run: python -m build
55
+
56
+ integration:
57
+ name: Integration (hot dev)
58
+ runs-on: ubuntu-latest
59
+ steps:
60
+ - name: Checkout
61
+ uses: actions/checkout@v7
62
+
63
+ - name: Set up Python
64
+ uses: actions/setup-python@v7
65
+ with:
66
+ python-version: "3.13"
67
+
68
+ - name: Install package
69
+ run: |
70
+ python -m venv .venv
71
+ .venv/bin/python -m pip install -e ".[dev]"
72
+
73
+ - name: Install hot
74
+ uses: hot-dev/setup-hot@92cf9e03f49293fb31f28a56ed2c85a3424d90ad # v1
75
+
76
+ - name: Run integration tests
77
+ run: ./integration/run.sh
78
+
79
+ postgres-isolation:
80
+ name: Org API isolation (PostgreSQL)
81
+ runs-on: ubuntu-24.04
82
+ timeout-minutes: 60
83
+ permissions:
84
+ contents: read
85
+ env:
86
+ CARGO_INCREMENTAL: "0"
87
+ CARGO_PROFILE_DEV_DEBUG: line-tables-only
88
+ CARGO_NET_RETRY: "2"
89
+ SQLX_OFFLINE: "true"
90
+ steps:
91
+ - name: Checkout SDK
92
+ uses: actions/checkout@v7
93
+
94
+ # A released CLI may lag these API changes. Pin the tested server source
95
+ # separately so its schema, runtime qualification, and OpenAPI agree.
96
+ # The weekly scheduled run builds hot main instead, to catch drift.
97
+ - name: Checkout matching Hot server
98
+ uses: actions/checkout@v7
99
+ with:
100
+ repository: hot-dev/hot
101
+ ref: ${{ github.event_name == 'schedule' && 'main' || 'd7700112ada1f75211e3b6e66519e9388998f045' }} # Keep aligned with integration/hot-server.ref
102
+ path: .hot-server
103
+ persist-credentials: false
104
+
105
+ - name: Verify matching Hot revision
106
+ if: github.event_name != 'schedule'
107
+ shell: bash
108
+ run: |
109
+ expected="$(cat integration/hot-server.ref)"
110
+ actual="$(git -C .hot-server rev-parse HEAD)"
111
+ if [[ "$expected" != "$actual" ]]; then
112
+ echo "Hot checkout and integration/hot-server.ref must match" >&2
113
+ exit 1
114
+ fi
115
+
116
+ - name: Set up Python for the fixture
117
+ uses: actions/setup-python@v7
118
+ with:
119
+ python-version: "3.13"
120
+
121
+ - name: Install build and PostgreSQL client dependencies
122
+ run: |
123
+ sudo apt-get update
124
+ sudo apt-get install -y build-essential pkg-config libssl-dev cmake clang lld postgresql-client
125
+ docker version
126
+
127
+ - name: Install server Rust toolchain
128
+ uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable
129
+ with:
130
+ toolchain: "1.99.1"
131
+
132
+ - name: Cache matching server build
133
+ uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2
134
+ with:
135
+ workspaces: .hot-server -> target
136
+ key: postgres-isolation-${{ github.event_name == 'schedule' && 'main' || hashFiles('integration/hot-server.ref') }}
137
+ cache-workspace-crates: "true"
138
+ save-if: ${{ github.ref == 'refs/heads/main' }}
139
+
140
+ - name: Install Tailwind for the server build
141
+ shell: bash
142
+ run: |
143
+ mkdir -p "$RUNNER_TEMP/hot-sdk-bin"
144
+ curl -fsSL --retry 3 \
145
+ https://github.com/tailwindlabs/tailwindcss/releases/download/v4.3.0/tailwindcss-linux-x64 \
146
+ -o "$RUNNER_TEMP/hot-sdk-bin/tailwindcss"
147
+ chmod +x "$RUNNER_TEMP/hot-sdk-bin/tailwindcss"
148
+ echo "$RUNNER_TEMP/hot-sdk-bin" >> "$GITHUB_PATH"
149
+
150
+ - name: Build matching Hot CLI
151
+ working-directory: .hot-server
152
+ run: cargo build --locked --package hot_cli --jobs 4
153
+
154
+ - name: Install Python SDK dependencies
155
+ run: python -m pip install -e ".[dev]"
156
+
157
+ - name: Test org API isolation with restricted runtime credentials
158
+ run: |
159
+ python3 integration/suborg_fixture.py \
160
+ --backend postgres \
161
+ --hot .hot-server/target/debug/hot \
162
+ --hot-repo .hot-server \
163
+ -- python -m pytest tests/test_suborg_integration.py -v
@@ -19,19 +19,19 @@ jobs:
19
19
 
20
20
  steps:
21
21
  - name: Checkout
22
- uses: actions/checkout@v4
22
+ uses: actions/checkout@v7
23
23
 
24
24
  - name: Set up Python
25
- uses: actions/setup-python@v5
25
+ uses: actions/setup-python@v7
26
26
  with:
27
27
  python-version: "3.13"
28
28
  cache: pip
29
29
 
30
30
  - name: Install build tools
31
- run: python -m pip install build
31
+ run: python -m pip install build==1.6.1
32
32
 
33
33
  - name: Build
34
34
  run: python -m build
35
35
 
36
36
  - name: Publish
37
- uses: pypa/gh-action-pypi-publish@release/v1
37
+ uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
@@ -15,14 +15,21 @@ This repo contains the Python SDK for the Hot Dev API.
15
15
  ```bash
16
16
  python -m pip install -e ".[dev]"
17
17
  ruff check .
18
+ ruff format --check src tests
18
19
  pytest
19
20
  python -m build
20
21
  ```
21
22
 
22
23
  ## CI and Releases
23
24
 
24
- - CI runs on pushes and pull requests to `main`: install, lint (`ruff`), test
25
- (`pytest`), and build (`python -m build`) on Python 3.10–3.13.
25
+ - CI runs on pushes and pull requests to `main`: install, lint (`ruff check`,
26
+ `ruff format --check`), test (`pytest`), and build (`python -m build`) on
27
+ Python 3.10–3.15. Dev tools are pinned in `pyproject.toml`; Dependabot bumps
28
+ them and the Actions weekly.
29
+ - The "Org API isolation (PostgreSQL)" job builds the hot revision in
30
+ `integration/hot-server.ref` (keep the CI checkout `ref:` identical) and runs
31
+ `integration/suborg_fixture.py` against restricted PostgreSQL roles. A weekly
32
+ scheduled run builds hot `main` instead, to catch API drift.
26
33
  - PyPI releases run from tags named `v<version>` matching the
27
34
  `pyproject.toml` version.
28
35
  - Publishing uses PyPI Trusted Publishing via OIDC against the `pypi` GitHub
@@ -48,7 +55,7 @@ the matching `@hot-dev/sdk` JavaScript release when possible.
48
55
  python3 on PATH) serving the Hot fixture project in `integration/fixture`
49
56
  (project `sdk-fixture`: an echo event handler, an always-failing handler and
50
57
  function, and hot:call targets). It binds 127.0.0.1 on HOT_TEST_PORT (default
51
- 4725), mints a full-access API key directly in the fixture's sqlite database,
58
+ 4725), mints a full-access API key with `hot key create`,
52
59
  exports HOT_TEST_BASE_URL / HOT_TEST_API_KEY, and runs `pytest tests/test_integration.py`.
53
60
  The integration tests skip when HOT_TEST_API_KEY is unset, so regular test
54
61
  runs are unaffected. The fixture pins the API to 127.0.0.1 because binding
@@ -68,6 +75,6 @@ lockstep. Checklist for a coordinated release:
68
75
  3. Run every repo's `integration/run.sh`.
69
76
  4. Commit, tag `v<version>`, push in each repo.
70
77
 
71
- The integration fixture (integration/fixture, mint_key.py, run.sh) is
78
+ The integration fixture (integration/fixture, run.sh) is
72
79
  duplicated across all five repos; the canonical copy lives in **hot-python** —
73
80
  change it there first, then sync the others.
hot_dev-1.3.0/PKG-INFO ADDED
@@ -0,0 +1,381 @@
1
+ Metadata-Version: 2.5
2
+ Name: hot-dev
3
+ Version: 1.3.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
+ Requires-Python: >=3.10
14
+ Requires-Dist: httpx>=0.28
15
+ Provides-Extra: dev
16
+ Requires-Dist: build==1.6.1; extra == 'dev'
17
+ Requires-Dist: pytest==9.2.0; extra == 'dev'
18
+ Requires-Dist: ruff==0.17.3; extra == 'dev'
19
+ Description-Content-Type: text/markdown
20
+
21
+ # hot-dev
22
+
23
+ Official Python SDK for the [Hot Dev](https://hot.dev) API.
24
+
25
+ - PyPI distribution: `hot-dev`
26
+ - Import package: `hot`
27
+ - Tested on Python 3.10 through 3.15
28
+
29
+ ## Install
30
+
31
+ ```bash
32
+ pip install hot-dev
33
+ ```
34
+
35
+ ## Quick Start
36
+
37
+ ```python
38
+ import os
39
+
40
+ from hot import HotClient
41
+
42
+ hot = HotClient(token=os.environ["HOT_API_KEY"])
43
+
44
+ # base_url defaults to https://api.hot.dev.
45
+ # For local development with `hot dev`, pass base_url="http://localhost:4681".
46
+
47
+ for event in hot.streams.subscribe_with_event(
48
+ {
49
+ "event_type": "team-agent:ask",
50
+ "event_data": {
51
+ "session_id": "web:chat:demo",
52
+ "user_id": "web:user:demo",
53
+ "user_name": "Demo User",
54
+ "question": "what is blocking launch?",
55
+ },
56
+ }
57
+ ):
58
+ if event["type"] == "stream:data":
59
+ print(event["data_type"], event.get("payload"))
60
+
61
+ if event["type"] == "run:stop":
62
+ print(event.get("run", {}).get("result"))
63
+ break
64
+ ```
65
+
66
+ The client closes its underlying HTTP connection cleanly when used as a context
67
+ manager:
68
+
69
+ ```python
70
+ with HotClient(token=os.environ["HOT_API_KEY"]) as hot:
71
+ event = hot.events.publish(
72
+ {
73
+ "event_type": "team-agent:ask",
74
+ "event_data": {"question": "what changed?"},
75
+ }
76
+ )
77
+ print(event["stream_id"])
78
+ ```
79
+
80
+ Authenticated clients should run server-side. Browser apps and public notebooks
81
+ should call your own backend route instead of exposing a Hot API key.
82
+ Administrative runtime endpoints require an API key with appropriate grants. Sessions and service keys are
83
+ permission-scoped and are mainly for event publishing and stream reads.
84
+
85
+ When code has a run id but does not need the full stream, wait on its durable
86
+ terminal snapshot. `timeout` bounds the whole wait, including reconnects:
87
+
88
+ ```python
89
+ run = hot.runs.wait(run_id, timeout=300)
90
+ print(run["result"])
91
+ ```
92
+
93
+ When a run returns a background task id, wait through the durable task resource:
94
+
95
+ ```python
96
+ task = hot.tasks.wait(task_id, timeout=300)
97
+ print(task["result"])
98
+ ```
99
+
100
+ The task waiter receives the latest persisted state first and reconnects, so it
101
+ cannot miss a task that completed before subscription. A failed, cancelled, or
102
+ timed-out task raises `HotTaskError` with the final task record.
103
+ To coordinate several tasks, wait on each one (`hot.tasks.wait`), for example
104
+ from a thread pool or with `asyncio.gather` on `AsyncHotClient`. The task's
105
+ parent stream also emits durable `task:update` events, but a plain
106
+ `streams.subscribe` ends at the API's 5-minute subscription limit.
107
+
108
+ ### Waiters and reconnects
109
+
110
+ `runs.wait`, `tasks.wait`, `streams.wait_for_run_result`, `events.call_hot`
111
+ and `streams.subscribe_with_event` share one reconnect policy:
112
+
113
+ - `timeout` is an absolute deadline over connecting, reading, and backoff. It
114
+ fires even while the server keeps sending keepalives. `subscribe_with_event`
115
+ takes an optional `timeout`; without one it has no deadline.
116
+ - Permanent errors (any 4xx except 408 and 429, including `HotKeyScopeError`)
117
+ raise at once.
118
+ - Transport errors, 408, 429 and 5xx reconnect with jittered exponential
119
+ backoff (0.25 s up to 10 s), honouring `retry_after`. A backoff that would
120
+ cross the deadline raises `TimeoutError` instead.
121
+ - `max_attempts` (default 5) counts consecutive failed connections. The API
122
+ closes every subscription 5 minutes after it opens, with `stream:complete`;
123
+ those rollovers reconnect at once and do not count, so long runs can be
124
+ awaited for as long as `timeout` allows.
125
+ - A run with status `pending_retry` is not final, whatever the event: the
126
+ waiter follows the handler's retry run (linked by `origin_run_id`). Hot can
127
+ replay a retried attempt as `run:fail` with status `failed` before the retry
128
+ run exists; when its `retry_attempt` shows a scheduled retry, the waiter
129
+ holds that failure for 5 seconds (or until `timeout`) and raises it only if
130
+ no retry run appears. `subscribe_with_event` yields that `run:fail` and ends
131
+ after the same grace.
132
+ - `on_chunk` receives `stream:data` text in order, including chunks the server
133
+ delivers before `run:start`.
134
+
135
+ ## Async Usage
136
+
137
+ ```python
138
+ import os
139
+
140
+ from hot import AsyncHotClient
141
+
142
+ async with AsyncHotClient(token=os.environ["HOT_API_KEY"]) as hot:
143
+ event = await hot.events.publish(
144
+ {
145
+ "event_type": "team-agent:ask",
146
+ "event_data": {"question": "what changed?"},
147
+ }
148
+ )
149
+ print(event["stream_id"])
150
+ ```
151
+
152
+ Async streaming is supported the same way:
153
+
154
+ ```python
155
+ async with AsyncHotClient(token=os.environ["HOT_API_KEY"]) as hot:
156
+ async for event in hot.streams.subscribe_with_event(
157
+ {
158
+ "event_type": "team-agent:ask",
159
+ "event_data": {"question": "what changed?"},
160
+ }
161
+ ):
162
+ print(event["type"], event)
163
+ ```
164
+
165
+ `AsyncHotClient` exposes the same resource namespaces as `HotClient`.
166
+
167
+ ## Errors
168
+
169
+ Non-2xx API responses raise `HotApiError` with structured fields:
170
+
171
+ ```python
172
+ from hot import HotApiError
173
+
174
+ try:
175
+ hot.projects.get("missing-project")
176
+ except HotApiError as error:
177
+ print(error.status_code, error.code, error.request_id, error.retry_after)
178
+ ```
179
+
180
+ A call made with the wrong kind of key raises `HotKeyScopeError` (a
181
+ `HotApiError` with status 403 and code `key_scope_mismatch`). Its
182
+ `required_scope` is `"org"` for `hot.orgs` and `hot.api_keys`, and `"env"` for
183
+ every runtime resource.
184
+
185
+ ### Retries
186
+
187
+ JSON requests are retried automatically (at most twice) when the API responds
188
+ 429 with a `retry_after`, and idempotent requests (GET, PUT, DELETE) also on
189
+ 502, 503 and 504. Other errors are raised as-is. Raw requests are never
190
+ retried; waiters follow the reconnect policy above.
191
+
192
+ ## Resources
193
+
194
+ `HotClient` mirrors the Hot API v1 resources:
195
+
196
+ - `hot.events` — publish, list, get, inspect event runs, and call Hot functions with `call_hot(fn, args)`
197
+ - `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)
198
+ - `hot.runs` — list, inspect, subscribe to, and wait for durable runs
199
+ - `hot.tasks` — get, subscribe to, and wait for durable background tasks
200
+ - `hot.files` — upload, download (`download_stream` for large files), list, and delete files (including multipart uploads)
201
+ - `hot.projects` — create, list, update, activate, deactivate, and delete projects
202
+ - `hot.builds` — upload, download (`download_stream`), deploy, and look up live/deployed builds
203
+ - `hot.blobs` — download large payloads spilled to blob storage (`download_stream` streams them); needs an environment API key
204
+ - `hot.context` — manage encrypted project context variables
205
+ - `hot.domains` — register, verify, list, and delete custom domains
206
+ - `hot.sessions` — create and revoke scoped sessions
207
+ - `hot.service_keys` — create and revoke scoped service keys
208
+ - `hot.org` — view the environment's usage and limits
209
+ - `hot.env` — read environment info, subscribe to environment events, and purge call traces
210
+ - `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
211
+ - `hot.api_keys` — with an org API key: get, narrow, rotate, and revoke API keys it issued
212
+
213
+ Use `hot.request(...)` or `hot.request_raw(...)` as an escape hatch for API
214
+ endpoints that do not yet have a resource helper.
215
+
216
+ `hot.env.subscribe()` requires API key credentials and a live API pub/sub
217
+ backend; local API servers without pub/sub return a 503. `subscribe_with_event`
218
+ reconnects across the API's 5-minute SSE timeout and stops after the terminal
219
+ run correlated to the event it published. Unrelated runs on the same stream do
220
+ not end the iterator.
221
+
222
+ ## Customizing the HTTP Client
223
+
224
+ Without `timeout` or `client`, requests time out after 60 s per read and 10 s
225
+ to connect; pass `timeout=httpx.Timeout(None)` to disable that. Streams and
226
+ waiters set their own timeouts.
227
+
228
+ `HotClient` and `AsyncHotClient` accept an `httpx.Client` (or
229
+ `httpx.AsyncClient`) via the `client=` argument. Use this to configure retries,
230
+ proxies, or custom transports:
231
+
232
+ ```python
233
+ import httpx
234
+
235
+ from hot import HotClient
236
+
237
+ http_client = httpx.Client(
238
+ timeout=httpx.Timeout(connect=5.0, read=60.0, write=30.0, pool=5.0),
239
+ transport=httpx.HTTPTransport(retries=3),
240
+ )
241
+
242
+ hot = HotClient(token=os.environ["HOT_API_KEY"], client=http_client)
243
+ ```
244
+
245
+ When you pass your own client, the SDK does not close it on exit.
246
+
247
+ ## Downloads
248
+
249
+ `files.download`, `builds.download` and `blobs.download` read the whole body into
250
+ memory. For large files, stream instead:
251
+
252
+ ```python
253
+ with hot.files.download_stream(file_id) as response, open("out.bin", "wb") as out:
254
+ for chunk in response.iter_bytes():
255
+ out.write(chunk)
256
+ ```
257
+
258
+ `blobs.download_stream(blob_ref_id)` works the same way.
259
+ `AsyncHotClient` offers the same with `async with` and `response.aiter_bytes()`.
260
+
261
+ ## Casing Policy
262
+
263
+ Core API request and response payloads use the Hot API wire format:
264
+ `event_type`, `event_data`, `stream_id`, and so on. SDK-only options use Python
265
+ style names such as `base_url` and `timeout`.
266
+
267
+ The SDK never transforms user-owned payloads such as `event_data`.
268
+
269
+ ## Type Hints
270
+
271
+ The package ships with `py.typed`, so editors and type checkers will pick up
272
+ the public API. Request and response payloads are currently typed as plain
273
+ `dict[str, Any]` — keys follow the Hot API wire format documented above. Strict
274
+ `TypedDict` shapes generated from the Hot API OpenAPI spec are planned for a
275
+ future release.
276
+
277
+ ## Org API
278
+
279
+ Requires Hot 3.0.1 or later. An org API key (created by an administrator of the parent organization in the
280
+ App) provisions sub-organizations, their environments, and environment API
281
+ keys. Org keys only call `hot.orgs` and `hot.api_keys`; environment keys,
282
+ service keys, and sessions only call runtime resources. Either kind of key on
283
+ the wrong routes raises `HotKeyScopeError`.
284
+
285
+ ```python
286
+ import os
287
+ import uuid
288
+
289
+ from hot import HotClient
290
+
291
+ with HotClient(token=os.environ["HOT_ORG_API_KEY"]) as org:
292
+ request_id = uuid.uuid4().hex[:24]
293
+ sub_org = org.orgs.create(
294
+ {
295
+ "name": "Customer",
296
+ "slug": f"customer-{request_id}", # 32 characters or fewer
297
+ "external_id": "customer-123",
298
+ "idempotency_key": request_id, # reuse it when retrying this request
299
+ }
300
+ )
301
+ org_id, env_id = sub_org["org"]["org_id"], sub_org["env_id"]
302
+ key = org.orgs.create_env_api_key(
303
+ org_id,
304
+ env_id,
305
+ {"description": "Customer backend", "permissions": {"*:*": ["*"]}},
306
+ )
307
+ # Projects, builds and context in the sub-organization's environment, with the org key.
308
+ org.orgs.env(org_id, env_id).projects.create({"name": "agent"})
309
+
310
+ with HotClient(token=key["token"]) as customer:
311
+ print(customer.env.get())
312
+ ```
313
+
314
+ | Method | Route |
315
+ | --- | --- |
316
+ | `orgs.list(limit=, offset=)` | `GET /v1/orgs` (list envelope) |
317
+ | `orgs.create(body)` | `POST /v1/orgs`: returns `org`, `env_id`, `created` |
318
+ | `orgs.get(org_id)` / `orgs.update(org_id, {"state": ...})` | `GET`/`PATCH /v1/orgs/{org_id}` (`active`, `suspended`, `archived`) |
319
+ | `orgs.usage(parent_org_id)` | `GET /v1/orgs/{org_id}/usage` (account usage; parent organization only) |
320
+ | `orgs.purge_calls(org_id, include_sub_orgs=False)` | `DELETE /v1/orgs/{org_id}/calls` |
321
+ | `orgs.list_envs` / `create_env` / `get_env` | `/v1/orgs/{org_id}/envs[/{env_id}]` (create is idempotent by name) |
322
+ | `orgs.list_api_keys` / `create_api_key` | `/v1/orgs/{org_id}/api-keys` (org keys) |
323
+ | `orgs.list_env_api_keys` / `create_env_api_key` | `/v1/orgs/{org_id}/envs/{env_id}/api-keys` |
324
+ | `api_keys.get` / `update` / `revoke` / `rotate(overlap_seconds=)` | `/v1/api-keys/{key_id}[/rotate]` |
325
+ | `orgs.env(org_id, env_id).projects` / `.builds` / `.context` | `/v1/orgs/{org_id}/envs/{env_id}/...` |
326
+
327
+ A minted or rotated key's `token` is returned only once. Minted grants must fit
328
+ inside the org key's own grants for that environment. Revoking or narrowing an
329
+ org key restricts every key, service key, and session issued under it.
330
+
331
+ `hot.org.usage()` (runtime) reports one environment's consumption, with
332
+ `env_id` and `usage_scope: "environment"`; its limits come from the billing
333
+ account. Use `orgs.usage(parent_org_id)` with an org key for the account total.
334
+
335
+ ## Local Development
336
+
337
+ ```bash
338
+ python -m venv .venv
339
+ source .venv/bin/activate
340
+ python -m pip install -e ".[dev]"
341
+ ruff check .
342
+ pytest
343
+ python -m build
344
+ ```
345
+
346
+ ## Org API integration tests
347
+
348
+ `integration/suborg_fixture.py` creates an owned disposable database and
349
+ loopback API server, seeds an org API key and a root environment key, checks
350
+ the live OpenAPI operations against `tests/openapi_operations.json`, and runs
351
+ the given test command. It removes only its own resources and never uses
352
+ deployed credentials. It needs Python 3 and a Hot CLI built from the revision
353
+ in `integration/hot-server.ref`. For PostgreSQL, also install Docker and `psql`
354
+ and provide that hot checkout (default: sibling `hot`). Migrations use a
355
+ non-superuser schema owner; the API uses a distinct non-owner
356
+ `NOSUPERUSER NOBYPASSRLS` login with RLS enforcement.
357
+
358
+ ```bash
359
+ python3 integration/suborg_fixture.py --hot ../hot/target/debug/hot --backend postgres -- \
360
+ .venv/bin/python -m pytest tests/test_suborg_integration.py -v
361
+ # For SQLite, use --backend sqlite.
362
+ ```
363
+
364
+ Coverage includes sub-organization and environment provisioning and idempotency, identical
365
+ project names in siblings, foreign-ID and stream denial, root runtime
366
+ isolation, org/environment key separation (`HotKeyScopeError`), account and
367
+ environment usage, provisioning projects and context through `orgs.env`,
368
+ restricted keys, key rotation, narrowing and revocation, service/session
369
+ issuance and revocation, descendants of a revoked or narrowed org key, and sub-organization
370
+ suspension and resumption. See [the validation record](integration/VALIDATION.md).
371
+
372
+ ## Related
373
+
374
+ - [Hot Dev documentation](https://hot.dev/docs)
375
+ - [SDK docs](https://hot.dev/docs/api/sdks)
376
+ - [JavaScript / TypeScript SDK](https://www.npmjs.com/package/@hot-dev/sdk)
377
+ - [Hot Chat demo](https://github.com/hot-dev/hot-demos/tree/main/hot-chat)
378
+
379
+ ## License
380
+
381
+ Apache-2.0