grok-assistant 1.0__tar.gz

grok_assistant-1.0/LICENSE.md

@@ -0,0 +1,39 @@
+# Licencia y límites — Grok Assistant
+
+Versión candidata 1.0. Aplicación experimental.
+
+Autor: Antonio Castellon, Castellon.CH.
+
+## Qué es
+
+Grok Assistant es un programa experimental para hablar con un asistente en este equipo. El audio se queda aquí. Cuando hace falta, el programa envía texto a Grok. Grok y sus herramientas son un servicio de un tercero, no de este programa.
+
+## Responsabilidad
+
+Antonio Castellon no se hace responsable de cualquier fallo de seguridad o brecha que pueda darse por el uso de Grok y de sus herramientas. Eso incluye el acceso a la cuenta, lo que Grok busque o escriba, un archivo que cambie cuando esa opción esté permitida, y cualquier daño o pérdida que venga de ese uso.
+
+El programa se ofrece tal cual, sin garantía. Quien lo ejecuta lo hace por su cuenta.
+
+Si un administrador permite que Grok cambie archivos, esa elección se hace en este equipo. La shell sigue apagada. Aun así, el autor no responde de lo que Grok haga con las herramientas que se hayan dejado activas.
+
+## Texto que manda
+
+Este archivo está en español. La traducción al inglés es una ayuda para leerlo. Si los dos textos no dicen lo mismo, manda el español.
+
+---
+
+# License and limits — Grok Assistant
+
+Release candidate 1.0. Experimental application.
+
+Author: Antonio Castellon, Castellon.CH.
+
+Grok Assistant is an experimental program for talking with an assistant on this computer. The audio stays here. When needed, the program sends text to Grok. Grok and its tools are a third-party service, not part of this program.
+
+Antonio Castellon is not responsible for any security failure or breach that may come from using Grok and its tools. That includes access to the account, what Grok looks up or writes, a file it changes when that option is allowed, and any damage or loss that comes from that use.
+
+The program is offered as it is, without warranty. Anyone who runs it does so on their own account.
+
+If an administrator allows Grok to change files, that choice is made on this computer. The shell stays off. The author is still not answerable for what Grok does with the tools that were left on.
+
+If the Spanish text and this English text differ, the Spanish text prevails.

grok_assistant-1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: grok_assistant
+Version: 1.0
+Summary: A PC voice assistant that listens at home and only calls Grok on purpose.
+Author: Antonio Castellon
+Project-URL: Homepage, https://github.com/antonio-castellon/Grok_Assistant
+Project-URL: Repository, https://github.com/antonio-castellon/Grok_Assistant
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pystray>=0.19
+Requires-Dist: Pillow>=10
+Requires-Dist: sherpa-onnx==1.13.8
+Requires-Dist: sounddevice==0.5.6
+Requires-Dist: numpy<2.5,>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+[Leer en español](README.ES.md) · [Lire en français](README.FR.md) · [Auf Deutsch lesen](README.DE.md)
+
+![Grok mark, with Assistant underneath](docs/img/banner.jpg)
+
+# Grok Assistant
+
+Release candidate 1.0.
+
+This is a voice companion for the moments when reading is difficult and the house is quiet. The laptop version is for an older person who already has a small computer nearby. The Raspberry Pi 4 version, with 4 GB of RAM, is the same assistant as a dedicated device, for a family that would rather not leave a laptop open. I plan to publish that code soon. The microphone can stay ready. The audio stays on the computer. Only text that was meant for the assistant is sent out.
+
+I spent years waiting for the Amazon Echo to become a better listener. It never really became more than a speaker with a light ring, so I decided to build my own.
+
+In my case, that person is my father. His eyesight is limited, and he spends many hours on his own. I wanted him to have a voice he could simply talk to — one that could answer questions and explain things without making him find a screen or read small text. That is now possible. Grok on this machine is also the foundation for the features and integrations I plan to add next.
+
+While the program is running, it can keep listening. Speech is turned into text on this computer. Grok only receives text when the assistant has actually been addressed: after a greeting, for a question, for a command beginning with `comando`, or when someone asks for a song. Ordinary conversation stays in the local session. If a command is unclear or misheard, Grok can help interpret it, but the assistant still asks for a `sí` before doing anything.
+
+That is the basic idea. Below are the listening window and the icon menu, with Escucha open. The pictures are the same in every language.
+
+![The window waiting, on the Simple tab](docs/img/app-window.png)
+
+![The icon menu, with Escucha open](docs/img/tray-menu.png)
+
+The diagram below shows what happens to a spoken phrase from the moment it is heard.
+
+![The STT engine turns speech into text. Before a conversation, the local model checks for a complete command. During a conversation, it notes the line and the text goes to Grok.](docs/img/flow.svg)
+
+In Settings, Grok only searches the internet. An administrator can allow Grok to change files on this machine. The shell stays off, and a relative path lands in the assistant data folder.
+
+## Read on
+
+- [How to use it](docs/en/guide.md)
+- [Look](docs/en/look.md)
+- [Voice prints and listeners](docs/en/prints.md)
+- [Sessions and agents](docs/en/sessions.md)
+- [Why Grok, and not another chat window](docs/en/why-grok.md)
+- [What is actually running](docs/en/pieces.md)
+- [What you can say](docs/en/saying.md)
+- [Run the executable](docs/en/run.md)
+- [Run it from the source tree](docs/en/source.md)

