← Amber English

Rewrite checks: methods & API

Open the workspace →

Enter an original and a rewrite once. Check runs vocabulary comparison and surface rules, with no AI call. Review meaning is a separate, explicit action: sign-in, one AI unit, and both texts sent to DeepSeek. Texts are kept only in the open page; leaving or reloading discards them. A sent AI request may still use allowance if the page closes.

Vocabulary comparison supports 300,000 characters per side. Surface and meaning checks support 18,000. Longer inputs can still be compared for vocabulary; they are never silently truncated for meaning checks. Partial failures keep the successful report and clearly mark the unavailable check.

The two APIs and their method versions are unchanged. Word-view JSON and CSV retain the complete comparison format. Meaning-view JSON contains the exact input plus the fidelity report. Display filters do not reduce any export. Locating a word uses spelling occurrences; it does not infer sentence or word-to-word alignment. Repeated excerpts can occur on either side independently.

In Amber, this workspace opens an accepted section of the chosen book version. Book, version and source anchors stay bound together; saved reports do not trigger new AI calls. Missing or mismatched historical reports stay unreviewed. A new manual check does not overwrite the accepted version or create learning evidence.

Vocabulary comparison

What this comparison measures

Both complete texts use the same counting method and word-list matching. Match is matched English word occurrences divided by counted English word occurrences. Higher match does not prove better writing, personal understanding or preserved meaning.

“New off-list” means a normalized spelling appears in the rewrite, is absent from the original, and is not matched by the chosen list. More occurrences of an existing off-list spelling are shown under Changes, not counted as a new spelling. Added and removed spellings are exact lexical differences, not word-to-word replacement alignments.

Optional checks enforce only what you declare: a maximum number of new off-list spellings, a minimum rewrite match ratio, or preservation of original spellings. A preserved spelling must exist in the original and remain at least once in the rewrite. Phrases, case-sensitive names and meaning preservation are not supported by this spelling check. No constraints means a descriptive report, not a quality approval.

Custom lists match lowercase spellings with curly apostrophes normalized; cat does not imply cats. Separate plain entries with whitespace, commas or semicolons, without headers or counts. Empty lists match nothing. NGSL uses explicitly published word forms, leaves multiple lemma candidates unresolved and excludes the supplementary list. NGSL 1.2 — Browne, Culligan & Phillips, CC BY-SA 4.0.

Markdown headings are excluded, contractions and hyphenated words stay whole, numbers and non-ASCII word tokens are excluded. Locations are UTF-16 offsets within returned body paragraphs, independently for each text. This tool does not test omissions, facts, grammar or semantic fidelity.

Example: original “The cat. Quux quux.” and rewrite “The cats. Quux blorb blorb.” with the list “the cat cats” match 2/4 (50%) and 2/5 (40%). Blorb is one new off-list spelling, appearing twice; cats is added but matched, cat is removed, and quux is already present. A maximum of zero new off-list spellings fails.

Method amber-vocabulary-comparison/1.0, coverage amber-vocabulary-coverage/1.0, profile amber-english-profile/1.0. Updated October 10, 2026.

API for agents and developers

Send JSON to POST /api/tools/vocabulary-comparison. Anonymous synchronous analysis, no model call, no AI credits or saved side effects. Maximum: 300,000 UTF-16 characters per text, 100,000 custom-list characters, 10,000 preserved-spelling characters and 1,800,000 request bytes. No per-account quota is configured.

curl -X POST https://amberenglish.app/api/tools/vocabulary-comparison -H 'Content-Type: application/json' -d '{"original":"The cat. Quux quux.","rewrite":"The cats. Quux blorb blorb.","list":{"kind":"custom","text":"the cat cats"},"constraints":{"maxNewOffListTypes":0}}'

original and rewrite are required strings. Omit list for NGSL or use {"kind":"ngsl"}. Optional constraints accepts maxNewOffListTypes (nonnegative integer), minimumCoverage (number 0–1), and preserveSpellings (plain spelling list). There is no partial scope input. Unrecognized fields are rejected.

