@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.75

package/dist/services/tool-providers/TTSToolProvider.js

@@ -1,46 +1,81 @@
 /**
  * TTS Tool Provider
  *
- * Unified provider for all TTS backends:
- * - Browser Web Speech API (no auth)
- * - AWS Polly (requires auth via server proxy)
- * - Google Cloud TTS (requires auth via server proxy)
+ * Unified provider for both TTS backends:
+ * - `browser`: the Web Speech API (no auth)
+ * - `server`: a TTS server, its service named by the config's `provider`.
+ *   `polly` and `google` run on the `pie` transport; `custom` runs on the
+ *   `custom` transport to a host's own service, which takes `lang_id`,
+ *   `speedRate` and `cache`
  *
  * Part of PIE Assessment Toolkit.
  */
+import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 import { BrowserTTSProvider } from "../../services/tts/browser-provider.js";
+const logger = createPieLogger("tts-tool-provider", isTtsDebugEnabled);
+/**
+ * Binds a server backend's provider to the config the registry initialized this
+ * tool provider with, including what `provider.runtime.authFetcher` returned.
+ * The bound config wins over the runtime config the TTS service initializes the
+ * provider with; `headers` and `providerOptions` merge key by key, keeping the
+ * host's headers and the service's telemetry reporter.
+ */
+function bindServerBackendConfig(provider, bound) {
+    return {
+        providerId: provider.providerId,
+        providerName: provider.providerName,
+        version: provider.version,
+        initialize: (config) => {
+            const runtime = config;
+            const merged = {
+                ...runtime,
+                ...bound,
+                headers: { ...runtime.headers, ...bound.headers },
+                providerOptions: {
+                    ...runtime.providerOptions,
+                    ...bound.providerOptions,
+                },
+            };
+            return provider.initialize(merged);
+        },
+        getCapabilities: () => provider.getCapabilities(),
+        destroy: () => provider.destroy(),
+    };
+}
 /**
  * TTS Tool Provider
  *
- * Wraps TTS providers (Browser, Polly, Google) with the ToolProviderApi interface
+ * Wraps the browser or a server TTS provider with the ToolProviderApi interface
  * for use in the ToolProviderRegistry.
  *
  * @example Browser TTS (no auth)
  * ```typescript
  * const provider = new TTSToolProvider();
- * await provider.initialize({ backend: 'browser' });
+ * await provider.initialize({});
  * const ttsProvider = await provider.createInstance();
  * ```
  *
- * @example Server TTS (with auth)
+ * @example Server TTS
  * ```typescript
- * const provider = new TTSToolProvider();
+ * const provider = new TTSToolProvider('server', {
+ *   loadServerProvider: async () => ServerTTSProvider,
+ * });
  * await provider.initialize({
- *   backend: 'polly',
- *   apiEndpoint: '/api/tts/synthesize',
- *   authToken: 'bearer-token', // Fetched via authFetcher
+ *   provider: 'polly',
+ *   apiEndpoint: '/api/tts',
  * });
  * const ttsProvider = await provider.createInstance();
  * ```
  */
 export class TTSToolProvider {
-    providerId = "tts-service";
     providerName = "Text-to-Speech";
     category = "tts";
     version = "1.0";
     requiresAuth;
+    backend;
     ttsProvider = null;
     config = null;
+    loadServerProvider;
     async emitTelemetry(eventName, payload) {
         try {
             await this.config?.onTelemetry?.(eventName, payload);
@@ -53,16 +88,19 @@ export class TTSToolProvider {
      * Create TTS tool provider
      *
      * @param backend TTS backend to use (default: 'browser')
+     * @param options Loader for the server adapter, required by server backends
      */
-    constructor(backend = "browser") {
+    constructor(backend = "browser", options = {}) {
+        this.backend = backend;
         this.requiresAuth = backend !== "browser";
+        this.loadServerProvider = options.loadServerProvider;
     }
     /**
      * Initialize TTS provider
      *
      * Sets up the appropriate TTS backend.
      *
-     * @param config Configuration with backend type and credentials
+     * @param config Runtime configuration and credentials
      * @throws Error if initialization fails or required config missing
      */
     async initialize(config) {
@@ -71,19 +109,17 @@ export class TTSToolProvider {
             return;
         }
         this.config = config;
-        switch (config.backend) {
+        switch (this.backend) {
             case "browser":
                 await this._initializeBrowserTTS(config);
                 break;
-            case "polly":
-            case "google":
             case "server":
                 await this._initializeServerTTS(config);
                 break;
             default:
-                throw new Error(`[TTSToolProvider] Unknown backend: ${config.backend}`);
+                throw new Error(`[TTSToolProvider] Unknown backend: ${this.backend}`);
         }
-        console.log(`[TTSToolProvider] Initialized successfully (backend: ${config.backend})`);
+        logger.debug(`initialized (backend: ${this.backend})`);
     }
     /**
      * Initialize browser TTS (Web Speech API)
@@ -94,29 +130,33 @@ export class TTSToolProvider {
             throw new Error("[TTSToolProvider] Browser TTS not supported (Web Speech API not available)");
         }
         this.ttsProvider = new BrowserTTSProvider();
-        console.log("[TTSToolProvider] Browser TTS initialized (Web Speech API)");
+        logger.debug("browser TTS initialized (Web Speech API)");
     }
     /**
-     * Initialize server-based TTS (Polly, Google)
+     * Initialize server-based TTS
      */
     async _initializeServerTTS(config) {
         if (!config.apiEndpoint) {
             throw new Error("[TTSToolProvider] apiEndpoint required for server-based TTS backends");
         }
-        // Server backends are optional; load implementation only when requested.
+        const loadServerProvider = this.loadServerProvider;
+        if (!loadServerProvider) {
+            throw new Error("[TTSToolProvider] server-based TTS backends need the loadServerProvider option");
+        }
+        const serverProvider = config.provider || this.backend;
         const moduleLoadStartedAt = Date.now();
         await this.emitTelemetry("pie-tool-library-load-start", {
             toolId: "textToSpeech",
             operation: "server-provider-module-import",
-            backend: config.serverProvider || config.backend,
+            backend: serverProvider,
         });
-        const serverModule = await (async () => {
+        const ServerProvider = await (async () => {
             try {
-                const loaded = (await import("@pie-players/tts-client-server"));
+                const loaded = await loadServerProvider();
                 await this.emitTelemetry("pie-tool-library-load-success", {
                     toolId: "textToSpeech",
                     operation: "server-provider-module-import",
-                    backend: config.serverProvider || config.backend,
+                    backend: serverProvider,
                     duration: Date.now() - moduleLoadStartedAt,
                 });
                 return loaded;
@@ -125,7 +165,7 @@ export class TTSToolProvider {
                 await this.emitTelemetry("pie-tool-library-load-error", {
                     toolId: "textToSpeech",
                     operation: "server-provider-module-import",
-                    backend: config.serverProvider || config.backend,
+                    backend: serverProvider,
                     duration: Date.now() - moduleLoadStartedAt,
                     errorType: "ToolLibraryLoadError",
                     message: error instanceof Error ? error.message : String(error),
@@ -133,8 +173,9 @@ export class TTSToolProvider {
                 throw error;
             }
         })();
-        this.ttsProvider = new serverModule.ServerTTSProvider();
-        console.log(`[TTSToolProvider] Server TTS initialized (provider: ${config.serverProvider || config.backend})`);
+        const { onTelemetry: _onTelemetry, ...backendConfig } = config;
+        this.ttsProvider = bindServerBackendConfig(new ServerProvider(), backendConfig);
+        logger.debug(`server TTS initialized (provider: ${serverProvider})`);
     }
     /**
      * Create a TTS provider instance
@@ -152,23 +193,23 @@ export class TTSToolProvider {
         return this.ttsProvider;
     }
     /**
-     * Get provider capabilities
-     *
-     * @returns TTS capabilities based on backend
+     * The backend's capabilities. Its features are the speech provider's own,
+     * and all false before {@link initialize} creates it.
      */
     getCapabilities() {
-        const isBrowser = this.config?.backend === "browser";
+        const isBrowser = this.backend === "browser";
+        const speech = this.ttsProvider?.getCapabilities();
         return {
             supportsOffline: isBrowser,
             requiresAuth: !isBrowser,
             maxInstances: 1, // Single TTS instance (playback is sequential)
             features: {
-                wordBoundary: true, // All backends support word highlighting
-                pause: true,
-                resume: true,
-                rateControl: true,
-                pitchControl: isBrowser, // Only browser supports pitch
-                voiceSelection: true,
+                wordBoundary: speech?.supportsWordBoundary ?? false,
+                pause: speech?.supportsPause ?? false,
+                resume: speech?.supportsResume ?? false,
+                rateControl: speech?.supportsRateControl ?? false,
+                pitchControl: speech?.supportsPitchControl ?? false,
+                voiceSelection: speech?.supportsVoiceSelection ?? false,
             },
         };
     }
@@ -191,6 +232,6 @@ export class TTSToolProvider {
             this.ttsProvider = null;
         }
         this.config = null;
-        console.log("[TTSToolProvider] Destroyed");
+        logger.debug("destroyed");
     }
 }

package/dist/services/tool-providers/ToolProviderApi.d.ts

@@ -11,14 +11,20 @@ export interface ToolProviderCapabilities {
     maxInstances?: number | null;
     features: Record<string, boolean>;
 }
-export interface ToolProviderApi<TConfig = any, TInstance = any> {
-    readonly providerId: string;
+/**
+ * A tool's provider. It registers under its tool's id, which is how the toolkit
+ * and the tool find it; it carries no id of its own.
+ *
+ * Config takes no type parameter (ADR 0002): an implementation narrows it in its
+ * own method signatures.
+ */
+export interface ToolProviderApi<TInstance = any> {
     readonly providerName: string;
     readonly category: ToolCategory;
     readonly version: string;
     readonly requiresAuth: boolean;
-    initialize(config: TConfig): Promise<void>;
-    createInstance(config?: Partial<TConfig>): Promise<TInstance>;
+    initialize(config: unknown): Promise<void>;
+    createInstance(config?: unknown): Promise<TInstance>;
     getCapabilities(): ToolProviderCapabilities;
     isReady(): boolean;
     destroy(): void;

package/dist/services/tool-providers/ToolProviderRegistry.d.ts

@@ -8,13 +8,13 @@
  */
 import type { ToolProviderApi, ToolCategory } from "./ToolProviderApi.js";
 /**
- * Configuration for registering a tool provider
+ * What `register` takes: the provider, its config, and how it starts.
  */
-export interface ToolProviderConfig<TConfig = any> {
+export interface ToolProviderRegistration<TConfig = any> {
     /**
      * Provider instance to register
      */
-    provider: ToolProviderApi<TConfig>;
+    provider: ToolProviderApi;
     /**
      * Configuration for this provider
      * (may include auth credentials, endpoints, etc.)
@@ -54,25 +54,27 @@ export interface ToolProviderConfig<TConfig = any> {
  * - Registration
  * - Lazy initialization
  * - Auth credential fetching
- * - Provider lookup by ID or category
+ * - Provider lookup by tool id or category
+ *
+ * The toolkit coordinator registers each provider under its tool's id.
  *
  * @example
  * ```typescript
  * const registry = new ToolProviderRegistry();
  *
  * // Register a provider with auth fetcher
- * registry.register('desmos-calculator', {
- *   provider: new DesmosToolProvider(),
+ * registry.register('calculator', {
+ *   provider: new ExampleToolProvider(),
  *   config: {},
  *   lazy: true,
  *   authFetcher: async () => {
- *     const response = await fetch('/api/desmos/token');
+ *     const response = await fetch('/api/example/token');
  *     return response.json();
  *   },
  * });
  *
  * // Get provider (auto-initializes if lazy)
- * const desmosProvider = await registry.getProvider('desmos-calculator');
+ * const provider = await registry.getProvider('calculator');
  * ```
  */
 export declare class ToolProviderRegistry {
@@ -85,23 +87,28 @@ export declare class ToolProviderRegistry {
      * Register a tool provider
      *
      * Adds a provider to the registry. If lazy is false, initializes immediately.
+     * A registration under an id already registered replaces it: the replaced
+     * provider is destroyed once a start in progress settles, and a caller
+     * waiting on that start gets the replacement.
      *
-     * @param providerId Unique provider identifier
+     * @param toolId Id of the tool the provider serves
      * @param config Provider configuration
-     * @throws Error if provider with same ID already registered
      */
-    register(providerId: string, config: ToolProviderConfig): void;
+    register(toolId: string, config: ToolProviderRegistration): void;
     /**
      * Initialize a provider
      *
      * Fetches auth if needed and initializes the provider.
      * Safe to call multiple times - subsequent calls wait for first initialization.
      *
-     * @param providerId Provider to initialize
+     * @param toolId Tool whose provider to initialize
      * @returns Promise that resolves when initialization complete
      * @throws Error if provider not registered or initialization fails
      */
-    initialize(providerId: string): Promise<void>;
+    initialize(toolId: string): Promise<void>;
+    /** Whether a registration replaced `provider` under `toolId`. */
+    private isReplaced;
+    private destroyProvider;
     /**
      * Internal initialization logic
      */
@@ -112,54 +119,51 @@ export declare class ToolProviderRegistry {
      * Retrieves a registered provider. If autoInitialize is true and provider
      * is not initialized, initializes it first.
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @param autoInitialize Auto-initialize if not ready (default: true)
      * @returns Provider instance
      * @throws Error if provider not registered
      */
-    getProvider<T extends ToolProviderApi = ToolProviderApi>(providerId: string, autoInitialize?: boolean): Promise<T>;
+    getProvider<T extends ToolProviderApi = ToolProviderApi>(toolId: string, autoInitialize?: boolean): Promise<T>;
     /**
-     * Get all providers in a category
+     * The ids of the tools whose provider is in `category`.
      *
      * @param category Tool category to filter by
-     * @returns Array of provider IDs in the category
      */
     getProvidersByCategory(category: ToolCategory): string[];
     /**
-     * Get all registered provider IDs
-     *
-     * @returns Array of all provider IDs
+     * The ids of the tools with a registered provider.
      */
     getProviderIds(): string[];
     /**
      * Check if provider is registered
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @returns true if provider is registered
      */
-    has(providerId: string): boolean;
+    has(toolId: string): boolean;
     /**
      * Check if provider is initialized
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @returns true if provider is initialized
      */
-    isInitialized(providerId: string): boolean;
+    isInitialized(toolId: string): boolean;
     /**
      * Check if provider is currently initializing
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @returns true if initialization in progress
      */
-    isInitializing(providerId: string): boolean;
+    isInitializing(toolId: string): boolean;
     /**
      * Unregister and destroy a provider
      *
      * Removes the provider from the registry and calls its destroy method.
      *
-     * @param providerId Provider to unregister
+     * @param toolId Tool whose provider to unregister
      */
-    unregister(providerId: string): Promise<void>;
+    unregister(toolId: string): Promise<void>;
     /**
      * Clean up all providers
      *