← Amber English

Simplify English: method & API

Open the workspace →

Enter English once. Generate with default settings, or preview protection, candidate words and learning choices. Continue adjusting from an accepted result; use JSON import to restore an exported session. The workspace accepts up to 18,000 characters, with at most 6,000 selected per generation. The independent preview APIs keep their larger limits below.

Preview calls are anonymous and free of model use. Generate and update require sign-in and reserve 2 AI units per attempt. Switching views, restoring reports and checking changes do not call a model. Inputs stay in the current page; export before refreshing. A stopped wait does not cancel a provider request already started.

Simplification & range

Method and limits

This is reference-guided English simplification, not a personal level assessment, summary or translation. Use NGSL 1.2 published forms or your own spelling list. Learning-word selection, term protection, vocabulary comparison and fidelity checks use the same core as Amber.

Paragraph numbers refer to parsed visible original text, starting at 1 in the page. Titles and Markdown formatting are normalized by Amber’s existing parser; exports preserve parsed paragraph text, not the source file’s bytes or formatting. The chosen range intersects the retained prefix: preservation always wins. Only selected paragraphs are rewritten. Each keeps its original anchor; sentences may split or combine within that paragraph. Outside paragraphs remain original, not a merge with an older rewrite.

Up to 18,000 UTF-16 characters per input, 6,000 selected characters per request. Learning items use the same three budgets as the selection tool, and protection takes priority. Selected spellings are editing choices, not knowledge evidence. The generation call and separate review use DeepSeek. Unresolved controls, structural errors, rule suspicions or semantic issues cannot yield accepted text. Model judgement can miss errors; compare with the original. General reference guidance does not promise a measured difficulty level or a minimum coverage percentage.

Plan without an account. Generate with existing sign-in and 2 AI units per attempt (including attempts that fail after reservation). There is no automatic retry, persistent tool task or saved result; keep this page open and export before refreshing. A timeout may have reached the provider; another attempt can cost another 2 units. Amber’s personal preparation retains its existing assessment, persistent task, retry and version rules. User inputs and results are not public or indexed.

API for agents and developers

POST application/json to /api/tools/controlled-english. action is plan (default, anonymous) or generate (existing authenticated session). Required text; optional range with zero-based startParagraph, exclusive endParagraph and preserveBefore count. Optional list is {kind:"ngsl"} or {kind:"custom",text:"..."}; locks use one term per line and | for explicit variants, or the documented term-lock array. Optional budget: maxItems 0–50, maxOccurrences 0–20,000, maxParagraphRatio 0–1. Optional choices: unique normalized word and retain/replace action, as in learning selection. No trusted or personal-evidence fields are accepted.

{
  "action": "generate",
  "text": "The automobile remained stationary.",
  "budget": {
    "maxItems": 0,
    "maxOccurrences": 0,
    "maxParagraphRatio": 0
  }
}

Plan schema controlled-english-plan/1; result controlled-english/1; method amber-controlled-english/1.0 and range method amber-processing-scope/1.0. Results include source fingerprint, paragraph coordinates, scope, controls, per-paragraph original/candidate text, fidelity, vocabulary comparison and execution token usage. Only status=accepted includes the final text field. HTTP 422 returns status=needs_review with diagnostic candidate paragraphs. Complete real-model request and response.

HTTP 400 correct input; 401 sign in; 413 shorten input/range; 415 send JSON; 422 inspect checks before another paid attempt; 429 wait or inspect allowance; 503 unavailable/incomplete provider, retain inputs and retry deliberately. Five generation requests per account per minute; request body at most 180,000 bytes. Private responses use no-store and noindex. Unknown fields are rejected. Updated October 10, 2026.

Protected terms

How protection works

Enter one term per line. Use | to group explicitly listed forms, such as CPU | CPUs. Each form is protected separately, with exact case and spelling at every occurrence. Forms are not interchangeable aliases. No stemming, case folding or inferred synonyms are used. A term does not match inside a larger letter, digit or underscore sequence.

Results locate terms in parsed original paragraphs using UTF-16 offsets and a source SHA-256. Duplicate forms, forms absent from the source, and nested expressions are reported for review. In Amber these conflicts prevent saving; the public report can be exported with conflicts clearly retained. Edit the input to resolve them.

Automatic candidates are conservative rule suggestions: multiword capitalized names and acronyms, capped at the first 100 in spelling order. They may miss a person or technical term, or include an ordinary phrase. Add only candidates you have checked; no candidate is automatically locked. This is a deterministic extraction aid, not a linguistic entity recognizer or a model judgement. Method amber-term-locks/1.0, updated October 10, 2026.

Use the result

Download the full report with positions, candidates and conflicts. Editing a term invalidates the previous result, so check again before exporting. Public input stays on this page and is not saved to an account; download before refreshing. Preview needs no login or AI call.

