@browserless/ai 13.9.3

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2019 Microlink <hello@microlink.io> (microlink.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+<div align="center">
+  <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner.png#gh-light-mode-only" alt="browserless">
+  <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner-light.png#gh-dark-mode-only" alt="browserless">
+  <br><br>
+  <a href="https://microlink.io"><img src="https://img.shields.io/badge/powered_by-microlink.io-blue?style=flat-square&color=%23EA407B" alt="Powered by microlink.io"></a>
+  <img src="https://img.shields.io/github/tag/microlinkhq/browserless.svg?style=flat-square" alt="Last version">
+  <a href="https://coveralls.io/github/microlinkhq/browserless"><img src="https://img.shields.io/coveralls/microlinkhq/browserless.svg?style=flat-square" alt="Coverage Status"></a>
+  <a href="https://www.npmjs.org/package/browserless"><img src="https://img.shields.io/npm/dm/browserless.svg?style=flat-square" alt="NPM Status"></a>
+  <br><br>
+</div>
+
+> @browserless/ai: Run Chrome Built-in AI from Node.js.
+
+See the [ai section](https://browserless.js.org/#/?id=ai) on our website for more information.
+
+## Install
+
+Using npm:
+
+```sh
+npm install @browserless/ai --save
+```
+
+Requires Node.js 24+ and a [browserless](https://www.npmjs.com/package/browserless) peer.
+
+## About
+
+This package runs [Chrome Built-in AI](https://developer.chrome.com/docs/ai/built-in-apis) from Node.js. It evaluates Prompt, Summarizer, Translator, and Language Detector on a browserless page, so you can call those APIs from a script instead of a visible Chrome window.
+
+Chrome for Testing does not download Gemini Nano for you. Pack a model on a machine that already has it, unpack it into one directory, then pass that `dir` to `createAi` / `launch`.
+
+Chrome’s docs allow the foundation model on **GPU (>4 GB VRAM) or CPU (16 GB RAM, 4+ cores)** at runtime. The 22 GB profile-volume space and unmetered connection apply only when desktop Chrome first downloads Nano, not when you launch with a packed `dir`.
+
+### Usage
+
+```js
+const createAi = require('@browserless/ai')
+
+const { dir } = await createAi.unpack(createAi.download)
+const ai = createAi({ dir })
+
+await ai.capabilities()
+await ai.detectLanguage('https://example.com', { text: 'Hello, how are you today?' })
+await ai.summarize('https://example.com', { type: 'tldr' })
+await ai.prompt('https://example.com', { prompt: 'What is this page about?' })
+const schema = { type: 'object', properties: { title: { type: 'string' } } }
+await ai.extract('https://example.com', { schema })
+await ai.translate('https://example.com', { text: 'Hello', sourceLanguage: 'en', targetLanguage: 'es' })
+await ai.close()
+```
+
+`unpack` accepts a local zip path or a download function. `createAi.download` is a signed R2 GetObject (`R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`). The bucket and object key can live in `R2_ENDPOINT` (`https://<account>.r2.cloudflarestorage.com/<bucket>/<key>`), or in `R2_BUCKET` / `R2_KEY`. The function can return a path, `Buffer`, stream, or S3 `GetObject` result, or write to the `dest` path it receives. If the directory is already unpacked, `unpack` reuses it unless you pass `{ force: true }`.
+
+If you already have a browserless instance:
+
+```js
+const createBrowser = require('browserless')
+const createAi = require('@browserless/ai')
+
+const browser = createBrowser(createAi.launch({ dir: process.env.BROWSERLESS_AI_DIR }))
+const ai = createAi(async teardown => {
+  const browserless = await browser.createContext()
+  teardown(() => browserless.destroyContext())
+  return browserless
+})
+```
+
+Each page-processing method is `(url, options)`. Pass `options.text` to use your own input; otherwise the package reads `document.body.innerText` after navigation. `capabilities` accepts `{ timeout, url }` and supplies defaults.
+
+| Method | Create options |
+|--------|----------------|
+| `prompt` / `extract` | `temperature`, `topK`, `initialPrompts`, `expectedInputs`, `expectedOutputs` |
+| `summarize` | `type`, `format`, `length`, `sharedContext`, `expectedInputLanguages`, `outputLanguage`, `expectedContextLanguages` |
+| `translate` | `sourceLanguage`, `targetLanguage` (required) |
+| `detectLanguage` | `expectedInputLanguages` |
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dir` | `string` | `BROWSERLESS_AI_DIR` | Unpacked model tree (`nano/`, `prompt/`, `summarize/`, `detect/`) |
+| `timeout` | `number` | `300000` | Launch and evaluate timeout (ms). `protocolTimeout` follows it |
+
+`unpack(source, { dir, force })` writes to `dir` when you pass one. Otherwise it uses `BROWSERLESS_AI_DIR`, or `~/.cache/browserless-ai`.
+
+### Pack a model
+
+From a machine that already has Nano (desktop Chrome, or `BROWSERLESS_AI_DIR`):
+
+```sh
+pnpm --filter @browserless/ai pack-model
+pnpm --filter @browserless/ai pack-model -- --upload
+```
+
+Writes `/tmp/browserless-ai-nano.zip`. `--upload` also pushes it to R2 (`R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`; bucket/key may be in the endpoint URL). Tests run `install-model` first and download that object when the same variables are set.
+
+### Example
+
+```sh
+pnpm --filter @browserless/ai start
+pnpm --filter @browserless/ai start https://example.com
+```
+
+### Methods
+
+| Method | Chrome API | Chrome |
+|--------|------------|--------|
+| `prompt` | `LanguageModel` | 148 |
+| `extract` | `LanguageModel` + `schema` / `responseConstraint` | 148 |
+| `summarize` | `Summarizer` | 138 |
+| `detectLanguage` | `LanguageDetector` | 138 |
+| `translate` | `Translator` | 138 |
+| `capabilities` | feature detect | — |
+
+`extract` requires `schema` or `responseConstraint`. `translate` requires `sourceLanguage` and `targetLanguage`. Language Detector and Translator download separately from Gemini Nano. Prompt and Summarizer use Nano.
+
+### How it fits in the monorepo
+
+This is an **extended functionality package**. It is not wired into `browserless` core — install `@browserless/ai` when you need Chrome Built-in AI from Node.js.
+
+## License
+
+**@browserless/ai** © [Microlink](https://microlink.io), released under the [MIT](https://github.com/microlinkhq/browserless/blob/master/LICENSE.md) License.<br>
+Authored and maintained by [Microlink](https://microlink.io) with help from [contributors](https://github.com/microlinkhq/browserless/contributors).
+
+The [logo](https://thenounproject.com/term/browser/288309/) has been designed by [xinh studio](https://xinh.studio).
+
+> [microlink.io](https://microlink.io) · GitHub [microlinkhq](https://github.com/microlinkhq) · X [@microlinkhq](https://x.com/microlinkhq)

package/examples/index.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const createAi = require('..')
+
+const url = process.argv[2] || 'https://example.com'
+const text = process.argv[3] || 'Hello, how are you today?'
+
+const main = async () => {
+  const ai = createAi()
+  try {
+    console.log(await ai.capabilities({ url }))
+    console.log(await ai.detectLanguage(url, { text }))
+  } finally {
+    await ai.close()
+  }
+}
+
+main().catch(error => {
+  console.error(error)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@browserless/ai",
+  "description": "Run Chrome Built-in AI APIs (Prompt, Summarizer, Translator, Language Detector) from Node.js using browserless.",
+  "homepage": "https://browserless.js.org",
+  "version": "13.9.3",
+  "main": "src",
+  "author": {
+    "email": "hello@microlink.io",
+    "name": "microlink.io",
+    "url": "https://microlink.io"
+  },
+  "repository": {
+    "directory": "packages/ai",
+    "type": "git",
+    "url": "git+https://github.com/microlinkhq/browserless.git#master"
+  },
+  "bugs": {
+    "url": "https://github.com/microlinkhq/browserless/issues"
+  },
+  "keywords": [
+    "ai",
+    "browserless",
+    "chrome",
+    "gemini-nano",
+    "headless",
+    "language-detector",
+    "prompt",
+    "puppeteer",
+    "summarizer",
+    "translator"
+  ],
+  "devDependencies": {
+    "ava": "5",
+    "browserless": "workspace:*",
+    "puppeteer": "25"
+  },
+  "peerDependencies": {
+    "browserless": ">=13"
+  },
+  "engines": {
+    "node": ">= 24"
+  },
+  "files": [
+    "examples",
+    "scripts",
+    "src"
+  ],
+  "scripts": {
+    "install-model": "node scripts/install-model.js",
+    "pack-model": "node scripts/pack-model.js",
+    "pretest": "DEBUG=browserless:ai node scripts/install-model.js",
+    "start": "node examples/index.js",
+    "test": "DEBUG=browserless:ai ava"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "ava": {
+    "serial": true,
+    "timeout": "10m",
+    "workerThreads": false
+  },
+  "dependencies": {
+    "debug-logfmt": "~1.4.12"
+  },
+  "gitHead": "625617f1fd88449f2ed6f4e1e1287627a1cc1016"
+}

package/scripts/docker-ci.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+set -eu
+
+root=$(CDPATH= cd -- "$(dirname "$0")/../../.." && pwd)
+ai="$root/packages/ai"
+image=${IMAGE:-kikobeats/microlink-api:ai}
+cmd=${1:-test}
+
+if ! docker image inspect "$image" >/dev/null 2>&1; then
+  weights=$(find "$ai/model" -name weights.bin -print -quit 2>/dev/null || true)
+  if [ ! -f "$weights" ]; then
+    BROWSERLESS_AI_DIR="$ai/model" pnpm --filter @browserless/ai install-model
+  fi
+  docker build --platform linux/amd64 -t "$image" -f "$ai/Dockerfile" "$ai"
+fi
+
+exec docker run --rm --platform linux/amd64 --shm-size=2g \
+  -e CI=1 \
+  -e DEBUG=browserless:ai \
+  -e DISPLAY=:99 \
+  -e LIBGL_ALWAYS_SOFTWARE=1 \
+  -v "$root:/src:ro" \
+  -v browserless-ai-ci-work:/work \
+  -v browserless-ai-ci-chrome:/root/.cache/puppeteer \
+  "$image" \
+  with-xvfb bash -lc "set -eu
+    tar -C /src --exclude node_modules --exclude .git -cf - . | tar -C /work -xf -
+    cd /work
+    pnpm install --dangerously-allow-all-builds
+    pnpm --filter @browserless/ai exec puppeteer browsers install chrome
+    if [ \"$cmd\" = test ]; then
+      pnpm --filter @browserless/ai test
+    else
+      pnpm --filter @browserless/ai exec node $cmd
+    fi"

package/scripts/install-model.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const debug = require('debug-logfmt')('browserless:ai')
+const createAi = require('..')
+const { credentials } = require('./util')
+
+const main = async () => {
+  const env = credentials()
+  if (!env.endpoint || !env.bucket || !env.accessKey || !env.secretKey) {
+    if (process.env.CI) process.stderr.write('skip model download: missing R2 credentials\n')
+    return
+  }
+  const { dir } = await createAi.unpack(createAi.download)
+  debug('install-model', { dir })
+  process.stdout.write(`${dir}\n`)
+}
+
+main().catch(error => {
+  console.error(error.message || error)
+  process.exit(1)
+})

package/scripts/pack-model.js

@@ -0,0 +1,172 @@
+'use strict'
+
+const { crc32 } = require('node:zlib')
+const path = require('node:path')
+const os = require('node:os')
+
+const { createReadStream, createWriteStream, existsSync, statSync } = require('node:fs')
+
+const { hasFile } = require('../src/find-dir')
+const { credentials, objectUrl, uploadFile } = require('./util')
+
+const ZIP32_MAX = 0xffffffff
+
+const chromeSupport = (...parts) =>
+  process.platform === 'darwin'
+    ? path.join(os.homedir(), 'Library', 'Application Support', 'Google', 'Chrome', ...parts)
+    : undefined
+
+const parseArgs = argv => {
+  const extra = argv.slice(2).filter(flag => flag !== '--upload')
+  if (extra.length) throw new Error('usage: pack-model.js [--upload]')
+  const dir = process.env.BROWSERLESS_AI_DIR
+  const model = process.env.BROWSERLESS_AI_MODEL || dir || chromeSupport('OptGuideOnDeviceModel')
+  const adaptation =
+    process.env.BROWSERLESS_AI_ADAPTATION || dir || chromeSupport('optimization_guide_model_store')
+  if (!model) throw new Error('set BROWSERLESS_AI_DIR or BROWSERLESS_AI_MODEL')
+  if (!adaptation) throw new Error('set BROWSERLESS_AI_DIR or BROWSERLESS_AI_ADAPTATION')
+  return {
+    model,
+    adaptation,
+    out: path.join(os.tmpdir(), 'browserless-ai-nano.zip'),
+    upload: argv.includes('--upload')
+  }
+}
+
+const ADAPTATIONS = [
+  { name: 'prompt', target: 49 },
+  { name: 'summarize', target: 51 },
+  { name: 'detect', target: 2 }
+]
+
+const resolveModelDir = root => {
+  const dir = hasFile(root, 'weights.bin')
+  if (!dir) throw new Error(`No weights.bin under ${root}`)
+  for (const name of ['weights.bin', 'manifest.json', 'on_device_model_execution_config.pb']) {
+    if (!existsSync(path.join(dir, name))) throw new Error(`Missing ${name} in ${dir}`)
+  }
+  return dir
+}
+
+const resolveFeatureDir = (root, { name, target }) =>
+  hasFile(path.join(root, name), 'model-info.pb') ||
+  hasFile(path.join(root, String(target)), 'model-info.pb')
+
+const crcAndSize = async file => {
+  const { size } = statSync(file)
+  if (size > ZIP32_MAX) throw new Error(`${file} is too large for ZIP32`)
+  let crc = 0
+  for await (const chunk of createReadStream(file)) crc = crc32(chunk, crc)
+  return { size, crc }
+}
+
+const localHeader = (name, { size, crc }) => {
+  const nameBuf = Buffer.from(name)
+  const header = Buffer.alloc(30)
+  header.writeUInt32LE(0x04034b50, 0)
+  header.writeUInt16LE(20, 4)
+  header.writeUInt32LE(crc, 14)
+  header.writeUInt32LE(size, 18)
+  header.writeUInt32LE(size, 22)
+  header.writeUInt16LE(nameBuf.length, 26)
+  return Buffer.concat([header, nameBuf])
+}
+
+const centralHeader = (name, { size, crc, offset }) => {
+  const nameBuf = Buffer.from(name)
+  const header = Buffer.alloc(46)
+  header.writeUInt32LE(0x02014b50, 0)
+  header.writeUInt16LE(20, 4)
+  header.writeUInt16LE(20, 6)
+  header.writeUInt32LE(crc, 16)
+  header.writeUInt32LE(size, 20)
+  header.writeUInt32LE(size, 24)
+  header.writeUInt16LE(nameBuf.length, 28)
+  header.writeUInt32LE(offset, 42)
+  return Buffer.concat([header, nameBuf])
+}
+
+const write = (stream, buf) =>
+  new Promise((resolve, reject) => {
+    stream.write(buf, err => (err ? reject(err) : resolve()))
+  })
+
+const writeZip = async (dest, entries) => {
+  const out = createWriteStream(dest)
+  const centrals = []
+  let offset = 0
+
+  for (const { name, file } of entries) {
+    process.stderr.write(`packing ${name}\n`)
+    const info = await crcAndSize(file)
+    const header = localHeader(name, info)
+    if (offset + header.length + info.size > ZIP32_MAX) {
+      throw new Error('archive exceeds ZIP32 size')
+    }
+    await write(out, header)
+    for await (const chunk of createReadStream(file)) await write(out, chunk)
+    centrals.push({ name, ...info, offset })
+    offset += header.length + info.size
+  }
+
+  let centralSize = 0
+  for (const entry of centrals) {
+    const header = centralHeader(entry.name, entry)
+    await write(out, header)
+    centralSize += header.length
+  }
+
+  const end = Buffer.alloc(22)
+  end.writeUInt32LE(0x06054b50, 0)
+  end.writeUInt16LE(centrals.length, 8)
+  end.writeUInt16LE(centrals.length, 10)
+  end.writeUInt32LE(centralSize, 12)
+  end.writeUInt32LE(offset, 16)
+  await write(out, end)
+
+  await new Promise((resolve, reject) => out.end(err => (err ? reject(err) : resolve())))
+}
+
+const main = async () => {
+  const opts = parseArgs(process.argv)
+  const modelDir = resolveModelDir(opts.model)
+  const version = path.basename(modelDir)
+  const entries = [
+    { name: `nano/${version}/weights.bin`, file: path.join(modelDir, 'weights.bin') },
+    { name: `nano/${version}/manifest.json`, file: path.join(modelDir, 'manifest.json') },
+    {
+      name: `nano/${version}/on_device_model_execution_config.pb`,
+      file: path.join(modelDir, 'on_device_model_execution_config.pb')
+    }
+  ]
+
+  let packed = 0
+  for (const feature of ADAPTATIONS) {
+    const dir = resolveFeatureDir(opts.adaptation, feature)
+    if (!dir) continue
+    packed++
+    for (const name of ['model.tflite', 'model-info.pb', 'on_device_model_execution_config.pb']) {
+      const file = path.join(dir, name)
+      if (existsSync(file)) entries.push({ name: `${feature.name}/${name}`, file })
+    }
+  }
+  if (!packed) throw new Error(`No prompt/summarize/detect adaptations under ${opts.adaptation}`)
+
+  await writeZip(opts.out, entries)
+  console.log(opts.out)
+  if (!opts.upload) return
+
+  const env = credentials()
+  if (!env.endpoint) throw new Error('set R2_ENDPOINT or R2_ACCOUNT_ID')
+  if (!env.bucket) throw new Error('set R2_BUCKET, or include the bucket in R2_ENDPOINT')
+  if (!env.accessKey || !env.secretKey) {
+    throw new Error('set R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY')
+  }
+  await uploadFile(env, opts.out)
+  console.log(objectUrl(env))
+}
+
+main().catch(error => {
+  console.error(error.message || error)
+  process.exit(1)
+})

package/scripts/probe.js

@@ -0,0 +1,33 @@
+'use strict'
+
+const createAi = require('..')
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+const main = async () => {
+  const ai = createAi()
+  try {
+    let available
+    for (let i = 0; i < 4; i++) {
+      available = await ai.capabilities()
+      console.log(JSON.stringify({ i, available }))
+      if (available.languageModel === 'available') break
+      await sleep(60000)
+    }
+    const language = await ai.detectLanguage('https://example.com', {
+      text: 'Hello, how are you today?'
+    })
+    console.log(JSON.stringify({ language }))
+    const reply = await ai.prompt('https://example.com', {
+      prompt: 'Reply with the single word OK.'
+    })
+    console.log(JSON.stringify({ reply }))
+  } finally {
+    await ai.close()
+  }
+}
+
+main().catch(error => {
+  console.error(error)
+  process.exit(1)
+})