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.
- hot_dev-1.3.0/.github/dependabot.yml +10 -0
- hot_dev-1.3.0/.github/workflows/ci.yml +163 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/.github/workflows/release.yml +4 -4
- {hot_dev-1.2.0 → hot_dev-1.3.0}/AGENTS.md +11 -4
- hot_dev-1.3.0/PKG-INFO +381 -0
- hot_dev-1.3.0/README.md +361 -0
- hot_dev-1.3.0/integration/VALIDATION.md +51 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/integration/fixture/hot/src/fixture/sdk.hot +23 -0
- hot_dev-1.3.0/integration/hot-server.ref +1 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/integration/run.sh +3 -10
- hot_dev-1.3.0/integration/suborg_fixture.py +473 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/pyproject.toml +6 -5
- {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/__init__.py +2 -1
- hot_dev-1.3.0/src/hot/_streaming.py +565 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/_transport.py +90 -13
- {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/client.py +20 -1
- {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/errors.py +54 -2
- hot_dev-1.3.0/src/hot/resources.py +2075 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/openapi_operations.json +57 -34
- hot_dev-1.3.0/tests/test_deadlines.py +228 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_integration.py +54 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_openapi_coverage.py +31 -1
- hot_dev-1.3.0/tests/test_orgs.py +215 -0
- hot_dev-1.3.0/tests/test_reconnect_policy.py +295 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_resources.py +60 -1
- hot_dev-1.3.0/tests/test_run_correlation.py +346 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_runs.py +2 -6
- hot_dev-1.3.0/tests/test_suborg_integration.py +244 -0
- hot_dev-1.3.0/tests/test_transport.py +132 -0
- hot_dev-1.2.0/.github/workflows/ci.yml +0 -65
- hot_dev-1.2.0/PKG-INFO +0 -241
- hot_dev-1.2.0/README.md +0 -221
- hot_dev-1.2.0/integration/mint_key.py +0 -42
- hot_dev-1.2.0/src/hot/resources.py +0 -1647
- {hot_dev-1.2.0 → hot_dev-1.3.0}/.gitignore +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/LICENSE +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/NOTICE +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/integration/fixture/.env.example +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/integration/fixture/.gitignore +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/integration/fixture/hot.hot +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/py.typed +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/sse.py +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/src/hot/types.py +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_client.py +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_reconnect.py +0 -0
- {hot_dev-1.2.0 → hot_dev-1.3.0}/tests/test_tasks.py +0 -0
|
@@ -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@
|
|
22
|
+
uses: actions/checkout@v7
|
|
23
23
|
|
|
24
24
|
- name: Set up Python
|
|
25
|
-
uses: actions/setup-python@
|
|
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
|
|
25
|
-
(`pytest`), and build (`python -m build`) on
|
|
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
|
|
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,
|
|
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
|