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.
- chatgpt_web_adapter-0.1.4/LICENSE +21 -0
- chatgpt_web_adapter-0.1.4/PKG-INFO +326 -0
- chatgpt_web_adapter-0.1.4/README.md +300 -0
- chatgpt_web_adapter-0.1.4/pyproject.toml +42 -0
- chatgpt_web_adapter-0.1.4/setup.cfg +4 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/__init__.py +129 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/approval_events.py +53 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/approval_policy.py +246 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/approval_types.py +303 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/attach.py +68 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/auth.py +141 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/client.py +1835 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/conversation_send.py +54 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/diagnostic_metrics.py +215 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/errors.py +19 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/exceptions.py +158 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/export.py +83 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/message_text.py +180 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/messages.py +201 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/model_detection.py +180 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/payload_builder.py +201 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/payload_validation.py +50 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/policy_approval.py +321 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/raw_payload.py +86 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/status.py +360 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/types.py +637 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter/wait.py +108 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter.egg-info/PKG-INFO +326 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter.egg-info/SOURCES.txt +62 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter.egg-info/dependency_links.txt +1 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter.egg-info/requires.txt +3 -0
- chatgpt_web_adapter-0.1.4/src/chatgpt_web_adapter.egg-info/top_level.txt +1 -0
- chatgpt_web_adapter-0.1.4/tests/test_approval_metrics_integration.py +32 -0
- chatgpt_web_adapter-0.1.4/tests/test_approval_policy.py +346 -0
- chatgpt_web_adapter-0.1.4/tests/test_approval_types.py +336 -0
- chatgpt_web_adapter-0.1.4/tests/test_attach_conversation.py +231 -0
- chatgpt_web_adapter-0.1.4/tests/test_attached_conversation.py +170 -0
- chatgpt_web_adapter-0.1.4/tests/test_auth.py +73 -0
- chatgpt_web_adapter-0.1.4/tests/test_chat_message.py +161 -0
- chatgpt_web_adapter-0.1.4/tests/test_chat_metrics.py +106 -0
- chatgpt_web_adapter-0.1.4/tests/test_client.py +1106 -0
- chatgpt_web_adapter-0.1.4/tests/test_conversation_ref.py +103 -0
- chatgpt_web_adapter-0.1.4/tests/test_conversation_status.py +155 -0
- chatgpt_web_adapter-0.1.4/tests/test_examples_pack.py +63 -0
- chatgpt_web_adapter-0.1.4/tests/test_export_conversation.py +168 -0
- chatgpt_web_adapter-0.1.4/tests/test_get_messages.py +505 -0
- chatgpt_web_adapter-0.1.4/tests/test_get_messages_model_metadata.py +54 -0
- chatgpt_web_adapter-0.1.4/tests/test_get_messages_text_extraction.py +66 -0
- chatgpt_web_adapter-0.1.4/tests/test_get_status.py +347 -0
- chatgpt_web_adapter-0.1.4/tests/test_message_text_extraction.py +140 -0
- chatgpt_web_adapter-0.1.4/tests/test_model_detection.py +210 -0
- chatgpt_web_adapter-0.1.4/tests/test_payload_builder.py +310 -0
- chatgpt_web_adapter-0.1.4/tests/test_payload_validation.py +127 -0
- chatgpt_web_adapter-0.1.4/tests/test_pending_approval.py +496 -0
- chatgpt_web_adapter-0.1.4/tests/test_policy_aware_approval.py +354 -0
- chatgpt_web_adapter-0.1.4/tests/test_public_api_surface.py +48 -0
- chatgpt_web_adapter-0.1.4/tests/test_raw_payload_docs.py +37 -0
- chatgpt_web_adapter-0.1.4/tests/test_readme_positioning.py +46 -0
- chatgpt_web_adapter-0.1.4/tests/test_rename_compatibility_docs.py +42 -0
- chatgpt_web_adapter-0.1.4/tests/test_request_error.py +54 -0
- chatgpt_web_adapter-0.1.4/tests/test_send_metrics.py +281 -0
- chatgpt_web_adapter-0.1.4/tests/test_send_payload.py +230 -0
- chatgpt_web_adapter-0.1.4/tests/test_send_to_conversation.py +191 -0
- 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
|
+
[](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
|
+
[](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"]
|