Amber stores confirmed lists per account and book. New preparation snapshots freeze the list; existing accepted versions stay unchanged. Generation and review receive the same list, and exact occurrence counts are checked before acceptance. Locking is an editing constraint, not evidence that you know or do not know a term. Count preservation alone is not a guarantee of semantic fidelity.

API for agents and developers

POST application/json to /api/tools/term-locks. Required field: text. Optional locks: line-separated terms with | forms, or an array of objects containing term and variants. All other fields are rejected. The response uses schema term-locks/1 and includes method, source, locks with form occurrences, conflicts, candidates and candidateLimit.

{"text":"Ada Lovelace used CPU systems and CPUs.","locks":[{"term":"CPU","variants":["CPUs"]}]}

Complete reproducible request and result. Limits: 300,000 UTF-16 characters; 100 terms, 8 variants each, 120 characters per form, 20,000 returned locations, 1,800,000 request bytes. HTTP 400: fix input; 413: split input; 415: send JSON; 500: retry the same request. Results are deterministic, no-store and noindex. No server persistence or model quota is used.

For a rewrite, consume only the explicitly chosen locks. Preserve each matching form and its occurrence count; keep candidates separate. Agent suggestions need the same review as human suggestions. Text analysis and export produce no learning evidence.

Check a rewrite with fidelity checking or vocabulary comparison.

Candidate preview

What the results mean

Outside reference means a spelling does not match NGSL 1.2 or your custom list. It does not mean the word is difficult for you. Reported difficulty comes from an explicit negative record in the exact original context; imported records never become tested sense evidence. Opposing records remain conflicts. Other uses stay unconfirmed, including spelling-only records, lookup, assisted answers and self-reported knowledge. A word’s other uses are not inferred.

Protected forms exclude overlapping word occurrences before selection. Matching is literal and case-sensitive with Unicode letter, digit and underscore boundaries. Duplicate or nested forms protect an occurrence once; absent forms protect nothing. Review declarations with the term protection tool. Candidates are suggestions for contextual review, not a command to replace all words. Preserve facts, essential terminology and the author’s meaning.

Each item represents one occurrence, not a distinct word or word family. Counts for state and reference gaps overlap. The default workspace view shows reference gaps. Use Show all candidates to include other occurrences. Each row shows the original context; Locate highlights its exact position. Results include parsed paragraph indexes and UTF-16 offsets; they do not point into raw markup. Long sentences use a bounded exact excerpt. Exact matching is conservative and does not perform word-sense disambiguation.

Use and export

Download the complete JSON report, including filtered-out rows. Editing keeps your inputs but discards the old result. No account, model call or quota is required. Public text and responses are not persisted or saved to an account; download before refreshing. Tool use does not create learning evidence.

Amber uses the same analyzer with its account-owned records and confirmed locks. Only native, unassisted responses in the exact applicable context can produce evidenced difficulty or exclude a correct use. New generation, review and repair share a frozen candidate policy. Existing versions stay unchanged.

The reference matcher uses NGSL 1.2, Browne, Culligan and Phillips (CC BY-SA 4.0), or exact normalized custom spellings. It inherits the coverage calculator counting rules. Method updated October 10, 2026. This is a deterministic locator, not a calibrated difficulty test or a rewrite service.

API for agents and developers

POST application/json to /api/tools/simplification-candidates. Required: text. Optional: list ({kind:"ngsl"} or {kind:"custom",text:"word lines"}), previous (word lines, CSV or vocabulary record array), locks (term lines with | forms, or objects with term and variants). Other fields, including trusted evidence, are rejected. Only submit records the person provided; Agent execution supplies no evidence of knowledge.

{"text":"The otter rested by the river bank.","locks":"river bank"}

Response schema simplification-candidates/1, method amber-simplification-candidates/1.0: source, reference, locks, counts and items. Each item contains id, word, exact context, contextStart, occurrence, referenceGap, state and original records. States: difficult (native account responses only), reported, conflict, unconfirmed. counts.known is the count excluded by matched native correct responses, not a mastery score. Public requests have no native evidence. Complete reproducible request and response.

Limits: 300,000 UTF-16 text characters; 20,000 candidate positions; 10,000 records; 600,000 characters in string records; 100,000 custom-list characters; 100 terms, 8 variants each, 120 characters per form; 1,800,000 total request bytes. HTTP 400: correct input; 413: split input; 415: send JSON; 500: retry the same request. Responses are deterministic, no-store and noindex. No partial candidate list is silently returned.

Learning words

How selection works

Items are normalized spellings, not word families or shared meanings. Each original occurrence keeps its context and evidence. Suggestions consider explicit negative records and gaps in the chosen reference list. Missing evidence and reference gaps do not mean a reader does not know a word.

Explicit retain choices come first, followed by original repeat count, number of negative contexts, a single unambiguous NGSL frequency rank, then alphabetical order. No recent-reading or mastery score is inferred. Search can reveal other original spellings for manual selection. Selecting a spelling keeps all its eligible occurrences together.

