@molecule/api-ai-classification

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.

Zero-shot AI text classification for molecule.dev.

Score a piece of text against a set of candidate labels using an LLM — no training, no fixed taxonomy. This core package defines the AIClassificationProvider contract and its bond accessor only; bond a concrete provider (e.g. @molecule/api-ai-classification-llm, which composes the swappable ai chat bond) to give an app classification.

Quick Start

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

// Wire an AI provider + the classifier at startup.
bond('ai', anthropic)
bond('ai-classification', classification)

// Use it anywhere.
const result = await requireProvider().classify({
  text: 'Win a FREE $1000 gift card now!!!',
  labels: ['spam', 'ham'],
})
console.log(result.top) // 'spam'
console.log(result.labels) // [{ label: 'spam', score: 0.98 }, { label: 'ham', score: 0.02 }]

Type

core

Installation

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

API

Interfaces

AIClassificationConfig

Config options for an AI classification bond.

interface AIClassificationConfig {
  [key: string]: unknown
}

AIClassificationProvider

AI classification provider interface.

Implement (or bond the default provider) to give an app zero-shot text classification. All providers return the same normalized ClassifyResult.

interface AIClassificationProvider {
  /** Provider identifier. */
  readonly name: string

  /**
   * Classify `text` against the candidate `labels`, returning a normalized,
   * score-sorted result.
   *
   * @param input - The text, candidate labels, and options.
   * @returns The scored, sorted labels plus the top label and token usage.
   */
  classify(input: ClassifyInput): Promise<ClassifyResult>
}

ClassifyInput

Input to a single classification request.

interface ClassifyInput {
  /** The text to classify. */
  text: string
  /** Candidate labels to score the text against (required, non-empty). */
  labels: string[]
  /** Allow multiple positive labels rather than a single winner (default `false`). */
  multiLabel?: boolean
  /** Extra guidance passed to the classifier (e.g. label definitions, tone). */
  instructions?: string
  /** Override the AI model used for this request. */
  model?: string
  /** Select a specific named AI provider (defaults to the bonded singleton). */
  provider?: string
  /** Abort signal to cancel the in-flight request. */
  signal?: AbortSignal
}

ClassifyResult

Result of a classification request.

interface ClassifyResult {
  /** All candidate labels with scores, sorted descending by score. Only labels from the candidate set. */
  labels: LabelScore[]
  /** The highest-scoring label. */
  top: string
  /** Token usage reported by the underlying AI provider, when available. */
  usage?: TokenUsage
}

LabelScore

A single label with its confidence score in the range 0..1.

interface LabelScore {
  /** The candidate label. */
  label: string
  /** Confidence score in the range `0..1`. */
  score: number
}

Functions

getAllProviders()

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

function getAllProviders(): Map<string, AIClassificationProvider>

Returns: Map of provider name → AIClassificationProvider.

getProvider()

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

Falls back to a single named provider when no singleton is bonded. When multiple named providers are bonded the fallback declines (returns null) because the choice is ambiguous — use getProviderByName(name) instead.

function getProvider(): AIClassificationProvider | null

Returns: The bonded AI classification provider, or null.

getProviderByName(name)

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

function getProviderByName(name: string): AIClassificationProvider | null

• name — The provider name.

Returns: The named AI classification provider, or null.

hasProvider(name)

Checks whether an AI classification 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 classification provider, throwing if none is bonded.

function requireProvider(): AIClassificationProvider

Returns: The bonded AI classification provider.

setProvider(provider)

Registers an AI classification provider in singleton mode.

function setProvider(provider: AIClassificationProvider): void

• provider — The default provider implementation for this process.

Available Providers

| Provider | Package | | ----------------- | ------------------------------------- | | Ai Classification | @molecule/api-ai-classification-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

• Interface + accessor only. This core ships zero implementation. The batteries-included classifier lives in @molecule/api-ai-classification-llm.

• Swappable. Both the classifier (bond('ai-classification', ...)) and the underlying model (bond('ai', ...)) are swappable at runtime.

• ClassifyResult.labels is restricted to the candidate set, sorted descending by score. See the bonded provider for parsing/normalization semantics.

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:

• [ ] Each flow that classifies content (tagging, routing, moderation, triage — whatever the app defines) runs it from the real UI and the returned top is one of the app's candidate labels, never free text, with a score in 0..1. The sandbox has a live AI provider, so assert on the actual result — never mock the classifier or hardcode a label.
• [ ] Assert BOTH directions with clear samples: a clearly-on-topic example lands in its expected class AND a clearly-different example lands in a different class. A classifier that returns the same label for every input is broken — one positive check alone does not prove it works.
• [ ] Ambiguity is treated as uncertain, not force-fit: when the app gates on a minimum confidence, a genuinely-ambiguous input yields a low winning score and is routed to the app's "unsure"/unlabeled path rather than silently assigned the top label.
• [ ] The label actually DRIVES app behavior (routes/filters/tags/badges the item), not just renders as text — verify the downstream effect in the UI, not only that a label appeared on screen.
• [ ] Empty or ambiguous input is handled without a crash or a blank screen (a visible "couldn't classify"/unlabeled state, not an unhandled error).
• [ ] The classify call runs SERVER-SIDE: it goes through the app's API and the AI provider key never reaches the browser — the Network tab shows no provider request or key issued from client code.