chatgpt-web-adapter 0.1.4__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 (64) hide show
  1. chatgpt_web_adapter-0.1.4/LICENSE +21 -0
  2. chatgpt_web_adapter-0.1.4/PKG-INFO +326 -0
  3. chatgpt_web_adapter-0.1.4/README.md +300 -0
  4. chatgpt_web_adapter-0.1.4/pyproject.toml +42 -0
  5. chatgpt_web_adapter-0.1.4/setup.cfg +4 -0
  6. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/__init__.py +129 -0
  7. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/approval_events.py +53 -0
  8. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/approval_policy.py +246 -0
  9. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/approval_types.py +303 -0
  10. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/attach.py +68 -0
  11. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/auth.py +141 -0
  12. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/client.py +1835 -0
  13. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/conversation_send.py +54 -0
  14. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/diagnostic_metrics.py +215 -0
  15. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/errors.py +19 -0
  16. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/exceptions.py +158 -0
  17. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/export.py +83 -0
  18. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/message_text.py +180 -0
  19. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/messages.py +201 -0
  20. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/model_detection.py +180 -0
  21. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/payload_builder.py +201 -0
  22. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/payload_validation.py +50 -0
  23. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/policy_approval.py +321 -0
  24. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/raw_payload.py +86 -0
  25. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/status.py +360 -0
  26. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/types.py +637 -0
  27. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/wait.py +108 -0
  28. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter.egg-info/PKG-INFO +326 -0
  29. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter.egg-info/SOURCES.txt +62 -0
  30. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter.egg-info/dependency_links.txt +1 -0
  31. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter.egg-info/requires.txt +3 -0
  32. chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter.egg-info/top_level.txt +1 -0
  33. chatgpt_web_adapter-0.1.4/tests/test_approval_metrics_integration.py +32 -0
  34. chatgpt_web_adapter-0.1.4/tests/test_approval_policy.py +346 -0
  35. chatgpt_web_adapter-0.1.4/tests/test_approval_types.py +336 -0
  36. chatgpt_web_adapter-0.1.4/tests/test_attach_conversation.py +231 -0
  37. chatgpt_web_adapter-0.1.4/tests/test_attached_conversation.py +170 -0
  38. chatgpt_web_adapter-0.1.4/tests/test_auth.py +73 -0
  39. chatgpt_web_adapter-0.1.4/tests/test_chat_message.py +161 -0
  40. chatgpt_web_adapter-0.1.4/tests/test_chat_metrics.py +106 -0
  41. chatgpt_web_adapter-0.1.4/tests/test_client.py +1106 -0
  42. chatgpt_web_adapter-0.1.4/tests/test_conversation_ref.py +103 -0
  43. chatgpt_web_adapter-0.1.4/tests/test_conversation_status.py +155 -0
  44. chatgpt_web_adapter-0.1.4/tests/test_examples_pack.py +63 -0
  45. chatgpt_web_adapter-0.1.4/tests/test_export_conversation.py +168 -0
  46. chatgpt_web_adapter-0.1.4/tests/test_get_messages.py +505 -0
  47. chatgpt_web_adapter-0.1.4/tests/test_get_messages_model_metadata.py +54 -0
  48. chatgpt_web_adapter-0.1.4/tests/test_get_messages_text_extraction.py +66 -0
  49. chatgpt_web_adapter-0.1.4/tests/test_get_status.py +347 -0
  50. chatgpt_web_adapter-0.1.4/tests/test_message_text_extraction.py +140 -0
  51. chatgpt_web_adapter-0.1.4/tests/test_model_detection.py +210 -0
  52. chatgpt_web_adapter-0.1.4/tests/test_payload_builder.py +310 -0
  53. chatgpt_web_adapter-0.1.4/tests/test_payload_validation.py +127 -0
  54. chatgpt_web_adapter-0.1.4/tests/test_pending_approval.py +496 -0
  55. chatgpt_web_adapter-0.1.4/tests/test_policy_aware_approval.py +354 -0
  56. chatgpt_web_adapter-0.1.4/tests/test_public_api_surface.py +48 -0
  57. chatgpt_web_adapter-0.1.4/tests/test_raw_payload_docs.py +37 -0
  58. chatgpt_web_adapter-0.1.4/tests/test_readme_positioning.py +46 -0
  59. chatgpt_web_adapter-0.1.4/tests/test_rename_compatibility_docs.py +42 -0
  60. chatgpt_web_adapter-0.1.4/tests/test_request_error.py +54 -0
  61. chatgpt_web_adapter-0.1.4/tests/test_send_metrics.py +281 -0
  62. chatgpt_web_adapter-0.1.4/tests/test_send_payload.py +230 -0
  63. chatgpt_web_adapter-0.1.4/tests/test_send_to_conversation.py +191 -0
  64. chatgpt_web_adapter-0.1.4/tests/test_wait_until_completed.py +302 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kymuco
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,326 @@
1
+ Metadata-Version: 2.4
2
+ Name: chatgpt-web-adapter
3
+ Version: 0.1.4
4
+ Summary: Python SDK for controlling existing ChatGPT web sessions without browser UI.
5
+ Author: kymuco
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/kymuco/chatgpt-web-adapter
8
+ Project-URL: Repository, https://github.com/kymuco/chatgpt-web-adapter
9
+ Project-URL: Issues, https://github.com/kymuco/chatgpt-web-adapter/issues
10
+ Project-URL: Changelog, https://github.com/kymuco/chatgpt-web-adapter/blob/main/CHANGELOG.md
11
+ Keywords: chatgpt,adapter,sdk,webchat
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Provides-Extra: test
24
+ Requires-Dist: pytest>=8; extra == "test"
25
+ Dynamic: license-file
26
+
27
+ # chatgpt-web-adapter
28
+
29
+ [![CI](https://github.com/kymuco/chatgpt-web-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/kymuco/chatgpt-web-adapter/actions/workflows/ci.yml)
30
+
31
+ Python SDK for controlling existing ChatGPT web sessions without browser UI.
32
+
33
+ > [!WARNING]
34
+ > Not the official OpenAI API.
35
+ > Uses an existing ChatGPT web session.
36
+ > Web backend behavior may change.
37
+
38
+ `chatgpt-web-adapter` is a small, dependency-free Python SDK for sending prompts, continuing conversations, reading conversation state, uploading images, and handling selected ChatGPT web workflows from Python.
39
+
40
+ It is designed for tools that already have valid ChatGPT web-session auth data and want to avoid driving the browser UI.
41
+
42
+ ## What This Is
43
+
44
+ `chatgpt-web-adapter` wraps the existing ChatGPT web backend behavior used by a logged-in web session. It focuses on reusable transport, request formatting, response parsing, and conversation helpers.
45
+
46
+ The package intentionally does not include the CLI, localization, auth capture, browser automation, or local chat-history management from `webchat-openai-cli`.
47
+
48
+ ## When It Is Useful
49
+
50
+ - controlling long ChatGPT conversations without loading the browser UI
51
+ - building local tools or CLIs on top of an existing ChatGPT web session
52
+ - continuing existing ChatGPT web conversations by id or URL
53
+ - streaming assistant tokens into terminal or app UIs
54
+ - reading messages and polling conversation status from Python
55
+ - uploading images through the web-session flow
56
+ - experimenting with browserless approval workflows
57
+
58
+ ## When Not To Use This
59
+
60
+ - when you need a stable, documented API contract
61
+ - when you need OpenAI-supported authentication and long-term platform guarantees
62
+ - when browser automation is acceptable and product-level UI behavior matters more than backend reuse
63
+ - when the workflow depends heavily on approval cards or other fast-changing connector behavior
64
+ - when your tool cannot tolerate breakage from undocumented `chatgpt.com` changes
65
+
66
+ ## What This Is Not
67
+
68
+ `chatgpt-web-adapter` is not:
69
+
70
+ - the official OpenAI API
71
+ - a replacement for the OpenAI Python SDK
72
+ - a login or auth-capture tool
73
+ - a browser automation framework
74
+ - a stable contract for undocumented ChatGPT web internals
75
+
76
+ ## Stable vs Experimental
77
+
78
+ The SDK has two support levels.
79
+
80
+ Stable core:
81
+
82
+ - `ChatGPTWebClient.send()`
83
+ - `send_to_conversation()`
84
+ - `attach_conversation()`
85
+ - `get_messages()`
86
+ - `get_status()`
87
+ - `wait_until_completed()`
88
+ - image upload for multimodal prompts
89
+
90
+ Experimental features:
91
+
92
+ - `approve_pending_action()`
93
+ - `wait_and_approve_pending_actions()`
94
+ - `send_and_auto_approve()`
95
+ - `PayloadBuilder`
96
+ - `validate_payload()`
97
+ - `send_payload()`
98
+
99
+ The stable core is the main surface intended for building tools on top of an existing ChatGPT web session. Experimental features are exposed because they are useful, but they rely more directly on changing web-client behavior.
100
+
101
+ ## Compatibility Policy
102
+
103
+ - Stable core APIs are the main compatibility target of the package.
104
+ - Experimental APIs may need faster iteration when the ChatGPT web client changes.
105
+ - A package release does not guarantee that undocumented web behavior on `chatgpt.com` has remained unchanged.
106
+ - When the site changes, experimental flows are expected to break before the stable core send/continue/read flows.
107
+
108
+ ## Known Failure Modes
109
+
110
+ - expired or mismatched session auth
111
+ - `accessToken`, cookies, and headers can drift out of sync
112
+ - changed anti-abuse requirements
113
+ - `chat-requirements`, proof-of-work, or Turnstile expectations can change
114
+ - changed backend payload schema
115
+ - send/continue flows can fail if required request fields move or change meaning
116
+ - changed SSE response shape
117
+ - token streaming, finish-reason parsing, or conversation-id extraction can break
118
+ - changed conversation payload schema
119
+ - attach, status, model detection, and message extraction depend on unstable fields
120
+ - changed upload flow
121
+ - file creation, upload, or attachment metadata contracts can shift
122
+ - changed approval protocol
123
+ - approval helpers are especially sensitive to connector and web-client changes
124
+
125
+ ## Features
126
+
127
+ - zero runtime Python dependencies
128
+ - sync `ChatGPTWebClient`
129
+ - streaming via `on_token` and structured events via `on_event`
130
+ - conversation continuation with returned conversation metadata
131
+ - attach/read/status helpers for existing conversations
132
+ - `auth_data.json` and `.env` auth loading
133
+ - image uploads from local paths, `Path`, URL, data URI, or raw bytes
134
+ - experimental browserless tool-approval helpers for web-agent flows
135
+ - experimental raw payload escape hatch for advanced users
136
+ - local `curl`-based transport for compatibility with stock Python
137
+
138
+ ## Requirements
139
+
140
+ - Python 3.10+
141
+ - system `curl` available in `PATH`
142
+ - valid `auth_data.json` with `accessToken`, or an optional `.env` fallback with `accessToken`
143
+
144
+ ## Install
145
+
146
+ ```bash
147
+ python -m pip install chatgpt-web-adapter
148
+ ```
149
+
150
+ For local development and tests:
151
+
152
+ ```bash
153
+ python -m pip install -e .[test]
154
+ pytest -q
155
+ ```
156
+
157
+ ## Quick Start
158
+
159
+ ```python
160
+ from chatgpt_web_adapter import ChatGPTWebClient
161
+
162
+ client = ChatGPTWebClient(auth_file="auth_data.json")
163
+
164
+ response = client.send(
165
+ "Give me a short summary of this project.",
166
+ model="gpt-4o-mini",
167
+ )
168
+
169
+ print(response.text)
170
+ ```
171
+
172
+ ## Authentication at a Glance
173
+
174
+ `chatgpt-web-adapter` does not log you in and does not capture auth by itself. It only reuses existing `chatgpt.com` web-session data.
175
+
176
+ Recommended `auth_data.json` shape:
177
+
178
+ ```json
179
+ {
180
+ "accessToken": "eyJhbGciOi...",
181
+ "cookies": {
182
+ "__Secure-next-auth.session-token": "..."
183
+ },
184
+ "headers": {
185
+ "user-agent": "Mozilla/5.0 ..."
186
+ }
187
+ }
188
+ ```
189
+
190
+ - `accessToken` is the ChatGPT web access token from your browser session. It is not an official OpenAI API key.
191
+ - `cookies` and `headers` should come from the same account/session as the token.
192
+ - `.env` is optional, not required. If present, `accessToken=...` is used only as a fallback when the file token is missing or expired.
193
+ - Older files that still use `api_key` are accepted for backward compatibility, but new examples and new files should use `accessToken`.
194
+ - If you need to generate this file, capture it with `webchat-openai-cli` and then reuse it here.
195
+
196
+ ## Common Workflows
197
+
198
+ ### Streaming Callback
199
+
200
+ ```python
201
+ from chatgpt_web_adapter import ChatGPTWebClient
202
+
203
+ client = ChatGPTWebClient(auth_file="auth_data.json")
204
+
205
+ response = client.send(
206
+ "Stream the answer token by token.",
207
+ on_token=lambda token: print(token, end="", flush=True),
208
+ )
209
+ ```
210
+
211
+ ### Continue an Existing ChatGPT Web Conversation
212
+
213
+ ```python
214
+ from chatgpt_web_adapter import ChatGPTWebClient
215
+
216
+ client = ChatGPTWebClient(auth_file="auth_data.json")
217
+
218
+ response = client.send_to_conversation(
219
+ "https://chatgpt.com/c/...",
220
+ "Continue from this point.",
221
+ )
222
+
223
+ print(response.text)
224
+ ```
225
+
226
+ `send_to_conversation()` attaches to the latest web conversation state, resolves the current parent message automatically, and preserves the detected model when possible. Model detection is best-effort because ChatGPT web payloads can change. If the model cannot be detected, the SDK uses the normal `send()` default model.
227
+
228
+ ### Continue from an SDK Response
229
+
230
+ ```python
231
+ from chatgpt_web_adapter import ChatGPTWebClient
232
+
233
+ client = ChatGPTWebClient(auth_file="auth_data.json")
234
+
235
+ first = client.send("Start a conversation.")
236
+ second = client.send(
237
+ "Continue it.",
238
+ conversation=first.conversation,
239
+ )
240
+ ```
241
+
242
+ Other common APIs:
243
+
244
+ - read conversation messages with `client.get_messages(...)`
245
+ - poll conversation status with `client.get_status(...)`
246
+ - wait for completion with `client.wait_until_completed(...)`
247
+ - approve selected tool flows with experimental `client.send_and_auto_approve(...)`
248
+ - inspect request latency with [examples/diagnose_latency.py](examples/diagnose_latency.py)
249
+
250
+ ## Examples
251
+
252
+ - [examples/basic_send.py](examples/basic_send.py) - send one prompt and print response metadata
253
+ - [examples/continue_saved.py](examples/continue_saved.py) - save `ChatConversation` metadata and continue later
254
+ - [examples/attach_existing.py](examples/attach_existing.py) - attach to an existing conversation URL or id
255
+ - [examples/read_messages.py](examples/read_messages.py) - read messages from an existing conversation
256
+ - [examples/status_polling.py](examples/status_polling.py) - poll conversation lifecycle status
257
+ - [examples/approve_tools.py](examples/approve_tools.py) - approve pending tool actions after review
258
+ - [examples/raw_payload.py](examples/raw_payload.py) - send an experimental raw web backend payload
259
+ - [examples/diagnose_latency.py](examples/diagnose_latency.py) - print request and streaming diagnostics
260
+ - [examples/github_auto_approve.py](examples/github_auto_approve.py) - specialized GitHub connector approval demo
261
+
262
+ ## Experimental Features
263
+
264
+ The SDK includes experimental browserless helpers for web-agent/tool approval flows:
265
+
266
+ - `approve_pending_action()`
267
+ - `wait_and_approve_pending_actions()`
268
+ - `send_and_auto_approve()`
269
+
270
+ These APIs are useful for ChatGPT web connector flows such as GitHub file creation, but they rely on reverse-engineered web behavior and should be treated as less stable than the base `send()` API.
271
+
272
+ Approval helpers are not a stable contract of this SDK. They are best-effort compatibility layers over changing ChatGPT web approval behavior and may require updates even when the base send/continue flows still work.
273
+
274
+ See [USAGE.md](USAGE.md) and [examples/github_auto_approve.py](examples/github_auto_approve.py).
275
+
276
+ The SDK also includes an experimental raw payload escape hatch for advanced users:
277
+
278
+ - `PayloadBuilder`
279
+ - `validate_payload()`
280
+ - `send_payload()`
281
+
282
+ See [docs/raw_payload.md](docs/raw_payload.md).
283
+
284
+ This API sends raw ChatGPT web backend payloads. It is not an official or stable API.
285
+
286
+ The example script includes:
287
+
288
+ - a neutral repository placeholder instead of a hard-coded demo repo
289
+ - live assistant token printing
290
+ - structured approval progress events
291
+
292
+ ## Auth Notes
293
+
294
+ This repository only consumes existing auth data. If you still need browser-based capture, generate `auth_data.json` with `webchat-openai-cli` first and then reuse it here.
295
+
296
+ ## Detailed Guide
297
+
298
+ For the full SDK walkthrough, including auth flows, `warmup()`, `temporary`, `web_search`, `reasoning_effort`, conversation continuation, image inputs, response objects, and error handling, see [USAGE.md](USAGE.md).
299
+
300
+ Operational docs:
301
+
302
+ - [docs/live_smoke_checklist.md](docs/live_smoke_checklist.md)
303
+ - [docs/release_checklist.md](docs/release_checklist.md)
304
+ - [docs/architecture.md](docs/architecture.md)
305
+ - [docs/building_on_top.md](docs/building_on_top.md)
306
+
307
+ ## Package Naming
308
+
309
+ Canonical package naming is:
310
+
311
+ - repository: `chatgpt-web-adapter`
312
+ - distribution: `chatgpt-web-adapter`
313
+ - import: `chatgpt_web_adapter`
314
+
315
+ See [docs/rename_compatibility.md](docs/rename_compatibility.md).
316
+
317
+ ## Status
318
+
319
+ Initial SDK baseline. The repository is intentionally small and focused on the transport layer first.
320
+ GitHub Actions validates tests on Python 3.10-3.13 across Ubuntu and Windows, and also checks that the package builds successfully.
321
+
322
+ Repository docs:
323
+
324
+ - [CONTRIBUTING.md](CONTRIBUTING.md)
325
+ - [SECURITY.md](SECURITY.md)
326
+ - [CHANGELOG.md](CHANGELOG.md)
@@ -0,0 +1,300 @@
1
+ # chatgpt-web-adapter
2
+
3
+ [![CI](https://github.com/kymuco/chatgpt-web-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/kymuco/chatgpt-web-adapter/actions/workflows/ci.yml)
4
+
5
+ Python SDK for controlling existing ChatGPT web sessions without browser UI.
6
+
7
+ > [!WARNING]
8
+ > Not the official OpenAI API.
9
+ > Uses an existing ChatGPT web session.
10
+ > Web backend behavior may change.
11
+
12
+ `chatgpt-web-adapter` is a small, dependency-free Python SDK for sending prompts, continuing conversations, reading conversation state, uploading images, and handling selected ChatGPT web workflows from Python.
13
+
14
+ It is designed for tools that already have valid ChatGPT web-session auth data and want to avoid driving the browser UI.
15
+
16
+ ## What This Is
17
+
18
+ `chatgpt-web-adapter` wraps the existing ChatGPT web backend behavior used by a logged-in web session. It focuses on reusable transport, request formatting, response parsing, and conversation helpers.
19
+
20
+ The package intentionally does not include the CLI, localization, auth capture, browser automation, or local chat-history management from `webchat-openai-cli`.
21
+
22
+ ## When It Is Useful
23
+
24
+ - controlling long ChatGPT conversations without loading the browser UI
25
+ - building local tools or CLIs on top of an existing ChatGPT web session
26
+ - continuing existing ChatGPT web conversations by id or URL
27
+ - streaming assistant tokens into terminal or app UIs
28
+ - reading messages and polling conversation status from Python
29
+ - uploading images through the web-session flow
30
+ - experimenting with browserless approval workflows
31
+
32
+ ## When Not To Use This
33
+
34
+ - when you need a stable, documented API contract
35
+ - when you need OpenAI-supported authentication and long-term platform guarantees
36
+ - when browser automation is acceptable and product-level UI behavior matters more than backend reuse
37
+ - when the workflow depends heavily on approval cards or other fast-changing connector behavior
38
+ - when your tool cannot tolerate breakage from undocumented `chatgpt.com` changes
39
+
40
+ ## What This Is Not
41
+
42
+ `chatgpt-web-adapter` is not:
43
+
44
+ - the official OpenAI API
45
+ - a replacement for the OpenAI Python SDK
46
+ - a login or auth-capture tool
47
+ - a browser automation framework
48
+ - a stable contract for undocumented ChatGPT web internals
49
+
50
+ ## Stable vs Experimental
51
+
52
+ The SDK has two support levels.
53
+
54
+ Stable core:
55
+
56
+ - `ChatGPTWebClient.send()`
57
+ - `send_to_conversation()`
58
+ - `attach_conversation()`
59
+ - `get_messages()`
60
+ - `get_status()`
61
+ - `wait_until_completed()`
62
+ - image upload for multimodal prompts
63
+
64
+ Experimental features:
65
+
66
+ - `approve_pending_action()`
67
+ - `wait_and_approve_pending_actions()`
68
+ - `send_and_auto_approve()`
69
+ - `PayloadBuilder`
70
+ - `validate_payload()`
71
+ - `send_payload()`
72
+
73
+ The stable core is the main surface intended for building tools on top of an existing ChatGPT web session. Experimental features are exposed because they are useful, but they rely more directly on changing web-client behavior.
74
+
75
+ ## Compatibility Policy
76
+
77
+ - Stable core APIs are the main compatibility target of the package.
78
+ - Experimental APIs may need faster iteration when the ChatGPT web client changes.
79
+ - A package release does not guarantee that undocumented web behavior on `chatgpt.com` has remained unchanged.
80
+ - When the site changes, experimental flows are expected to break before the stable core send/continue/read flows.
81
+
82
+ ## Known Failure Modes
83
+
84
+ - expired or mismatched session auth
85
+ - `accessToken`, cookies, and headers can drift out of sync
86
+ - changed anti-abuse requirements
87
+ - `chat-requirements`, proof-of-work, or Turnstile expectations can change
88
+ - changed backend payload schema
89
+ - send/continue flows can fail if required request fields move or change meaning
90
+ - changed SSE response shape
91
+ - token streaming, finish-reason parsing, or conversation-id extraction can break
92
+ - changed conversation payload schema
93
+ - attach, status, model detection, and message extraction depend on unstable fields
94
+ - changed upload flow
95
+ - file creation, upload, or attachment metadata contracts can shift
96
+ - changed approval protocol
97
+ - approval helpers are especially sensitive to connector and web-client changes
98
+
99
+ ## Features
100
+
101
+ - zero runtime Python dependencies
102
+ - sync `ChatGPTWebClient`
103
+ - streaming via `on_token` and structured events via `on_event`
104
+ - conversation continuation with returned conversation metadata
105
+ - attach/read/status helpers for existing conversations
106
+ - `auth_data.json` and `.env` auth loading
107
+ - image uploads from local paths, `Path`, URL, data URI, or raw bytes
108
+ - experimental browserless tool-approval helpers for web-agent flows
109
+ - experimental raw payload escape hatch for advanced users
110
+ - local `curl`-based transport for compatibility with stock Python
111
+
112
+ ## Requirements
113
+
114
+ - Python 3.10+
115
+ - system `curl` available in `PATH`
116
+ - valid `auth_data.json` with `accessToken`, or an optional `.env` fallback with `accessToken`
117
+
118
+ ## Install
119
+
120
+ ```bash
121
+ python -m pip install chatgpt-web-adapter
122
+ ```
123
+
124
+ For local development and tests:
125
+
126
+ ```bash
127
+ python -m pip install -e .[test]
128
+ pytest -q
129
+ ```
130
+
131
+ ## Quick Start
132
+
133
+ ```python
134
+ from chatgpt_web_adapter import ChatGPTWebClient
135
+
136
+ client = ChatGPTWebClient(auth_file="auth_data.json")
137
+
138
+ response = client.send(
139
+ "Give me a short summary of this project.",
140
+ model="gpt-4o-mini",
141
+ )
142
+
143
+ print(response.text)
144
+ ```
145
+
146
+ ## Authentication at a Glance
147
+
148
+ `chatgpt-web-adapter` does not log you in and does not capture auth by itself. It only reuses existing `chatgpt.com` web-session data.
149
+
150
+ Recommended `auth_data.json` shape:
151
+
152
+ ```json
153
+ {
154
+ "accessToken": "eyJhbGciOi...",
155
+ "cookies": {
156
+ "__Secure-next-auth.session-token": "..."
157
+ },
158
+ "headers": {
159
+ "user-agent": "Mozilla/5.0 ..."
160
+ }
161
+ }
162
+ ```
163
+
164
+ - `accessToken` is the ChatGPT web access token from your browser session. It is not an official OpenAI API key.
165
+ - `cookies` and `headers` should come from the same account/session as the token.
166
+ - `.env` is optional, not required. If present, `accessToken=...` is used only as a fallback when the file token is missing or expired.
167
+ - Older files that still use `api_key` are accepted for backward compatibility, but new examples and new files should use `accessToken`.
168
+ - If you need to generate this file, capture it with `webchat-openai-cli` and then reuse it here.
169
+
170
+ ## Common Workflows
171
+
172
+ ### Streaming Callback
173
+
174
+ ```python
175
+ from chatgpt_web_adapter import ChatGPTWebClient
176
+
177
+ client = ChatGPTWebClient(auth_file="auth_data.json")
178
+
179
+ response = client.send(
180
+ "Stream the answer token by token.",
181
+ on_token=lambda token: print(token, end="", flush=True),
182
+ )
183
+ ```
184
+
185
+ ### Continue an Existing ChatGPT Web Conversation
186
+
187
+ ```python
188
+ from chatgpt_web_adapter import ChatGPTWebClient
189
+
190
+ client = ChatGPTWebClient(auth_file="auth_data.json")
191
+
192
+ response = client.send_to_conversation(
193
+ "https://chatgpt.com/c/...",
194
+ "Continue from this point.",
195
+ )
196
+
197
+ print(response.text)
198
+ ```
199
+
200
+ `send_to_conversation()` attaches to the latest web conversation state, resolves the current parent message automatically, and preserves the detected model when possible. Model detection is best-effort because ChatGPT web payloads can change. If the model cannot be detected, the SDK uses the normal `send()` default model.
201
+
202
+ ### Continue from an SDK Response
203
+
204
+ ```python
205
+ from chatgpt_web_adapter import ChatGPTWebClient
206
+
207
+ client = ChatGPTWebClient(auth_file="auth_data.json")
208
+
209
+ first = client.send("Start a conversation.")
210
+ second = client.send(
211
+ "Continue it.",
212
+ conversation=first.conversation,
213
+ )
214
+ ```
215
+
216
+ Other common APIs:
217
+
218
+ - read conversation messages with `client.get_messages(...)`
219
+ - poll conversation status with `client.get_status(...)`
220
+ - wait for completion with `client.wait_until_completed(...)`
221
+ - approve selected tool flows with experimental `client.send_and_auto_approve(...)`
222
+ - inspect request latency with [examples/diagnose_latency.py](examples/diagnose_latency.py)
223
+
224
+ ## Examples
225
+
226
+ - [examples/basic_send.py](examples/basic_send.py) - send one prompt and print response metadata
227
+ - [examples/continue_saved.py](examples/continue_saved.py) - save `ChatConversation` metadata and continue later
228
+ - [examples/attach_existing.py](examples/attach_existing.py) - attach to an existing conversation URL or id
229
+ - [examples/read_messages.py](examples/read_messages.py) - read messages from an existing conversation
230
+ - [examples/status_polling.py](examples/status_polling.py) - poll conversation lifecycle status
231
+ - [examples/approve_tools.py](examples/approve_tools.py) - approve pending tool actions after review
232
+ - [examples/raw_payload.py](examples/raw_payload.py) - send an experimental raw web backend payload
233
+ - [examples/diagnose_latency.py](examples/diagnose_latency.py) - print request and streaming diagnostics
234
+ - [examples/github_auto_approve.py](examples/github_auto_approve.py) - specialized GitHub connector approval demo
235
+
236
+ ## Experimental Features
237
+
238
+ The SDK includes experimental browserless helpers for web-agent/tool approval flows:
239
+
240
+ - `approve_pending_action()`
241
+ - `wait_and_approve_pending_actions()`
242
+ - `send_and_auto_approve()`
243
+
244
+ These APIs are useful for ChatGPT web connector flows such as GitHub file creation, but they rely on reverse-engineered web behavior and should be treated as less stable than the base `send()` API.
245
+
246
+ Approval helpers are not a stable contract of this SDK. They are best-effort compatibility layers over changing ChatGPT web approval behavior and may require updates even when the base send/continue flows still work.
247
+
248
+ See [USAGE.md](USAGE.md) and [examples/github_auto_approve.py](examples/github_auto_approve.py).
249
+
250
+ The SDK also includes an experimental raw payload escape hatch for advanced users:
251
+
252
+ - `PayloadBuilder`
253
+ - `validate_payload()`
254
+ - `send_payload()`
255
+
256
+ See [docs/raw_payload.md](docs/raw_payload.md).
257
+
258
+ This API sends raw ChatGPT web backend payloads. It is not an official or stable API.
259
+
260
+ The example script includes:
261
+
262
+ - a neutral repository placeholder instead of a hard-coded demo repo
263
+ - live assistant token printing
264
+ - structured approval progress events
265
+
266
+ ## Auth Notes
267
+
268
+ This repository only consumes existing auth data. If you still need browser-based capture, generate `auth_data.json` with `webchat-openai-cli` first and then reuse it here.
269
+
270
+ ## Detailed Guide
271
+
272
+ For the full SDK walkthrough, including auth flows, `warmup()`, `temporary`, `web_search`, `reasoning_effort`, conversation continuation, image inputs, response objects, and error handling, see [USAGE.md](USAGE.md).
273
+
274
+ Operational docs:
275
+
276
+ - [docs/live_smoke_checklist.md](docs/live_smoke_checklist.md)
277
+ - [docs/release_checklist.md](docs/release_checklist.md)
278
+ - [docs/architecture.md](docs/architecture.md)
279
+ - [docs/building_on_top.md](docs/building_on_top.md)
280
+
281
+ ## Package Naming
282
+
283
+ Canonical package naming is:
284
+
285
+ - repository: `chatgpt-web-adapter`
286
+ - distribution: `chatgpt-web-adapter`
287
+ - import: `chatgpt_web_adapter`
288
+
289
+ See [docs/rename_compatibility.md](docs/rename_compatibility.md).
290
+
291
+ ## Status
292
+
293
+ Initial SDK baseline. The repository is intentionally small and focused on the transport layer first.
294
+ GitHub Actions validates tests on Python 3.10-3.13 across Ubuntu and Windows, and also checks that the package builds successfully.
295
+
296
+ Repository docs:
297
+
298
+ - [CONTRIBUTING.md](CONTRIBUTING.md)
299
+ - [SECURITY.md](SECURITY.md)
300
+ - [CHANGELOG.md](CHANGELOG.md)
@@ -0,0 +1,42 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "chatgpt-web-adapter"
7
+ version = "0.1.4"
8
+ description = "Python SDK for controlling existing ChatGPT web sessions without browser UI."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [
14
+ { name = "kymuco" }
15
+ ]
16
+ keywords = ["chatgpt", "adapter", "sdk", "webchat"]
17
+ classifiers = [
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3 :: Only",
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Programming Language :: Python :: 3.13",
24
+ "Operating System :: OS Independent",
25
+ "Topic :: Software Development :: Libraries :: Python Modules",
26
+ ]
27
+ dependencies = []
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/kymuco/chatgpt-web-adapter"
31
+ Repository = "https://github.com/kymuco/chatgpt-web-adapter"
32
+ Issues = "https://github.com/kymuco/chatgpt-web-adapter/issues"
33
+ Changelog = "https://github.com/kymuco/chatgpt-web-adapter/blob/main/CHANGELOG.md"
34
+
35
+ [project.optional-dependencies]
36
+ test = ["pytest>=8"]
37
+
38
+ [tool.setuptools]
39
+ package-dir = { "" = "src" }
40
+
41
+ [tool.setuptools.packages.find]
42
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+