Morphological Evaluation Engine Specification (Token-Level)¶

1) Princípio¶

Single Linguistic Source of Truth: toda avaliação parte dos dados linguísticos oficiais, sem heurísticas soltas fora do banco:

vocabulary (lemma/cabeça lexical)
word_forms (realizações morfológicas)
sentence_tokens (slot, ordem, papel contextual)

A frase de referência é sempre decomposta em tokens avaliáveis alinhados ao template/token graph de sentence_tokens.

2) Escopos de avaliação (camadas)¶

A engine deve produzir diagnóstico em 3 camadas, na ordem abaixo.

2.1 Lexical Layer¶

Valida se o token observado existe no banco e se aponta para o lemma/form esperado.

Regras: 1. Resolver token observado para candidato(s) em word_forms.form e/ou vocabulary.lemma. 2. Se não houver candidato válido: wrong_lemma ou extra (dependendo do alinhamento). 3. Se houver candidato, prosseguir para camada morfológica.

Exemplos: - Esperado: went (lemma go) | Observado: goed → wrong_form (lexicalmente próximo, mas forma inválida). - Esperado: book (noun) | Observado: notebook → wrong_lemma.

2.2 Morphology Layer¶

Valida concordância de features entre token esperado e observado.

Features mínimas (dependem de POS): - Verbos: tense, aspect, mood, person, number, voice - Substantivos: number, countability, gender (se aplicável) - Adjetivos: degree - Pronomes/determinantes: person, number, case, definiteness

Status típicos: - wrong_form - wrong_morphology - correct

Exemplo: - Esperado: she goes | Observado: she go → wrong_morphology (3rd person singular).

2.3 Syntax/Ordering Layer¶

Valida ordem e função sintática no template da sentença.

Base de checagem: - índice/slot de sentence_tokens - dependências (dep_role) e referência de cabeça (head_token_index) quando disponíveis - constraints de estrutura da sentença (sentence_structure)

Status típicos: - wrong_order - missing - extra

Exemplo: - Esperado: a red car | Observado: a car red → wrong_order.

3) Tipos de entrada (modalidades)¶

Todas as modalidades convergem para o mesmo formato observed_tokens[].

3.1 Typing¶

Entrada livre em texto.
Pipeline: normalize → tokenize → align.

3.2 Drag-and-drop¶

Tokens já segmentados por UI.
Pipeline: apenas normalize leve (casefold/pontuação) → align.

3.3 Speaking (ASR)¶

ASR produz hipótese textual + confidence por token (se disponível).
Pipeline: normalize ASR (contrações/ruído/fillers) → tokenize → align.
observed.meta.asr_confidence pode reduzir penalidade em borderline ambiguity.

4) Normalização e matching¶

4.1 Tokenization rules¶

Separar pontuação terminal (. , ! ? ; :) em tokens não-lexicais.
Preservar contrações como unidade primária (don't, I'm, won't) com opção de expansão lógica para matching.
Tratar clíticos conforme idioma; para EN, foco em contrações auxiliares/pronominais.
Hífens: manter composto quando cadastrado, senão dividir com fallback.

4.2 Normalização¶

Casefolding padrão (lowercase para matching, mantendo surface original para feedback).
Unicode normalize (NFKC).
Optional lemmatization para heurística de sugestão, sem sobrescrever truth do banco.
OOV (out of vocabulary): marcar ambiguous/wrong_lemma com sugestão de nearest candidates.

4.3 Ambiguidade POS¶

Exemplo: book (noun/verb).

Estratégia de desambiguação: 1. Contexto local (tokens vizinhos + slot esperado). 2. Restrição do template em sentence_tokens. 3. Empate: retornar ambiguous com candidatos e UI de fallback.

5) Evaluation Result Contract (JSON)¶

Versão inicial: 1.0.

{
  "version": "1.0",
  "sentence_id": "uuid",
  "expected": [
    {
      "index": 0,
      "token": "she",
      "word_id": "uuid",
      "lemma": "she",
      "form": "she",
      "pos": "pronoun",
      "features": { "person": 3, "number": "singular" },
      "slot": "subject"
    }
  ],
  "observed": [
    {
      "index": 0,
      "surface": "she",
      "normalized": "she",
      "source": "typing|dragdrop|speaking"
    }
  ],
  "token_feedback": [
    {
      "index": 3,
      "status": "correct|wrong_lemma|wrong_form|wrong_morphology|wrong_order|missing|extra|ambiguous",
      "expected": {
        "word_id": "uuid",
        "lemma": "go",
        "form": "goes",
        "features": { "tense": "present", "person": 3, "number": "singular" },
        "pos": "verb"
      },
      "observed": {
        "surface": "go",
        "match": {
          "word_id": "uuid",
          "lemma": "go",
          "form": "go",
          "confidence": 0.92
        }
      },
      "explain": {
        "short": "Use a forma de 3ª pessoa no presente.",
        "long": "Com sujeito 'she/he/it', o verbo no simple present recebe -s/-es.",
        "pt_br": "Com sujeito da 3ª pessoa singular, use 'goes'.",
        "en": "With third person singular subjects, use 'goes'."
      }
    }
  ],
  "summary": {
    "score": 86,
    "lexical_score": 90,
    "morphology_score": 80,
    "syntax_score": 85,
    "next_steps": ["Review Simple Present (3rd person -s)", "Practice subject-verb agreement"]
  }
}

6) Políticas de pontuação¶

Distribuição recomendada v1.0: - Lexical: 40 - Morphology: 40 - Syntax/Ordering: 20

Justificativa: - Prioriza seleção da unidade lexical correta + forma gramatical correta. - Ordem sintática é crítica, porém com menor peso em estágios iniciais de produção.

Regras: - missing: penalidade forte por token obrigatório ausente. - extra: penalidade moderada por ruído. - ambiguous: penalidade leve se candidato top-1 conflita com slot esperado. - Múltiplas respostas corretas: aceitar se estiver em whitelist de equivalência (synonyms/alt forms/contractions permitidas por template).

7) Feedback pedagógico¶

Cada item em token_feedback deve ter: - explain.short: 1 frase acionável - explain.long: explicação didática curta - explain.pt_br e explain.en

Mapeamento pedagógico: - Relacionar erro com grammar_concepts e word_grammar. - Ex.: erro wrong_morphology em verbo presente → conceito “3rd person -s”.

Visual/UI: - Colorização por POS via pos_colors. - Exibir “erro por função” (subject, auxiliary, main verb, object etc.) conforme slot.

8) Casos especiais (obrigatório)¶

Irregular verbs: go → went, eat → ate.
Contrações: don't, I'm, won't com equivalência lógica para forma expandida quando permitido.
Artigos e contáveis: a/an/the/ø com validação de countability e contexto fonético mínimo para a/an.
Ordem adjetivo-substantivo: em EN, adjetivo pré-nominal padrão.
Preposições comuns: on/in/at com mensagens de uso contextual.
Negation auxiliaries: do/does/did + not e formas contraídas.
Phrasal verbs: modelar como unidade semântica (look up) via semantic_relations/tags e avaliar tanto coesão lexical quanto ordem permitida.

9) Roadmap versionado¶

v1.0¶

Rule-based.
Template-guided por sentence_tokens.
Scoring por camada + feedback explicável.

v1.1¶

Enriquecer com dependency roles e head_position/head_token_index quando disponível.
Melhorar desambiguação contextual.

v2.0¶

Assistência de ML para ranking de hipóteses e hints.
Sem quebrar explicabilidade e sem substituir fonte de verdade linguística.