grok_assistant-1.0/README.md

@@ -0,0 +1,39 @@
+[Leer en español](README.ES.md) · [Lire en français](README.FR.md) · [Auf Deutsch lesen](README.DE.md)
+
+![Grok mark, with Assistant underneath](docs/img/banner.jpg)
+
+# Grok Assistant
+
+Release candidate 1.0.
+
+This is a voice companion for the moments when reading is difficult and the house is quiet. The laptop version is for an older person who already has a small computer nearby. The Raspberry Pi 4 version, with 4 GB of RAM, is the same assistant as a dedicated device, for a family that would rather not leave a laptop open. I plan to publish that code soon. The microphone can stay ready. The audio stays on the computer. Only text that was meant for the assistant is sent out.
+
+I spent years waiting for the Amazon Echo to become a better listener. It never really became more than a speaker with a light ring, so I decided to build my own.
+
+In my case, that person is my father. His eyesight is limited, and he spends many hours on his own. I wanted him to have a voice he could simply talk to — one that could answer questions and explain things without making him find a screen or read small text. That is now possible. Grok on this machine is also the foundation for the features and integrations I plan to add next.
+
+While the program is running, it can keep listening. Speech is turned into text on this computer. Grok only receives text when the assistant has actually been addressed: after a greeting, for a question, for a command beginning with `comando`, or when someone asks for a song. Ordinary conversation stays in the local session. If a command is unclear or misheard, Grok can help interpret it, but the assistant still asks for a `sí` before doing anything.
+
+That is the basic idea. Below are the listening window and the icon menu, with Escucha open. The pictures are the same in every language.
+
+![The window waiting, on the Simple tab](docs/img/app-window.png)
+
+![The icon menu, with Escucha open](docs/img/tray-menu.png)
+
+The diagram below shows what happens to a spoken phrase from the moment it is heard.
+
+![The STT engine turns speech into text. Before a conversation, the local model checks for a complete command. During a conversation, it notes the line and the text goes to Grok.](docs/img/flow.svg)
+
+In Settings, Grok only searches the internet. An administrator can allow Grok to change files on this machine. The shell stays off, and a relative path lands in the assistant data folder.
+
+## Read on
+
+- [How to use it](docs/en/guide.md)
+- [Look](docs/en/look.md)
+- [Voice prints and listeners](docs/en/prints.md)
+- [Sessions and agents](docs/en/sessions.md)
+- [Why Grok, and not another chat window](docs/en/why-grok.md)
+- [What is actually running](docs/en/pieces.md)
+- [What you can say](docs/en/saying.md)
+- [Run the executable](docs/en/run.md)
+- [Run it from the source tree](docs/en/source.md)

