@molecule/api-ocr-molecule

molecule.dev hosted OCR provider for @molecule/api-ocr.

Extracts text from images on molecule.dev and bills the recognition to your molecule project, so the app needs no OCR vendor account. It is an ordinary bond: swap it for @molecule/api-ocr-tesseract (self-hosted, no per-call cost) or @molecule/api-ocr-llm (your own AI provider) without changing code that calls the core.

Quick Start

import { setProvider, requireProvider } from '@molecule/api-ocr'
import { provider as ocr } from '@molecule/api-ocr-molecule'

setProvider(ocr) // reads MOLECULE_API_KEY from the environment

const result = await requireProvider().recognize({
  data: new Uint8Array(imageBytes),
  mimeType: 'image/png',
})
if (result.text.trim()) {
  // Index, display or store the recognized text.
}

Type

provider

Installation

npm install @molecule/api-ocr-molecule @molecule/api-ocr @molecule/api-secrets

API

Interfaces

MoleculeOcrConfig

Options for createProvider. Every field falls back to an env var, so the zero-argument provider export works from .env alone.

interface MoleculeOcrConfig {
  /**
   * The molecule project API key (`mk_…`), or the sandbox token molecule.dev
   * writes for in-IDE apps (`mbk_…`). Defaults to `MOLECULE_API_KEY`.
   */
  apiKey?: string
  /**
   * The hosted services base URL, without a trailing slash. Defaults to
   * `MOLECULE_SERVICES_URL`, then `https://api.molecule.dev/api/v1/services`.
   */
  servicesUrl?: string
  /** Per-request timeout in milliseconds. Default 60000 — recognition is slower than moderation. */
  timeoutMs?: number
}

ProcessEnv

Environment variables this provider reads.

interface ProcessEnv {
  MOLECULE_API_KEY?: string
  MOLECULE_SERVICES_URL?: string
}

Classes

MoleculeOcrProvider

OCR provider backed by molecule.dev's hosted service.

MoleculeServiceError

Error thrown for a refused or failed hosted-service call.

Functions

createProvider(config)

Create a hosted OCR provider.

function createProvider(config?: MoleculeOcrConfig): OcrProvider

• config — Options; each falls back to its env var.

Returns: An OcrProvider backed by molecule.dev.

Constants

DEFAULT_SERVICES_URL

Default hosted services base URL.

const DEFAULT_SERVICES_URL: 'https://api.molecule.dev/api/v1/services'

OCR_IMAGE_TYPES

Image types the hosted service accepts.

const OCR_IMAGE_TYPES: readonly ['image/png', 'image/jpeg', 'image/webp', 'image/gif']

OCR_SERVICE_LIMITS

Per-request limits of the hosted service.

const OCR_SERVICE_LIMITS: { readonly maxImageBytes: number }

ocrMoleculeSecretDefinitions

Secret definitions required by the molecule.dev hosted OCR bond.

const ocrMoleculeSecretDefinitions: SecretDefinition[]

provider

The provider implementation (wire with setProvider).

const provider: OcrProvider

Core Interface

Implements @molecule/api-ocr interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-ocr'
import { provider } from '@molecule/api-ocr-molecule'

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

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-ocr >=1.0.0
• @molecule/api-secrets ^1.0.1

Environment Variables

• MOLECULE_API_KEY (required) — molecule.dev project API key
  • Setup: Create one for your project with mlcl apikey create --project <id> --name <name> (keys start with mk_).
  • Get it here: https://www.molecule.dev
  • Example: mk_...

Runtime Dependencies

• @molecule/api-ocr

• @molecule/api-secrets

• Config: MOLECULE_API_KEY (SERVER-side only) — a molecule project API key (mk_…) with scope broker or broker:ocr. Optional MOLECULE_SERVICES_URL (default https://api.molecule.dev/api/v1/services; required — plain-http is refused unless the host is loopback or a private-network endpoint (RFC 1918 / *.docker.internal, e.g. the sandbox gateway host.docker.internal)).

• At most 8 MB of image (png, jpeg, webp or gif) per recognition. Larger scans must be split or downscaled — the service refuses oversized bodies with 413 rather than resampling them.

• language is optional and free-form (en, de, zh-TW, "German"): the hosted service recognizes with a vision model, so any language hint a model understands works. Omit it for mixed-language images.

• Metered per image and billed to the project (spend is the vision model's token usage on molecule's account). result.pages[0] carries no confidence — the model behind the service does not self-score.

• Errors are MoleculeServiceError with status and errorKey (401 bad key, 402 allowance used up, 413 too large, 429 / 503 retry later). Nothing is retried — an upload pipeline that needs guaranteed extraction should queue failures for a retry, not drop them.