Fix authenticated Bextts Space calls

HF_SPACE_CONNECTION.md

@@ -0,0 +1,154 @@
+# Hugging Face Space Connection Notes
+
+Space: https://huggingface.co/spaces/archivartaunik/NotebookLM
+
+Runtime URL: https://archivartaunik-notebooklm.hf.space
+
+Repo: https://huggingface.co/spaces/archivartaunik/NotebookLM
+
+Local workspace: `D:\CodexPRJ\OpenNotebook`
+
+Hugging Face account currently used by `hf` CLI: `archivartaunik`
+
+## SSH / Dev Mode
+
+Dev Mode SSH command:
+
+```powershell
+ssh -i C:\Users\admin\.ssh\hagginfacekey archivartaunik-notebooklm@ssh.hf.space
+```
+
+Equivalent Hugging Face CLI command to print the SSH command:
+
+```powershell
+hf spaces ssh archivartaunik/NotebookLM --dry-run -i C:\Users\admin\.ssh\hagginfacekey
+```
+
+Enable Dev Mode:
+
+```powershell
+hf spaces dev-mode archivartaunik/NotebookLM
+```
+
+Disable Dev Mode:
+
+```powershell
+hf spaces dev-mode archivartaunik/NotebookLM --stop
+```
+
+Check Space status:
+
+```powershell
+hf spaces info archivartaunik/NotebookLM
+```
+
+Restart Space:
+
+```powershell
+hf spaces restart archivartaunik/NotebookLM
+```
+
+Factory rebuild if the normal restart keeps an old container:
+
+```powershell
+hf spaces restart archivartaunik/NotebookLM --factory-reboot
+```
+
+## Repo Workflow
+
+Local repo remote:
+
+```powershell
+git remote -v
+```
+
+Expected remote:
+
+```text
+origin  https://huggingface.co/spaces/archivartaunik/NotebookLM (fetch)
+origin  https://huggingface.co/spaces/archivartaunik/NotebookLM (push)
+```
+
+Before pushing, sync with remote:
+
+```powershell
+git fetch origin
+git rebase origin/main
+```
+
+Commit and push:
+
+```powershell
+git add <files>
+git commit -m "Your commit message"
+git push origin main
+```
+
+Important: changes made directly inside Dev Mode SSH are not safely preserved unless committed and pushed from inside the Space or copied back to the local repo and pushed.
+
+## Useful Runtime Checks
+
+Check that SSH reaches the Space:
+
+```powershell
+ssh -o StrictHostKeyChecking=accept-new -i C:\Users\admin\.ssh\hagginfacekey archivartaunik-notebooklm@ssh.hf.space "pwd && echo SSH_OK"
+```
+
+Check API health from inside the Space:
+
+```powershell
+ssh -i C:\Users\admin\.ssh\hagginfacekey archivartaunik-notebooklm@ssh.hf.space "curl -fsS http://localhost:5055/health"
+```
+
+Check frontend from inside the Space:
+
+```powershell
+ssh -i C:\Users\admin\.ssh\hagginfacekey archivartaunik-notebooklm@ssh.hf.space "curl -fsS -o /dev/null -w 'frontend_http=%{http_code}\n' http://localhost:8502"
+```
+
+Check important processes:
+
+```powershell
+ssh -i C:\Users\admin\.ssh\hagginfacekey archivartaunik-notebooklm@ssh.hf.space "ps -eo pid,stat,comm,args | grep -E 'supervisord|uvicorn|next-server|surreal-command|surreal start' | grep -v grep"
+```
+
+Fetch run logs:
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+hf spaces logs archivartaunik/NotebookLM --tail 120
+```
+
+Fetch build logs:
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+hf spaces logs archivartaunik/NotebookLM --build
+```
+
+## Bextts / ZeroGPU Token
+
+NotebookLM uses the public Bextts Space for Belarusian TTS:
+
+```powershell
+hf spaces info archivartaunik/Bextts --expand runtime
+```
+
+The Bextts Space runs on ZeroGPU, so NotebookLM must call it with an authenticated
+Hugging Face token. Store the token as a NotebookLM Space secret:
+
+```powershell
+$token = hf auth token
+hf spaces secrets add archivartaunik/NotebookLM -s "HF_TOKEN=$token"
+```
+
+At startup, `start-hf.sh` copies `HF_TOKEN` into the Bextts model credential config
+as the provider API key. Without this, Bextts calls are anonymous and can fail with
+`Bextts generation failed` while Bextts logs show `ZeroGPU quota exceeded`.
+
+## Current Notes
+
+- Dev Mode requires the Docker image to include `git`. The Dockerfile currently installs `bash`, `curl`, `git`, `git-lfs`, `procps`, and `wget`.
+- The previous startup crash was caused by a directory named `/app/frontend/node_modules/next/dist/compiled/ipaddr.js`. `start-hf.sh` now skips non-files before calling `read_text()`.
+- Current known good commit after that fix: `fb2282d`.
+- Do not store Hugging Face access tokens or service account secrets in this document.

