@molecule/api-ai-summarization

AI summarization for molecule.dev — concise summaries over any bonded LLM.

A core package: it defines the AISummarizationProvider contract and the bond accessor only — zero concrete implementation. The batteries-included default lives in the bond package @molecule/api-ai-summarization-llm, which composes the swappable ai chat bond (@molecule/api-ai). Apps may bond that default or any custom AISummarizationProvider.

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 } from '@molecule/api-ai-summarization-llm'
import { bond } from '@molecule/api-bond'

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

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

Type

core

Installation

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

API

Interfaces

SummarizeInput

Input for a summarize request.

interface SummarizeInput {
  /** The source text to summarize. */
  text: string
  /** Approximate target length in words (a hint to the model, not enforced). */
  maxLength?: number
  /**
   * HARD cap in words, enforced in code by the provider: the answer is cut
   * back to whole sentences and, when it still runs long, the model is asked
   * again. A summary is never sliced mid-phrase to fit.
   */
  maxWords?: number
  /** How many sentences the summary may have. Defaults to 1 for `'tldr'`. */
  sentences?: number
  /** Model calls allowed to reach the caps (default 3). */
  attempts?: number
  /** Output shape. Defaults to `'paragraph'`. */
  format?: 'paragraph' | 'bullets' | 'tldr'
  /** Optional angle or extra instructions to steer the summary. */
  focus?: string
  /** AI model override, passed through to the AI provider. */
  model?: string
  /** Named AI provider to use; falls back to the bonded default when omitted. */
  provider?: string
  /** Abort signal to cancel the in-flight AI request. */
  signal?: AbortSignal
}

SummarizeResult

Result of a summarize request.

interface SummarizeResult {
  /** The generated summary. */
  summary: string
  /** Token usage reported by the underlying AI provider, when available. */
  usage?: TokenUsage
  /**
   * With `maxWords`/`sentences`: whether the summary meets them. `false` means
   * every attempt ran long and this is the shortest complete sentence the
   * model gave — never a cut-off one.
   */
  withinCap?: boolean
  /** Model calls made. */
  attempts?: number
}

AISummarizationProvider

AI summarization provider interface.

Implemented by the batteries-included default (composing @molecule/api-ai) or by a custom bond package. All implementations return the same normalized SummarizeResult regardless of the LLM behind them.

interface AISummarizationProvider {
  readonly name: string

  /**
   * Summarize the given text.
   *
   * @param input - The source text plus optional shape/length/focus controls.
   * @returns The summary and (when reported) token usage.
   */
  summarize(input: SummarizeInput): Promise<SummarizeResult>
}

AISummarizationConfig

Config options for an AI summarization bond.

interface AISummarizationConfig {
  [key: string]: unknown
}

Functions

setProvider(provider)

Registers an AI summarization provider in singleton mode.

• Singleton: setProvider(provider) — bonds a single default provider.

function setProvider(provider: AISummarizationProvider): void

• provider — The default provider implementation for this process.

getProvider()

Retrieves the singleton AI summarization provider, or null if none is bonded.

Falls back to a single named provider when no singleton is bonded — this lets apps that wire bond('ai-summarization', 'fast', provider) directly still work with the simple getProvider() / requireProvider() accessors. When multiple named providers are bonded, the fallback declines (returns null) because the choice is ambiguous.

function getProvider(): AISummarizationProvider | null

Returns: The bonded AI summarization provider, or null.

getProviderByName(name)

Retrieves a named AI summarization provider, or null if not bonded.

function getProviderByName(name: string): AISummarizationProvider | null

• name — The provider name.

Returns: The named provider, or null.

getAllProviders()

Retrieves all named AI summarization providers as a Map keyed by name.

function getAllProviders(): Map<string, AISummarizationProvider>

Returns: Map of provider name → AISummarizationProvider.

hasProvider(name)

Checks whether an AI summarization provider is currently bonded.

function hasProvider(name?: string): boolean

• name — Optional provider name. If omitted, checks the singleton.

Returns: true if the provider is bonded.

requireProvider()

Retrieves the bonded AI summarization provider, throwing if none is bonded.

function requireProvider(): AISummarizationProvider

Returns: The bonded provider.

Available Providers

Provider	Package
Ai Summarization	@molecule/api-ai-summarization-llm

Injection Notes

Requirements

Peer dependencies:

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

Runtime Dependencies

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

This core imports @molecule/api-ai only as a type (the shared TokenUsage interface on SummarizeResult) — never for runtime use. A provider must be bonded before requireProvider() resolves (it throws otherwise). Swap in a custom AISummarizationProvider via bond('ai-summarization', myProvider) without changing any call site.

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.