Apppublic

Youngmeen/language-learning-analytics

sourceHugging Faceupdated 3mo agoView on Hugging Face

0likes

App README

Linguistic Analytics Service

FastAPI microservice computing the SPEC §7 text-based linguistic metrics on a learner's session production. Called by the Next.js app after a session ends; writes results to analytics_results in Supabase (service-role key — the only writer by design).

—POST /analyze {"session_id": "..."} — Authorization: Bearer $ANALYTICS_SERVICE_SECRET
—GET /health

Env vars: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, ANALYTICS_SERVICE_SECRET.

Metrics — version `text-1.0`

Computed on learner turns only, tokenized/parsed with spaCy small models (en_core_web_sm, ko_core_news_sm, ja_core_news_sm, zh_core_web_sm, fr_core_news_sm, de_core_news_sm). Small models are a deliberate v1 tradeoff for hosting cost; an upgrade (e.g. Stanza) bumps metrics_version so results stay comparable within a version. "Words" = alphabetic tokens, lowercased.

volume

key	definition
token_count	alphabetic tokens across learner turns
utterance_count	learner turns

lexical_diversity

key	definition	null when
ttr	types / tokens	no tokens
mattr	moving-average TTR, window 50	< 50 tokens
mtld	bidirectional MTLD, factor TTR threshold 0.72 (McCarthy & Jarvis 2010)	< 50 tokens
hdd	HD-D with sample size 42 (vocd-D analogue, McCarthy & Jarvis 2007)	< 42 tokens

lexical_sophistication (wordfreq Zipf scale, per target language)

key	definition
mean_zipf	mean Zipf frequency of tokens known to wordfreq
lowfreqratio	share of known tokens with Zipf < 4.0
advanced_ratio	share of known tokens with Zipf < 3.0 (the "academic/advanced" proxy — language-neutral; a curated academic word list exists only for English and is deferred)
unknown_ratio	share of all tokens unknown to wordfreq (typos, names) — excluded from the ratios above
bandcommon / bandmid / band_rare	known-token shares with Zipf ≥ 5 / 4–5 / < 4

syntax (dependency-parse approximations)

key	definition
mlu_words	mean words per utterance (word-based, not morpheme-based — a documented simplification, esp. for zh/ja)
meantunit_length	words / main clauses; main clauses = sentence roots + verbal conjuncts of the root
clausesperutterance	(main + subordinate clauses) / utterances
subordination_ratio	subordinate / all clauses; subordinate labels: advcl, ccomp, xcomp, acl, relcl, acl:relcl, csubj(:pass)
meanparsedepth / maxparsedepth	dependency tree depth per sentence (root = 1)

repetition

key	definition
immediaterepetitioncount	immediately repeated tokens ("the the") within an utterance
repeatedbigramratio	share of within-utterance bigram instances that are duplicates

repair (typing-mode heuristic — limited until speech mode adds timing)

key	definition
correctionmarkercount	chat-convention self-corrections (`*word`)

Development

bash

uv sync
uv pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl
uv run pytest          # metric tests are hand-computed known-input/expected-output
uv run uvicorn app.main:app --port 7860