start-hf.sh

@@ -41,6 +41,7 @@ fi
 export TTS_BATCH_SIZE="${TTS_BATCH_SIZE:-1}"
 export TTS_BATCH_DELAY_SECONDS="${TTS_BATCH_DELAY_SECONDS:-5}"
 export BEXTTS_BASE_URL="${BEXTTS_BASE_URL:-https://archivartaunik-bextts.hf.space}"
+export BEXTTS_API_KEY="${BEXTTS_API_KEY:-${HF_TOKEN:-}}"
 
 (
 /app/.venv/bin/python - <<'PY'
@@ -62,6 +63,7 @@ BEXTTS_BASE_URL = os.getenv(
     "BEXTTS_BASE_URL",
     "https://archivartaunik-bextts.hf.space",
 )
+BEXTTS_API_KEY = os.getenv("BEXTTS_API_KEY") or os.getenv("HF_TOKEN")
 
 
 def wait_for_api() -> None:
@@ -109,6 +111,7 @@ async def upsert_vertex_credential() -> str:
 
 async def upsert_bextts_credential() -> str:
     from open_notebook.domain.credential import Credential
+    from pydantic import SecretStr
 
     credentials = await Credential.get_by_provider("bextts")
     credential = next((item for item in credentials if item.name == "Bextts"), None)
@@ -125,6 +128,7 @@ async def upsert_bextts_credential() -> str:
     credential.provider = "bextts"
     credential.modalities = ["text_to_speech"]
     credential.base_url = BEXTTS_BASE_URL
+    credential.api_key = SecretStr(BEXTTS_API_KEY) if BEXTTS_API_KEY else None
     await credential.save()
     return str(credential.id)
 

upstream-esperanto/src/esperanto/providers/tts/bextts.py

@@ -86,9 +86,20 @@ class BexttsTextToSpeechModel(TextToSpeechModel):
         base_url: Optional[str] = None,
         **kwargs: Any,
     ):