grok_assistant-1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "grok_assistant"
+version = "1.0"
+description = "A PC voice assistant that listens at home and only calls Grok on purpose."
+readme = "README.md"
+requires-python = ">=3.11"
+license-files = ["LICENSE.md"]
+authors = [{name = "Antonio Castellon"}]
+dependencies = [
+    "pystray>=0.19",
+    "Pillow>=10",
+    "sherpa-onnx==1.13.8",
+    "sounddevice==0.5.6",
+    "numpy>=2.2,<2.5",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/antonio-castellon/Grok_Assistant"
+Repository = "https://github.com/antonio-castellon/Grok_Assistant"
+
+[project.scripts]
+grok-assistant = "grok_assistant.__main__:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+grok_assistant = [
+    "lines/*",
+    "lang/*",
+    "ui/themes/*",
+    "build_stamp.txt",
+    "_bundle/scripts/*",
+    "_bundle/listeners/*",
+    "_bundle/docs/img/*",
+    "_bundle/LICENSE.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

grok_assistant-1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

grok_assistant-1.0/setup.py

@@ -0,0 +1,54 @@
+"""Stage the files a pip install needs, then let pyproject.toml describe the package."""
+
+import sys
+from pathlib import Path
+import shutil
+
+from setuptools import setup
+
+ROOT = Path(__file__).resolve().parent
+sys.path.insert(0, str(ROOT / "src"))
+PACKAGE = ROOT / "src" / "grok_assistant"
+BUNDLE = PACKAGE / "_bundle"
+
+
+def stage() -> None:
+    """Copy repo files into the package. A wheel built from the sdist already has them."""
+    from grok_assistant.buildinfo import write_stamp
+
+    speak = ROOT / "scripts" / "speak.ps1"
+    if not speak.is_file():
+        if not (BUNDLE / "scripts" / "speak.ps1").is_file():
+            raise SystemExit("scripts/speak.ps1 is missing")
+        return
+    if BUNDLE.exists():
+        shutil.rmtree(BUNDLE)
+    shutil.copytree(ROOT / "scripts", BUNDLE / "scripts")
+    shutil.copytree(ROOT / "listeners", BUNDLE / "listeners")
+    images = BUNDLE / "docs" / "img"
+    images.mkdir(parents=True)
+    for name in ("grok.ico", "grok-mark.png"):
+        source = ROOT / "docs" / "img" / name
+        if source.is_file():
+            shutil.copy2(source, images / name)
+    shutil.copy2(ROOT / "LICENSE.md", BUNDLE / "LICENSE.md")
+    write_stamp(PACKAGE / "build_stamp.txt")
+
+
+def packaged_files() -> list[str]:
+    names: list[str] = []
+    for folder in ("lines", "lang", "ui/themes", "_bundle"):
+        base = PACKAGE / folder
+        if not base.exists():
+            continue
+        for path in base.rglob("*"):
+            if path.is_file():
+                names.append(path.relative_to(PACKAGE).as_posix())
+    stamp = PACKAGE / "build_stamp.txt"
+    if stamp.is_file():
+        names.append("build_stamp.txt")
+    return names
+
+
+stage()
+setup(package_data={"grok_assistant": packaged_files()})

grok_assistant-1.0/src/grok_assistant/__init__.py

@@ -0,0 +1,4 @@
+"""A voice assistant that listens at home and bothers the cloud on purpose."""
+
+__version__ = "1.0"
+__release__ = "v1.0-rc.2"

grok_assistant-1.0/src/grok_assistant/__main__.py

@@ -0,0 +1,110 @@
+"""Grok Assistant, the PC body of the experiment."""
+
+from __future__ import annotations
+
+import faulthandler
+import sys
+import tempfile
+import traceback
+from pathlib import Path
+
+from grok_assistant.paths import bundle_root, default_data_dir, load_lines
+
+_FAULT_LOG = None
+
+
+def main(argv: list[str] | None = None) -> None:
+    try:
+        folder = default_data_dir()
+        folder.mkdir(parents=True, exist_ok=True)
+        crash = folder / "crash.log"
+        # The file has to stay referenced or a later native fault has nowhere to land.
+        global _FAULT_LOG
+        _FAULT_LOG = crash.open("a", encoding="utf-8")
+        faulthandler.enable(_FAULT_LOG, all_threads=True)
+    except OSError:
+        pass
+    try:
+        _main(argv)
+    except Exception:
+        path = _crash_log()
+        _tell_crash(path)
+        raise SystemExit(1)
+
+
+def _main(argv: list[str] | None) -> None:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if "--check" in args:
+        _write_check()
+        return
+    if "--console" in args:
+        from grok_assistant.console import run
+        run()
+        return
+    from grok_assistant.cloud.setup_grok import ensure_grok
+    from grok_assistant.ui.app import run
+
+    ensure_grok()
+    run()
+
+
+def _crash_log() -> Path:
+    folder = default_data_dir()
+    folder.mkdir(parents=True, exist_ok=True)
+    path = folder / "crash.log"
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(traceback.format_exc())
+        handle.write("\n")
+    return path
+
+
+def _tell_crash(path: Path) -> None:
+    try:
+        import tkinter as tk
+        from tkinter import messagebox
+
+        root = tk.Tk()
+        root.withdraw()
+        messagebox.showerror("Grok Assistant", f"Se cerró por un error.\n{path}")
+        root.destroy()
+    except Exception:
+        return
+
+
+def _importable(name: str) -> bool:
+    try:
+        __import__(name)
+    except Exception:
+        return False
+    return True
+
+
+def _kroko_ready() -> bool:
+    from grok_assistant.listening.kroko_ear import kroko_dir
+
+    return kroko_dir() is not None
+
+
+def _write_check() -> None:
+    from grok_assistant import __version__
+    from grok_assistant.cloud.grok_cli import GrokCLI
+    from grok_assistant.cloud.setup_grok import probe
+
+    status = probe()
+    lines = [
+        f"version={__version__}",
+        "channel=release-candidate",
+        f"hellos={len(load_lines('hellos-es.txt'))}",
+        f"scripts={(bundle_root() / 'scripts' / 'speak.ps1').exists()}",
+        f"listeners={(bundle_root() / 'listeners' / 'dictation.ps1').exists()}",
+        f"grok={GrokCLI.find() or ''}",
+        f"state={status.state}",
+        f"kroko_model={_kroko_ready()}",
+        f"sherpa={_importable('sherpa_onnx')}",
+        f"mic={_importable('sounddevice')}",
+    ]
+    Path(tempfile.gettempdir(), "GrokAssistant-check.txt").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

grok_assistant-1.0/src/grok_assistant/_bundle/LICENSE.md

@@ -0,0 +1,39 @@
+# Licencia y límites — Grok Assistant
+
+Versión candidata 1.0. Aplicación experimental.
+
+Autor: Antonio Castellon, Castellon.CH.
+
+## Qué es
+
+Grok Assistant es un programa experimental para hablar con un asistente en este equipo. El audio se queda aquí. Cuando hace falta, el programa envía texto a Grok. Grok y sus herramientas son un servicio de un tercero, no de este programa.
+
+## Responsabilidad
+
+Antonio Castellon no se hace responsable de cualquier fallo de seguridad o brecha que pueda darse por el uso de Grok y de sus herramientas. Eso incluye el acceso a la cuenta, lo que Grok busque o escriba, un archivo que cambie cuando esa opción esté permitida, y cualquier daño o pérdida que venga de ese uso.
+
+El programa se ofrece tal cual, sin garantía. Quien lo ejecuta lo hace por su cuenta.
+
+Si un administrador permite que Grok cambie archivos, esa elección se hace en este equipo. La shell sigue apagada. Aun así, el autor no responde de lo que Grok haga con las herramientas que se hayan dejado activas.
+
+## Texto que manda
+
+Este archivo está en español. La traducción al inglés es una ayuda para leerlo. Si los dos textos no dicen lo mismo, manda el español.
+
+---
+
+# License and limits — Grok Assistant
+
+Release candidate 1.0. Experimental application.
+
+Author: Antonio Castellon, Castellon.CH.
+
+Grok Assistant is an experimental program for talking with an assistant on this computer. The audio stays here. When needed, the program sends text to Grok. Grok and its tools are a third-party service, not part of this program.
+
+Antonio Castellon is not responsible for any security failure or breach that may come from using Grok and its tools. That includes access to the account, what Grok looks up or writes, a file it changes when that option is allowed, and any damage or loss that comes from that use.
+
+The program is offered as it is, without warranty. Anyone who runs it does so on their own account.
+
+If an administrator allows Grok to change files, that choice is made on this computer. The shell stays off. The author is still not answerable for what Grok does with the tools that were left on.
+
+If the Spanish text and this English text differ, the Spanish text prevails.

grok_assistant-1.0/src/grok_assistant/_bundle/listeners/dictation.ps1

@@ -0,0 +1,80 @@
+param(
+    [string]$Culture = "es-ES",
+    [string]$PauseFile = "",
+    [string]$ScoreDir = "",
+    [switch]$Probe
+)
+$ErrorActionPreference = "Stop"
+Add-Type -AssemblyName System.Speech
+# The string constructor wants a recognizer id such as MS-3082-80-DESK, not a culture name.
+try {
+    $cultureInfo = [System.Globalization.CultureInfo]::new($Culture)
+    $engine = New-Object System.Speech.Recognition.SpeechRecognitionEngine($cultureInfo)
+} catch {
+    $info = [System.Speech.Recognition.SpeechRecognitionEngine]::InstalledRecognizers() |
+        Where-Object { $_.Culture.Name -eq $Culture } |
+        Select-Object -First 1
+    if (-not $info) {
+        [Console]::Out.WriteLine("ERR:no-recognizer")
+        [Console]::Out.Flush()
+        exit 2
+    }
+    try {
+        $engine = New-Object System.Speech.Recognition.SpeechRecognitionEngine($info)
+    } catch {
+        [Console]::Out.WriteLine("ERR:no-recognizer")
+        [Console]::Out.Flush()
+        exit 2
+    }
+}
+if ($Probe) {
+    [Console]::Out.WriteLine("READY")
+    [Console]::Out.Flush()
+    exit 0
+}
+if ($ScoreDir) {
+    try {
+        $engine.LoadGrammar((New-Object System.Speech.Recognition.DictationGrammar))
+    } catch {
+        [Console]::Out.WriteLine("ERR:no-recognizer")
+        [Console]::Out.Flush()
+        exit 2
+    }
+    Get-ChildItem -LiteralPath $ScoreDir -Filter *.wav | Sort-Object Name | ForEach-Object {
+        $text = ""
+        try {
+            $engine.SetInputToWaveFile($_.FullName)
+            $result = $engine.Recognize()
+            if ($result -and $result.Text) { $text = $result.Text }
+        } catch {
+            $text = ""
+        }
+        [Console]::Out.WriteLine("LINE:" + $_.Name + "|" + $text)
+        [Console]::Out.Flush()
+    }
+    exit 0
+}
+try {
+    $engine.LoadGrammar((New-Object System.Speech.Recognition.DictationGrammar))
+    $engine.SetInputToDefaultAudioDevice()
+} catch {
+    [Console]::Out.WriteLine("ERR:no-microphone")
+    [Console]::Out.Flush()
+    exit 3
+}
+$engine.EndSilenceTimeout = [TimeSpan]::FromMilliseconds(700)
+$engine.EndSilenceTimeoutAmbiguous = [TimeSpan]::FromMilliseconds(700)
+$engine.InitialSilenceTimeout = [TimeSpan]::FromSeconds(2)
+[Console]::Out.WriteLine("READY")
+[Console]::Out.Flush()
+while ($true) {
+    if ($PauseFile -and (Test-Path -LiteralPath $PauseFile)) {
+        Start-Sleep -Milliseconds 200
+        continue
+    }
+    $result = $engine.Recognize()
+    if ($result -and $result.Text) {
+        [Console]::Out.WriteLine("LINE:" + $result.Text)
+        [Console]::Out.Flush()
+    }
+}

grok_assistant-1.0/src/grok_assistant/_bundle/listeners/install_speech.ps1

@@ -0,0 +1,19 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Log
+)
+$ErrorActionPreference = "Stop"
+try {
+    $name = "Language.Speech~~~es-ES~0.0.1.0"
+    $cap = Get-WindowsCapability -Online | Where-Object { $_.Name -eq $name } | Select-Object -First 1
+    if (-not $cap) {
+        throw "Windows no ofrece el idioma de voz es-ES en este equipo."
+    }
+    if ($cap.State -ne "Installed") {
+        Add-WindowsCapability -Online -Name $name | Out-Null
+    }
+    Set-Content -LiteralPath $Log -Value "OK" -Encoding utf8
+} catch {
+    Set-Content -LiteralPath $Log -Value ("ERR:" + $_.Exception.Message) -Encoding utf8
+    exit 1
+}

