Concepts

Targets in the examples are short forms from the SBL Greek New Testament (CC BY-SA 4.0): λόγος, θεός, ἐν ἀρχῇ. The calls are IPA strings. There is no audio in the documented examples.

Proximity

Calibrated score after the stress penalty. Unchanged by coaching and heard_as.

An exact phone match with no stress penalty is 1.0 (exactLogos). real_edits counts phones whose scoring status is incorrect, missing, or extra. It is 0 on that call and 1 when θεός is heard as s e o s.

The Python package and the Rust worker agree on these examples within 0.000005. That is the same tolerance the golden tests use.

acceptable variant (cost 0.02) is not a real edit. θεός heard as tʰ e o s has phones[0].status acceptable variant, real_edits 0, and proximity 0.988187.

A stress penalty of 0.10 is subtracted once, after the phone score, when it applies. λόγος heard as l o g ˈo s has proximity 0.9 and real_edits 0. coaching and heard_as do not change proximity. Frame GOP does not change it either. Duration is not in the score.

Scoring status and learner status

phones[].status is the alignment label. The enum is correct, acceptable, acceptable variant, incorrect, missing, extra.

coaching.sounds[].status is the learner label:

exact matches scoring status correct. acceptable_variant matches scoring status "acceptable variant" (the 0.02 taught-versus-historical pairs). close is scoring status acceptable, or an incorrect substitution whose closeness is at least 0.5, or a far substitution whose low_confidence flag is true. far is an incorrect substitution whose closeness is below 0.5 and whose confidence is not low. missing and extra match those scoring statuses.

On thetaAsS, the first sound is close with error_code dental_fricative_to_alveolar_sibilant and closeness 0.875. The scoring status of that phone is incorrect.

Feature diffs and error codes

Stable code for this phone difference. Null when status is exact. A consonant substitution names place and manner. Fricatives s, z, ʃ, and ʒ use sibilant in the code, so θ→s is dental_fricative_to_alveolar_sibilant. Voice, aspiration, and length words appear only when that feature differs. A vowel substitution names height, backness, and rounding on both sides. Missing and extra prefix the same token. Low confidence does not change the code.

Features that differ, in order: kind, place, manner, voicing, aspiration, rounding, height, backness, length. Empty when status is exact.

Feature names, in order: kind, place, manner, voicing, aspiration, rounding, height, backness, length. The first sound of thetaAsS differs in:

[
  {
    "feature": "place",
    "target": "dental",
    "heard": "alveolar"
  }
]

coaching.summary.fixes lists at most three repairs with score_gain above 0. The code on a fix is the same error_code. There is no learner sentence in the JSON.

Stress

The penalty is 0.10 once per attempt. Monosyllables, unaccented words, and words whose only accent is varia are not penalized. A primary ˈ in the IPA selects the attempt syllable (stress.method mark), including a mark on a verse. Secondary ˌ is ignored. The phone alignment drops the mark, so real_edits does not move.

stressShift puts ˈ on the second syllable of λόγος. The written accent is the first.

stress.method mark
stress.penalty 0.1
stress.match false
coaching.stress.error_code stress_shift
coaching.stress.target_letters λό
coaching.stress.detected_letters γος

With no ˈ and no audio, stress.method is unavailable and match is null (exactLogos). Audio without a mark uses an energy share and a pitch share. A gap under 0.04 abstains (match null, penalty 0). A multi-word clip that does not frame-align does not pay 0.10. match can still be false when a compared polysyllable disagrees. A single word, and a ˈ mark, still pay 0.10.

heard_as

posterior when at least one candidate received a CTC forward score from the request posteriors. distance-softmax otherwise. Both paths order candidates with the same softmax. Published confidence is the Platt map, not that mass.

Softmax temperature used to order candidates. The shipped value is 0.1. Published confidence is a separate Platt map of the top-1 gap, the normalized tutor cost, and a non-word indicator.

Rank order is the temperature-0.1 softmax. Published confidence is the Platt map, not that mass. Candidates sum to at most 1. other is a candidate kind. A verse puts one ranking in heard_as.words per target word. verseArche (ἐν ἀρχῇ, e n a r x i) has proximity 1.0, real_edits 0, and 2 word rankings.

different_word reports the closest one-edit neighbor. It does not change proximity. The examples send different_word: false, so checked is false.

Versioning

/v1 plus api: tutor-v1 is the score contract. Adding a field is not a break. Removing or renaming one would be /v2. Error bodies changed from plain text to application/problem+json without a new path; detail still carries the old sentence. See Errors.