+        config_api_key = (
+            kwargs.get("api_key")
+            or kwargs.get("HF_TOKEN")
+            or kwargs.get("hf_token")
+        )
+        resolved_api_key = (
+            api_key
+            or config_api_key
+            or os.getenv("BEXTTS_API_KEY")
+            or os.getenv("HF_TOKEN")
+        )
         super().__init__(
             model_name=model_name or BEXTTS_DEFAULT_MODEL,
-            api_key=api_key,
+            api_key=resolved_api_key,
             base_url=(
                 base_url
                 or os.getenv("BEXTTS_BASE_URL")
@@ -121,6 +132,9 @@ class BexttsTextToSpeechModel(TextToSpeechModel):
     def _file_url(self, file_path: str) -> str:
         return f"{self.base_url}/gradio_api/file={file_path}"
 
+    def _auth_headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}
+
     def _build_reference_file(self, kwargs: Dict[str, Any]) -> Optional[Dict[str, Any]]:
         reference_audio = (
             kwargs.get("reference_audio")
@@ -253,7 +267,10 @@ class BexttsTextToSpeechModel(TextToSpeechModel):
         file_path = file_data.get("path")
         if not file_path:
             raise RuntimeError("Bextts response did not include an audio path")
-        response = self.client.get(self._file_url(str(file_path)))
+        response = self.client.get(
+            self._file_url(str(file_path)),
+            headers=self._auth_headers(),
+        )
         if response.status_code >= 400:
             raise RuntimeError(f"Bextts audio download failed: HTTP {response.status_code}")
         return response.content
@@ -262,7 +279,10 @@ class BexttsTextToSpeechModel(TextToSpeechModel):
         file_path = file_data.get("path")
         if not file_path:
             raise RuntimeError("Bextts response did not include an audio path")
-        response = await self.async_client.get(self._file_url(str(file_path)))
+        response = await self.async_client.get(
+            self._file_url(str(file_path)),
+            headers=self._auth_headers(),
+        )
         if response.status_code >= 400:
             raise RuntimeError(f"Bextts audio download failed: HTTP {response.status_code}")
         return response.content
@@ -307,11 +327,17 @@ class BexttsTextToSpeechModel(TextToSpeechModel):
             payload = self._build_payload(normalized_text, voice, kwargs)
             response = self.client.post(
                 self._predict_url(),
-                headers={"Content-Type": "application/json"},
+                headers={
+                    "Content-Type": "application/json",
+                    **self._auth_headers(),
+                },
                 json=payload,
             )
             event_id = self._extract_event_id(response)
-            event_response = self.client.get(self._event_url(event_id))
+            event_response = self.client.get(
+                self._event_url(event_id),
+                headers=self._auth_headers(),
+            )
             if event_response.status_code >= 400:
                 raise RuntimeError(
                     f"Bextts event stream failed: HTTP {event_response.status_code}"
@@ -345,11 +371,17 @@ class BexttsTextToSpeechModel(TextToSpeechModel):
             payload = self._build_payload(normalized_text, voice, kwargs)
             response = await self.async_client.post(
                 self._predict_url(),
-                headers={"Content-Type": "application/json"},
+                headers={
+                    "Content-Type": "application/json",
+                    **self._auth_headers(),
+                },
                 json=payload,
             )
             event_id = self._extract_event_id(response)
-            event_response = await self.async_client.get(self._event_url(event_id))
+            event_response = await self.async_client.get(
+                self._event_url(event_id),
+                headers=self._auth_headers(),
+            )
             if event_response.status_code >= 400:
                 raise RuntimeError(
                     f"Bextts event stream failed: HTTP {event_response.status_code}"

upstream-esperanto/tests/providers/tts/test_bextts.py

@@ -60,6 +60,29 @@ def test_init_defaults():
     assert model.base_url == BEXTTS_DEFAULT_BASE_URL
 
 
+def test_init_uses_bextts_api_key_env(monkeypatch):
+    monkeypatch.setenv("BEXTTS_API_KEY", "hf_test_token")
+
+    model = BexttsTextToSpeechModel()
+
+    assert model.api_key == "hf_test_token"
+
+
+def test_init_uses_hf_token_env_as_fallback(monkeypatch):
+    monkeypatch.delenv("BEXTTS_API_KEY", raising=False)
+    monkeypatch.setenv("HF_TOKEN", "hf_test_token")
+
+    model = BexttsTextToSpeechModel()
+
+    assert model.api_key == "hf_test_token"
+
+
+def test_init_uses_hf_token_config():
+    model = BexttsTextToSpeechModel(HF_TOKEN="hf_test_token")
+
+    assert model.api_key == "hf_test_token"
+
+
 def test_generate_speech_posts_to_gradio_and_downloads_wav(tts_model):
     tts_model.client.post.return_value = make_response(
         json_data={"event_id": "evt-1"}
@@ -89,6 +112,30 @@ def test_generate_speech_posts_to_gradio_and_downloads_wav(tts_model):
     assert response.provider == "bextts"
 
 
+def test_generate_speech_sends_authorization_header(tts_model):
+    tts_model.api_key = "hf_test_token"
+    tts_model.client.post.return_value = make_response(
+        json_data={"event_id": "evt-1"}
+    )
+    tts_model.client.get.side_effect = [
+        make_response(text=COMPLETE_EVENT),
+        make_response(content=RAW_AUDIO),
+    ]
+
+    tts_model.generate_speech("Прывітанне", voice="Aaron Dreschner")
+
+    assert tts_model.client.post.call_args.kwargs["headers"] == {
+        "Content-Type": "application/json",
+        "Authorization": "Bearer hf_test_token",
+    }
+    assert tts_model.client.get.call_args_list[0].kwargs["headers"] == {
+        "Authorization": "Bearer hf_test_token",
+    }
+    assert tts_model.client.get.call_args_list[1].kwargs["headers"] == {
+        "Authorization": "Bearer hf_test_token",
+    }
+
+
 def test_generate_speech_defaults_to_prepared_voice(tts_model):
     tts_model.client.post.return_value = make_response(
         json_data={"event_id": "evt-1"}

upstream-open-notebook/api/credentials_service.py

@@ -61,7 +61,7 @@ PROVIDER_ENV_CONFIG: Dict[str, dict] = {
     },
     "dashscope": {"required": ["DASHSCOPE_API_KEY"]},
     "minimax": {"required": ["MINIMAX_API_KEY"]},
-    "bextts": {"required_any": ["BEXTTS_BASE_URL"]},
+    "bextts": {"required_any": ["BEXTTS_BASE_URL", "BEXTTS_API_KEY", "HF_TOKEN"]},
 }
 
 PROVIDER_MODALITIES: Dict[str, List[str]] = {
@@ -304,10 +304,12 @@ def create_credential_from_env(provider: str) -> Credential:
             api_key=SecretStr(api_key) if api_key else None,
         )
     elif provider == "bextts":
+        api_key = os.environ.get("BEXTTS_API_KEY") or os.environ.get("HF_TOKEN")
         return Credential(
             name=name,
             provider=provider,
             modalities=modalities,
+            api_key=SecretStr(api_key) if api_key else None,
             base_url=os.environ.get("BEXTTS_BASE_URL"),
         )
     else:

upstream-open-notebook/open_notebook/domain/credential.py

@@ -78,7 +78,10 @@ class Credential(ObjectModel):
         """
         config: Dict[str, Any] = {}
         if self.api_key:
-            config["api_key"] = self.api_key.get_secret_value()
+            secret_value = self.api_key.get_secret_value()
+            config["api_key"] = secret_value
+            if self.provider and self.provider.lower() == "bextts":
+                config["HF_TOKEN"] = secret_value
         if self.base_url:
             config["base_url"] = self.base_url
             # For Azure, base_url from the UI form maps to endpoint

upstream-open-notebook/tests/test_bextts_provider.py

@@ -13,7 +13,9 @@ from open_notebook.ai.model_discovery import (
 
 
 def test_bextts_credential_metadata():
-    assert PROVIDER_ENV_CONFIG["bextts"] == {"required_any": ["BEXTTS_BASE_URL"]}
+    assert PROVIDER_ENV_CONFIG["bextts"] == {
+        "required_any": ["BEXTTS_BASE_URL", "BEXTTS_API_KEY", "HF_TOKEN"]
+    }
     assert get_default_modalities("bextts") == ["text_to_speech"]
 
 

upstream-open-notebook/tests/test_credentials_api.py

@@ -216,6 +216,29 @@ class TestCredentialNumCtx:
         assert "num_ctx" not in cred.to_esperanto_config()
 
 
+class TestBexttsCredentialConfig:
+    """Tests for Bextts credential values threaded into Esperanto config."""
+
+    def test_api_key_is_exposed_as_hf_token_alias(self):
+        from pydantic import SecretStr
+
+        from open_notebook.domain.credential import Credential
+
+        cred = Credential(
+            name="Bextts",
+            provider="bextts",
+            modalities=["text_to_speech"],
+            api_key=SecretStr("hf_test_token"),
+            base_url="https://archivartaunik-bextts.hf.space",
+        )
+
+        config = cred.to_esperanto_config()
+
+        assert config["api_key"] == "hf_test_token"
+        assert config["HF_TOKEN"] == "hf_test_token"
+        assert config["base_url"] == "https://archivartaunik-bextts.hf.space"
+
+
 class TestAudioProviderWiring:
     """Tests for the new audio providers (Mistral STT/TTS, Deepgram TTS, xAI TTS)."""