grok_assistant-1.0/src/grok_assistant/_bundle/scripts/build_exe.ps1

@@ -0,0 +1,21 @@
+# Build the single GrokAssistant.exe. This is for making the program, not for installing it.
+$ErrorActionPreference = "Stop"
+$root = Resolve-Path (Join-Path $PSScriptRoot "..")
+Set-Location $root
+$python = $null
+foreach ($candidate in @("python", "py")) {
+    if (Get-Command $candidate -ErrorAction SilentlyContinue) {
+        if ($candidate -eq "py") {
+            $python = & py -3 -c "import sys; print(sys.executable)"
+        } else {
+            $python = & python -c "import sys; print(sys.executable)"
+        }
+        break
+    }
+}
+if (-not $python) { throw "Python 3.11 or newer is required to build the executable." }
+& $python -m pip install --upgrade pip pyinstaller pystray Pillow "sherpa-onnx==1.13.8" "sounddevice==0.5.6" "numpy>=2.2,<2.5"
+& $python -m PyInstaller --noconfirm --clean (Join-Path $root "GrokAssistant.spec")
+$exe = Join-Path $root "dist\GrokAssistant.exe"
+if (-not (Test-Path $exe)) { throw "The executable was not created." }
+Write-Host "Built $exe"

grok_assistant-1.0/src/grok_assistant/_bundle/scripts/speak.ps1

