punctify

Paragraph-level punctuation correction powered by LLMs.

Splits text into paragraphs, sends them to an LLM for correction, then diffs the result and accepts only punctuation-character changes. Word changes, capitalization changes, and spacing changes are rejected by the safety filter — the LLM can only fix punctuation.

Install

npm install punctify

Quick start

import { punctify } from 'punctify'

const result = await punctify(
  'The court considered standing ripeness and mootness.',
  { apiKey: process.env.OPENAI_API_KEY, provider: 'openai' }
)

result.text
// → 'The court considered standing, ripeness, and mootness.'

result.corrections
// → [{ position: 30, original: ' ', replacement: ', ', context: '...' }, ...]

result.unchanged
// → false

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 punctify(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 | 10 | Maximum paragraphs per LLM call |

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

Result

interface PunctifyResult {
  text: string          // The corrected text
  corrections: Array<{  // Only punctuation that was changed
    position: number    // Index in original text
    original: string    // What was there
    replacement: string // What it became
    context: string     // Surrounding snippet for audit
  }>
  unchanged: boolean    // true if nothing was modified
}

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

All punctuation 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 { punctify } from 'punctify'

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

Design decisions

Paragraph-level, not character-level. Punctuation is dense — every sentence has multiple marks. A comma's correctness depends on clause structure (Oxford comma, which vs that, semicolons in complex lists). Sending full paragraphs gives the LLM the clause context it needs.

Safety filter. The LLM returns corrected paragraphs, but only punctuation-character changes are accepted. Character-level diffing (via diff-match-patch) rejects any hunk that touches letters, digits, or non-punctuation symbols. The allowlist is explicit: .,:;?!'"()[]{}/-\ and their typographic variants.

CRLF-aware. Paragraph 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