Skip to content

The open-source AI voice studio. Clone, dictate, create.

Add docstrings for OpenAI-compat backend and settings helpers

Moroya Sakamoto796e8356f55e
diff --git a/backend/backends/openai_compat_backend.py b/backend/backends/openai_compat_backend.py
index 2611878c..75f12045 100644
--- a/backend/backends/openai_compat_backend.py
+++ b/backend/backends/openai_compat_backend.py
@@ -35,6 +35,18 @@ class OpenAICompatLLMBackend:
api_key: Optional[str] = None,
timeout: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
):
+ """Configure the backend for a specific remote endpoint.
+
+ Args:
+ endpoint: Full base URL up to and including the ``/v1``
+ segment (trailing slash tolerated).
+ model: Model name to send in every request's ``model`` field.
+ api_key: Optional bearer token; empty string treated the same
+ as ``None`` so a blank UI field disables auth.
+ timeout: Per-request timeout in seconds. Defaults to two
+ minutes so slow remote hosts don't cut off long
+ generations.
+ """
# Strip a trailing slash so callers can pass either
# ``http://host:port/v1`` or ``http://host:port/v1/``.
self.endpoint = endpoint.rstrip("/")
@@ -50,8 +62,13 @@ class OpenAICompatLLMBackend:
self._current_model_size = model
def is_loaded(self) -> bool:
- # A remote endpoint is always "loaded" from this process's point of
- # view — no local weights to page in.
+ """Return ``True`` unconditionally — the remote server owns model state.
+
+ Voicebox's shared plumbing polls ``is_loaded`` to decide whether
+ to show a "downloading model…" progress bar; since a remote
+ endpoint has nothing to page in from this process's point of
+ view, the answer is always yes.
+ """
return True
async def load_model(self, model_size: Optional[str] = None) -> None: # noqa: ARG002
@@ -71,6 +88,20 @@ class OpenAICompatLLMBackend:
model_size: Optional[str] = None, # noqa: ARG002 — kept for protocol parity
examples: Optional[list[tuple[str, str]]] = None,
) -> str:
+ """Post one non-streaming chat completion and return the assistant text.
+
+ Mirrors ``LLMBackend.generate`` — the same call signature the
+ built-in Qwen backends use — so refinement and personality
+ services can swap between local and remote transparently.
+ ``model_size`` is accepted for protocol parity but ignored:
+ remote model selection is pinned at construction time.
+
+ Raises:
+ httpx.HTTPStatusError: The remote returned a non-2xx status.
+ httpx.RequestError: Transport failure (timeout, DNS, TLS).
+ ValueError: The response was well-formed HTTP but carried no
+ content in either the chat or legacy completion shapes.
+ """
messages = _build_messages(prompt, system, examples)
payload = {
"model": self.model,
@@ -113,6 +144,14 @@ def _build_messages(
system: Optional[str],
examples: Optional[list[tuple[str, str]]],
) -> list[dict]:
+ """Assemble the ``messages`` array for a chat completion request.
+
+ Optional system prompt and few-shot ``(user, assistant)`` pairs are
+ laid out in the order the OpenAI protocol expects: system first,
+ then example turns, then the fresh user prompt. Small models pattern-
+ match on inline examples in the system prompt but generalise from
+ structured turns, so refinement passes examples through this path.
+ """
messages: list[dict] = []
if system:
messages.append({"role": "system", "content": system})
@@ -125,6 +164,14 @@ def _build_messages(
def _extract_content(data: dict, url: str) -> str:
+ """Pull the assistant text out of a parsed chat-completion response.
+
+ Prefers the modern ``choices[0].message.content`` field but falls
+ back to the legacy ``choices[0].text`` layout for servers that still
+ return the text-completion shape from the chat endpoint. Raises
+ ``ValueError`` when neither field is present so the failure surfaces
+ with the offending URL and payload for debugging.
+ """
choices = data.get("choices") or []
if not choices:
raise ValueError(f"No choices in response from {url}: {data!r}")
diff --git a/backend/services/settings.py b/backend/services/settings.py
index fd9cc04a..f7ac6fc7 100644
--- a/backend/services/settings.py
+++ b/backend/services/settings.py
@@ -23,6 +23,12 @@ SINGLETON_ID = 1
def _get_or_create_capture_row(db: Session) -> DBCaptureSettings:
+ """Fetch the singleton capture-settings row, lazily creating it on first read.
+
+ Every setter path is a partial update against this row, so callers
+ can assume the returned object exists and holds the schema defaults
+ for any field the user hasn't customised yet.
+ """
row = db.query(DBCaptureSettings).filter(DBCaptureSettings.id == SINGLETON_ID).first()
if row is None:
row = DBCaptureSettings(
@@ -37,6 +43,11 @@ def _get_or_create_capture_row(db: Session) -> DBCaptureSettings:
def _get_or_create_generation_row(db: Session) -> DBGenerationSettings:
+ """Fetch the singleton generation-settings row, lazily creating it on first read.
+
+ Symmetric counterpart to :func:`_get_or_create_capture_row` for the
+ long-form generation defaults (chunk sizer, crossfade, normalize).
+ """
row = db.query(DBGenerationSettings).filter(DBGenerationSettings.id == SINGLETON_ID).first()
if row is None:
row = DBGenerationSettings(id=SINGLETON_ID)
@@ -70,6 +81,13 @@ def get_capture_settings(db: Session) -> DBCaptureSettings:
def update_capture_settings(db: Session, patch: dict[str, Any]) -> DBCaptureSettings:
+ """Apply a partial update to the capture-settings singleton and persist it.
+
+ After the commit, propagates the (possibly changed) custom-LLM
+ endpoint into the backend module state via
+ :func:`_sync_llm_backend_config` so subsequent refinement /
+ personality calls route to the new URL without needing a restart.
+ """
row = _get_or_create_capture_row(db)
_apply_patch(row, patch)
db.commit()
@@ -110,6 +128,13 @@ def get_generation_settings(db: Session) -> DBGenerationSettings:
def update_generation_settings(db: Session, patch: dict[str, Any]) -> DBGenerationSettings:
+ """Apply a partial update to the generation-settings singleton and persist it.
+
+ Unlike :func:`update_capture_settings`, no runtime state depends on
+ these values — the fields flow directly into the next
+ ``run_generation`` invocation via ``GenerationSettings`` — so the
+ commit is enough.
+ """
row = _get_or_create_generation_row(db)
_apply_patch(row, patch)
db.commit()