google-ai-mode-py 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- google_ai_mode_py-1.0.0/LICENSE +21 -0
- google_ai_mode_py-1.0.0/PKG-INFO +267 -0
- google_ai_mode_py-1.0.0/README.md +230 -0
- google_ai_mode_py-1.0.0/pyproject.toml +64 -0
- google_ai_mode_py-1.0.0/setup.cfg +4 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/__about__.py +3 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/__init__.py +70 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/__main__.py +6 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/api.py +1002 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/browserless.py +291 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/cli.py +202 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/client.py +596 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/clipboard.py +127 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/config.py +230 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/constants.py +67 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/cookies.py +115 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/exceptions.py +34 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/models.py +62 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/parser.py +502 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/storage.py +208 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py/tui.py +1656 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py.egg-info/PKG-INFO +267 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py.egg-info/SOURCES.txt +32 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py.egg-info/dependency_links.txt +1 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py.egg-info/entry_points.txt +4 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py.egg-info/requires.txt +12 -0
- google_ai_mode_py-1.0.0/src/google_ai_mode_py.egg-info/top_level.txt +1 -0
- google_ai_mode_py-1.0.0/tests/test_api_and_clipboard.py +187 -0
- google_ai_mode_py-1.0.0/tests/test_client_and_browserless.py +262 -0
- google_ai_mode_py-1.0.0/tests/test_config_cookies_storage.py +100 -0
- google_ai_mode_py-1.0.0/tests/test_live_integration.py +43 -0
- google_ai_mode_py-1.0.0/tests/test_parser.py +125 -0
- google_ai_mode_py-1.0.0/tests/test_tui_and_cli.py +293 -0
- google_ai_mode_py-1.0.0/tests/test_zero_comments.py +70 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tej
|
|
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,267 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: google-ai-mode-py
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Request-based Python client, FastAPI server, and animated terminal UI for Google AI Mode
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/tejzv/google-ai-mode-py
|
|
7
|
+
Project-URL: Repository, https://github.com/tejzv/google-ai-mode-py
|
|
8
|
+
Project-URL: Issues, https://github.com/tejzv/google-ai-mode-py/issues
|
|
9
|
+
Project-URL: Releases, https://github.com/tejzv/google-ai-mode-py/releases
|
|
10
|
+
Keywords: google,ai-mode,search,fastapi,cli,tui,async,http
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: curl_cffi>=0.11.0
|
|
26
|
+
Requires-Dist: beautifulsoup4>=4.12.0
|
|
27
|
+
Requires-Dist: rich>=13.7.0
|
|
28
|
+
Requires-Dist: fastapi>=0.115.0
|
|
29
|
+
Requires-Dist: uvicorn>=0.30.0
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pytest>=8.0.0; extra == "dev"
|
|
32
|
+
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
|
|
33
|
+
Requires-Dist: httpx>=0.27.0; extra == "dev"
|
|
34
|
+
Requires-Dist: build>=1.0.0; extra == "dev"
|
|
35
|
+
Requires-Dist: twine>=5.0.0; extra == "dev"
|
|
36
|
+
Dynamic: license-file
|
|
37
|
+
|
|
38
|
+
<div align="center">
|
|
39
|
+
|
|
40
|
+
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:0b090c,55:7a1628,100:ff4d6d&height=190§ion=header&text=google-ai-mode-py&fontSize=54&fontColor=ffffff&animation=fadeIn&fontAlignY=38&desc=Request-Based%20Google%20AI%20Mode%20%E2%80%A2%20FastAPI%20%E2%80%A2%20Terminal%20UI&descAlignY=62&descSize=17" width="100%" />
|
|
41
|
+
|
|
42
|
+
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=500&size=18&duration=2800&pause=1000&color=FF8FA3¢er=true&vCenter=true&width=680&lines=Direct+HTTP+Client+%E2%80%A2+Multi-Turn+Sessions;FastAPI+REST+%2B+%2Fv1%2Fchat%2Fcompletions+%2B+Web+UI;Terminal+Chat+%E2%80%A2+Incognito+Mode+%E2%80%A2+Auto-Saved+Chats" alt="google-ai-mode-py Highlights" />
|
|
43
|
+
|
|
44
|
+
<p>
|
|
45
|
+
<a href="https://pypi.org/project/google-ai-mode-py/"><img src="https://img.shields.io/badge/PyPI-google--ai--mode--py-3775A9?style=for-the-badge&logo=pypi&logoColor=white" /></a>
|
|
46
|
+
<img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" />
|
|
47
|
+
<img src="https://img.shields.io/badge/FastAPI-OpenAI_Compat-009688?style=for-the-badge&logo=fastapi&logoColor=white" />
|
|
48
|
+
<img src="https://img.shields.io/badge/Windows-aimode.exe-0078D4?style=for-the-badge&logo=windows&logoColor=white" />
|
|
49
|
+
<a href="https://github.com/tejzv/google-ai-mode-py/releases/latest"><img src="https://img.shields.io/badge/Release-v1.0.0-238636?style=for-the-badge&logo=github" /></a>
|
|
50
|
+
<img src="https://img.shields.io/badge/License-MIT-ffffff?style=for-the-badge" />
|
|
51
|
+
</p>
|
|
52
|
+
|
|
53
|
+
<br />
|
|
54
|
+
|
|
55
|
+
<img src="https://raw.githubusercontent.com/tejzv/google-ai-mode-py/main/assets/demo.gif" alt="google-ai-mode-py Interactive Demo" width="820" />
|
|
56
|
+
|
|
57
|
+
</div>
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Overview
|
|
62
|
+
|
|
63
|
+
**`google-ai-mode-py`** is a lightweight, request-based Python client, FastAPI server, and terminal chat interface for Google AI Mode using Chrome TLS impersonation (`curl_cffi`).
|
|
64
|
+
|
|
65
|
+
| Component | Details |
|
|
66
|
+
| :--- | :--- |
|
|
67
|
+
| **HTTP Client** | Direct `/search?udm=50`, `/async/folwr`, and single-request `/async/folif` multi-turn follow-ups |
|
|
68
|
+
| **FastAPI Server** | `/api/chat`, `/api/ask`, `/v1/chat/completions` (OpenAI-compatible JSON & SSE), Swagger `/docs`, and Web UI at `/` |
|
|
69
|
+
| **Terminal UI** | Non-blocking terminal chat with `/` autocomplete, Markdown styling, clickable links, clipboard Copy, and interactive `[ ⚇ Incognito ]` / `[ Lang ]` / `[ ↻ Restart ]` / `[ ✕ Quit ]` toolbar |
|
|
70
|
+
| **Rate-Limit Fallback** | Cookie reuse with interactive Browserless API key prompt (`Browserless (Proxy Provider)`) & `/stealth/bql` fallback on `429` or challenges |
|
|
71
|
+
| **Storage** | Automatic saving to `conversations/<conversation_id>.json` and Markdown export (skipped in `⚇ Incognito Mode`) |
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Inspiration
|
|
76
|
+
|
|
77
|
+
Inspired by **[`chrome-lens-py`](https://github.com/bropines/chrome-lens-py)** by **[bropines](https://github.com/bropines)** — a clean, lightweight request-based reverse-engineered Python library for Google Lens. Big thanks and credit for the architecture and inspiration.
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Install & Launch
|
|
82
|
+
|
|
83
|
+
### Python Package (PyPI)
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
pip install google-ai-mode-py
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Or install directly from GitHub:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
pip install git+https://github.com/tejzv/google-ai-mode-py.git
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Windows Binary ([Latest Release](https://github.com/tejzv/google-ai-mode-py/releases/latest))
|
|
96
|
+
|
|
97
|
+
Download **`aimode.exe`** from **[Releases → v1.0.0](https://github.com/tejzv/google-ai-mode-py/releases/latest)**:
|
|
98
|
+
|
|
99
|
+
```powershell
|
|
100
|
+
.\aimode.exe
|
|
101
|
+
.\aimode.exe --incognito
|
|
102
|
+
.\aimode.exe /api --port 8000
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### Windows One-Click Setup
|
|
106
|
+
|
|
107
|
+
```powershell
|
|
108
|
+
git clone https://github.com/tejzv/google-ai-mode-py.git
|
|
109
|
+
cd google-ai-mode-py
|
|
110
|
+
.\setup.bat
|
|
111
|
+
.\launch.bat
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Terminal & CLI
|
|
117
|
+
|
|
118
|
+
Start interactive chat or jump straight into Incognito Mode / the local API server:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
aimode
|
|
122
|
+
aimode --incognito
|
|
123
|
+
aimode /api
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
You can also invoke via `google-ai-mode-py` or `python -m google_ai_mode_py`.
|
|
127
|
+
|
|
128
|
+
Type `/` for live command recommendations (`Tab` to complete, `Up`/`Down` to select), click toolbar buttons (`[ ⚇ Incognito ]`, `[ Lang: en ]`, `[ ↻ Restart ]`, `[ ✕ Quit ]`), click `[ Copy ]`, or use keyboard shortcuts:
|
|
129
|
+
|
|
130
|
+
| Shortcut | Action |
|
|
131
|
+
| :--- | :--- |
|
|
132
|
+
| `F1` / `Ctrl+R` | Restart session & clear transcript |
|
|
133
|
+
| `F2` / `Ctrl+N` | Toggle `⚇ Incognito Mode` (chat is not saved) |
|
|
134
|
+
| `F3` / `Ctrl+L` | Switch reply language (`en` default) |
|
|
135
|
+
| `Ctrl+Y` | Copy the latest AI reply |
|
|
136
|
+
| `Ctrl+Q` / `Esc` | Quit |
|
|
137
|
+
|
|
138
|
+
Non-incognito chats save automatically to `conversations/<conversation_id>.json`.
|
|
139
|
+
|
|
140
|
+
One-shot queries:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
aimode "Explain how photosynthesis works"
|
|
144
|
+
aimode "What is the capital of Japan?" -f "What currency does it use?"
|
|
145
|
+
aimode "Compare Rust and Go briefly" --json --incognito
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Slash Commands
|
|
149
|
+
|
|
150
|
+
| Command | Action |
|
|
151
|
+
| :--- | :--- |
|
|
152
|
+
| `/api [port\|stop]` | Start or stop the FastAPI server (`127.0.0.1:8000` by default) |
|
|
153
|
+
| `/incognito [on\|off]` | Toggle `⚇ Incognito Mode` (chat is not saved) |
|
|
154
|
+
| `/lang [code]` | Cycle or set language (`en` default) |
|
|
155
|
+
| `/restart` | Restart session and clear transcript |
|
|
156
|
+
| `/new` | Start a new conversation |
|
|
157
|
+
| `/copy [n]` | Copy the latest or Nth AI reply |
|
|
158
|
+
| `/save [id]` | Save conversation JSON to `conversations/<id>.json` |
|
|
159
|
+
| `/export [path]` | Export conversation to Markdown |
|
|
160
|
+
| `/history` | List saved conversations |
|
|
161
|
+
| `/load <id>` | Resume a saved conversation |
|
|
162
|
+
| `/key <token>` | Save optional Browserless API key |
|
|
163
|
+
| `/country <code>` | Set preferred proxy country (`de`, `jp`, `fr`, `nl`, `sg`, `au`) |
|
|
164
|
+
| `/status` | Show cookie and session info |
|
|
165
|
+
| `/clear` | Clear chat viewport |
|
|
166
|
+
| `/exit` | Quit |
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## FastAPI Server & Web UI
|
|
171
|
+
|
|
172
|
+
Start the API server directly or run `/api` inside interactive chat:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
aimode /api --port 8000
|
|
176
|
+
aimode --api --host 127.0.0.1 --port 8000
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Open `http://127.0.0.1:8000` for the web chat interface (`⚇ Incognito`, `Lang`, `↻ Restart`, interactive rate-limit key prompt) or `http://127.0.0.1:8000/docs` for Swagger documentation.
|
|
180
|
+
|
|
181
|
+
| Endpoint | Method | Purpose |
|
|
182
|
+
| :--- | :--- | :--- |
|
|
183
|
+
| `/api/chat` | `POST` | Stateful multi-turn chat (`query`, `session_id`, `incognito`, `lang`) |
|
|
184
|
+
| `/api/ask` | `POST` | Query endpoint with optional session state & incognito flag |
|
|
185
|
+
| `/api/config` | `GET` | Read current language, key status, and supported languages |
|
|
186
|
+
| `/api/key` | `POST` | Persist Browserless API key (`api_key`) |
|
|
187
|
+
| `/api/lang` | `POST` | Switch reply language (`lang`) |
|
|
188
|
+
| `/v1/chat/completions` | `POST` | OpenAI-compatible chat completions (supports `stream: true`) |
|
|
189
|
+
| `/v1/models` | `GET` | Available model entries |
|
|
190
|
+
| `/api/conversations` | `GET` | Saved conversation list |
|
|
191
|
+
| `/health` | `GET` | Server health and uptime |
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
curl -X POST http://127.0.0.1:8000/api/chat \
|
|
195
|
+
-H "Content-Type: application/json" \
|
|
196
|
+
-d '{"query":"Summarize Python asyncio in 2 bullets","session_id":"demo"}'
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Python SDK
|
|
202
|
+
|
|
203
|
+
```python
|
|
204
|
+
import asyncio
|
|
205
|
+
from google_ai_mode_py import AIModeClient
|
|
206
|
+
|
|
207
|
+
async def main():
|
|
208
|
+
async with AIModeClient() as client:
|
|
209
|
+
first = await client.ask("What is the capital of Japan?")
|
|
210
|
+
print(first.markdown)
|
|
211
|
+
|
|
212
|
+
followup = await client.chat("What currency does it use?")
|
|
213
|
+
print(followup.text)
|
|
214
|
+
|
|
215
|
+
asyncio.run(main())
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
```python
|
|
219
|
+
from google_ai_mode_py import AIModeSession
|
|
220
|
+
|
|
221
|
+
with AIModeSession() as ai:
|
|
222
|
+
resp = ai.ask("Explain HTTP/2 multiplexing in 3 bullets")
|
|
223
|
+
print(resp.markdown)
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## Optional Rate-Limit Proxy
|
|
229
|
+
|
|
230
|
+
If you encounter a Google rate limit (`429` / challenge) without a configured key, both the terminal UI and Web UI display a clickable signup link for **[Browserless (Proxy Provider)](https://www.browserless.io/signup/email?plan=free)**, prompt for your API key, save it locally, and automatically retry the failed prompt.
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
aimode --set-key YOUR_BROWSERLESS_API_KEY
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## Tests & Build
|
|
239
|
+
|
|
240
|
+
```powershell
|
|
241
|
+
pytest -v -m "not network"
|
|
242
|
+
python -m build
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## Community & Support
|
|
248
|
+
|
|
249
|
+
- **Discord Server**: https://discord.gg/PYfeSaDGPJ
|
|
250
|
+
- **Contact**: [@sqnq](https://discord.com/users/987979957907116052)
|
|
251
|
+
- **Website**: [tejv.in](https://tejv.in)
|
|
252
|
+
|
|
253
|
+
### Buy Me A Coffee ☕
|
|
254
|
+
|
|
255
|
+
**Litecoin (LTC)**:
|
|
256
|
+
|
|
257
|
+
```text
|
|
258
|
+
LbDG5BE3foVsfK6JRsSc7UtBVX4DqYYKXN
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
<div align="center">
|
|
262
|
+
|
|
263
|
+
**Made With ♥️ By [tejzv](https://github.com/tejzv)**
|
|
264
|
+
|
|
265
|
+
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:0b090c,55:7a1628,100:ff4d6d&height=100§ion=footer" width="100%" />
|
|
266
|
+
|
|
267
|
+
</div>
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:0b090c,55:7a1628,100:ff4d6d&height=190§ion=header&text=google-ai-mode-py&fontSize=54&fontColor=ffffff&animation=fadeIn&fontAlignY=38&desc=Request-Based%20Google%20AI%20Mode%20%E2%80%A2%20FastAPI%20%E2%80%A2%20Terminal%20UI&descAlignY=62&descSize=17" width="100%" />
|
|
4
|
+
|
|
5
|
+
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=500&size=18&duration=2800&pause=1000&color=FF8FA3¢er=true&vCenter=true&width=680&lines=Direct+HTTP+Client+%E2%80%A2+Multi-Turn+Sessions;FastAPI+REST+%2B+%2Fv1%2Fchat%2Fcompletions+%2B+Web+UI;Terminal+Chat+%E2%80%A2+Incognito+Mode+%E2%80%A2+Auto-Saved+Chats" alt="google-ai-mode-py Highlights" />
|
|
6
|
+
|
|
7
|
+
<p>
|
|
8
|
+
<a href="https://pypi.org/project/google-ai-mode-py/"><img src="https://img.shields.io/badge/PyPI-google--ai--mode--py-3775A9?style=for-the-badge&logo=pypi&logoColor=white" /></a>
|
|
9
|
+
<img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" />
|
|
10
|
+
<img src="https://img.shields.io/badge/FastAPI-OpenAI_Compat-009688?style=for-the-badge&logo=fastapi&logoColor=white" />
|
|
11
|
+
<img src="https://img.shields.io/badge/Windows-aimode.exe-0078D4?style=for-the-badge&logo=windows&logoColor=white" />
|
|
12
|
+
<a href="https://github.com/tejzv/google-ai-mode-py/releases/latest"><img src="https://img.shields.io/badge/Release-v1.0.0-238636?style=for-the-badge&logo=github" /></a>
|
|
13
|
+
<img src="https://img.shields.io/badge/License-MIT-ffffff?style=for-the-badge" />
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
<br />
|
|
17
|
+
|
|
18
|
+
<img src="https://raw.githubusercontent.com/tejzv/google-ai-mode-py/main/assets/demo.gif" alt="google-ai-mode-py Interactive Demo" width="820" />
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Overview
|
|
25
|
+
|
|
26
|
+
**`google-ai-mode-py`** is a lightweight, request-based Python client, FastAPI server, and terminal chat interface for Google AI Mode using Chrome TLS impersonation (`curl_cffi`).
|
|
27
|
+
|
|
28
|
+
| Component | Details |
|
|
29
|
+
| :--- | :--- |
|
|
30
|
+
| **HTTP Client** | Direct `/search?udm=50`, `/async/folwr`, and single-request `/async/folif` multi-turn follow-ups |
|
|
31
|
+
| **FastAPI Server** | `/api/chat`, `/api/ask`, `/v1/chat/completions` (OpenAI-compatible JSON & SSE), Swagger `/docs`, and Web UI at `/` |
|
|
32
|
+
| **Terminal UI** | Non-blocking terminal chat with `/` autocomplete, Markdown styling, clickable links, clipboard Copy, and interactive `[ ⚇ Incognito ]` / `[ Lang ]` / `[ ↻ Restart ]` / `[ ✕ Quit ]` toolbar |
|
|
33
|
+
| **Rate-Limit Fallback** | Cookie reuse with interactive Browserless API key prompt (`Browserless (Proxy Provider)`) & `/stealth/bql` fallback on `429` or challenges |
|
|
34
|
+
| **Storage** | Automatic saving to `conversations/<conversation_id>.json` and Markdown export (skipped in `⚇ Incognito Mode`) |
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Inspiration
|
|
39
|
+
|
|
40
|
+
Inspired by **[`chrome-lens-py`](https://github.com/bropines/chrome-lens-py)** by **[bropines](https://github.com/bropines)** — a clean, lightweight request-based reverse-engineered Python library for Google Lens. Big thanks and credit for the architecture and inspiration.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Install & Launch
|
|
45
|
+
|
|
46
|
+
### Python Package (PyPI)
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
pip install google-ai-mode-py
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Or install directly from GitHub:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install git+https://github.com/tejzv/google-ai-mode-py.git
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Windows Binary ([Latest Release](https://github.com/tejzv/google-ai-mode-py/releases/latest))
|
|
59
|
+
|
|
60
|
+
Download **`aimode.exe`** from **[Releases → v1.0.0](https://github.com/tejzv/google-ai-mode-py/releases/latest)**:
|
|
61
|
+
|
|
62
|
+
```powershell
|
|
63
|
+
.\aimode.exe
|
|
64
|
+
.\aimode.exe --incognito
|
|
65
|
+
.\aimode.exe /api --port 8000
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Windows One-Click Setup
|
|
69
|
+
|
|
70
|
+
```powershell
|
|
71
|
+
git clone https://github.com/tejzv/google-ai-mode-py.git
|
|
72
|
+
cd google-ai-mode-py
|
|
73
|
+
.\setup.bat
|
|
74
|
+
.\launch.bat
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Terminal & CLI
|
|
80
|
+
|
|
81
|
+
Start interactive chat or jump straight into Incognito Mode / the local API server:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
aimode
|
|
85
|
+
aimode --incognito
|
|
86
|
+
aimode /api
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
You can also invoke via `google-ai-mode-py` or `python -m google_ai_mode_py`.
|
|
90
|
+
|
|
91
|
+
Type `/` for live command recommendations (`Tab` to complete, `Up`/`Down` to select), click toolbar buttons (`[ ⚇ Incognito ]`, `[ Lang: en ]`, `[ ↻ Restart ]`, `[ ✕ Quit ]`), click `[ Copy ]`, or use keyboard shortcuts:
|
|
92
|
+
|
|
93
|
+
| Shortcut | Action |
|
|
94
|
+
| :--- | :--- |
|
|
95
|
+
| `F1` / `Ctrl+R` | Restart session & clear transcript |
|
|
96
|
+
| `F2` / `Ctrl+N` | Toggle `⚇ Incognito Mode` (chat is not saved) |
|
|
97
|
+
| `F3` / `Ctrl+L` | Switch reply language (`en` default) |
|
|
98
|
+
| `Ctrl+Y` | Copy the latest AI reply |
|
|
99
|
+
| `Ctrl+Q` / `Esc` | Quit |
|
|
100
|
+
|
|
101
|
+
Non-incognito chats save automatically to `conversations/<conversation_id>.json`.
|
|
102
|
+
|
|
103
|
+
One-shot queries:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
aimode "Explain how photosynthesis works"
|
|
107
|
+
aimode "What is the capital of Japan?" -f "What currency does it use?"
|
|
108
|
+
aimode "Compare Rust and Go briefly" --json --incognito
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Slash Commands
|
|
112
|
+
|
|
113
|
+
| Command | Action |
|
|
114
|
+
| :--- | :--- |
|
|
115
|
+
| `/api [port\|stop]` | Start or stop the FastAPI server (`127.0.0.1:8000` by default) |
|
|
116
|
+
| `/incognito [on\|off]` | Toggle `⚇ Incognito Mode` (chat is not saved) |
|
|
117
|
+
| `/lang [code]` | Cycle or set language (`en` default) |
|
|
118
|
+
| `/restart` | Restart session and clear transcript |
|
|
119
|
+
| `/new` | Start a new conversation |
|
|
120
|
+
| `/copy [n]` | Copy the latest or Nth AI reply |
|
|
121
|
+
| `/save [id]` | Save conversation JSON to `conversations/<id>.json` |
|
|
122
|
+
| `/export [path]` | Export conversation to Markdown |
|
|
123
|
+
| `/history` | List saved conversations |
|
|
124
|
+
| `/load <id>` | Resume a saved conversation |
|
|
125
|
+
| `/key <token>` | Save optional Browserless API key |
|
|
126
|
+
| `/country <code>` | Set preferred proxy country (`de`, `jp`, `fr`, `nl`, `sg`, `au`) |
|
|
127
|
+
| `/status` | Show cookie and session info |
|
|
128
|
+
| `/clear` | Clear chat viewport |
|
|
129
|
+
| `/exit` | Quit |
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## FastAPI Server & Web UI
|
|
134
|
+
|
|
135
|
+
Start the API server directly or run `/api` inside interactive chat:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
aimode /api --port 8000
|
|
139
|
+
aimode --api --host 127.0.0.1 --port 8000
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Open `http://127.0.0.1:8000` for the web chat interface (`⚇ Incognito`, `Lang`, `↻ Restart`, interactive rate-limit key prompt) or `http://127.0.0.1:8000/docs` for Swagger documentation.
|
|
143
|
+
|
|
144
|
+
| Endpoint | Method | Purpose |
|
|
145
|
+
| :--- | :--- | :--- |
|
|
146
|
+
| `/api/chat` | `POST` | Stateful multi-turn chat (`query`, `session_id`, `incognito`, `lang`) |
|
|
147
|
+
| `/api/ask` | `POST` | Query endpoint with optional session state & incognito flag |
|
|
148
|
+
| `/api/config` | `GET` | Read current language, key status, and supported languages |
|
|
149
|
+
| `/api/key` | `POST` | Persist Browserless API key (`api_key`) |
|
|
150
|
+
| `/api/lang` | `POST` | Switch reply language (`lang`) |
|
|
151
|
+
| `/v1/chat/completions` | `POST` | OpenAI-compatible chat completions (supports `stream: true`) |
|
|
152
|
+
| `/v1/models` | `GET` | Available model entries |
|
|
153
|
+
| `/api/conversations` | `GET` | Saved conversation list |
|
|
154
|
+
| `/health` | `GET` | Server health and uptime |
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
curl -X POST http://127.0.0.1:8000/api/chat \
|
|
158
|
+
-H "Content-Type: application/json" \
|
|
159
|
+
-d '{"query":"Summarize Python asyncio in 2 bullets","session_id":"demo"}'
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## Python SDK
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
import asyncio
|
|
168
|
+
from google_ai_mode_py import AIModeClient
|
|
169
|
+
|
|
170
|
+
async def main():
|
|
171
|
+
async with AIModeClient() as client:
|
|
172
|
+
first = await client.ask("What is the capital of Japan?")
|
|
173
|
+
print(first.markdown)
|
|
174
|
+
|
|
175
|
+
followup = await client.chat("What currency does it use?")
|
|
176
|
+
print(followup.text)
|
|
177
|
+
|
|
178
|
+
asyncio.run(main())
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
```python
|
|
182
|
+
from google_ai_mode_py import AIModeSession
|
|
183
|
+
|
|
184
|
+
with AIModeSession() as ai:
|
|
185
|
+
resp = ai.ask("Explain HTTP/2 multiplexing in 3 bullets")
|
|
186
|
+
print(resp.markdown)
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## Optional Rate-Limit Proxy
|
|
192
|
+
|
|
193
|
+
If you encounter a Google rate limit (`429` / challenge) without a configured key, both the terminal UI and Web UI display a clickable signup link for **[Browserless (Proxy Provider)](https://www.browserless.io/signup/email?plan=free)**, prompt for your API key, save it locally, and automatically retry the failed prompt.
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
aimode --set-key YOUR_BROWSERLESS_API_KEY
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Tests & Build
|
|
202
|
+
|
|
203
|
+
```powershell
|
|
204
|
+
pytest -v -m "not network"
|
|
205
|
+
python -m build
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## Community & Support
|
|
211
|
+
|
|
212
|
+
- **Discord Server**: https://discord.gg/PYfeSaDGPJ
|
|
213
|
+
- **Contact**: [@sqnq](https://discord.com/users/987979957907116052)
|
|
214
|
+
- **Website**: [tejv.in](https://tejv.in)
|
|
215
|
+
|
|
216
|
+
### Buy Me A Coffee ☕
|
|
217
|
+
|
|
218
|
+
**Litecoin (LTC)**:
|
|
219
|
+
|
|
220
|
+
```text
|
|
221
|
+
LbDG5BE3foVsfK6JRsSc7UtBVX4DqYYKXN
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
<div align="center">
|
|
225
|
+
|
|
226
|
+
**Made With ♥️ By [tejzv](https://github.com/tejzv)**
|
|
227
|
+
|
|
228
|
+
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:0b090c,55:7a1628,100:ff4d6d&height=100§ion=footer" width="100%" />
|
|
229
|
+
|
|
230
|
+
</div>
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "google-ai-mode-py"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Request-based Python client, FastAPI server, and animated terminal UI for Google AI Mode"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
keywords = ["google", "ai-mode", "search", "fastapi", "cli", "tui", "async", "http"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
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
|
+
"Topic :: Internet :: WWW/HTTP",
|
|
25
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
26
|
+
]
|
|
27
|
+
dependencies = [
|
|
28
|
+
"curl_cffi>=0.11.0",
|
|
29
|
+
"beautifulsoup4>=4.12.0",
|
|
30
|
+
"rich>=13.7.0",
|
|
31
|
+
"fastapi>=0.115.0",
|
|
32
|
+
"uvicorn>=0.30.0",
|
|
33
|
+
]
|
|
34
|
+
|
|
35
|
+
[project.optional-dependencies]
|
|
36
|
+
dev = [
|
|
37
|
+
"pytest>=8.0.0",
|
|
38
|
+
"pytest-asyncio>=0.23.0",
|
|
39
|
+
"httpx>=0.27.0",
|
|
40
|
+
"build>=1.0.0",
|
|
41
|
+
"twine>=5.0.0",
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
[project.urls]
|
|
45
|
+
Homepage = "https://github.com/tejzv/google-ai-mode-py"
|
|
46
|
+
Repository = "https://github.com/tejzv/google-ai-mode-py"
|
|
47
|
+
Issues = "https://github.com/tejzv/google-ai-mode-py/issues"
|
|
48
|
+
Releases = "https://github.com/tejzv/google-ai-mode-py/releases"
|
|
49
|
+
|
|
50
|
+
[project.scripts]
|
|
51
|
+
google-ai-mode-py = "google_ai_mode_py.cli:main"
|
|
52
|
+
aimode = "google_ai_mode_py.cli:main"
|
|
53
|
+
aimode-api = "google_ai_mode_py.api:run_cli"
|
|
54
|
+
|
|
55
|
+
[tool.setuptools.packages.find]
|
|
56
|
+
where = ["src"]
|
|
57
|
+
|
|
58
|
+
[tool.pytest.ini_options]
|
|
59
|
+
testpaths = ["tests"]
|
|
60
|
+
asyncio_mode = "auto"
|
|
61
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
62
|
+
markers = [
|
|
63
|
+
"network: live network integration tests against Google AI Mode",
|
|
64
|
+
]
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
from importlib import import_module
|
|
2
|
+
from typing import Any
|
|
3
|
+
|
|
4
|
+
from .__about__ import __version__
|
|
5
|
+
|
|
6
|
+
__all__ = (
|
|
7
|
+
"__version__",
|
|
8
|
+
"AIModeClient",
|
|
9
|
+
"AIModeSession",
|
|
10
|
+
"ask_sync",
|
|
11
|
+
"Settings",
|
|
12
|
+
"AIResponse",
|
|
13
|
+
"Citation",
|
|
14
|
+
"ShellTokens",
|
|
15
|
+
"ConversationStore",
|
|
16
|
+
"ConversationRecord",
|
|
17
|
+
"CookieStore",
|
|
18
|
+
"BrowserlessClient",
|
|
19
|
+
"create_app",
|
|
20
|
+
"copy_to_clipboard",
|
|
21
|
+
"AIModeError",
|
|
22
|
+
"ValidationError",
|
|
23
|
+
"NetworkError",
|
|
24
|
+
"RateLimitError",
|
|
25
|
+
"ChallengeError",
|
|
26
|
+
"TokenExtractionError",
|
|
27
|
+
"ParseError",
|
|
28
|
+
"BrowserlessError",
|
|
29
|
+
"BrowserlessQuotaError",
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
_LAZY_MAP = {
|
|
33
|
+
"AIModeClient": (".client", "AIModeClient"),
|
|
34
|
+
"AIModeSession": (".client", "AIModeSession"),
|
|
35
|
+
"ask_sync": (".client", "ask_sync"),
|
|
36
|
+
"Settings": (".config", "Settings"),
|
|
37
|
+
"AIResponse": (".models", "AIResponse"),
|
|
38
|
+
"Citation": (".models", "Citation"),
|
|
39
|
+
"ShellTokens": (".models", "ShellTokens"),
|
|
40
|
+
"ConversationStore": (".storage", "ConversationStore"),
|
|
41
|
+
"ConversationRecord": (".storage", "ConversationRecord"),
|
|
42
|
+
"CookieStore": (".cookies", "CookieStore"),
|
|
43
|
+
"BrowserlessClient": (".browserless", "BrowserlessClient"),
|
|
44
|
+
"create_app": (".api", "create_app"),
|
|
45
|
+
"copy_to_clipboard": (".clipboard", "copy_to_clipboard"),
|
|
46
|
+
"AIModeError": (".exceptions", "AIModeError"),
|
|
47
|
+
"ValidationError": (".exceptions", "ValidationError"),
|
|
48
|
+
"NetworkError": (".exceptions", "NetworkError"),
|
|
49
|
+
"RateLimitError": (".exceptions", "RateLimitError"),
|
|
50
|
+
"ChallengeError": (".exceptions", "ChallengeError"),
|
|
51
|
+
"TokenExtractionError": (".exceptions", "TokenExtractionError"),
|
|
52
|
+
"ParseError": (".exceptions", "ParseError"),
|
|
53
|
+
"BrowserlessError": (".exceptions", "BrowserlessError"),
|
|
54
|
+
"BrowserlessQuotaError": (".exceptions", "BrowserlessQuotaError"),
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def __getattr__(name: str) -> Any:
|
|
59
|
+
target = _LAZY_MAP.get(name)
|
|
60
|
+
if target is None:
|
|
61
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
62
|
+
mod_name, attr_name = target
|
|
63
|
+
module = import_module(mod_name, __name__)
|
|
64
|
+
value = getattr(module, attr_name)
|
|
65
|
+
globals()[name] = value
|
|
66
|
+
return value
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def __dir__() -> list[str]:
|
|
70
|
+
return sorted(set(globals()) | set(__all__))
|