chat-client-sdk 0.1.1__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.
@@ -0,0 +1,134 @@
1
+ Metadata-Version: 2.4
2
+ Name: chat-client-sdk
3
+ Version: 0.1.1
4
+ Summary: Python wrapper for the Rust chat client C ABI
5
+ License: MIT
6
+ Requires-Python: >=3.9
7
+ Description-Content-Type: text/markdown
8
+
9
+ # Python Chat SDK
10
+
11
+ This package wraps the Rust `chat-client-sdk` C ABI using only the Python standard library. It supports Windows, Linux, and macOS on x86-64 and ARM64. Starting with package version 0.1.1, PyPI releases include the native library automatically for Windows x86-64 and Linux x86-64 (glibc 2.39 or newer). Other OS/architecture combinations still need the matching native library in a `builds/` folder.
12
+
13
+ ## Install
14
+
15
+ ```sh
16
+ python -m pip install .
17
+ ```
18
+
19
+ Install the SDK from PyPI with `python -m pip install chat-client-sdk`. On Windows x86-64 and Linux x86-64 with glibc 2.39 or newer, pip selects a wheel that contains the matching native library. On macOS, ARM64, and older Linux distributions, follow the native-library placement steps below.
20
+
21
+ ### Publishing releases from GitLab
22
+
23
+ The repository's `.gitlab-ci.yml` builds and checks a source distribution, a pure Python fallback wheel, and bundled Windows x86-64 and Linux x86-64 wheels for merge requests and the default branch. It uploads them to PyPI only for a version tag such as `v0.1.1`, and rejects a tag that does not match `project.version` in this directory's `pyproject.toml`.
24
+
25
+ Set up PyPI Trusted Publishing once for the PyPI project (no long-lived PyPI token is needed):
26
+
27
+ 1. On PyPI, add a Trusted Publisher for GitLab.com. If the package does not exist yet, create a pending publisher under your PyPI account's publishing settings.
28
+ 2. Set the GitLab namespace to `soberonlineemail-group`, repository to `chat-subsystem`, workflow filename to `.gitlab-ci.yml`, and environment to `pypi`.
29
+ 3. Set the package version in `pyproject.toml`, commit the change, then push a matching tag. For example, after setting the version to `0.1.2`:
30
+
31
+ ```sh
32
+ git tag v0.1.2
33
+ git push origin v0.1.2
34
+ ```
35
+
36
+ GitLab runs the packaging job first, then uses its OIDC identity to upload the artifacts. Protect release tags in GitLab so only maintainers can trigger a publish. Each version can be uploaded to PyPI only once.
37
+
38
+ The x86-64 Windows and Linux wheels bundle their native library. The pure wheel remains available as a fallback for macOS and ARM64; those platforms still use separately distributed Rust `.dll`, `.so`, or `.dylib` builds.
39
+
40
+ Place the native library for each platform you distribute in an OS/architecture subfolder beneath the application's `builds/` directory:
41
+
42
+ ```text
43
+ your-project/
44
+ builds/
45
+ windows-x86_64/chat_client_sdk.dll
46
+ windows-aarch64/chat_client_sdk.dll
47
+ linux-x86_64/libchat_client_sdk.so
48
+ linux-aarch64/libchat_client_sdk.so
49
+ darwin-x86_64/libchat_client_sdk.dylib
50
+ darwin-aarch64/libchat_client_sdk.dylib
51
+ app.py
52
+ ```
53
+
54
+ The SDK chooses the matching subfolder automatically. A library placed directly in `builds/` is also accepted. When using this source checkout, `python-sdk/builds/` is checked too. If no local library is found, initialization downloads the version-matched Windows x86-64 or Linux x86-64 wheel from PyPI, verifies the wheel and library SHA-256 hashes, and places the library in `./builds/<os>-<arch>/`. If that directory is not writable, it uses the user's cache directory. Automatic downloads for macOS and ARM64 will be enabled when matching release binaries are available.
55
+
56
+ Set `auto_download=False` on `ChatClient` or `CHAT_SDK_AUTO_DOWNLOAD=0` to disable downloads, for example in offline environments. Set `CHAT_SDK_NATIVE_DIR` to choose a writable builds directory. Advanced users can override library discovery with `CHAT_SDK_LIBRARY` or `library_path`:
57
+
58
+ ```powershell
59
+ $env:CHAT_SDK_LIBRARY = "C:\path\to\chat_client_sdk.dll"
60
+ ```
61
+
62
+ ```sh
63
+ export CHAT_SDK_LIBRARY=/path/to/libchat_client_sdk.so
64
+ ```
65
+
66
+ ## Use
67
+
68
+ ```python
69
+ from chat_sdk import ChatClient
70
+
71
+ with ChatClient(url="ws://127.0.0.1:8080/ws", bearer_token="alice-token") as chat:
72
+ request, accepted = chat.send_message_and_wait(
73
+ "<conversation-uuid>",
74
+ "Hello from Python",
75
+ )
76
+ print("persisted as:", accepted["data"]["message_id"])
77
+ print("correlation key:", request.idempotency_key)
78
+ ```
79
+
80
+ Passing `url` and `bearer_token` connects immediately and starts the event pump for you. `send_message_and_wait()` returns after persistence is acknowledged. `send_event(event_type, data)` sends any version 1 event from the protocol. `receive()` returns a decoded server event dictionary or `None` when no event arrives before its timeout. The background pump is the only native socket reader; concurrent `receive()` and `wait_for_ack()` calls are routed safely. Concurrent sends are serialized through a bounded queue. If the event queue fills, the pump applies backpressure instead of dropping events. `receive()` calls distribute events between concurrent consumers. Retrying a message after a timeout must reuse its `idempotency_key`; duplicate live message events are deduplicated by conversation sequence within a bounded cache of the most recent 8,192 messages per client instance. WSS connections use the Rust SDK's bundled WebPKI root certificates.
81
+
82
+ Create a conversation with `create_conversation(user_ids)` after connecting as one of its participants. It returns the server-generated `conversation_id`; save that ID in your application's database and reuse it when reopening the chat. An async version, `create_conversation_async(user_ids)`, is also available. In production, your backend should call this endpoint after it has decided that the participants are allowed to chat.
83
+
84
+ The synchronous API can also be used from asyncio without blocking the event loop:
85
+
86
+ ```python
87
+ import asyncio
88
+ from chat_sdk import ChatClient
89
+
90
+ async def main():
91
+ async with ChatClient() as chat:
92
+ await chat.aconnect("wss://chat.example.com/ws", "alice-token")
93
+ sent, accepted = await chat.send_message_and_wait_async(
94
+ "<conversation-uuid>", "Hello from asyncio"
95
+ )
96
+ print(sent.idempotency_key, accepted["data"]["sequence"])
97
+ event = await chat.receive_async(timeout_ms=1000)
98
+
99
+ asyncio.run(main())
100
+ ```
101
+
102
+ These async methods run the blocking C ABI and HTTP calls in worker threads; they keep the asyncio loop responsive but do not turn the native C ABI into a nonblocking socket API. Network errors and server slow-consumer disconnects are reported to the caller. Reconnect explicitly with `await chat.aconnect(...)`, then request missed conversation history using the protocol's `history` event and your last confirmed sequence.
103
+
104
+ For a short-lived token refresh, ask your backend for a new token after a connection error, then call `chat.reconnect(url, new_token, {conversation_id: last_saved_sequence})`. The helper reconnects and sends one history request per conversation. Use `await chat.areconnect(...)` from asyncio. Save your sequence only after your app has handled the corresponding message.
105
+
106
+ Conversation setup is repeat-safe with `ensure_conversation(external_key, user_ids)`. Choose a stable key from your app record, such as `tenant-12:support-ticket:4812`, and save the returned ID. Calling it again with the same participants returns the same conversation. Using that key with different participants returns a conflict.
107
+
108
+ ## Attachments
109
+
110
+ The native library handles WebSocket traffic. Attachment bytes use the server's HTTP endpoints and are handled by Python's standard library:
111
+
112
+ ```python
113
+ with ChatClient(url="wss://chat.example.com/ws", bearer_token="alice-token") as chat:
114
+ attachment = chat.upload_attachment(
115
+ "<conversation-uuid>", "photo.jpg", content_type="image/jpeg"
116
+ )
117
+ send, _accepted = chat.send_message_and_wait(
118
+ "<conversation-uuid>",
119
+ "Photo",
120
+ attachments=[attachment["attachment_id"]],
121
+ )
122
+ # For a received message, use its attachment reference's `download` path:
123
+ # chat.download_attachment(reference["download"], "downloads/photo.jpg")
124
+ ```
125
+
126
+ Uploads and downloads follow the server's 10 MiB limit and membership checks. Upload MIME type is inferred from the filename unless supplied explicitly.
127
+
128
+ ## Native runtime requirements
129
+
130
+ - Linux `.so`: GitHub Actions builds target glibc 2.35 on x86-64 and ARM64. The checked-in x86-64 library in this workspace was built on glibc 2.39 and requires glibc 2.39 or newer; use the CI artifact for older distributions.
131
+ - Windows `.dll`: x64 or ARM64 Windows and the matching Microsoft Visual C++ runtime.
132
+ - macOS `.dylib`: x86-64 or ARM64 macOS.
133
+
134
+ See `../crates/client-sdk/include/chat_sdk.h` for the underlying C ABI.
@@ -0,0 +1,126 @@
1
+ # Python Chat SDK
2
+
3
+ This package wraps the Rust `chat-client-sdk` C ABI using only the Python standard library. It supports Windows, Linux, and macOS on x86-64 and ARM64. Starting with package version 0.1.1, PyPI releases include the native library automatically for Windows x86-64 and Linux x86-64 (glibc 2.39 or newer). Other OS/architecture combinations still need the matching native library in a `builds/` folder.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ python -m pip install .
9
+ ```
10
+
11
+ Install the SDK from PyPI with `python -m pip install chat-client-sdk`. On Windows x86-64 and Linux x86-64 with glibc 2.39 or newer, pip selects a wheel that contains the matching native library. On macOS, ARM64, and older Linux distributions, follow the native-library placement steps below.
12
+
13
+ ### Publishing releases from GitLab
14
+
15
+ The repository's `.gitlab-ci.yml` builds and checks a source distribution, a pure Python fallback wheel, and bundled Windows x86-64 and Linux x86-64 wheels for merge requests and the default branch. It uploads them to PyPI only for a version tag such as `v0.1.1`, and rejects a tag that does not match `project.version` in this directory's `pyproject.toml`.
16
+
17
+ Set up PyPI Trusted Publishing once for the PyPI project (no long-lived PyPI token is needed):
18
+
19
+ 1. On PyPI, add a Trusted Publisher for GitLab.com. If the package does not exist yet, create a pending publisher under your PyPI account's publishing settings.
20
+ 2. Set the GitLab namespace to `soberonlineemail-group`, repository to `chat-subsystem`, workflow filename to `.gitlab-ci.yml`, and environment to `pypi`.
21
+ 3. Set the package version in `pyproject.toml`, commit the change, then push a matching tag. For example, after setting the version to `0.1.2`:
22
+
23
+ ```sh
24
+ git tag v0.1.2
25
+ git push origin v0.1.2
26
+ ```
27
+
28
+ GitLab runs the packaging job first, then uses its OIDC identity to upload the artifacts. Protect release tags in GitLab so only maintainers can trigger a publish. Each version can be uploaded to PyPI only once.
29
+
30
+ The x86-64 Windows and Linux wheels bundle their native library. The pure wheel remains available as a fallback for macOS and ARM64; those platforms still use separately distributed Rust `.dll`, `.so`, or `.dylib` builds.
31
+
32
+ Place the native library for each platform you distribute in an OS/architecture subfolder beneath the application's `builds/` directory:
33
+
34
+ ```text
35
+ your-project/
36
+ builds/
37
+ windows-x86_64/chat_client_sdk.dll
38
+ windows-aarch64/chat_client_sdk.dll
39
+ linux-x86_64/libchat_client_sdk.so
40
+ linux-aarch64/libchat_client_sdk.so
41
+ darwin-x86_64/libchat_client_sdk.dylib
42
+ darwin-aarch64/libchat_client_sdk.dylib
43
+ app.py
44
+ ```
45
+
46
+ The SDK chooses the matching subfolder automatically. A library placed directly in `builds/` is also accepted. When using this source checkout, `python-sdk/builds/` is checked too. If no local library is found, initialization downloads the version-matched Windows x86-64 or Linux x86-64 wheel from PyPI, verifies the wheel and library SHA-256 hashes, and places the library in `./builds/<os>-<arch>/`. If that directory is not writable, it uses the user's cache directory. Automatic downloads for macOS and ARM64 will be enabled when matching release binaries are available.
47
+
48
+ Set `auto_download=False` on `ChatClient` or `CHAT_SDK_AUTO_DOWNLOAD=0` to disable downloads, for example in offline environments. Set `CHAT_SDK_NATIVE_DIR` to choose a writable builds directory. Advanced users can override library discovery with `CHAT_SDK_LIBRARY` or `library_path`:
49
+
50
+ ```powershell
51
+ $env:CHAT_SDK_LIBRARY = "C:\path\to\chat_client_sdk.dll"
52
+ ```
53
+
54
+ ```sh
55
+ export CHAT_SDK_LIBRARY=/path/to/libchat_client_sdk.so
56
+ ```
57
+
58
+ ## Use
59
+
60
+ ```python
61
+ from chat_sdk import ChatClient
62
+
63
+ with ChatClient(url="ws://127.0.0.1:8080/ws", bearer_token="alice-token") as chat:
64
+ request, accepted = chat.send_message_and_wait(
65
+ "<conversation-uuid>",
66
+ "Hello from Python",
67
+ )
68
+ print("persisted as:", accepted["data"]["message_id"])
69
+ print("correlation key:", request.idempotency_key)
70
+ ```
71
+
72
+ Passing `url` and `bearer_token` connects immediately and starts the event pump for you. `send_message_and_wait()` returns after persistence is acknowledged. `send_event(event_type, data)` sends any version 1 event from the protocol. `receive()` returns a decoded server event dictionary or `None` when no event arrives before its timeout. The background pump is the only native socket reader; concurrent `receive()` and `wait_for_ack()` calls are routed safely. Concurrent sends are serialized through a bounded queue. If the event queue fills, the pump applies backpressure instead of dropping events. `receive()` calls distribute events between concurrent consumers. Retrying a message after a timeout must reuse its `idempotency_key`; duplicate live message events are deduplicated by conversation sequence within a bounded cache of the most recent 8,192 messages per client instance. WSS connections use the Rust SDK's bundled WebPKI root certificates.
73
+
74
+ Create a conversation with `create_conversation(user_ids)` after connecting as one of its participants. It returns the server-generated `conversation_id`; save that ID in your application's database and reuse it when reopening the chat. An async version, `create_conversation_async(user_ids)`, is also available. In production, your backend should call this endpoint after it has decided that the participants are allowed to chat.
75
+
76
+ The synchronous API can also be used from asyncio without blocking the event loop:
77
+
78
+ ```python
79
+ import asyncio
80
+ from chat_sdk import ChatClient
81
+
82
+ async def main():
83
+ async with ChatClient() as chat:
84
+ await chat.aconnect("wss://chat.example.com/ws", "alice-token")
85
+ sent, accepted = await chat.send_message_and_wait_async(
86
+ "<conversation-uuid>", "Hello from asyncio"
87
+ )
88
+ print(sent.idempotency_key, accepted["data"]["sequence"])
89
+ event = await chat.receive_async(timeout_ms=1000)
90
+
91
+ asyncio.run(main())
92
+ ```
93
+
94
+ These async methods run the blocking C ABI and HTTP calls in worker threads; they keep the asyncio loop responsive but do not turn the native C ABI into a nonblocking socket API. Network errors and server slow-consumer disconnects are reported to the caller. Reconnect explicitly with `await chat.aconnect(...)`, then request missed conversation history using the protocol's `history` event and your last confirmed sequence.
95
+
96
+ For a short-lived token refresh, ask your backend for a new token after a connection error, then call `chat.reconnect(url, new_token, {conversation_id: last_saved_sequence})`. The helper reconnects and sends one history request per conversation. Use `await chat.areconnect(...)` from asyncio. Save your sequence only after your app has handled the corresponding message.
97
+
98
+ Conversation setup is repeat-safe with `ensure_conversation(external_key, user_ids)`. Choose a stable key from your app record, such as `tenant-12:support-ticket:4812`, and save the returned ID. Calling it again with the same participants returns the same conversation. Using that key with different participants returns a conflict.
99
+
100
+ ## Attachments
101
+
102
+ The native library handles WebSocket traffic. Attachment bytes use the server's HTTP endpoints and are handled by Python's standard library:
103
+
104
+ ```python
105
+ with ChatClient(url="wss://chat.example.com/ws", bearer_token="alice-token") as chat:
106
+ attachment = chat.upload_attachment(
107
+ "<conversation-uuid>", "photo.jpg", content_type="image/jpeg"
108
+ )
109
+ send, _accepted = chat.send_message_and_wait(
110
+ "<conversation-uuid>",
111
+ "Photo",
112
+ attachments=[attachment["attachment_id"]],
113
+ )
114
+ # For a received message, use its attachment reference's `download` path:
115
+ # chat.download_attachment(reference["download"], "downloads/photo.jpg")
116
+ ```
117
+
118
+ Uploads and downloads follow the server's 10 MiB limit and membership checks. Upload MIME type is inferred from the filename unless supplied explicitly.
119
+
120
+ ## Native runtime requirements
121
+
122
+ - Linux `.so`: GitHub Actions builds target glibc 2.35 on x86-64 and ARM64. The checked-in x86-64 library in this workspace was built on glibc 2.39 and requires glibc 2.39 or newer; use the CI artifact for older distributions.
123
+ - Windows `.dll`: x64 or ARM64 Windows and the matching Microsoft Visual C++ runtime.
124
+ - macOS `.dylib`: x86-64 or ARM64 macOS.
125
+
126
+ See `../crates/client-sdk/include/chat_sdk.h` for the underlying C ABI.
@@ -0,0 +1,21 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "chat-client-sdk"
7
+ version = "0.1.1"
8
+ description = "Python wrapper for the Rust chat client C ABI"
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = { text = "MIT" }
12
+ dependencies = []
13
+
14
+ [tool.setuptools]
15
+ package-dir = {"" = "src"}
16
+
17
+ [tool.setuptools.packages.find]
18
+ where = ["src"]
19
+
20
+ [tool.setuptools.package-data]
21
+ chat_sdk = ["builds/*.dll", "builds/*.so", "builds/*.dylib", "builds/*/*.dll", "builds/*/*.so", "builds/*/*.dylib"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,134 @@
1
+ Metadata-Version: 2.4
2
+ Name: chat-client-sdk
3
+ Version: 0.1.1
4
+ Summary: Python wrapper for the Rust chat client C ABI
5
+ License: MIT
6
+ Requires-Python: >=3.9
7
+ Description-Content-Type: text/markdown
8
+
9
+ # Python Chat SDK
10
+
11
+ This package wraps the Rust `chat-client-sdk` C ABI using only the Python standard library. It supports Windows, Linux, and macOS on x86-64 and ARM64. Starting with package version 0.1.1, PyPI releases include the native library automatically for Windows x86-64 and Linux x86-64 (glibc 2.39 or newer). Other OS/architecture combinations still need the matching native library in a `builds/` folder.
12
+
13
+ ## Install
14
+
15
+ ```sh
16
+ python -m pip install .
17
+ ```
18
+
19
+ Install the SDK from PyPI with `python -m pip install chat-client-sdk`. On Windows x86-64 and Linux x86-64 with glibc 2.39 or newer, pip selects a wheel that contains the matching native library. On macOS, ARM64, and older Linux distributions, follow the native-library placement steps below.
20
+
21
+ ### Publishing releases from GitLab
22
+
23
+ The repository's `.gitlab-ci.yml` builds and checks a source distribution, a pure Python fallback wheel, and bundled Windows x86-64 and Linux x86-64 wheels for merge requests and the default branch. It uploads them to PyPI only for a version tag such as `v0.1.1`, and rejects a tag that does not match `project.version` in this directory's `pyproject.toml`.
24
+
25
+ Set up PyPI Trusted Publishing once for the PyPI project (no long-lived PyPI token is needed):
26
+
27
+ 1. On PyPI, add a Trusted Publisher for GitLab.com. If the package does not exist yet, create a pending publisher under your PyPI account's publishing settings.
28
+ 2. Set the GitLab namespace to `soberonlineemail-group`, repository to `chat-subsystem`, workflow filename to `.gitlab-ci.yml`, and environment to `pypi`.
29
+ 3. Set the package version in `pyproject.toml`, commit the change, then push a matching tag. For example, after setting the version to `0.1.2`:
30
+
31
+ ```sh
32
+ git tag v0.1.2
33
+ git push origin v0.1.2
34
+ ```
35
+
36
+ GitLab runs the packaging job first, then uses its OIDC identity to upload the artifacts. Protect release tags in GitLab so only maintainers can trigger a publish. Each version can be uploaded to PyPI only once.
37
+
38
+ The x86-64 Windows and Linux wheels bundle their native library. The pure wheel remains available as a fallback for macOS and ARM64; those platforms still use separately distributed Rust `.dll`, `.so`, or `.dylib` builds.
39
+
40
+ Place the native library for each platform you distribute in an OS/architecture subfolder beneath the application's `builds/` directory:
41
+
42
+ ```text
43
+ your-project/
44
+ builds/
45
+ windows-x86_64/chat_client_sdk.dll
46
+ windows-aarch64/chat_client_sdk.dll
47
+ linux-x86_64/libchat_client_sdk.so
48
+ linux-aarch64/libchat_client_sdk.so
49
+ darwin-x86_64/libchat_client_sdk.dylib
50
+ darwin-aarch64/libchat_client_sdk.dylib
51
+ app.py
52
+ ```
53
+
54
+ The SDK chooses the matching subfolder automatically. A library placed directly in `builds/` is also accepted. When using this source checkout, `python-sdk/builds/` is checked too. If no local library is found, initialization downloads the version-matched Windows x86-64 or Linux x86-64 wheel from PyPI, verifies the wheel and library SHA-256 hashes, and places the library in `./builds/<os>-<arch>/`. If that directory is not writable, it uses the user's cache directory. Automatic downloads for macOS and ARM64 will be enabled when matching release binaries are available.
55
+
56
+ Set `auto_download=False` on `ChatClient` or `CHAT_SDK_AUTO_DOWNLOAD=0` to disable downloads, for example in offline environments. Set `CHAT_SDK_NATIVE_DIR` to choose a writable builds directory. Advanced users can override library discovery with `CHAT_SDK_LIBRARY` or `library_path`:
57
+
58
+ ```powershell
59
+ $env:CHAT_SDK_LIBRARY = "C:\path\to\chat_client_sdk.dll"
60
+ ```
61
+
62
+ ```sh
63
+ export CHAT_SDK_LIBRARY=/path/to/libchat_client_sdk.so
64
+ ```
65
+
66
+ ## Use
67
+
68
+ ```python
69
+ from chat_sdk import ChatClient
70
+
71
+ with ChatClient(url="ws://127.0.0.1:8080/ws", bearer_token="alice-token") as chat:
72
+ request, accepted = chat.send_message_and_wait(
73
+ "<conversation-uuid>",
74
+ "Hello from Python",
75
+ )
76
+ print("persisted as:", accepted["data"]["message_id"])
77
+ print("correlation key:", request.idempotency_key)
78
+ ```
79
+
80
+ Passing `url` and `bearer_token` connects immediately and starts the event pump for you. `send_message_and_wait()` returns after persistence is acknowledged. `send_event(event_type, data)` sends any version 1 event from the protocol. `receive()` returns a decoded server event dictionary or `None` when no event arrives before its timeout. The background pump is the only native socket reader; concurrent `receive()` and `wait_for_ack()` calls are routed safely. Concurrent sends are serialized through a bounded queue. If the event queue fills, the pump applies backpressure instead of dropping events. `receive()` calls distribute events between concurrent consumers. Retrying a message after a timeout must reuse its `idempotency_key`; duplicate live message events are deduplicated by conversation sequence within a bounded cache of the most recent 8,192 messages per client instance. WSS connections use the Rust SDK's bundled WebPKI root certificates.
81
+
82
+ Create a conversation with `create_conversation(user_ids)` after connecting as one of its participants. It returns the server-generated `conversation_id`; save that ID in your application's database and reuse it when reopening the chat. An async version, `create_conversation_async(user_ids)`, is also available. In production, your backend should call this endpoint after it has decided that the participants are allowed to chat.
83
+
84
+ The synchronous API can also be used from asyncio without blocking the event loop:
85
+
86
+ ```python
87
+ import asyncio
88
+ from chat_sdk import ChatClient
89
+
90
+ async def main():
91
+ async with ChatClient() as chat:
92
+ await chat.aconnect("wss://chat.example.com/ws", "alice-token")
93
+ sent, accepted = await chat.send_message_and_wait_async(
94
+ "<conversation-uuid>", "Hello from asyncio"
95
+ )
96
+ print(sent.idempotency_key, accepted["data"]["sequence"])
97
+ event = await chat.receive_async(timeout_ms=1000)
98
+
99
+ asyncio.run(main())
100
+ ```
101
+
102
+ These async methods run the blocking C ABI and HTTP calls in worker threads; they keep the asyncio loop responsive but do not turn the native C ABI into a nonblocking socket API. Network errors and server slow-consumer disconnects are reported to the caller. Reconnect explicitly with `await chat.aconnect(...)`, then request missed conversation history using the protocol's `history` event and your last confirmed sequence.
103
+
104
+ For a short-lived token refresh, ask your backend for a new token after a connection error, then call `chat.reconnect(url, new_token, {conversation_id: last_saved_sequence})`. The helper reconnects and sends one history request per conversation. Use `await chat.areconnect(...)` from asyncio. Save your sequence only after your app has handled the corresponding message.
105
+
106
+ Conversation setup is repeat-safe with `ensure_conversation(external_key, user_ids)`. Choose a stable key from your app record, such as `tenant-12:support-ticket:4812`, and save the returned ID. Calling it again with the same participants returns the same conversation. Using that key with different participants returns a conflict.
107
+
108
+ ## Attachments
109
+
110
+ The native library handles WebSocket traffic. Attachment bytes use the server's HTTP endpoints and are handled by Python's standard library:
111
+
112
+ ```python
113
+ with ChatClient(url="wss://chat.example.com/ws", bearer_token="alice-token") as chat:
114
+ attachment = chat.upload_attachment(
115
+ "<conversation-uuid>", "photo.jpg", content_type="image/jpeg"
116
+ )
117
+ send, _accepted = chat.send_message_and_wait(
118
+ "<conversation-uuid>",
119
+ "Photo",
120
+ attachments=[attachment["attachment_id"]],
121
+ )
122
+ # For a received message, use its attachment reference's `download` path:
123
+ # chat.download_attachment(reference["download"], "downloads/photo.jpg")
124
+ ```
125
+
126
+ Uploads and downloads follow the server's 10 MiB limit and membership checks. Upload MIME type is inferred from the filename unless supplied explicitly.
127
+
128
+ ## Native runtime requirements
129
+
130
+ - Linux `.so`: GitHub Actions builds target glibc 2.35 on x86-64 and ARM64. The checked-in x86-64 library in this workspace was built on glibc 2.39 and requires glibc 2.39 or newer; use the CI artifact for older distributions.
131
+ - Windows `.dll`: x64 or ARM64 Windows and the matching Microsoft Visual C++ runtime.
132
+ - macOS `.dylib`: x86-64 or ARM64 macOS.
133
+
134
+ See `../crates/client-sdk/include/chat_sdk.h` for the underlying C ABI.
@@ -0,0 +1,8 @@
1
+ README.md
2
+ pyproject.toml
3
+ src/chat_client_sdk.egg-info/PKG-INFO
4
+ src/chat_client_sdk.egg-info/SOURCES.txt
5
+ src/chat_client_sdk.egg-info/dependency_links.txt
6
+ src/chat_client_sdk.egg-info/top_level.txt
7
+ src/chat_sdk/__init__.py
8
+ tests/test_native_download.py