@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

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

@@ -1,14 +1,16 @@
 /**
  * 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)
- *
- * Part of PIE Assessment Toolkit.
+ * 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`
  */
+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.
@@ -19,8 +21,6 @@ import { BrowserTTSProvider } from "../../services/tts/browser-provider.js";
 function bindServerBackendConfig(provider, bound) {
     return {
         providerId: provider.providerId,
-        providerName: provider.providerName,
-        version: provider.version,
         initialize: (config) => {
             const runtime = config;
             const merged = {
@@ -34,7 +34,6 @@ function bindServerBackendConfig(provider, bound) {
             };
             return provider.initialize(merged);
         },
-        supportsFeature: (feature) => provider.supportsFeature(feature),
         getCapabilities: () => provider.getCapabilities(),
         destroy: () => provider.destroy(),
     };
@@ -42,34 +41,34 @@ function bindServerBackendConfig(provider, bound) {
 /**
  * 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
  * ```typescript
- * const provider = new TTSToolProvider('polly', {
+ * const provider = new TTSToolProvider('server', {
  *   loadServerProvider: async () => ServerTTSProvider,
  * });
  * await provider.initialize({
- *   backend: 'polly',
+ *   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;
@@ -81,23 +80,15 @@ export class TTSToolProvider {
             console.warn("[TTSToolProvider] telemetry callback failed:", error);
         }
     }
-    /**
-     * Create TTS tool provider
-     *
-     * @param backend TTS backend to use (default: 'browser')
-     * @param options Loader for the server adapter, required by server backends
-     */
+    /** A server backend needs `options.loadServerProvider`. */
     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
-     * @throws Error if initialization fails or required config missing
+     * Set up the backend's TTS provider. Throws when the backend is unavailable
+     * or its required config is missing. Once initialized, a call only warns.
      */
     async initialize(config) {
         if (this.ttsProvider) {
@@ -105,34 +96,25 @@ export class TTSToolProvider {
             return;
         }
         this.config = config;
-        switch (config.backend) {
+        switch (this.backend) {
             case "browser":
-                await this._initializeBrowserTTS(config);
+                await this._initializeBrowserTTS();
                 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)
-     */
-    async _initializeBrowserTTS(config) {
-        // Check if Web Speech API is available
+    async _initializeBrowserTTS() {
         if (typeof window === "undefined" || !("speechSynthesis" in window)) {
             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)
-     */
     async _initializeServerTTS(config) {
         if (!config.apiEndpoint) {
             throw new Error("[TTSToolProvider] apiEndpoint required for server-based TTS backends");
@@ -141,11 +123,12 @@ export class TTSToolProvider {
         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 ServerProvider = await (async () => {
             try {
@@ -153,7 +136,7 @@ export class TTSToolProvider {
                 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;
@@ -162,7 +145,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),
@@ -170,18 +153,13 @@ export class TTSToolProvider {
                 throw error;
             }
         })();
-        const { backend, serverProvider, onTelemetry, ...backendConfig } = config;
+        const { onTelemetry: _onTelemetry, ...backendConfig } = config;
         this.ttsProvider = bindServerBackendConfig(new ServerProvider(), backendConfig);
-        console.log(`[TTSToolProvider] Server TTS initialized (provider: ${config.serverProvider || config.backend})`);
+        logger.debug(`server TTS initialized (provider: ${serverProvider})`);
     }
     /**
-     * Create a TTS provider instance
-     *
-     * Returns the initialized TTS provider.
-     *
-     * @param config Optional instance-specific configuration (currently unused)
-     * @returns TTS provider
-     * @throws Error if provider not initialized
+     * The initialized TTS provider; every call returns the same one and ignores
+     * `config`. Throws before `initialize`.
      */
     async createInstance(config) {
         if (!this.ttsProvider) {
@@ -189,46 +167,15 @@ export class TTSToolProvider {
         }
         return this.ttsProvider;
     }
-    /**
-     * Get provider capabilities
-     *
-     * @returns TTS capabilities based on backend
-     */
-    getCapabilities() {
-        const isBrowser = this.config?.backend === "browser";
-        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,
-            },
-        };
-    }
-    /**
-     * Check if provider is ready
-     *
-     * @returns true if provider is initialized
-     */
     isReady() {
         return this.ttsProvider !== null;
     }
-    /**
-     * Clean up provider resources
-     *
-     * Destroys the TTS provider and releases resources.
-     */
     destroy() {
         if (this.ttsProvider) {
             this.ttsProvider.destroy();
             this.ttsProvider = null;
         }
         this.config = null;
-        console.log("[TTSToolProvider] Destroyed");
+        logger.debug("destroyed");
     }
 }

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

@@ -5,21 +5,20 @@
  * configuration, authentication, or external services.
  */
 export type ToolCategory = "calculator" | "tts" | "translation" | "annotation" | "accessibility" | "other";
-export interface ToolProviderCapabilities {
-    supportsOffline: boolean;
-    requiresAuth: boolean;
-    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>;
-    getCapabilities(): ToolProviderCapabilities;
+    initialize(config: unknown): Promise<void>;
+    createInstance(config?: unknown): Promise<TInstance>;
     isReady(): boolean;
     destroy(): void;
 }

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

@@ -3,18 +3,16 @@
  *
  * Centralized registry for managing tool providers.
  * Handles initialization, authentication, and lazy loading.
- *
- * Part of PIE Assessment Toolkit.
  */
 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.)
@@ -36,7 +34,7 @@ export interface ToolProviderConfig<TConfig = any> {
      * @example
      * ```typescript
      * authFetcher: async () => {
-     *   const response = await fetch('/api/desmos/token');
+     *   const response = await fetch('/api/tools/desmos/auth');
      *   return response.json(); // { apiKey: '...' }
      * }
      * ```
@@ -54,14 +52,16 @@ 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('example-provider', {
+ * registry.register('calculator', {
  *   provider: new ExampleToolProvider(),
  *   config: {},
  *   lazy: true,
@@ -72,7 +72,7 @@ export interface ToolProviderConfig<TConfig = any> {
  * });
  *
  * // Get provider (auto-initializes if lazy)
- * const provider = await registry.getProvider('example-provider');
+ * const provider = await registry.getProvider('calculator');
  * ```
  */
 export declare class ToolProviderRegistry {
@@ -85,23 +85,22 @@ export declare class ToolProviderRegistry {
      * Register a tool provider
      *
      * Adds a provider to the registry. If lazy is false, initializes immediately.
-     *
-     * @param providerId Unique provider identifier
-     * @param config Provider configuration
-     * @throws Error if provider with same ID already registered
+     * 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.
      */
-    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
-     * @returns Promise that resolves when initialization complete
-     * @throws Error if provider not registered or initialization fails
+     * Throws when the provider is not registered or its 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
      */
@@ -110,56 +109,26 @@ export declare class ToolProviderRegistry {
      * Get a provider instance
      *
      * Retrieves a registered provider. If autoInitialize is true and provider
-     * is not initialized, initializes it first.
-     *
-     * @param providerId Provider identifier
-     * @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>;
-    /**
-     * Get all providers in a category
-     *
-     * @param category Tool category to filter by
-     * @returns Array of provider IDs in the category
+     * is not initialized, initializes it first. Throws when the provider is not
+     * registered.
      */
+    getProvider<T extends ToolProviderApi = ToolProviderApi>(toolId: string, autoInitialize?: boolean): Promise<T>;
+    /** The ids of the tools whose provider is in `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
-     * @returns true if provider is registered
-     */
-    has(providerId: string): boolean;
-    /**
-     * Check if provider is initialized
-     *
-     * @param providerId Provider identifier
-     * @returns true if provider is initialized
-     */
-    isInitialized(providerId: string): boolean;
-    /**
-     * Check if provider is currently initializing
-     *
-     * @param providerId Provider identifier
-     * @returns true if initialization in progress
-     */
-    isInitializing(providerId: string): boolean;
+    has(toolId: string): boolean;
+    isInitialized(toolId: 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
+     * Removes the provider from the registry and calls its destroy method,
+     * after any start in progress settles.
      */
-    unregister(providerId: string): Promise<void>;
+    unregister(toolId: string): Promise<void>;
     /**
      * Clean up all providers
      *