voizce 0.1.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.
voizce-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rafa
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 @@
1
+ prune tests
voizce-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,166 @@
1
+ Metadata-Version: 2.4
2
+ Name: voizce
3
+ Version: 0.1.0
4
+ Summary: Private real-time prompter for video calls: hears the questions, answers from your repo with Claude, invisible to screen sharing.
5
+ Author: Rafa
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/rafavth/Voizce
8
+ Keywords: claude,meeting-assistant,speech-to-text,parakeet,windows
9
+ Classifier: Operating System :: Microsoft :: Windows :: Windows 10
10
+ Classifier: Operating System :: Microsoft :: Windows :: Windows 11
11
+ Classifier: Environment :: Win32 (MS Windows)
12
+ Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
13
+ Classifier: Programming Language :: Python :: 3
14
+ Requires-Python: <3.13,>=3.11
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: onnx-asr==0.12.0
18
+ Requires-Dist: onnxruntime-directml==1.24.4
19
+ Requires-Dist: PyAudioWPatch==0.2.12.9
20
+ Requires-Dist: silero-vad-lite==0.4.0
21
+ Requires-Dist: claude-agent-sdk==0.2.186
22
+ Requires-Dist: anthropic==2.12.0
23
+ Requires-Dist: PySide6==6.12.0
24
+ Requires-Dist: numpy==2.5.5
25
+ Requires-Dist: huggingface_hub==2.4.0
26
+ Dynamic: license-file
27
+
28
+ <div align="center">
29
+
30
+ # 🎙️ Voizce
31
+
32
+ **Your private prompter for video calls.**
33
+ It hears the questions people ask you, transcribes them on your PC and shows you an answer in under 3 seconds,
34
+ in a window nobody sees, even when you share your screen.
35
+
36
+ ![Windows](https://img.shields.io/badge/Windows-10%202004%2B%20%7C%2011-0078D4?logo=windows&logoColor=white)
37
+ ![Python](https://img.shields.io/badge/Python-3.12-3776AB?logo=python&logoColor=white)
38
+ ![Claude](https://img.shields.io/badge/Claude-Haiku%205.5-D97757?logo=anthropic&logoColor=white)
39
+ ![ASR](https://img.shields.io/badge/ASR-Parakeet%20(local)-76B900)
40
+ ![License](https://img.shields.io/badge/license-MIT-green)
41
+
42
+ **English** · [Español](https://github.com/rafavth/Voizce/blob/main/README.es.md)
43
+
44
+ <!-- TODO: demo GIF, recorded with `voizce --demo` -->
45
+
46
+ </div>
47
+
48
+ ---
49
+
50
+ Made for **defending your own work**: a thesis defense, a technical demo, a client call about your code.
51
+ Voizce reads your repository beforehand, so when someone asks *"why did you pick Cloudflare?"* or
52
+ *"how do you protect the WebSocket?"*, the answer, based on your actual code, is already on screen.
53
+
54
+ ## ✨ Features
55
+
56
+ - 🔊 **Only listens to the others.** It captures what plays through your speakers or headphones (WASAPI loopback) and never touches your microphone.
57
+ - 🧠 **Local transcription.** Parakeet TDT 0.6b v3 runs on your CPU, so the audio never leaves your machine.
58
+ - ❓ **Spots the questions.** A permissive local filter picks candidates, and Claude ignores whatever isn't meant for you.
59
+ - ⚡ **Answers in under 3 s** after the other person stops talking, streamed as it's written. Median in testing: 1.6 s.
60
+ - 📚 **Knows your project:** a summary of your repository, your own documents and a few lines about you.
61
+ - 🙈 **Invisible to screen sharing and recordings** (`WDA_EXCLUDEFROMCAPTURE`), frameless and always on top.
62
+ - 🖱️ **Click to answer.** If a question slipped through, click its line in the transcript.
63
+ - 💳 **Two engines:** your Claude Code subscription (default) or an Anthropic API key.
64
+
65
+ ## 🚀 Install
66
+
67
+ You need **Windows 10 (2004+) or 11** and either [Claude Code](https://claude.com/claude-code) logged in
68
+ (`claude`, then `/login`) or an [Anthropic API key](https://console.anthropic.com/).
69
+
70
+ **Starting from scratch**, paste this into PowerShell. It installs [uv](https://docs.astral.sh/uv/), then
71
+ Voizce (uv fetches the right Python by itself), then opens it:
72
+
73
+ ```powershell
74
+ irm https://astral.sh/uv/install.ps1 | iex; & "$HOME\.local\bin\uv.exe" tool install voizce; & "$HOME\.local\bin\voizce.exe"
75
+ ```
76
+
77
+ **Already have uv?**
78
+
79
+ ```powershell
80
+ uv tool install voizce
81
+ voizce
82
+ ```
83
+
84
+ The first time, a settings window opens:
85
+
86
+ 1. **Pick your project's folder.** Claude Code reads it (read-only) and writes a summary, which takes a few minutes.
87
+ 2. **Write a few lines about yourself** and the situation.
88
+ 3. **Click *Create shortcuts*** so next time you can open Voizce from the desktop or the Start menu.
89
+
90
+ > The first launch also downloads the Parakeet model (~650 MB).
91
+
92
+ ## 🎯 Usage
93
+
94
+ | Control | What it does |
95
+ |---|---|
96
+ | **▶ Listen / ⏸ Pause** | Starts or stops capturing audio. Nothing is captured while paused. |
97
+ | **📌** | Pins the window to the top center, under the webcam. |
98
+ | **⚙** | Settings: repository, extra document, about you, API key. |
99
+ | **Click a line** | Claude answers that line. |
100
+ | **✕** | Closes everything. |
101
+
102
+ Each answer shows how long it took since the other person stopped talking. If your repository changes, the
103
+ status bar tells you; tick *Create the repository summary now* in ⚙ to update it.
104
+
105
+ ## 🔄 How it works
106
+
107
+ ```mermaid
108
+ flowchart LR
109
+ A[🔊 System audio<br/>WASAPI loopback] --> B[Silero VAD<br/>splits phrases]
110
+ B --> C[Parakeet<br/>local transcription]
111
+ C --> D{Filter<br/>question?}
112
+ D -- no --> T[Transcript]
113
+ D -- yes --> E[Claude Haiku<br/>+ repo summary]
114
+ E -- SKIP --> T
115
+ E -- answer --> F[🪟 Window hidden<br/>from capture]
116
+ T -. click .-> E
117
+ ```
118
+
119
+ **What reaches Claude:** your documents (repository summary, extra document, about you) and, for each
120
+ question, that phrase plus the 10 lines before it. Audio and everything else stay on your PC.
121
+
122
+ **Languages:** Parakeet transcribes 25 European languages and Claude answers in the language of the
123
+ question. The question filter is tuned for Spanish and English; in other languages it relies on question
124
+ marks, and you can always click a line. The interface is in English or Spanish, following Windows.
125
+
126
+ ## ⚙️ Advanced settings
127
+
128
+ Everything lives in `%APPDATA%\Voizce`: `config.toml`, the repository summary (`REPO_DIGEST.md`) and
129
+ `voizce.log`. Besides what ⚙ shows, `config.toml` accepts:
130
+
131
+ | Key | Default | What for |
132
+ |---|---|---|
133
+ | `silence_ms` | `250` | Silence that closes a phrase. The main latency knob: lower is faster, but cuts more phrases in half (Voizce rejoins them) |
134
+ | `model` | `claude-haiku-5-5` | Answer model. Haiku is the fastest |
135
+ | `timeout_s` | `8` | Seconds before a question is given up |
136
+ | `asr` | `cpu-int8` | `directml` to transcribe on the GPU (it was slower on the AMD GPU we tested) |
137
+ | `digest_model` | (Claude Code's) | Model that writes the repository summary |
138
+
139
+ Command line: `voizce digest` rewrites the summary from the terminal, and `voizce --demo` keeps the window
140
+ visible to screen recordings so you can record it.
141
+
142
+ ## 🧑‍💻 Development
143
+
144
+ ```powershell
145
+ git clone https://github.com/rafavth/Voizce.git
146
+ cd Voizce
147
+ uv venv; uv pip install -e .
148
+ .\.venv\Scripts\python -m voizce
149
+ ```
150
+
151
+ ## 🗑️ Uninstall
152
+
153
+ ```powershell
154
+ uv tool uninstall voizce
155
+ ```
156
+
157
+ Then delete `%APPDATA%\Voizce` and the shortcuts.
158
+
159
+ ## ⚠️ Disclaimer
160
+
161
+ Voizce doesn't record audio, but it does transcribe other people. Depending on the context and where you
162
+ live, you may need to tell the other participants. That's your responsibility.
163
+
164
+ ## 📄 License
165
+
166
+ [MIT](https://github.com/rafavth/Voizce/blob/main/LICENSE)
voizce-0.1.0/README.md ADDED
@@ -0,0 +1,139 @@
1
+ <div align="center">
2
+
3
+ # 🎙️ Voizce
4
+
5
+ **Your private prompter for video calls.**
6
+ It hears the questions people ask you, transcribes them on your PC and shows you an answer in under 3 seconds,
7
+ in a window nobody sees, even when you share your screen.
8
+
9
+ ![Windows](https://img.shields.io/badge/Windows-10%202004%2B%20%7C%2011-0078D4?logo=windows&logoColor=white)
10
+ ![Python](https://img.shields.io/badge/Python-3.12-3776AB?logo=python&logoColor=white)
11
+ ![Claude](https://img.shields.io/badge/Claude-Haiku%205.5-D97757?logo=anthropic&logoColor=white)
12
+ ![ASR](https://img.shields.io/badge/ASR-Parakeet%20(local)-76B900)
13
+ ![License](https://img.shields.io/badge/license-MIT-green)
14
+
15
+ **English** · [Español](https://github.com/rafavth/Voizce/blob/main/README.es.md)
16
+
17
+ <!-- TODO: demo GIF, recorded with `voizce --demo` -->
18
+
19
+ </div>
20
+
21
+ ---
22
+
23
+ Made for **defending your own work**: a thesis defense, a technical demo, a client call about your code.
24
+ Voizce reads your repository beforehand, so when someone asks *"why did you pick Cloudflare?"* or
25
+ *"how do you protect the WebSocket?"*, the answer, based on your actual code, is already on screen.
26
+
27
+ ## ✨ Features
28
+
29
+ - 🔊 **Only listens to the others.** It captures what plays through your speakers or headphones (WASAPI loopback) and never touches your microphone.
30
+ - 🧠 **Local transcription.** Parakeet TDT 0.6b v3 runs on your CPU, so the audio never leaves your machine.
31
+ - ❓ **Spots the questions.** A permissive local filter picks candidates, and Claude ignores whatever isn't meant for you.
32
+ - ⚡ **Answers in under 3 s** after the other person stops talking, streamed as it's written. Median in testing: 1.6 s.
33
+ - 📚 **Knows your project:** a summary of your repository, your own documents and a few lines about you.
34
+ - 🙈 **Invisible to screen sharing and recordings** (`WDA_EXCLUDEFROMCAPTURE`), frameless and always on top.
35
+ - 🖱️ **Click to answer.** If a question slipped through, click its line in the transcript.
36
+ - 💳 **Two engines:** your Claude Code subscription (default) or an Anthropic API key.
37
+
38
+ ## 🚀 Install
39
+
40
+ You need **Windows 10 (2004+) or 11** and either [Claude Code](https://claude.com/claude-code) logged in
41
+ (`claude`, then `/login`) or an [Anthropic API key](https://console.anthropic.com/).
42
+
43
+ **Starting from scratch**, paste this into PowerShell. It installs [uv](https://docs.astral.sh/uv/), then
44
+ Voizce (uv fetches the right Python by itself), then opens it:
45
+
46
+ ```powershell
47
+ irm https://astral.sh/uv/install.ps1 | iex; & "$HOME\.local\bin\uv.exe" tool install voizce; & "$HOME\.local\bin\voizce.exe"
48
+ ```
49
+
50
+ **Already have uv?**
51
+
52
+ ```powershell
53
+ uv tool install voizce
54
+ voizce
55
+ ```
56
+
57
+ The first time, a settings window opens:
58
+
59
+ 1. **Pick your project's folder.** Claude Code reads it (read-only) and writes a summary, which takes a few minutes.
60
+ 2. **Write a few lines about yourself** and the situation.
61
+ 3. **Click *Create shortcuts*** so next time you can open Voizce from the desktop or the Start menu.
62
+
63
+ > The first launch also downloads the Parakeet model (~650 MB).
64
+
65
+ ## 🎯 Usage
66
+
67
+ | Control | What it does |
68
+ |---|---|
69
+ | **▶ Listen / ⏸ Pause** | Starts or stops capturing audio. Nothing is captured while paused. |
70
+ | **📌** | Pins the window to the top center, under the webcam. |
71
+ | **⚙** | Settings: repository, extra document, about you, API key. |
72
+ | **Click a line** | Claude answers that line. |
73
+ | **✕** | Closes everything. |
74
+
75
+ Each answer shows how long it took since the other person stopped talking. If your repository changes, the
76
+ status bar tells you; tick *Create the repository summary now* in ⚙ to update it.
77
+
78
+ ## 🔄 How it works
79
+
80
+ ```mermaid
81
+ flowchart LR
82
+ A[🔊 System audio<br/>WASAPI loopback] --> B[Silero VAD<br/>splits phrases]
83
+ B --> C[Parakeet<br/>local transcription]
84
+ C --> D{Filter<br/>question?}
85
+ D -- no --> T[Transcript]
86
+ D -- yes --> E[Claude Haiku<br/>+ repo summary]
87
+ E -- SKIP --> T
88
+ E -- answer --> F[🪟 Window hidden<br/>from capture]
89
+ T -. click .-> E
90
+ ```
91
+
92
+ **What reaches Claude:** your documents (repository summary, extra document, about you) and, for each
93
+ question, that phrase plus the 10 lines before it. Audio and everything else stay on your PC.
94
+
95
+ **Languages:** Parakeet transcribes 25 European languages and Claude answers in the language of the
96
+ question. The question filter is tuned for Spanish and English; in other languages it relies on question
97
+ marks, and you can always click a line. The interface is in English or Spanish, following Windows.
98
+
99
+ ## ⚙️ Advanced settings
100
+
101
+ Everything lives in `%APPDATA%\Voizce`: `config.toml`, the repository summary (`REPO_DIGEST.md`) and
102
+ `voizce.log`. Besides what ⚙ shows, `config.toml` accepts:
103
+
104
+ | Key | Default | What for |
105
+ |---|---|---|
106
+ | `silence_ms` | `250` | Silence that closes a phrase. The main latency knob: lower is faster, but cuts more phrases in half (Voizce rejoins them) |
107
+ | `model` | `claude-haiku-5-5` | Answer model. Haiku is the fastest |
108
+ | `timeout_s` | `8` | Seconds before a question is given up |
109
+ | `asr` | `cpu-int8` | `directml` to transcribe on the GPU (it was slower on the AMD GPU we tested) |
110
+ | `digest_model` | (Claude Code's) | Model that writes the repository summary |
111
+
112
+ Command line: `voizce digest` rewrites the summary from the terminal, and `voizce --demo` keeps the window
113
+ visible to screen recordings so you can record it.
114
+
115
+ ## 🧑‍💻 Development
116
+
117
+ ```powershell
118
+ git clone https://github.com/rafavth/Voizce.git
119
+ cd Voizce
120
+ uv venv; uv pip install -e .
121
+ .\.venv\Scripts\python -m voizce
122
+ ```
123
+
124
+ ## 🗑️ Uninstall
125
+
126
+ ```powershell
127
+ uv tool uninstall voizce
128
+ ```
129
+
130
+ Then delete `%APPDATA%\Voizce` and the shortcuts.
131
+
132
+ ## ⚠️ Disclaimer
133
+
134
+ Voizce doesn't record audio, but it does transcribe other people. Depending on the context and where you
135
+ live, you may need to tell the other participants. That's your responsibility.
136
+
137
+ ## 📄 License
138
+
139
+ [MIT](https://github.com/rafavth/Voizce/blob/main/LICENSE)
@@ -0,0 +1,42 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "voizce"
7
+ version = "0.1.0"
8
+ description = "Private real-time prompter for video calls: hears the questions, answers from your repo with Claude, invisible to screen sharing."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Rafa" }]
13
+ # Only 3.12 is tested; uv picks it automatically.
14
+ requires-python = ">=3.11,<3.13"
15
+ keywords = ["claude", "meeting-assistant", "speech-to-text", "parakeet", "windows"]
16
+ classifiers = [
17
+ "Operating System :: Microsoft :: Windows :: Windows 10",
18
+ "Operating System :: Microsoft :: Windows :: Windows 11",
19
+ "Environment :: Win32 (MS Windows)",
20
+ "Topic :: Multimedia :: Sound/Audio :: Speech",
21
+ "Programming Language :: Python :: 3",
22
+ ]
23
+ dependencies = [
24
+ "onnx-asr==0.12.0",
25
+ "onnxruntime-directml==1.24.4",
26
+ "PyAudioWPatch==0.2.12.9",
27
+ "silero-vad-lite==0.4.0",
28
+ "claude-agent-sdk==0.2.186",
29
+ "anthropic==2.12.0",
30
+ "PySide6==6.12.0",
31
+ "numpy==2.5.5",
32
+ "huggingface_hub==2.4.0",
33
+ ]
34
+
35
+ [project.urls]
36
+ Homepage = "https://github.com/rafavth/Voizce"
37
+
38
+ [project.scripts]
39
+ voizce = "voizce.__main__:main"
40
+
41
+ [tool.setuptools]
42
+ packages = ["voizce"]
voizce-0.1.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1 @@
1
+ """Voizce: a private, real-time prompter for video calls."""
@@ -0,0 +1,37 @@
1
+ """`voizce` opens the window, `voizce --demo` too but visible to screen recordings,
2
+ `voizce digest` writes the repository summary from the terminal."""
3
+ import sys
4
+
5
+
6
+ def _hide_child_consoles():
7
+ # With no console of its own, Windows opens a terminal window for claude.exe when you press
8
+ # Listen. The SDK doesn't let us pass creationflags, so add them to everything it launches.
9
+ import functools
10
+ import subprocess
11
+ import anyio
12
+
13
+ open_process = anyio.open_process
14
+
15
+ @functools.wraps(open_process)
16
+ async def open_process_hidden(*args, **kwargs):
17
+ kwargs.setdefault("creationflags", subprocess.CREATE_NO_WINDOW)
18
+ return await open_process(*args, **kwargs)
19
+
20
+ anyio.open_process = open_process_hidden
21
+
22
+
23
+ def main():
24
+ if sys.stderr is None: # pythonw (shortcut): no console, errors go to voizce.log
25
+ from .app import APP_DIR
26
+ APP_DIR.mkdir(parents=True, exist_ok=True)
27
+ sys.stdout = sys.stderr = open(APP_DIR / "voizce.log", "a", encoding="utf-8")
28
+ _hide_child_consoles()
29
+ if sys.argv[1:2] == ["digest"]:
30
+ from .digest import main as run
31
+ else:
32
+ from .app import main as run
33
+ run()
34
+
35
+
36
+ if __name__ == "__main__":
37
+ main()
@@ -0,0 +1,257 @@
1
+ """Question filter, prompt, SKIP handling and the two engines (subscription / API)."""
2
+ import asyncio
3
+ import re
4
+
5
+ from .i18n import tr
6
+
7
+ # --- quick filter (local and permissive: Claude discards the rest) --------------------------
8
+
9
+ # Parakeet often drops «¿» and accents («que es lo primero…», «Como sabemos…»), so at the start
10
+ # of a sentence or clause the unaccented forms and the usual yes/no openers count too.
11
+ _CLAUSE_START = r"(?:^|[.,;:!?¡¿]\s*)(?:y |pero |entonces |vale,? |oye,? )?(?:tú )?"
12
+ _CANDIDATE = re.compile(
13
+ r"[?¿]"
14
+ r"|\b(qué|cómo|dónde|adónde|cuándo|cuál|cuáles|quién|quiénes|cuánto|cuánta|cuántos|cuántas|por qué|para qué)\b"
15
+ r"|" + _CLAUSE_START +
16
+ r"(que|como|donde|cuando|cual|cuales|quien|quienes|cuanto|cuanta|cuantos|cuantas|porque|por que|para que"
17
+ r"|se puede|puedes?|podemos|podéis|hay|es posible|tienes?|tenemos|tenéis|has|habéis|existe|está|estás"
18
+ r"|funciona|usáis|usas|soporta|no crees|crees|piensas|consideras|te parece"
19
+ r"|\w+(?:aste|iste))\b" # 2nd person past tense: «usaste…», «elegiste…», «hiciste…»
20
+ r"|\b(me|nos) (explicas|explicarías|cuentas|contarías|dices|dirías|enseñas)\b"
21
+ r"|\b(explícame|explícanos|cuéntame|cuéntanos|dime|dinos|podrías|podríais|sabrías|sab(?:e|es|éis|eis|en) si"
22
+ r"|puedes (contar|explicar|decir)|tienes idea|alguna idea|qu[eé] tal si)\b"
23
+ r"|\b(what|how|where|when|which|who|why|could you|can you|do you know|tell me)\b",
24
+ re.IGNORECASE,
25
+ )
26
+
27
+
28
+ def is_candidate(text: str) -> bool:
29
+ return bool(_CANDIDATE.search(text))
30
+
31
+
32
+ # --- SKIP ------------------------------------------------------------------------------------
33
+
34
+ class SkipGate:
35
+ """Holds back the start of the stream until it's clear whether the answer is SKIP.
36
+
37
+ feed() returns the text that can already be shown; finish() whatever is left at the end.
38
+ """
39
+
40
+ def __init__(self):
41
+ self.buf, self.open, self.skipped = "", False, False
42
+
43
+ def feed(self, chunk: str) -> str:
44
+ if self.open:
45
+ return chunk
46
+ if self.skipped:
47
+ return ""
48
+ self.buf += chunk
49
+ s = self.buf.lstrip()
50
+ if "SKIP".startswith(s): # empty or a prefix of SKIP: can't tell yet
51
+ return ""
52
+ if s.startswith("SKIP"):
53
+ self.skipped = True
54
+ return ""
55
+ self.open = True
56
+ return s
57
+
58
+ def finish(self) -> str:
59
+ if self.open or self.skipped:
60
+ return ""
61
+ s = self.buf.strip()
62
+ if s == "SKIP":
63
+ self.skipped = True
64
+ return ""
65
+ self.open = True
66
+ return s
67
+
68
+
69
+ # --- prompt ----------------------------------------------------------------------------------
70
+
71
+ _INSTRUCTIONS = """\
72
+ You are the user's private prompter during a video call. Other people ask them questions about \
73
+ their work and you give them, in a window only they can see, an answer they can read out loud.
74
+
75
+ You receive the recent conversation (only what the others say) and a PHRASE. Both come from \
76
+ speech recognition: question marks and accents are often missing, and in Spanish «por qué» \
77
+ often comes out as «porque». Judge whether it is a question by its meaning, not its punctuation.
78
+
79
+ 1. Decide whether the PHRASE is a question or request aimed at the user about the project, the \
80
+ code or their work. If it isn't (greetings, comments, rhetorical questions, small talk, questions \
81
+ for someone else), reply exactly SKIP and nothing else. Whether the documents cover the answer \
82
+ plays no part in this decision: a question for the user is never SKIP.
83
+ 2. If it is, answer it:
84
+ - In the language of the PHRASE.
85
+ - At most 2 sentences and 50 words in total.
86
+ - The first sentence is what the user will say out loud, in the first person, as if they were \
87
+ speaking: no "you could say", no quotes. The second, only if it helps, a concrete detail (file, \
88
+ function, figure).
89
+ - Use only the DOCUMENTS below and the conversation. If they don't cover the question, start \
90
+ with "I'm not sure" (in the language of the PHRASE) and say only what they do state. Never make \
91
+ up names, files, figures or behaviour.
92
+ - Don't offer to do anything else. Plain text: no markdown, no lists, no preamble.
93
+ """
94
+
95
+
96
+ def build_system(digest: str, extra: str, personal: str) -> str:
97
+ parts = [_INSTRUCTIONS]
98
+ if personal.strip():
99
+ parts.append("## About the user\n\n" + personal.strip())
100
+ parts.append("## DOCUMENT 1: repository summary\n\n" + (digest.strip() or "(not available)"))
101
+ parts.append("## DOCUMENT 2: additional documentation\n\n" + (extra.strip() or "(not available)"))
102
+ return "\n\n".join(parts) + "\n"
103
+
104
+
105
+ def build_user(recent: list[str], phrase: str, manual: bool = False) -> str:
106
+ convo = "\n".join(f"- {s}" for s in recent) or "(nothing)"
107
+ msg = f"Recent conversation:\n{convo}\n\nPHRASE: «{phrase}»\n\n"
108
+ if manual:
109
+ msg += "The user asked for this phrase to be answered: don't reply SKIP. "
110
+ else:
111
+ msg += ("SKIP only if it isn't a question for the user. Without punctuation it can still be "
112
+ "one: «se puede usar X», «sabe si hay Y», «porque pasa Z», «any plans to open "
113
+ "source it» are questions. ")
114
+ # Repeated at the end: with tens of thousands of document tokens in front, Haiku forgets the
115
+ # limits and copies the documents' tone (in testing, that of a university thesis).
116
+ return msg + ("At most 2 sentences and 50 words, in the first person; if the documents don't "
117
+ "cover it, start with \"I'm not sure\". Spoken tone, like in a conversation: "
118
+ "short sentences and plain words, don't copy the style of the documents.")
119
+
120
+
121
+ # --- engines ---------------------------------------------------------------------------------
122
+ # Common interface: await start(); async for chunk in stream(user_text); await close().
123
+ # stream() can be cancelled (task.cancel()); the engine is ready for the next one afterwards.
124
+
125
+ class ApiEngine:
126
+ def __init__(self, api_key: str, model: str, system: str):
127
+ import anthropic
128
+ self.client = anthropic.AsyncAnthropic(api_key=api_key, max_retries=0)
129
+ self.model = model
130
+ # 1 h TTL: in a meeting more than 5 minutes can go by between questions.
131
+ self.system = [{"type": "text", "text": system, "cache_control": {"type": "ephemeral", "ttl": "1h"}}]
132
+
133
+ def _params(self, user_text: str, max_tokens: int) -> dict:
134
+ return dict(
135
+ model=self.model,
136
+ max_tokens=max_tokens,
137
+ system=self.system,
138
+ thinking={"type": "disabled"},
139
+ output_config={"effort": "low"},
140
+ messages=[{"role": "user", "content": user_text}],
141
+ )
142
+
143
+ async def start(self):
144
+ # Warms the system prompt cache so the first question doesn't pay for it.
145
+ try:
146
+ await self.client.messages.create(**self._params("hi", 1))
147
+ except Exception:
148
+ pass # the real error shows up on the first question, with its message
149
+
150
+ async def stream(self, user_text: str):
151
+ import anthropic
152
+ try:
153
+ async with self.client.messages.stream(**self._params(user_text, 300)) as s:
154
+ async for text in s.text_stream:
155
+ yield text
156
+ except anthropic.AuthenticationError:
157
+ raise RuntimeError(tr("Invalid Anthropic API key."))
158
+ except anthropic.RateLimitError:
159
+ raise RuntimeError(tr("Anthropic API rate limit reached."))
160
+
161
+ async def close(self):
162
+ await self.client.close()
163
+
164
+
165
+ _SUB_ERRORS = {
166
+ "authentication_failed": "Claude Code isn't logged in: run «claude» and use /login.",
167
+ "rate_limit": "Claude usage limit reached.",
168
+ "billing_error": "Claude usage limit reached (billing).",
169
+ }
170
+
171
+
172
+ class SubscriptionEngine:
173
+ """One Claude Code process kept warm for the whole session (Claude Agent SDK), one conversation.
174
+
175
+ Reusing the conversation measured better than /clear per question (20/20 vs 18/20 within
176
+ 3 s; after /clear the first token took up to 2-4 s).
177
+ ponytail: the history grows with each question (~250 tokens); irrelevant in a one-hour
178
+ meeting. If it ever matters, /clear between questions once it passes some size.
179
+ """
180
+
181
+ def __init__(self, model: str, system: str):
182
+ import tempfile
183
+ from pathlib import Path
184
+ from claude_agent_sdk import ClaudeAgentOptions
185
+ # Through a file: a ~100 KB prompt doesn't fit on the Windows command line.
186
+ self.system_file = Path(tempfile.gettempdir()) / "voizce_system_prompt.md"
187
+ self.system_file.write_text(system, encoding="utf-8")
188
+ self.options = ClaudeAgentOptions(
189
+ system_prompt={"type": "file", "path": str(self.system_file)},
190
+ model=model,
191
+ tools=[],
192
+ setting_sources=[],
193
+ strict_mcp_config=True,
194
+ max_turns=1,
195
+ thinking={"type": "disabled"},
196
+ effort="low",
197
+ include_partial_messages=True,
198
+ # Otherwise the CLI would use an API key from the environment instead of the subscription.
199
+ env={"ANTHROPIC_API_KEY": ""},
200
+ )
201
+ self.client = None
202
+ self._lock = asyncio.Lock()
203
+ self._dirty = False # interrupted turn whose messages haven't been drained yet
204
+
205
+ async def start(self):
206
+ from claude_agent_sdk import ClaudeSDKClient
207
+ self.client = ClaudeSDKClient(self.options)
208
+ await self.client.connect()
209
+ # First call before the meeting: writes the prompt cache and warms up the process.
210
+ async for _ in self.stream(build_user([], "Hi, can you hear me?")):
211
+ pass
212
+
213
+ async def _drain(self):
214
+ async def run():
215
+ async for _ in self.client.receive_response():
216
+ pass
217
+ await asyncio.wait_for(run(), 5)
218
+
219
+ async def _tidy(self):
220
+ if self._dirty:
221
+ await self.client.interrupt()
222
+ await self._drain()
223
+ self._dirty = False
224
+
225
+ async def stream(self, user_text: str):
226
+ from claude_agent_sdk import AssistantMessage, ResultMessage, StreamEvent
227
+ async with self._lock:
228
+ await self._tidy() # usually the background task already did it
229
+ self._dirty = True
230
+ try:
231
+ await self.client.query(user_text)
232
+ async for msg in self.client.receive_response():
233
+ if isinstance(msg, StreamEvent):
234
+ ev = msg.event
235
+ if ev.get("type") == "content_block_delta" and ev["delta"].get("type") == "text_delta":
236
+ yield ev["delta"]["text"]
237
+ elif isinstance(msg, AssistantMessage) and msg.error:
238
+ raise RuntimeError(tr(_SUB_ERRORS[msg.error]) if msg.error in _SUB_ERRORS
239
+ else f"Claude Code: {msg.error}")
240
+ elif isinstance(msg, ResultMessage):
241
+ self._dirty = False
242
+ if msg.is_error:
243
+ raise RuntimeError("Claude Code: " + "; ".join(msg.errors or [msg.result or msg.subtype]))
244
+ finally:
245
+ if self._dirty: # cancelled halfway: interrupt and drain in the background
246
+ asyncio.get_running_loop().create_task(self._locked_tidy())
247
+
248
+ async def _locked_tidy(self):
249
+ async with self._lock:
250
+ try:
251
+ await self._tidy()
252
+ except Exception:
253
+ pass
254
+
255
+ async def close(self):
256
+ if self.client:
257
+ await self.client.disconnect()