Built-in AI Task APIs Polyfills

This package provides browser polyfills for the Built-in AI Task APIs, specifically:

• Summarizer API
• Writer API
• Rewriter API
• Language Detector API
• Translator API
• SemanticEmbedder API

The Summarizer, Writer, Rewriter, Language Detector, and Translator polyfills are backed by the prompt-api-polyfill, which is automatically loaded if window.LanguageModel is not detected. This means they support the same dynamic backends.

The SemanticEmbedder polyfill is backed by EmbeddingGemma 300M — the same model Chrome's built-in SemanticEmbedder API uses on-device — running in-browser via @huggingface/transformers (a peer dependency you must install separately).

When loaded in the browser, they define globals:

window.Summarizer;
window.Writer;
window.Rewriter;
window.LanguageDetector;
window.Translator;
window.SemanticEmbedder;

so you can use these Task APIs even in environments where they are not yet natively available.

Installation

Install from npm:

npm install built-in-ai-task-apis-polyfills

If you use the SemanticEmbedder polyfill, also install the peer dependency:

npm install @huggingface/transformers

Quick start

Recommended Loading Strategy

To ensure your app uses the native implementation when available, use a defensive dynamic import strategy:

<script type="module">
  import config from './.env.json' with { type: 'json' };

  // Example: Use Gemini backend
  window.GEMINI_CONFIG = config;

  // Load polyfills only if not natively supported
  const polyfills = [];
  if (!('Summarizer' in window)) {
    polyfills.push(import('built-in-ai-task-apis-polyfills/summarizer'));
  }
  if (!('Writer' in window)) {
    polyfills.push(import('built-in-ai-task-apis-polyfills/writer'));
  }
  if (!('Rewriter' in window)) {
    polyfills.push(import('built-in-ai-task-apis-polyfills/rewriter'));
  }
  if (!('LanguageDetector' in window)) {
    polyfills.push(import('built-in-ai-task-apis-polyfills/language-detector'));
  }
  if (!('Translator' in window)) {
    polyfills.push(import('built-in-ai-task-apis-polyfills/translator'));
  }
  if (!('SemanticEmbedder' in window)) {
    polyfills.push(import('built-in-ai-task-apis-polyfills/semantic-embedder'));
  }
  await Promise.all(polyfills);

  // Now you can use the APIs
  if ((await Summarizer.availability()) === 'available') {
    const summarizer = await Summarizer.create();
    const summary = await summarizer.summarize('Long text to summarize...');
    console.log(summary);
  }
</script>

API Usage Examples

Summarizer API

const summarizer = await Summarizer.create({
  type: 'key-points',
  format: 'markdown',
  length: 'short',
});

const result = await summarizer.summarize(text);
// or streaming
const stream = summarizer.summarizeStreaming(text);
for await (const chunk of stream) {
  console.log(chunk);
}

Writer API

const writer = await Writer.create({
  tone: 'formal',
  format: 'plain-text',
});

const result = await writer.write(
  'Draft of an email to my boss telling her I will be late.'
);

Rewriter API

const rewriter = await Rewriter.create({
  tone: 'more-casual',
});

const result = await rewriter.rewrite(
  'I am writing to inform you that I will be late.'
);

Language Detector API

const detector = await LanguageDetector.create();
const results = await detector.detect("C'est la vie");

for (const { detectedLanguage, confidence } of results) {
  console.log(`${detectedLanguage} (${(confidence * 100).toFixed(1)}%)`);
}

Translator API

const translator = await Translator.create({
  sourceLanguage: 'en',
  targetLanguage: 'fr',
});

const result = await translator.translate('Hello world');

SemanticEmbedder API

Backed by EmbeddingGemma 300M via @huggingface/transformers. The model (~420 MB) is downloaded and cached in the browser on first use.

const embedder = await SemanticEmbedder.create({
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Download progress: ${Math.round(e.loaded * 100)}%`);
    });
  },
});

// Embed a single text
const { embeddings } = await embedder.embed('Hello world');
console.log(embeddings[0].values); // Float32Array of 768 values

// Semantic search: embed query and corpus with appropriate task prefixes
const [queryResult, docsResult] = await Promise.all([
  embedder.embed('What is machine learning?', { taskType: 'query' }),
  embedder.embed(['AI transforms software.', 'Paris is in France.'], {
    taskType: 'document',
  }),
]);

const queryVec = queryResult.embeddings[0].values;
const scores = docsResult.embeddings.map((e) =>
  SemanticEmbedder.cosineSimilarity(queryVec, e.values)
);

Configuration

Configuring .env.json

This repo ships with a dot_env.json template. Copy it to .env.json and fill in your credentials:

cp dot_env.json .env.json

The polyfill will look for these configurations on the window object. Adjust your loading logic to pass the JSON content to the appropriate global (e.g., window.GEMINI_CONFIG).

API surface

Once the polyfills are loaded, you can use them as described in the official documentation:

• Summarizer API
• Writer API
• Rewriter API
• Language Detector API
• Translator API
• SemanticEmbedder API

For complete examples, see:

• demo-summarizer.html
• demo-writer.html
• demo-rewriter.html
• demo-language-detector.html
• demo-translator.html
• demo-semantic-embedder.html

Running the demos locally

1. Install dependencies:

   npm install

2. Copy and fill in your config:

   cp dot_env.json .env.json

3. Start the server:

   npm start

Testing

The project includes a comprehensive test suite based on Web Platform Tests (WPT).

npm run test:wpt

License

Apache 2.0