Chrome Built-in AI and Gemini Nano: A Production Guide to the Prompt, Summarizer, and Rewriter APIs

// src/lib/ai/chrome-language-model.ts
export type BuiltInAvailability = "available" | "downloadable" | "downloading" | "unavailable";

export interface PromptSessionOptions {
  systemPrompt?: string;
  temperature?: number;
  topK?: number;
  onDownloadProgress?: (loadedRatio: number) => void;
  signal?: AbortSignal;
}

interface ChromeLanguageModelFactory {
  availability(options?: Record<string, unknown>): Promise<BuiltInAvailability>;
  params(): Promise<{ defaultTemperature: number; maxTemperature: number; defaultTopK: number; maxTopK: number }>;
  create(options?: Record<string, unknown>): Promise<ChromeLanguageModelSession>;
}

export interface ChromeLanguageModelSession {
  prompt(input: string, options?: { responseConstraint?: object; signal?: AbortSignal }): Promise<string>;
  promptStreaming(input: string, options?: { responseConstraint?: object; signal?: AbortSignal }): ReadableStream<string>;
  measureInputUsage(input: string): Promise<number>;
  readonly inputUsage: number;
  readonly inputQuota: number;
  clone(options?: { signal?: AbortSignal }): Promise<ChromeLanguageModelSession>;
  destroy(): void;
}

function getLanguageModelFactory(): ChromeLanguageModelFactory | null {
  const g = globalThis as unknown as {
    LanguageModel?: ChromeLanguageModelFactory;
    ai?: { languageModel?: ChromeLanguageModelFactory };
  };
  return g.LanguageModel ?? g.ai?.languageModel ?? null;
}

export async function createBrowserPromptSession(
  options: PromptSessionOptions = {}
): Promise<ChromeLanguageModelSession | null> {
  const factory = getLanguageModelFactory();
  if (!factory) return null;

  const status = await factory.availability();
  if (status === "unavailable") {
    return null;
  }

  const defaults = await factory.params();
  return await factory.create({
    systemPrompt:
      options.systemPrompt ??
      "You are a concise, code-first web architecture assistant on CodingCat.dev.",
    temperature: options.temperature ?? defaults.defaultTemperature,
    topK: options.topK ?? defaults.defaultTopK,
    signal: options.signal,
    monitor(m: EventTarget) {
      m.addEventListener("downloadprogress", (event: Event) => {
        const e = event as unknown as { loaded?: number; total?: number };
        if (typeof e.loaded === "number" && options.onDownloadProgress) {
          const ratio = e.total ? e.loaded / e.total : e.loaded;
          options.onDownloadProgress(Math.min(1, Math.max(0, ratio)));
        }
      });
    },
  });
}

// src/lib/ai/classify-article-client.ts
import { createBrowserPromptSession } from "./chrome-language-model";

const TAG_EXTRACTION_SCHEMA = {
  type: "object",
  properties: {
    primaryPillar: {
      type: "string",
      enum: ["Courses", "Podcasts", "Blog"],
    },
    difficulty: {
      type: "string",
      enum: ["beginner", "intermediate", "advanced"],
    },
    technicalTags: {
      type: "array",
      items: { type: "string" },
      maxItems: 5,
    },
    oneSentenceSummary: {
      type: "string",
    },
  },
  required: ["primaryPillar", "difficulty", "technicalTags", "oneSentenceSummary"],
  additionalProperties: false,
};

export async function analyzeDraftInBrowser(markdownDraft: string) {
  const baseSession = await createBrowserPromptSession({
    systemPrompt:
      "Analyze developer tutorials for CodingCat.dev and extract structured metadata.",
  });

  if (!baseSession) {
    throw new Error("Chrome Built-in AI (Gemini Nano) is not available on this device.");
  }

  try {
    // Check token budget before prompting so we never blow the context window
    const tokenCost = await baseSession.measureInputUsage(markdownDraft);
    const remainingTokens = baseSession.inputQuota - baseSession.inputUsage;
    const boundedInput =
      tokenCost > remainingTokens ? markdownDraft.slice(0, 6000) : markdownDraft;

    // Clone the warm session so repeated runs reuse the system prompt KV cache
    const workerSession = await baseSession.clone();
    try {
      const rawJson = await workerSession.prompt(
        `Extract metadata for this draft:\n\n${boundedInput}`,
        { responseConstraint: TAG_EXTRACTION_SCHEMA }
      );
      return JSON.parse(rawJson);
    } finally {
      workerSession.destroy();
    }
  } finally {
    baseSession.destroy();
  }
}

// src/lib/ai/summarize-transcript.ts
export async function streamTranscriptKeyPoints(
  transcriptText: string,
  onChunk: (partialMarkdown: string) => void
): Promise<string> {
  const SummarizerApi = (globalThis as Record<string, any>).Summarizer;
  if (!SummarizerApi) {
    throw new Error("Summarizer API is not supported in this browser.");
  }

  const availability = await SummarizerApi.availability();
  if (availability === "unavailable") {
    throw new Error("Summarizer model is unavailable on this hardware.");
  }

  const summarizer = await SummarizerApi.create({
    type: "key-points",
    format: "markdown",
    length: "medium",
    sharedContext:
      "This is a technical software engineering tutorial from CodingCat.dev.",
  });

  try {
    const stream: ReadableStream<string> = summarizer.summarizeStreaming(transcriptText, {
      context: "Focus on architectural trade-offs, browser APIs, and production benchmarks.",
    });

    const reader = stream.getReader();
    let accumulated = "";
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      // Handle both cumulative and delta streaming implementations across Chrome releases
      accumulated = value.startsWith(accumulated) ? value : accumulated + value;
      onChunk(accumulated);
    }
    return accumulated;
  } finally {
    if (typeof summarizer.destroy === "function") {
      summarizer.destroy();
    }
  }
}