@molecule/api-ai-summarization-llm

Default (llm) AI summarization provider for molecule.dev.

Turns a block of text into a concise summary over whatever LLM the app has bonded. It has no vendor of its own — it composes the swappable ai chat bond (@molecule/api-ai) with a summarizer system prompt built from the requested format / length / focus, so swapping the LLM swaps the summarizer.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { provider as anthropic } from '@molecule/api-ai-anthropic'
import { requireProvider } from '@molecule/api-ai-summarization'
import { provider as summarization } from '@molecule/api-ai-summarization-llm'
import { bond } from '@molecule/api-bond'

// Wire the AI chat provider this composes, then bond the summarizer.
bond('ai', anthropic)
bond('ai-summarization', summarization)

// Use anywhere after startup.
const { summary, usage } = await requireProvider().summarize({
  text: longArticle,
  format: 'bullets',
  maxLength: 60,
  focus: 'the financial impact',
})

// A one-sentence TL;DR with a HARD word cap, cached across builds — e.g. a
// build step that summarizes each long section of each page.
import { provider as anthropic } from '@molecule/api-ai-anthropic'
import { setProvider as setAI } from '@molecule/api-ai'
import { setProvider as setSummarizer } from '@molecule/api-ai-summarization'
import {
  countWords,
  createFileSummaryCache,
  provider as summarization,
  summarizeCached,
} from '@molecule/api-ai-summarization-llm'

setAI(anthropic)
setSummarizer(summarization)

const cache = createFileSummaryCache('.cache/summaries.json')
const rows: Record<string, string> = {}
for (const section of sections) {
  if (countWords(section.prose) < 80) continue // too short to be worth a summary
  const r = await summarizeCached({ text: section.prose, format: 'tldr', maxWords: 25 }, { cache })
  rows[r.key] = r.summary // one complete sentence, ≤ 25 words
}
cache.save()
// publish `rows` (e.g. write it next to the page as summaries.json)

Type

provider

Installation

npm install @molecule/api-ai-summarization-llm @molecule/api-ai @molecule/api-ai-summarization @molecule/api-i18n

API

Interfaces

CachedSummary

One cached summary.

interface CachedSummary {
  summary: string
  withinCap?: boolean
}

SummaryCache

The cache: a key → summary map persisted to a JSON file.

interface SummaryCache {
  /** The file the cache reads and writes. */
  readonly file: string
  get(key: string): CachedSummary | undefined
  set(key: string, value: CachedSummary): void
  /** Every entry, e.g. to publish them as a static file. */
  entries(): Record<string, CachedSummary>
  /** Writes the file (creating its directory). */
  save(): void
}

LlmSummarizationConfig

Configuration for {@link createProvider}.

interface LlmSummarizationConfig {
  /**
   * The `ai` provider this provider composes: an already-resolved provider
   * instance, or the name of one to resolve at call time. Defaults to the
   * bonded singleton of `@molecule/api-ai`.
   */
  aiProvider?: AIProvider | string
  /** Default model for every summarize call. A call's own `model` wins. */
  model?: string
}

Functions

summaryKey(input)

The cache key for a request: a SHA-256 of the text (whitespace-normalized) and every option that changes the answer.

function summaryKey(input: SummarizeInput): string

• input — The summarize request.

Returns: A 64-char hex key.

createFileSummaryCache(file)

Opens (or starts) a summary cache stored at file.

function createFileSummaryCache(file: string): SummaryCache

• file — Path of the JSON file, e.g. .cache/summaries.json.

Returns: The cache.

summarizeCached(input, options)

Summarize through the cache: a hit returns without a model call; a miss summarizes and stores the result. A summary that did not meet its caps (withinCap: false) is returned but not stored, so the next run tries again.

function summarizeCached(
  input: SummarizeInput,
  options: { cache: SummaryCache; summarizer?: AISummarizationProvider },
): Promise<SummarizeResult & { cached: boolean; key: string }>

• input — The summarize request.
• options — The cache, and optionally a provider (defaults to the bonded one).
• options.cache — The cache to read and fill.
• options.summarizer — A provider to use instead of the bonded one.

Returns: The result, with cached: true on a hit and key for publishing.

createProvider(config)

Creates an LLM summarization provider.

Composes the ai chat provider (@molecule/api-ai) — an AI provider MUST be bonded first (bond('ai', <provider>)), or summarize() throws, unless config.aiProvider supplies one directly (how a hosted handler injects its own provider). The module-level provider is this factory with no config.

function createProvider(config?: LlmSummarizationConfig): AISummarizationProvider

• config — Optional ai provider and default model.

Returns: An AISummarizationProvider composed over the ai bond.

countWords(s)

Words in a string, the way a reader counts them.

function countWords(s: string): number

• s — Any text.

Returns: The number of whitespace-separated words.

