Merge pull request #186 from TheWizardsCode/ge-hch.9/plan

WIP: Runtime: integrate embeddings into engine (bge-hch.5.22)

Author: rgardler-msft

.beads/issues.jsonl

@@ -38,8 +38,10 @@ directorConfig:
   # Default director risk threshold used by the demo UI and Director when not set per-call
   # Value between 0.0 (strict) and 1.0 (lenient). Default: 0.4
   riskThreshold: 0.4
+  
+  # Enable use of embeddings in the local GEngine environment (true/false)
+  enableEmbeddings: true
 
 # Notes:
 # - The proxy prefers CLI args, then environment variables, then this file.
 # - To expand settings, update scripts/cors-proxy.js and package.json.
-

.beads/sync_base.jsonl

@@ -0,0 +1,28 @@
+Embedding Integration (runtime)
+
+Overview
+--------
+The Director can optionally use local semantic embeddings to improve scoring for thematic consistency, lore adherence, and character voice. This feature is opt-in and disabled by default.
+
+Enabling
+--------
+- Set `enableEmbeddings: true` in `.gengine/config.yaml` under `directorConfig`, or pass `{ enableEmbeddings: true }` via the `evaluate()` `config` argument.
+- For Node integration tests you may set environment flags (used by embedding service): `EMBED_NODE=1` to enable Node fallback.
+
+Telemetry
+---------
+When embeddings are enabled, Director emits embedding telemetry inside the `director_decision` event under `metrics.embedding` with fields:
+- `used` (boolean) - whether embeddings were successfully computed
+- `latencyMs` (number) - inference time in milliseconds
+- `fallback` (boolean) - true when embeddings were not used and placeholders were applied
+- `metrics` (optional object) - similarity metrics (0..1) for `thematic`, `lore`, and `voice` when available
+
+Implementation notes
+--------------------
+- `evaluate()` computes embeddings asynchronously (using `web/demo/js/embedding-service.js` when available) and derives similarity metrics when story-level embeddings are provided on `storyContext` as `themeEmbedding`, `loreEmbedding`, `voiceEmbedding` arrays.
+- `computeRiskScore()` remains synchronous and reads precomputed `config.embeddingMetrics` (if present) to convert similarities into placeholder risks. This keeps the core scoring deterministic and testable.
+
+Follow-ups
+----------
+1) Precompute story-level embeddings at load-time and attach them to story context. (bead created)
+2) Optionally emit a dedicated `embedding_inference` telemetry event in addition to including embedding metadata in director telemetry. (bead created)

.gengine/config.example.yaml

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
+    "postinstall": "npx playwright install --with-deps chromium",
     "serve-demo": "http-server web",
     "build": "echo 'no-op build'",
     "validate-story": "node scripts/validate-story.js --glob \"web/stories/**/*.ink\" --output json --max-steps 2000",

docs/dev/embeddings.md

@@ -74,6 +74,13 @@ const defaults = {
 
   placeholderDefault: 0.3,
 
+  // Enable embedding-based scoring in the runtime. Disabled by default.
+  // Can be toggled via local .gengine/config.yaml or environment overrides
+  // (see loadLocalConfig/ENV parsing in this file). When enabled the Director
+  // will attempt to compute semantic embeddings for proposals and use
+  // similarity-derived metrics for thematic/lore/voice scoring.
+  enableEmbeddings: false,
+
   // Global default decision threshold used by the Director when not overridden per-call
   // Value is in 0.0..1.0 where lower is stricter (default 0.4)
   riskThreshold: 0.4

package-lock.json

@@ -151,7 +151,9 @@ test('Director threshold slider updates stored settings', async ({ page }) => {
   await expect(page.locator('.ai-config-section')).toBeVisible();
 
   const slider = page.locator('#director-risk-threshold');
-  await expect(slider).toHaveValue('0.4');
+  // Wait for defaults to hydrate from ApiKeyManager. Expect UI default (0.4)
+  // regardless of server-provided director-config.
+  await expect(slider).toHaveValue('0.4', { timeout: 5000 });
 
   await slider.evaluate((el) => {
     (el as HTMLInputElement).value = '0.65';
@@ -161,8 +163,10 @@ test('Director threshold slider updates stored settings', async ({ page }) => {
 
   await expect(page.locator('#director-threshold-value')).toHaveText('0.65');
 
+  // Allow change handler to persist before reading (input -> change is async for storage)
+  await page.waitForTimeout(50);
   const saved = await page.evaluate(() => window.ApiKeyManager.getSettings().directorRiskThreshold);
-  expect(saved).toBeCloseTo(0.65, 2);
+  await expect(saved).toBeCloseTo(0.65, 2);
 });
 
 test('invalid threshold input clamps to range', async ({ page }) => {

package.json

@@ -0,0 +1,41 @@
+// Custom Jest environment that strips Node's Web Storage accessors, which throw
+// unless `--localstorage-file` is provided (Node 25+). We temporarily remove the
+// accessors before loading `jest-environment-node` so Jest won't copy them into
+// the test context, then restore them for the rest of the process.
+
+const keys = ['localStorage', 'sessionStorage'];
+const saved = [];
+
+for (const key of keys) {
+  const desc = Object.getOwnPropertyDescriptor(globalThis, key);
+  if (desc && desc.configurable) {
+    saved.push([key, desc]);
+    try {
+      delete globalThis[key];
+    } catch (err) {
+      // If delete fails, fall back to defining a harmless value.
+      try {
+        Object.defineProperty(globalThis, key, {
+          value: undefined,
+          writable: true,
+          configurable: true,
+          enumerable: desc.enumerable,
+        });
+      } catch (err2) {
+        // ignore
+      }
+    }
+  }
+}
+
+const NodeEnvironment = require('jest-environment-node').TestEnvironment || require('jest-environment-node');
+
+for (const [key, desc] of saved) {
+  try {
+    Object.defineProperty(globalThis, key, desc);
+  } catch (err) {
+    // ignore
+  }
+}
+
+module.exports = class NodeNoWebStorageEnvironment extends NodeEnvironment {};

src/runtime/director-config.js

@@ -1,6 +1,4 @@
-/** @jest-environment node */
-
-/** @jest-environment node */
+/** @jest-environment ./tests/helpers/node-no-webstorage-environment.js */
 
 // Optional integration test. Requires network + model download. Skip in CI by default.
 // Set EMBED_NODE=1 to force Node fallback (no Worker) or INTEGRATION_EMBEDDING=1 for browser path.