fix: ws_mermaid crash when STT deps missing, host Ollama via host-gateway by jaewilson07 · Pull Request #6 · jaewilson07/projects

jaewilson07 · 2026-04-21T18:25:51Z

Summary

Bug: ws_mermaid used WHISPER_ENABLED (config intent) to guard the from whisperlivekit import AudioProcessor import, causing HTTP 500 on every WebSocket connection when whisper.enabled=true but the package isn't installed (e.g. Docker without requirements.stt.txt). Fixed by replacing all WHISPER_ENABLED guards inside the handler with _stt_available (the runtime flag set only after a successful import at startup).
Docker Ollama: Removed the hard-coded OLLAMA_URL=http://ollama:11434 environment override from docker-compose so .env can override it. Added extra_hosts: host.docker.internal:host-gateway so the container can reach a host-resident Ollama without pulling models into the bundled vtm-ollama container.

Test plan

WebSocket connects and returns handshake even with whisper.enabled=true and no STT deps installed
{"type": "generate", "text": "..."} produces a diagram response via host Ollama
stt_enabled: false in /v1/config when whisper import fails

🤖 Generated with Claude Code

Ensures containers recover automatically after crashes or Docker restarts, supporting Docker Desktop auto-start on Windows login. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

whisper.enabled/model/language/device, ollama.default_model, openai.model, and paths now live in config.yaml (volume-mounted, editable without rebuild). .env reduced to secrets only (OLLAMA_URL). Env var overrides still work. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ck, WHISPER_DEVICE wired, default enabled=false

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…nabled in /v1/config Address Copilot review on PR #5: - Add _config_section() helper to guard against non-dict config sections - Replace bare _cfg.get("x", {}).get() chains with per-section dicts - Introduce _stt_available flag (False until WhisperLiveKit loads); stt_enabled in /v1/config now reflects actual runtime state instead of config intent Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…d _stt_available flag Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…an up .env.example and README - config.yaml: add comment explaining whisper.enabled=true is safe (graceful failure via _stt_available) - .env.example: remove OLLAMA_MODEL, WHISPER_MODEL/DEVICE, MERMAID_PROMPT_PATH (moved to config.yaml) - README: split env table into config.yaml section and .env secrets-only section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ama via host-gateway - ws_mermaid: replace WHISPER_ENABLED guards with _stt_available so WS works when whisper config is enabled but import failed (Docker without STT deps) - docker-compose: remove hard-coded OLLAMA_URL override; add extra_hosts for host.docker.internal so .env can point at host Ollama Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9ca1b461be

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-21T18:29:03Z

    env_file: .env
-    environment:
-      - OLLAMA_URL=http://ollama:11434
-    depends_on:
-      - ollama
+    # OLLAMA_URL comes from .env — default uses bundled vtm-ollama; set to
+    # http://host.docker.internal:11434 to use a host Ollama instead.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"


Restore service URL override for bundled Ollama

Removing the OLLAMA_URL=http://ollama:11434 override makes the default Docker flow fail: with env_file: .env and the shipped .env.example (OLLAMA_URL=http://localhost:11434), the API container points to itself instead of the ollama service, so /v1/config model discovery and diagram generation fail unless users manually edit .env. This regresses the out-of-the-box docker-compose up path that previously worked with the bundled Ollama container.

Useful? React with 👍 / 👎.

Copilot

Pull request overview

Fixes a WebSocket crash path when Whisper/STT dependencies are missing, and adjusts Docker Compose to better support using a host-resident Ollama instance.

Changes:

Add a runtime _stt_available flag set only after successful WhisperLiveKit import/initialization, and use it throughout the WebSocket handler/config response.
Remove the hard-coded OLLAMA_URL override in docker-compose.yml and add host.docker.internal:host-gateway for host Ollama routing.
Update configuration/docs to distinguish config.yaml (non-secrets) from .env (secrets), and document the new behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`voice-to-mermaid/backend/main.py`	Introduces `_stt_available` and uses it to prevent WS import crashes when STT deps are absent.
`voice-to-mermaid/backend/docker-compose.yml`	Removes forced `OLLAMA_URL` and adds host-gateway mapping for host Ollama access.
`voice-to-mermaid/backend/config.yaml`	Updates Whisper config comments and toggles `whisper.enabled`.
`voice-to-mermaid/backend/.env.example`	Removes non-secret settings and leaves only secret/env URLs/keys.
`voice-to-mermaid/README.md`	Documents config.yaml vs .env split and updates configuration tables.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-21T18:29:50Z


 | Variable | Default | Description |
 |---|---|---|
 | `OLLAMA_URL` | `http://localhost:11434` | Ollama server URL |


The OLLAMA_URL default here is documented as http://localhost:11434, but when running via backend/docker-compose.yml the in-network URL to the bundled service is http://ollama:11434. Consider clarifying the table (e.g., separate defaults for local vs Docker Compose) to prevent a common misconfiguration.

Suggested change

| `OLLAMA_URL` | `http://localhost:11434` | Ollama server URL |

| `OLLAMA_URL` | Local: `http://localhost:11434`<br>Docker Compose: `http://ollama:11434` | Ollama server URL; use the Docker Compose value when connecting to the bundled Ollama service from the backend container |

Copilot · 2026-04-21T18:29:51Z

+  # If import fails (deps not installed), _stt_available stays False and
+  # /v1/config returns stt_enabled: false — no crash.
+  # Install requirements.stt.txt (or add it to Dockerfile) before setting true.
+  enabled: true