@@ -0,0 +1,14 @@
+param(
+    [Parameter(Mandatory = $true)][string]$Path,
+    [int]$Volume = 70,
+    [string]$Voice = ""
+)
+$ErrorActionPreference = "Stop"
+Add-Type -AssemblyName System.Speech
+$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
+$synth.Volume = [Math]::Max(0, [Math]::Min(100, $Volume))
+if ($Voice) {
+    try { $synth.SelectVoice($Voice) } catch { }
+}
+$text = Get-Content -LiteralPath $Path -Raw -Encoding UTF8
+if ($text) { $synth.Speak($text) }

grok_assistant-1.0/src/grok_assistant/_bundle/scripts/voices.ps1

@@ -0,0 +1,6 @@
+$ErrorActionPreference = "Stop"
+Add-Type -AssemblyName System.Speech
+$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
+$synth.GetInstalledVoices() | ForEach-Object {
+    $_.VoiceInfo.Name + "|" + $_.VoiceInfo.Culture.Name
+}

grok_assistant-1.0/src/grok_assistant/build_stamp.txt

@@ -0,0 +1,2 @@
+73c54b29e221
+2026-10-02T07:32:53Z

grok_assistant-1.0/src/grok_assistant/buildinfo.py

@@ -0,0 +1,69 @@
+"""The build baked into this copy. About shows it. The updater compares it."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _git(cwd: Path, *args: str) -> str:
+    try:
+        from grok_assistant.quiet import no_window
+
+        out = subprocess.check_output(
+            ["git", *args],
+            cwd=cwd,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            stderr=subprocess.DEVNULL,
+            timeout=5,
+            **no_window(),
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return out.strip()
+
+
+def _read_file(path: Path) -> tuple[str, str]:
+    try:
+        lines = [line.strip() for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+    except OSError:
+        return "", ""
+    ident = lines[0] if lines else ""
+    when = lines[1] if len(lines) > 1 else ""
+    if not ident or ident == "unknown":
+        return "", when
+    return ident, when
+
+
+def read_stamp() -> tuple[str, str]:
+    """Return the build id and the UTC time it was made. Empty strings when unknown."""
+    if getattr(sys, "frozen", False):
+        return _read_file(Path(getattr(sys, "_MEIPASS")) / "grok_assistant" / "build_stamp.txt")
+    here = Path(__file__).resolve()
+    checkout = here.parents[2]
+    if (checkout / "scripts" / "speak.ps1").is_file():
+        ident = _git(checkout, "rev-parse", "--short=12", "HEAD")
+        if ident:
+            return ident, _git(checkout, "log", "-1", "--format=%cI")
+    return _read_file(here.parent / "build_stamp.txt")
+
+
+def build_line() -> str:
+    ident, _when = read_stamp()
+    if not ident:
+        return "build —"
+    return f"build {ident}"
+
+
+def write_stamp(path: Path | None = None) -> tuple[str, str]:
+    """Write the source commit and the current UTC time. The executable and the wheel both call this."""
+    dest = Path(path) if path else Path(__file__).resolve().parent / "build_stamp.txt"
+    checkout = Path(__file__).resolve().parents[2]
+    ident = _git(checkout, "rev-parse", "--short=12", "HEAD")
+    when = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    dest.write_text(f"{ident}\n{when}\n", encoding="utf-8")
+    return ident, when

grok_assistant-1.0/src/grok_assistant/cloud/__init__.py

@@ -0,0 +1 @@
+"""The door to the Grok executable."""