Improve demo (#855)

* Improve demo

* Improvements on token set, improve readme and release note, add some error logging

* Update document

* Improve error handling and update azd parameter file, update docs

* clear readme

* Improve model parameter check and adding debug log

* hardcode model config instead

* Update to use parameters_json, we expect the model to do model specific filter

* simplify the config.json.tpl for a non-breaking update

Author: vicancy

samples/ai/chat-demo.zip

@@ -0,0 +1,39 @@
+## .webappignore controls what source files are excluded from App Service packaging.
+## Similar semantics to .gitignore; evaluated by Azure Developer CLI when creating the zip.
+
+# Local environment secrets
+.env
+*.env
+.env.*
+
+# Node modules (rebuilt in prepackage hook / Oryx build)
+client/node_modules
+node_modules
+
+# Git metadata
+**/.git
+
+# Python virtual environments & caches
+**/.venv
+**/__pycache__
+*.py[cod]
+*.log
+
+# Frontend intermediate artifacts (final build copied into python_server/static)
+client/.vite
+client/dist
+
+# DO NOT exclude python_server/static (serves built client)
+
+# Editor / platform cruft
+.vscode
+.idea
+Thumbs.db
+.DS_Store
+
+# Coverage / test artifacts (optional)
+coverage/
+htmlcov/
+
+# Experimental local scripts
+scripts/local*/

samples/ai/chat-demo/.azureignore

@@ -18,22 +18,40 @@ Prereqs:
 * Node 18+
 
 1. Create a PAT with **Models – Read**: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
-2. Install backend + frontend deps:
-  ```bash
-  pip install -r requirements.txt
-  # optional (tests, typing): pip install -r requirements-dev.txt
-  ```
-3. (Set token if you want AI answers)
-  ```bash
-  export GITHUB_TOKEN=<your_pat>        # bash/zsh
-  # PowerShell
-  $env:GITHUB_TOKEN="<your_pat>"
-  ```
-4. Start everything (serves React build automatically):
-  ```bash
-  python start_dev.py
-  ```
-5. Open http://localhost:5173
+2. (Recommended) Create and activate a virtual environment:
+   * macOS/Linux (bash/zsh):
+     ```bash
+     python3 -m venv .venv
+     source .venv/bin/activate
+     python -m pip install --upgrade pip
+     ```
+   * Windows (PowerShell):
+     ```pwsh
+     python -m venv .venv
+     .venv\Scripts\Activate.ps1
+     python -m pip install --upgrade pip
+     ```
+   Deactivate anytime with:
+   ```bash
+   deactivate
+   ```
+3. Install backend + frontend deps (inside the venv):
+   ```bash
+   pip install -r requirements.txt
+   # optional (tests, typing): pip install -r requirements-dev.txt
+   ```
+4. (Set token if you want AI answers)
+   ```bash
+   export GITHUB_TOKEN=<your_pat>        # bash/zsh
+   # PowerShell
+   $env:GITHUB_TOKEN="<your_pat>"
+   ```
+   Alternatively, you can update GITHUB_TOKEN in [./python_server/.env](./python_server/.env)
+5. Start everything (serves React build automatically):
+   ```bash
+   python start_dev.py
+   ```
+6. Open http://localhost:5173
 
 Running services:
 * HTTP API :5000
@@ -71,29 +89,64 @@ Frontend (Vitest + RTL):
 npm --prefix client test
 ```
 Selected coverage areas (backend): config merge, room store limits, transport factory, room lifecycle, streaming send path.
-Coverage snapshot:
-* Runtime config validation & merging
-* In‑memory room store behavior / limits
-* Chat service builder (self vs webpubsub path & credential preconditions)
-* Room lifecycle (add/remove)
-* Streaming send path basic invariants
 
-#### Frontend (Vitest + RTL)
-Location: `client/src/__tests__`
+## Deploy to Azure
+Install the Azure Developer CLI if you haven't: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd
 
-Run:
+```bash
+azd env new chatenv
+azd env set githubModelsToken ghp_your_token_here   # store token for this env
+azd up
 ```
-npm --prefix client test
+
+Security note: `azd env set` persists the value in the environment state on disk; avoid committing the `.azure` folder.
+
+That single `azd up` command:
+1. Provisions Azure Web PubSub + Storage + App Service (with Managed Identity)
+2. Builds the React client
+3. Deploys the Python backend
+4. Applies app settings sourced from previously persisted environment values (e.g. `githubModelsToken` set via `azd env set`)
+5. Prints your site URL + negotiate endpoint
+
+### Enable AI Features (One-time Setup)
+**Recommended Default:** Pass the token via secure Bicep parameter at provision time (Option A). This avoids surprise hooks and keeps behavior explicit. For production, prefer Key Vault (Option D).
+
+**Option A (Secure Bicep Parameter – default)**
+```bash
+azd env set githubModelsToken ghp_your_token_here
+azd up
 ```
-Included tests:
-* Room switching: cached messages isolated & textarea present after switch
-* Sender fallback: history messages without `from` show `AI Assistant`
+Rotate: `azd env set githubModelsToken <new>` then `azd provision`.
+Remove: `azd env unset githubModelsToken` then `azd provision`.
 
-Add more ideas:
-* Mid‑stream room switch preserves previous room’s partial content when returning
-* Simulated error banner rendering
-* Theme / avatar contexts snapshot
+**Option B (Manual CLI – update anytime)**
+```bash
+az webapp config appsettings set \
+   --resource-group <your-resource-group> \
+   --name <your-web-app-name> \
+   --settings GITHUB_TOKEN="ghp_your_github_token_here"
+
+az webapp restart \
+   --resource-group <your-resource-group> \
+   --name <your-web-app-name>
+```
+
+**Option C (Portal)** Azure Portal → App Service → Configuration → Application settings → New application setting: Name=`GITHUB_TOKEN`, Value=`your-token`
 
+**Option D (Key Vault Reference – production / rotation)**
+1. Store the PAT as a secret in a Key Vault you control.
+2. Grant the web app’s managed identity `get` permissions.
+3. Add an app setting: `[email protected](SecretUri=https://<vault>.vault.azure.net/secrets/<secret-name>/<version>)`
+4. Restart the web app.
+
+### Next Changes
+```bash
+azd deploy   # code only (frontend or backend)
+```
+Infra template changes:
+```bash
+azd provision && azd deploy
+```
 
 ## Core Environment Variables
 | Variable | Purpose |
@@ -113,7 +166,9 @@ Notes:
 ## Custom Resource Names (Optional)
 Want predictable names? Provide overrides (must be globally unique where required):
 ```bash
-azd provision --set webPubSubNameOverride=mywps1234 --set webAppNameOverride=mychatweb1234
+azd env set webPubSubNameOverride mywps1234
+azd env set webAppNameOverride mychatweb1234
+azd provision
 ```
 
 ## Iteration Cheatsheet
@@ -151,6 +206,47 @@ More: **[ADVANCED.md](./docs/ADVANCED.md#2-local-development-paths)**
 - Customize AI logic in `python_server/chat_model_client.py`
 - Review how scalable history works now (Table storage) in the persistence section of the advanced doc.
 
+## Debugging & Logs
+**Control runtime log level**
+- Set `LOG_LEVEL` to adjust all server logs (`DEBUG`, `INFO`, `WARNING`, `ERROR`). Defaults to `INFO`.
+- Optional: customize the format with `LOG_FORMAT` (defaults to `"%(asctime)s %(levelname)s %(name)s: %(message)s"`).
+
+Example (PowerShell):
+```pwsh
+$env:LOG_LEVEL="DEBUG"
+python start_dev.py
+```
+- `DEBUG` enables verbose traces from Flask, OpenAI SDK, and httpx transport.
+
+**Azure App Service**
+- Portal → App Service → Configuration → Application settings → add `LOG_LEVEL`, then restart.
+- Stream logs: `az webapp log tail --resource-group <rg> --name <app-name>`.
+
+## Troubleshooting
+**App Service setting `GITHUB_TOKEN` missing after `azd up`**
+1. Make sure you set the value *before* the first `azd provision`: `azd env set githubModelsToken <token>`.
+3. If you added the token *after* the first deployment, run `azd provision` (you don't need `azd deploy` for an app setting change). Use `azd provision --no-state` if it claims no changes.
+
+**Changed token but app setting didn’t update**
+- Confirm the parameter file or environment value is non-empty.
+- Run `azd env get githubModelsToken` to verify what azd stored.
+- Re-run `azd provision`. (Only a code change needs `azd deploy`.)
+
+**Early `ECONNREFUSED` errors in the browser during local dev**
+- The React dev server starts first and immediately proxies `/api/*` to Flask while it’s still binding.
+- These transient errors vanish once `Flask app running` appears in the terminal. Safe to ignore.
+
+**Web PubSub negotiate failing (401/403 or missing access)**
+- Ensure the web app’s Managed Identity has necessary roles (e.g. Web PubSub Service Owner / Contributor) on the Web PubSub resource.
+- If using the `createRoleAssignments` parameter and you turned it off after first provision, assign roles manually.
+
+**`Unauthorized` error when calling openai**
+- Check if the GitHub PAT has **model read** permission
+
+**General diagnostic tips**
+- Show current environment values: `azd env get`.
+- List effective app settings (Azure): `az webapp config appsettings list --name <app-name> --resource-group <rg>`.
+
 ---
 Happy hacking! Open an issue or PR in [our GitHub repo](https://github.com/Azure/azure-webpubsub) with feedback.
 

samples/ai/chat-demo/.webappignore

@@ -2,8 +2,23 @@
 
 Plain-language updates focused on what demo users can try. Non-customer internal details intentionally omitted.
 
-## [Unreleased]
-Nothing user-facing has changed yet.
+## [0.1.1] - 2025-10-30 (Preview)
+
+### Added
+- `config.json` configuration file added to support different models with distinct parameters.
+
+### Changed
+- Provide `githubModelsToken` parameter for `azd`
+- AI error visibility: early initialization surfaces missing/invalid token directly to users via broadcast message.
+- Logging improved around streaming start / completion / error states.
+
+### Upgrade Guidance (0.1.0 → 0.1.1)
+1. If you want AI immediately, set the token before running `azd up`:
+	`azd env set githubModelsToken <token>` then `azd up`.
+2. If you deployed without a token, enable AI later with:
+	`azd env set githubModelsToken <token>` then `azd provision`.
+3. Rotate token: `azd env set githubModelsToken <new_token>` then `azd provision`.
+3. To change the token later, repeat provision with the new value.
 
 ## [0.1.0] - 2025-10-11 (Preview)
 Initial preview release.

samples/ai/chat-demo/README.md

@@ -4,39 +4,16 @@ metadata:
 infra:
   provider: bicep
   path: infra
-  # To override the default web app name (<baseName>-web), set parameter:
-  # parameters:
-  #   webAppNameOverride: your-custom-name
-    # To override (or guarantee uniqueness for) the Web PubSub service name:
-    # azd provision --set webPubSubNameOverride=myuniquewpsname123
 services:
   chatserver:
-    # Use repo root as the project so `python_server` remains a package
-    # and Oryx can load `wsgi:app` from the root wsgi.py
     project: .
     language: python
     host: appservice
-    # Frontend build hook (build React and copy static files) - ensure this exists in project root or scripts
     hooks:
       prepackage:
         windows:
           shell: pwsh
-          run: |
-            Push-Location .\client
-            if (Test-Path node_modules) {
-              Write-Host "Reusing existing node_modules" 
-            } else {
-              Write-Host "Installing dependencies in client/" 
-              npm install
-            }
-            npm run build
-            Pop-Location
-            if (Test-Path .\python_server\static) { Remove-Item -Recurse -Force .\python_server\static }
-            Copy-Item -Recurse .\client\dist .\python_server\static
+          run: ./scripts/prepackage.ps1
         posix:
           shell: sh
-          run: |
-            (cd ./client && ([ -d node_modules ] || npm install) && npm run build)
-            rm -rf ./python_server/static
-            mkdir -p ./python_server
-            cp -R ./client/dist ./python_server/static
+          run: ./scripts/prepackage.sh