cleanSummary(raw)

Strips what models wrap a summary in: reasoning blocks, a "TL;DR:" or "Summary:" label, surrounding quotes or bold, and line breaks.

function cleanSummary(raw: string): string

• raw — The model's answer.

Returns: The bare summary text.

firstSentences(s, n)

The first n complete sentences of a text. A trailing fragment with no terminal punctuation is dropped, never kept or given a full stop.

function firstSentences(s: string, n: number): string

• s — Cleaned summary text.
• n — How many sentences to keep.

Returns: Those sentences, or '' when the text holds no complete sentence.

meetsCap(s, maxWords)

Whether a summary meets the caps and reads as finished: at most maxWords words, terminal punctuation, and a last word that is not a function word.

function meetsCap(s: string, maxWords?: number): boolean

• s — Candidate summary.
• maxWords — The hard word cap, if any.

Returns: true when the summary can be published as is.

Constants

provider

Default AI summarization provider.

Composes the bonded ai chat provider (@molecule/api-ai) — an AI provider MUST be bonded first (bond('ai', <provider>)), or summarize() throws. Bond it with bond('ai-summarization', provider); swap in a custom AISummarizationProvider to replace it without touching call sites.

const provider: AISummarizationProvider

Core Interface

Implements @molecule/api-ai-summarization interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-ai-summarization'
import { provider } from '@molecule/api-ai-summarization-llm'

export function setupAiSummarizationLlm(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-ai ^1.0.1
• @molecule/api-ai-summarization ^1.0.1
• @molecule/api-i18n ^1.0.1

Runtime Dependencies

• @molecule/api-ai
• @molecule/api-ai-summarization
• @molecule/api-i18n

A hard cap is enforced here, in code — do not rebuild it. With maxWords (and/or sentences, which defaults to 1 for format: 'tldr') the provider cleans the answer (drops "TL;DR:" labels, quotes, <think> blocks), keeps whole sentences only, checks the cap and that the last word is not a function word ("the", "and", "of"…), and asks the model again when it runs long (attempts, default 3). It never slices a sentence and adds a full stop. If every attempt runs long it returns the shortest complete sentence with withinCap: false; summarizeCached does not store those, so the next run retries. It throws only when the model returns no usable text at all, or the AI provider fails — so "unavailable" is for a missing key or an unreachable provider, never for a long answer.

Model quirks it already handles: it sends no temperature (several current models reject it), and it asks for a large output budget, because a model that reasons before answering can spend a small maxTokens entirely on hidden reasoning and stream no text.

summarizeCached keys by a SHA-256 of the whitespace-normalized text plus every option, so an unchanged text is never re-summarized; summaryKey(input) gives the same key without calling the model. The cache is a plain JSON file ({ version: 1, entries: { key: { summary } } }); call save() once at the end. Server-only (Node fs/crypto): run it in a build script or a server route, never in client code — at build time, bond the ai provider inside the script that summarizes, since a bundler's separate passes do not share bonds set up elsewhere.

Composes the swappable ai bond: an ai provider MUST be bonded first (bond('ai', <provider>)) or summarize() throws (a missing AI provider throws at summarize() time, not at import). Pass provider on the input to target a specific named ai provider. Because it is just prompt orchestration over the bonded LLM, swapping the ai provider swaps the model behind every summary without touching call sites. createProvider({ aiProvider, model }) builds the same provider over an explicitly injected ai provider (how molecule.dev's hosted summarization service runs it) with a default model.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

• [ ] Summarizing a real long document through the app's UI returns a summary that is clearly SHORTER than the input and captures its key points — not a truncation of the first N characters, not an echo of the input, not empty. The sandbox has a live AI provider, so this runs for real; the output is non-deterministic, so assert on behavior (it is shorter, the main ideas are present), never on an exact string.
• [ ] A second, different document yields a genuinely different summary — not the same cached/boilerplate text — confirming each summary reflects the actual input rather than a canned response.
• [ ] The shape/length controls actually change the output: a smaller maxLength (approx target words) produces a shorter summary than a larger one, and switching format between 'paragraph', 'bullets', and 'tldr' visibly changes the structure (bullets render as a list, tldr is terser). If the app exposes only some of these, verify the ones it exposes.
• [ ] Edge inputs are handled, not silently mangled: empty or whitespace-only input does not crash and gives a clear "nothing to summarize" response; very long input (beyond the model's limit) either summarizes or fails with a visible, clear message — never a silent truncation that drops half the meaning.
• [ ] A provider failure (the AI request errors, is rate-limited, or times out) surfaces gracefully in the UI — a readable error, no blank screen, no crash, no uncaught 500.
• [ ] The summarize call runs server-side only: no AI key or provider secret is ever exposed to the browser. Confirm the request goes to this app's own API and the key never appears in network traffic or the client bundle.