recapify

Structure-aware capitalization correction powered by LLMs.

Classifies text segments (headings, subheadings, body, list items, definitions), sends them with type tags to an LLM for correction, then diffs the result and accepts only case changes. Word changes, punctuation changes, and insertions/deletions are rejected by the safety filter — the LLM can only fix capitalization.

Install

npm install recapify

Quick start

import { recapify } from 'recapify'

const result = await recapify(
  'article iii — remedies\n\nthe buyer shall notify the seller.',
  { apiKey: process.env.OPENAI_API_KEY, provider: 'openai' }
)

result.text
// → 'ARTICLE III — REMEDIES\n\nThe Buyer shall notify the Seller.'

result.corrections
// → [{ position: 0, original: 'article iii — remedies', replacement: 'ARTICLE III — REMEDIES', context: '...' }, ...]

result.unchanged
// → false

Segment types

Each segment is classified before being sent to the LLM, so capitalization rules are applied in context:

| Type | Heuristic | Example | |---|---|---| | heading | Short + majority uppercase or ARTICLE/SECTION pattern | ARTICLE III — REMEDIES | | subheading | Short + Section \d or \d+.\d+ pattern | Section 3.1 — Indemnification | | definition | Contains "X" means or "X" shall mean | "Agreement" means this contract | | list-item | Starts with (a), (i), 1., etc. | (a) the Buyer shall notify... | | body | Everything else | The court held that... |

Providers

Built-in support for any OpenAI-compatible API, plus a native Anthropic adapter.

| Provider | Default model | Notes | |---|---|---| | openai | gpt-4o-mini | | | anthropic | claude-haiku-4-5-20251001 | Native adapter (different API format) | | gemini | gemini-2.0-flash | OpenAI-compatible endpoint | | groq | llama-3.3-70b-versatile | | | together | meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo | | | mistral | mistral-small-latest | | | xai | grok-3-mini-fast | | | deepseek | deepseek-chat | | | openrouter | (none — must specify model) | |

Custom LLM function

Bypass the built-in client entirely:

const result = await recapify(text, {
  llm: async (messages) => {
    const res = await myLlmCall(messages)
    return res.text
  },
})

Options

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | — | API key for the LLM provider | | provider | Provider | — | Provider name (maps to base URL + default model) | | model | string | (per provider) | Model name. Required if no provider default. | | baseURL | string | — | Custom endpoint URL. Overrides provider mapping. | | llm | (messages) => Promise<string> | — | Custom LLM function. Overrides apiKey/provider/model. | | rules | string | "" | Custom rules prepended to the system prompt | | batchSize | number | 15 | Maximum segments per LLM call |

You must provide either apiKey (with provider or model) or llm.

Result

interface RecapifyResult {
  text: string          // The corrected text
  corrections: Array<{  // Only capitalization that was changed
    position: number    // Index in original text
    original: string    // What was there
    replacement: string // What it became (case-only change)
    context: string     // Surrounding snippet for audit
  }>
  unchanged: boolean    // true if nothing was modified
}

No segments in text: LLM is not called. Returns immediately with unchanged: true.

All capitalization already correct: LLM is called, but corrections is empty and unchanged is true.

Custom rules

Works with lexstyle for structured rule management:

import { rules, serialize } from 'lexstyle'
import { recapify } from 'recapify'

const result = await recapify(text, {
  apiKey: process.env.OPENAI_API_KEY,
  provider: 'openai',
  rules: serialize(rules, 'capitalization'),
})

Design decisions

Structure-aware. Capitalization rules differ by context: "article iii" in a heading becomes "ARTICLE III"; in body text it stays lowercase. Without segment classification, the LLM can't apply the right rules.

Safety filter. The LLM returns corrected segments, but only case changes are accepted. Character-level diffing (via diff-match-patch) verifies that each changed character pair is related by toUpperCase() — same letter, different casing. Unicode confusables are rejected.

Classification before correction. Segments are heuristically classified as heading, subheading, body, list-item, or definition. The type tag is sent with each segment so the LLM knows which capitalization conventions apply.

CRLF-aware. Segment splitting normalizes \r\n to \n internally, with offset mapping that preserves correct positions in the original text.

Batch validation. Each batch response is validated against its expected IDs before merging.

Robust response parsing. Strict JSON first, bracket-extraction fallback for LLM preamble text.

Development

npm install
npm test
npm run typecheck
npm run build     # ESM + CJS + .d.ts

License

Apache-2.0