Three limits apply: distinct items, occurrence count and the ratio of retained tokens in each original paragraph. Defaults are 5 items, 20 occurrences and 20% per paragraph; these editable starting values are not a scientific learning prescription. Zero is valid. An item that cannot fit is skipped, rather than partially retained. These original-text editing limits are separate from Amber’s existing limits on new assessed targets and rewritten-text occupancy.

Exact protected occurrences and native correct contexts are excluded first. Protected terms always win; explicit replace removes a spelling from the learning set, then retain requests and automatic suggestions compete within the budget. “Replace” means available for simplification, not mandatory deletion. Conflict rows identify excluded occurrences or a budget failure. Uncheck, reset or adjust the budget to resolve them. Choosing words creates no learning evidence or quiz.

The workspace shows the first 80 matching rows; search and JSON export cover the full result. Requests use shared deterministic code and do not save your text, account data or result. Export before refreshing. In Amber, saving uses the current account and book, and only a new generation snapshot consumes that choice. Existing reading versions remain unchanged.

API for agents and developers

POST application/json to /api/tools/learning-selection. Required: text. Optional: budget (maxItems integer 0–50, maxOccurrences integer 0–20,000, maxParagraphRatio number 0–1), choices (unique normalized word and action retain or replace), list (NGSL or custom spelling list), previous (word lines, CSV or vocabulary-record array), locks (protected forms). Unrecognized fields and forged trusted evidence are rejected. Choices are editing intentions, not assertions of knowledge.

{"text":"The otter rested. The otter returned.","budget":{"maxItems":2,"maxOccurrences":5,"maxParagraphRatio":0.5},"choices":[]}

Schema learning-selection/1, method amber-learning-selection/1.0. Response: source (fingerprint, original paragraphs and UTF-16 positions), reference, budget, choices, counts, per-paragraph density and items with decision, reason, conflicts and original evidence. Reproducible request and complete response.

Limits: 300,000 UTF-16 text characters, 20,000 candidate occurrences, 2,000 unique choices, 10,000 records (600,000 characters if serialized), 100,000 custom-list characters, 100 locks with 8 variants each; request body 1,800,000 bytes. HTTP 400: correct input; 413: split input; 415: send JSON; 500: retry. No partial result is silently returned. Responses are no-store and noindex. Updated October 10, 2026.

Locate candidates · Protect terms · Check coverage

Unread updates

Method and limits

Amber compares spelling-list membership in the original text, then preserves your chosen prefix and updates only affected paragraphs. Reference-list membership is not evidence that you know a word. Original anchors and the SHA-256 fingerprint must match; paragraphs are never joined by ordinal alone. Imported reports are user-provided data: their earlier quality checks are not reverified.

The shared method is amber-unread-update/1.0. Amber’s personal reading path uses changes to contextual vocabulary records; this public tool uses reference spellings. Both use the same anchor validation, impact planning and preserved-version merge. New text goes through the English simplifier’s controls and separate fidelity review. Protected terms and retained-word budgets carry forward. Unresolved checks leave the old result available.

Use reports exported by the simplifier or this tool, up to 800 KB in the page (900,000 request bytes), containing up to 18,000 UTF-16 source characters. The original interval containing the affected paragraphs is limited to 6,000 characters per attempt. New reference lists allow 100,000 characters. Planning needs no account or model call. Generation requires sign-in, allows five requests per minute and reserves 2 AI units per attempt; failed or timed-out attempts can consume units. No automatic retry or background public job. Inputs and results are not stored by this tool or indexed. Export both versions before refreshing.

API for agents and developers

POST application/json to /api/tools/unread-update with action plan (default) or generate, previous (the exported report object), list (NGSL or custom spellings) and preserveBefore (a zero-based paragraph count, including 0). previous must contain request.text and an accepted result with its original source fingerprint, controls and complete paragraph anchors.

{
  "action": "plan",
  "previous": "<complete exported report object>",
  "list": {
    "kind": "custom",
    "text": "the a garden city"
  },
  "preserveBefore": 2
}

Plans return unread-update-plan/1 with changed records, affected original paragraphs, preserved boundary and selected anchors. No affected paragraphs returns a plan without charging. Accepted generation returns unread-update/1 with complete merged text, per-paragraph status, impact, checks and execution usage. Export the next input as {request:{text:originalText},result:response}. HTTP 422 returns unread-update-candidate/1 without accepted merged text. Earlier passages are preserved exactly as parsed visible text, not as source-file bytes.

400 correct input or anchors; 401 sign in; 413 reduce size; 415 send JSON; 422 inspect candidate checks; 429 wait or inspect allowance; 503 retain inputs and retry deliberately. Responses use no-store/noindex. Unknown request fields are rejected. Real-model example. Updated October 10, 2026.