Schema vocabulary-comparison/1 returns complete original/rewrite coverage profiles with the same list SHA-256, delta for tokens/types/coverage/offListTokens, added/removed/newOffList spelling arrays, echoed constraints, issues and passed. Each spelling includes occurrence locations. passed means only that declared checks passed; it is true when no checks are declared. Issues are new_off_list_limit, coverage_below_minimum or missing_preserved_spelling, with actual/expected values and a spelling where applicable.

Complete reproducible response. Copy JSON returns the same report. CSV includes every spelling, both occurrence counts, count change, new-off-list flag and both sets of paragraph:start:end locations (zero-based UTF-16 offsets). CSV is a report, not an input spelling list.

Constraint failures return HTTP 200 with passed:false. Input failures return {"error":{"code":"invalid_constraints","message":"…"}}. HTTP 400: invalid_input, invalid_json, empty_input, no_english_tokens, invalid_list, invalid_constraints; correct the input. HTTP 413: input_too_long or list_too_long; shorten inputs. HTTP 415: unsupported_media_type; use application/json. HTTP 500: analysis_failed; retry. The page times out after 20 seconds and keeps inputs.

Responses use no-store and noindex. User text and results do not become public pages or appear in URLs. Amber book access is authenticated separately.

Meaning and surface checks

How the checks work

Rule checks compare numeric spellings, explicit negative markers, acronyms and selected multiword capitalized names. They also check any expressions you lock. These are surface differences, not confirmed errors. Single names, written-out numbers and implicit negation are not exhaustively detected. Reordering and equivalent paraphrases can trigger concerns.

Meaning review is a separate model judgement from the rewrite author, using only the two supplied texts. It looks for omissions, additions, changed facts, references, conditions and perspective. Amber uses this same review instruction and report validator during its second-pass review. A separate call to the same model is not independent scientific validation.

Every model concern must quote at least one exact excerpt. Invalid or incomplete responses stay incomplete, never clear. A clear meaning review cannot erase a rule concern. Amber sends unresolved concerns through repair and review, or marks preparation as failed. Existing accepted reading remains available.

No result promises 100% fidelity. This method has been checked on small authored examples, not calibrated against a representative benchmark. The tool does not score your vocabulary or write learning evidence. The shared workspace keeps word-list changes in a separate view.

Method amber-fidelity/1.0 · October 10, 2026. Positions are zero-based UTF-16 offsets in each exact input, with exclusive end positions. Repeated exact quotes show all matching locations; this is not a unique sentence alignment.

API for agents and developers

POST JSON to /api/tools/fidelity. Required strings: original, rewrite. Optional locked: array of up to 100 exact case-sensitive expressions (each at most 120 characters). Optional semantic: boolean, default false. Each text is limited to 18,000 UTF-16 characters and the request to 180,000 bytes. Only documented fields are accepted.

curl -X POST https://amberenglish.app/api/tools/fidelity -H 'Content-Type: application/json' -d '{"original":"NASA sent 12 people.","rewrite":"NASA sent 21 people."}'

Anonymous rules-only calls return semantic.status=not_run and passed=false. semantic=true requires the normal signed-in Amber session, is limited to 10 requests per minute and consumes one AI service unit under the existing account and site quotas. The browser page also uses this API. No API key or operator credential can replace account authentication.

Schema fidelity/1 returns method, text lengths, rules and semantic sections with status and issues, and passed. Each issue has kind, message and original/rewrite location arrays with start, end, quote. Semantic execution adds model, elapsedMs and provider token usage. Export adds the exact input texts and locked expressions to the same report. Complete rules-only example.

HTTP 200 can contain concerns; passed is true only when both sections are clear. HTTP 400: invalid_input, invalid_json, invalid_locked, locked_not_in_original; correct the inputs. 401: sign in. 413: shorten input. 415: use application/json. 429: quota or rate limit, retry later. 502: model response could not be validated, report contains semantic.status=failed. 503: review unavailable or timed out; retry may consume another unit. Client timeout is 35 seconds; provider timeout is 25 seconds. A request already sent may still consume a unit if you leave the page.

Tool inputs are not stored or placed in URLs. Meaning review transmits texts to DeepSeek; provider processing applies. Responses use no-store and noindex. Public documentation is indexable; submitted results are private. Amber separately stores its own account-owned version reports.