prompt-api-polyfill 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,12 @@
-# Prompt API Polyfill (Firebase AI Logic backend)
+# Prompt API Polyfill
 
 This package provides a browser polyfill for the
-[Prompt API `LanguageModel`](https://github.com/webmachinelearning/prompt-api)
-backed by **Firebase AI Logic**.
+[Prompt API `LanguageModel`](https://github.com/webmachinelearning/prompt-api),
+supporting dynamic backends:
+
+- **Firebase AI Logic**
+- **Google Gemini API**
+- **OpenAI API**
 
 When loaded in the browser, it defines a global:
 
@@ -13,8 +17,28 @@ window.LanguageModel;
 so you can use the Prompt API shape even in environments where it is not yet
 natively available.
 
-- Back end: Firebase AI Logic
-- Default model: `gemini-2.5-flash-lite` (configurable via `modelName`)
+## Supported Backends
+
+### Firebase AI Logic
+
+- **Uses**: `firebase/ai` SDK.
+- **Select by setting**: `window.FIREBASE_CONFIG`.
+- **Model**: Uses default if not specified (see
+  [`backends/defaults.js`](backends/defaults.js)).
+
+### Google Gemini API
+
+- **Uses**: `@google/generative-ai` SDK.
+- **Select by setting**: `window.GEMINI_CONFIG`.
+- **Model**: Uses default if not specified (see
+  [`backends/defaults.js`](backends/defaults.js)).
+
+### OpenAI API
+
+- **Uses**: `openai` SDK.
+- **Select by setting**: `window.OPENAI_CONFIG`.
+- **Model**: Uses default if not specified (see
+  [`backends/defaults.js`](backends/defaults.js)).
 
 ---
 
@@ -28,37 +52,78 @@ npm install prompt-api-polyfill
 
 ## Quick start
 
-1. **Create a Firebase project with Generative AI enabled** (see Configuration
-   below).
-2. **Provide your Firebase config** on `window.FIREBASE_CONFIG`.
-3. **Import the polyfill** so it can attach `window.LanguageModel`.
+### Backed by Firebase
 
-### Example (using a JSON config file)
-
-Create a `.env.json` file (see
-[Configuring `dot_env.json` / `.env.json`](#configuring-dot_envjson--envjson))
-and then use it from a browser entry point:
+1. **Create a Firebase project with Generative AI enabled**.
+2. **Provide your Firebase config** on `window.FIREBASE_CONFIG`.
+3. **Import the polyfill**.
 
 ```html
 <script type="module">
   import firebaseConfig from './.env.json' with { type: 'json' };
 
-  // Make the config available to the polyfill
+  // Set FIREBASE_CONFIG to select the Firebase backend
   window.FIREBASE_CONFIG = firebaseConfig;
 
-  // Only load the polyfill if LanguageModel is not available natively
   if (!('LanguageModel' in window)) {
     await import('prompt-api-polyfill');
   }
 
   const session = await LanguageModel.create();
-  const text = await session.prompt('Say hello from the polyfill!');
-  console.log(text);
 </script>
 ```
 
-> **Note**: The polyfill attaches `LanguageModel` to `window` as a side effect.
-> There are no named exports.
+### Backed by Gemini API
+
+1. **Get a Gemini API Key** from
+   [Google AI Studio](https://aistudio.google.com/).
+2. **Provide your API Key** on `window.GEMINI_CONFIG`.
+3. **Import the polyfill**.
+
+```html
+<script type="module">
+  // NOTE: Do not expose real keys in production source code!
+  // Set GEMINI_CONFIG to select the Gemini backend
+  window.GEMINI_CONFIG = { apiKey: 'YOUR_GEMINI_API_KEY' };
+
+  if (!('LanguageModel' in window)) {
+    await import('prompt-api-polyfill');
+  }
+
+  const session = await LanguageModel.create();
+</script>
+```
+
+### Backed by OpenAI API
+
+1. **Get an OpenAI API Key** from the
+   [OpenAI Platform](https://platform.openai.com/).
+2. **Provide your API Key** on `window.OPENAI_CONFIG`.
+3. **Import the polyfill**.
+
+```html
+<script type="module">
+  // NOTE: Do not expose real keys in production source code!
+  // Set OPENAI_CONFIG to select the OpenAI backend
+  window.OPENAI_CONFIG = { apiKey: 'YOUR_OPENAI_API_KEY' };
+
+  if (!('LanguageModel' in window)) {
+    await import('prompt-api-polyfill');
+  }
+
+  const session = await LanguageModel.create();
+</script>
+```
+
+---
+
+## Configuration
+
+### Example (using a JSON config file)
+
+Create a `.env.json` file (see
+[Configuring `dot_env.json` / `.env.json`](#configuring-dot_envjson--envjson))
+and then use it from a browser entry point.
 
 ### Example based on `index.html` in this repo
 
@@ -76,8 +141,8 @@ A simplified version of how it is wired up:
 
 ```html
 <script type="module">
-  import firebaseConfig from './.env.json' with { type: 'json' };
-  window.FIREBASE_CONFIG = firebaseConfig;
+  // Set GEMINI_CONFIG to select the Gemini backend
+  window.GEMINI_CONFIG = { apiKey: 'YOUR_GEMINI_API_KEY' };
 
   // Load the polyfill only when necessary
   if (!('LanguageModel' in window)) {
@@ -110,17 +175,20 @@ This repo ships with a template file:
 ```jsonc
 // dot_env.json
 {
-  "apiKey": "",
+  // For Firebase:
   "projectId": "",
   "appId": "",
   "modelName": "",
+
+  // For Firebase OR Gemini OR OpenAI:
+  "apiKey": "",
 }
 ```
 
 You should treat `dot_env.json` as a **template** and create a real `.env.json`
 that is **not committed** with your secrets.
 
-### 1. Create `.env.json`
+### Create `.env.json`
 
 Copy the template:
 
@@ -128,63 +196,56 @@ Copy the template:
 cp dot_env.json .env.json
 ```
 
-Then open `.env.json` and fill in the values from your Firebase project:
+Then open `.env.json` and fill in the values.
+
+**For Firebase:**
 
 ```json
 {
   "apiKey": "YOUR_FIREBASE_WEB_API_KEY",
   "projectId": "your-gcp-project-id",
   "appId": "YOUR_FIREBASE_APP_ID",
-  "modelName": "gemini-2.5-flash-lite"
+  "modelName": "choose-model-for-firebase"
 }
 ```
 
-### 2. Field-by-field explanation
-
-- `apiKey` Your **Firebase Web API key**. You can find this in the Firebase
-  Console under: _Project settings → General → Your apps → Web app_.
+**For Gemini:**
 
-- `projectId` The **GCP / Firebase project ID**, e.g. `my-ai-project`.
-
-- `appId` The **Firebase Web app ID**, e.g. `1:1234567890:web:abcdef123456`.
-
-- `modelName` (optional) The Gemini model ID to use. If omitted, the polyfill
-  defaults to:
+```json
+{
+  "apiKey": "YOUR_GEMINI_CONFIG",
+  "modelName": "choose-model-for-gemini"
+}
+```
 
-  ```json
-  "modelName": "gemini-2.5-flash-lite"
-  ```
+**For OpenAI:**
 
-  You can substitute another supported Gemini model here if desired.
+```json
+{
+  "apiKey": "YOUR_OPENAI_API_KEY",
+  "modelName": "choose-model-for-openai"
+}
+```
 
-These fields are passed directly to:
+### Field-by-field explanation
 
-- `initializeApp(firebaseConfig)` from Firebase
-- `getAI(app, { backend: new GoogleAIBackend() })` from the Firebase AI SDK
+- `apiKey`:
+  - **Firebase**: Your Firebase Web API key.
+  - **Gemini**: Your Gemini API Key.
+  - **OpenAI**: Your OpenAI API Key.
+- `projectId` / `appId`: **Firebase only**.
 
-and `modelName` is used to select which Gemini model to call.
+- `modelName` (optional): The model ID to use. If not provided, the polyfill
+  uses the defaults defined in [`backends/defaults.js`](backends/defaults.js).
 
 > **Important:** Do **not** commit a real `.env.json` with production
 > credentials to source control. Use `dot_env.json` as the committed template
 > and keep `.env.json` local.
 
-### 3. Wiring the config into the polyfill
+### Wiring the config into the polyfill
 
-Once `.env.json` is filled out, you can import it and expose it to the polyfill
-exactly like in `index.html`:
-
-```js
-import firebaseConfig from './.env.json' with { type: 'json' };
-
-window.FIREBASE_CONFIG = firebaseConfig;
-
-if (!('LanguageModel' in window)) {
-  await import('prompt-api-polyfill');
-}
-```
-
-From this point on, `LanguageModel.create()` will use your Firebase
-configuration.
+Once `.env.json` is filled out, you can import it and expose it to the polyfill.
+See the [Quick start](#quick-start) examples above.
 
 ---
 
@@ -200,8 +261,7 @@ For a complete, end-to-end example, see the `index.html` file in this directory.
 
 ## Running the demo locally
 
-1. Install dependencies and this package (if using the npm-installed version in
-   another project):
+1. Install dependencies:
 
    ```bash
    npm install
@@ -211,17 +271,34 @@ For a complete, end-to-end example, see the `index.html` file in this directory.
 
    ```bash
    cp dot_env.json .env.json
-   # then edit .env.json with your Firebase and model settings
    ```
 
 3. Serve `index.html`:
-
    ```bash
    npm start
    ```
 
-You should see network requests to the Vertex AI / Firebase AI backend and
-streaming responses logged in the console.
+You should see network requests to the backends logs.
+
+---
+
+## Testing
+
+The project includes a comprehensive test suite that runs in a headless browser.
+
+### Running Browser Tests
+
+Uses `playwright` to run tests in a real Chromium instance. This is the
+recommended way to verify environmental fidelity and multimodal support.
+
+```bash
+npm run test:browser
+```
+
+To see the browser and DevTools while testing, you can modify
+`vitest.browser.config.js` to set `headless: false`.
+
+---
 
 ## License
 

package/backends/base.js

@@ -0,0 +1,59 @@
+/**
+ * Abstract class representing a backend for the LanguageModel polyfill.
+ */
+export default class PolyfillBackend {
+  #model;
+
+  /**
+   * @param {string} modelName - The name of the model.
+   */
+  constructor(modelName) {
+    this.modelName = modelName;
+  }
+
+  /**
+   * Checks if the backend is available given the options.
+   * @param {Object} options - LanguageModel options.
+   * @returns {string} 'available', 'unavailable', 'downloadable', or 'downloading'.
+   */
+  static availability(options) {
+    return 'available';
+  }
+
+  /**
+   * Creates a model session and stores it.
+   * @param {Object} options - LanguageModel options.
+   * @param {Object} inCloudParams - Parameters for the cloud model.
+   * @returns {any} The created session object.
+   */
+  createSession(options, inCloudParams) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Generates content (non-streaming).
+   * @param {Array} content - The history + new message content.
+   * @returns {Promise<{text: string, usage: number}>}
+   */
+  async generateContent(content) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Generates content stream.
+   * @param {Array} content - The history + new content.
+   * @returns {Promise<AsyncIterable>} Stream of chunks.
+   */
+  async generateContentStream(content) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Counts tokens.
+   * @param {Array} content - The content to count.
+   * @returns {Promise<number>} Total tokens.
+   */
+  async countTokens(content) {
+    throw new Error('Not implemented');
+  }
+}

package/backends/defaults.js

@@ -0,0 +1,9 @@
+/**
+ * Default model versions for each backend.
+ */
+export const DEFAULT_MODELS = {
+  firebase: 'gemini-2.5-flash-lite',
+  gemini: 'gemini-2.0-flash-lite-preview-02-05',
+  openai: 'gpt-4o',
+  transformers: 'onnx-community/Qwen3-4B-ONNX',
+};

package/backends/firebase.js

@@ -0,0 +1,45 @@
+import { initializeApp } from 'https://esm.run/firebase/app';
+import {
+  getAI,
+  getGenerativeModel,
+  GoogleAIBackend,
+  InferenceMode,
+} from 'https://esm.run/firebase/ai';
+import PolyfillBackend from './base.js';
+import { DEFAULT_MODELS } from './defaults.js';
+
+/**
+ * Firebase AI Logic Backend
+ */
+export default class FirebaseBackend extends PolyfillBackend {
+  #model;
+
+  constructor(config) {
+    super(config.modelName || DEFAULT_MODELS.firebase);
+    this.ai = getAI(initializeApp(config), { backend: new GoogleAIBackend() });
+  }
+
+  createSession(_options, inCloudParams) {
+    this.#model = getGenerativeModel(this.ai, {
+      mode: InferenceMode.ONLY_IN_CLOUD,
+      inCloudParams,
+    });
+    return this.#model;
+  }
+
+  async generateContent(contents) {
+    const result = await this.#model.generateContent({ contents });
+    const usage = result.response.usageMetadata?.promptTokenCount || 0;
+    return { text: result.response.text(), usage };
+  }
+
+  async generateContentStream(contents) {
+    const result = await this.#model.generateContentStream({ contents });
+    return result.stream;
+  }
+
+  async countTokens(contents) {
+    const { totalTokens } = await this.#model.countTokens({ contents });
+    return totalTokens;
+  }
+}

package/backends/gemini.js

@@ -0,0 +1,48 @@
+import { GoogleGenerativeAI } from 'https://esm.run/@google/generative-ai';
+import PolyfillBackend from './base.js';
+import { DEFAULT_MODELS } from './defaults.js';
+
+/**
+ * Google Gemini API Backend
+ */
+export default class GeminiBackend extends PolyfillBackend {
+  #model;
+
+  constructor(config) {
+    super(config.modelName || DEFAULT_MODELS.gemini);
+    this.genAI = new GoogleGenerativeAI(config.apiKey);
+  }
+
+  createSession(options, inCloudParams) {
+    const modelParams = {
+      model: options.modelName || this.modelName,
+      generationConfig: inCloudParams.generationConfig,
+      systemInstruction: inCloudParams.systemInstruction,
+    };
+    // Clean undefined systemInstruction
+    if (!modelParams.systemInstruction) {
+      delete modelParams.systemInstruction;
+    }
+
+    this.#model = this.genAI.getGenerativeModel(modelParams);
+    return this.#model;
+  }
+
+  async generateContent(contents) {
+    // Gemini SDK expects { role, parts: [...] } which matches our internal structure
+    const result = await this.#model.generateContent({ contents });
+    const response = await result.response;
+    const usage = response.usageMetadata?.promptTokenCount || 0;
+    return { text: response.text(), usage };
+  }
+
+  async generateContentStream(contents) {
+    const result = await this.#model.generateContentStream({ contents });
+    return result.stream;
+  }
+
+  async countTokens(contents) {
+    const { totalTokens } = await this.#model.countTokens({ contents });
+    return totalTokens;
+  }
+}