whisper.enabled is set to true here, but the surrounding comments say it should only be enabled after installing requirements.stt.txt. This also conflicts with the README table that lists the default as false. Consider reverting the default to false (and letting users opt-in), or update the comments/docs to match the intended default behavior.

Suggested change

enabled: true

enabled: false

Copilot · 2026-04-21T18:29:51Z

+| `ollama.default_model` | `qwen3:8b` | Ollama model for diagram generation |
+| `ollama.model_filter` | _(list)_ | Model name prefixes shown in the UI picker |
+| `openai.model` | `gpt-4o-mini` | OpenAI-compatible model name |
+| `whisper.enabled` | `false` | Set `true` after installing `requirements.stt.txt` |


The table lists whisper.enabled default as false, but backend/config.yaml currently sets it to true. Please align the documentation with the actual shipped default (or adjust the config default) to avoid confusion.

Suggested change

| `whisper.enabled` | `false` | Set `true` after installing `requirements.stt.txt` |

| `whisper.enabled` | `true` | Enables Whisper transcription by default |

Copilot · 2026-04-21T18:29:51Z

 # Option A: Ollama (local, recommended for self-hosting)
 OLLAMA_URL=http://localhost:11434


OLLAMA_URL is set to http://localhost:11434, which works for local (non-Docker) runs, but will not reach the bundled ollama service from inside the api container. Given the docker-compose change removing the hard-coded override, consider setting the example to http://ollama:11434 (and documenting http://host.docker.internal:11434 for a host Ollama) so docker-compose up works out of the box.

Suggested change

# Option A: Ollama (local, recommended for self-hosting)

OLLAMA_URL=http://localhost:11434

# Option A: Ollama (bundled Docker Compose service, recommended for self-hosting)

# If Ollama runs on the host instead, use http://host.docker.internal:11434

OLLAMA_URL=http://ollama:11434

Copilot · 2026-04-21T18:29:52Z

+    # OLLAMA_URL comes from .env — default uses bundled vtm-ollama; set to
+    # http://host.docker.internal:11434 to use a host Ollama instead.


This comment says the default OLLAMA_URL uses the bundled vtm-ollama, but the compose file no longer sets OLLAMA_URL (it now comes entirely from .env). With .env.example currently using http://localhost:11434, docker-compose up will point the api container at itself instead of the ollama service. Suggest either (a) set a default in compose (e.g., environment: OLLAMA_URL=${OLLAMA_URL:-http://ollama:11434}), or (b) change .env.example/docs so the default is http://ollama:11434 for compose usage.

Suggested change

# OLLAMA_URL comes from .env — default uses bundled vtm-ollama; set to

# http://host.docker.internal:11434 to use a host Ollama instead.

# Default to the bundled ollama service; set OLLAMA_URL to

# http://host.docker.internal:11434 to use a host Ollama instead.

environment:

OLLAMA_URL: ${OLLAMA_URL:-http://ollama:11434}

…bled default - docker-compose: restore OLLAMA_URL default (http://ollama:11434) via ${OLLAMA_URL:-http://ollama:11434} so docker-compose up works out of the box; .env still overrides it (host.docker.internal:11434 for host Ollama) - .env.example: use http://ollama:11434 as default with host Ollama commented variant - config.yaml: revert whisper.enabled to false (safe default; README already said false) - README: align whisper.enabled description and OLLAMA_URL default with actual shipped values Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jaewilson07 and others added 8 commits April 19, 2026 23:04

fix: add restart: unless-stopped to vtm-api and ollama services

844c929

Ensures containers recover automatically after crashes or Docker restarts, supporting Docker Desktop auto-start on Windows login. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix: address PR review comments — dict validation, ImportError fallba…

d87cd93

…ck, WHISPER_DEVICE wired, default enabled=false

feat: enable whisper STT locally (medium.en, auto device)

49ab161

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

merge: resolve conflicts with main — keep _config_section() helper an…

57b21fc

…d _stt_available flag Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings April 21, 2026 18:25

Copilot started reviewing on behalf of jaewilson07 April 21, 2026 18:26 View session

chatgpt-codex-connector Bot reviewed Apr 21, 2026

View reviewed changes

Copilot AI reviewed Apr 21, 2026

View reviewed changes

jaewilson07 and others added 2 commits April 21, 2026 12:41

merge: resolve conflicts with main — keep PR #6 review fixes

6e723bf

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jaewilson07 merged commit 66ddd58 into main Apr 21, 2026
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: ws_mermaid crash when STT deps missing, host Ollama via host-gateway#6

fix: ws_mermaid crash when STT deps missing, host Ollama via host-gateway#6
jaewilson07 merged 10 commits into
mainfrom
feat/config-yaml-settings

jaewilson07 commented Apr 21, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Apr 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	\| `OLLAMA_URL` \| `http://localhost:11434` \| Ollama server URL \|
	\| `OLLAMA_URL` \| Local: `http://localhost:11434`<br>Docker Compose: `http://ollama:11434` \| Ollama server URL; use the Docker Compose value when connecting to the bundled Ollama service from the backend container \|

	\| `whisper.enabled` \| `false` \| Set `true` after installing `requirements.stt.txt` \|
	\| `whisper.enabled` \| `true` \| Enables Whisper transcription by default \|

		# Option A: Ollama (local, recommended for self-hosting)
		OLLAMA_URL=http://localhost:11434

		# OLLAMA_URL comes from .env — default uses bundled vtm-ollama; set to
		# http://host.docker.internal:11434 to use a host Ollama instead.

Conversation

jaewilson07 commented Apr 21, 2026

Summary

Test plan

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants