talk-tag
talk-tag is a tool for automatic morphosyntactic error annotation in transcribed speech.
It adds inline CHAT-compatible error tags to utterances, helping researchers and annotators pre-annotate transcripts for review. The current system follows a subset of the CHAT word-level error coding scheme described in Tools for Analyzing Talk, Part 1: The CHAT Transcription Format (Chapter 18.1).
What It Annotates
TalkTag currently annotates:
- morphological errors:
[* m:*] - substitution errors (subset of semantic errors in the manual):
[* s:r:*]and[* s:r:gc:*]
It also inserts target reconstructions inline, following CHAT conventions:
[: target]when the produced form is a non-word[= target]when the produced form is a real word but the intended target should still be recorded
For the current package behavior:
- non-word reconstructions such as
[: went]are preserved - real-word reconstructions are converted to
[= target] [= target]output is hidden by default and included only when--show-targetis set
This is intentional: according to the CHAT manual, [= target] is not required
for analysis in the way [: target] is, so TalkTag keeps it optional and
defaults to the cleaner output.
The underlying model was trained before the current manual standardized the
real-word target notation as [= target]. Because of that, raw generations may
still reflect the older [:: target] convention. TalkTag rewrites those cases
to [= target] in post-processing before saving output.
The CHAT manual distinguishes these because [: target] lets MOR use "the real
word target" for parsing, whereas the real-word replacement notation lets MOR
use "the actual word produced" while still preserving the target for other CLAN
analyses. See the CHAT
manual and the CLAN
manual.
Quick Examples
Yesterday I walk [= walked] [* m:0ed] to school .
Yesterday I goed [: went] [* m:=ed] to school .
Yesterday me [= I] [* s:r:gc:pro] walked to school .
Yesterday I went in [= to] [* s:r:prep] school .
See the CHAT Transcription Guidelines.
Annotation Scheme
Morphological Labels
CHAT error tags are compositional: each part of a tag indicates, from general to fine-grained the error and its underline process.
For example, in [* m:0ed], m marks a morphosyntactic error, 0 marks a missing form, and ed marks past morpheme.
| Level 1 | Meaning |
|---|---|
* m: |
morphosyntactic error |
| Level 2 | Meaning |
0 |
missing regular form |
= |
over-regularisation |
+ |
superfluous marking |
++ |
double marking |
base: |
base for irregular form |
irr: |
irregular for base form |
sub: |
past/perfective substitution |
allo |
allomorphic errors |
vsg: |
irregular verb 3SG |
vun: |
irregular verb unmarked |
| Level 3 | Meaning |
mor |
target morpheme |
a |
agreement error |
i |
irregular target |
Common level-3 morphemes include:
ed, en, 3s, ing, s, 's, er, and est.
In practice, common outputs include:
[* m:0ed]for missing past tense[* m:=ed]for over-regularised past forms[* m:03s:a]for missing 3SG agreement marking
Substitution Labels
| Level 1 | Meaning |
|---|---|
* s: |
substitution error |
| Level 2 | Meaning |
r: |
related lexical substitution |
r:gc: |
related grammatical substitution |
| Level 3 | Meaning |
POS |
target part of speech |
Supported part-of-speech (POS) in the paper include:
pro(pronoun), det (determiner), and prep (preposition).
In practice, common outputs include:
-
[* s:r:gc:pro]for pronoun substitutions: possessive for nominative:her/his/theirforshe/he/they) -
[* s:r:prep]for preposition substitutions: e.g., *he is marriedwith(instead ofto) Maria
Scope Notes
- The current runtime follows a narrow prototype scope and does not cover the full CHAT error inventory.
- The paper's model was developed on children's narrative data from the ENNI corpus under low-resource conditions.
- The most realistic use case is assisted annotation and review of plausible error candidates.
Install
Python requirement: >=3.10.
pip install "talk-tag[runtime]"
Runtime extras include torch, transformers, peft, and bitsandbytes.
Runtime support
The current fixed deployment is based on a bnb-4bit Hugging Face model. In
practice, this means:
- CUDA is the preferred accelerated runtime
- CPU is supported as a fallback
- Apple MPS is not supported for this deployment
First-run workflow
- Check environment:
talk-tag doctor
- Pull/warm model assets:
talk-tag model pull --device auto
On Apple Silicon, --device auto will fall back to CPU instead of MPS.
- Run annotation:
talk-tag annotate \
--input-dir ./input \
--output-dir ./output \
--target-speaker "*CHI" \
--device auto
From a repository checkout, try TalkTag with the bundled synthetic transcript instead of private data:
talk-tag annotate \
--input-path ./examples/sample.cha \
--output-dir ./examples/sample_out \
--target-speaker "*CHI" \
--device auto \
--limit 2 \
--show-target
Single-file .cha example:
talk-tag annotate \
--input-path ./input/sample.cha \
--output-dir ./output \
--target-speaker "*CHI" \
--device auto
Show optional real-word reconstructions in the output:
talk-tag annotate \
--input-path ./input/sample.cha \
--output-dir ./output \
--target-speaker "*CHI" \
--show-target \
--device auto
--show-target only affects optional real-word reconstructions such as
[= goes]. Non-word reconstructions such as [: went], which are needed for
analysis, are preserved either way.
For quick debugging, you can also print only the target utterances that changed:
talk-tag annotate \
--input-path ./input/sample.cha \
--output-dir ./output \
--target-speaker "*CHI" \
--limit 5 \
--print-debug-lines \
--device auto
This prints changed lines as original/annotated pairs during the run. It does not change the output file content.
If needed, you can also cap inference for quick local checks:
talk-tag annotate \
--input-path ./input/sample.cha \
--output-dir ./output \
--target-speaker "*CHI" \
--limit 20 \
--device auto
When --limit is greater than 0, TalkTag still writes the output file. It
simply stops annotation after the first N target utterances and prints a
notice that the limit is active.
Inference defaults
max_new_tokens = 128max_seq_length = 512max_context_chars = 1200limit = 0(0means no cap; use it as a debug/testing limit on target utterances)- greedy decoding (
do_sample = false)
The CLI currently exposes:
--limitto cap the number of target utterances processed in one run for testing/debugging; output files are still written--print-debug-linesto print only changed target utterances during a run for quick debugging
Supported runtime inputs
.cha.jsonl(requires--speaker-fieldand--text-field)
The annotate command accepts either:
--input-dirfor folder annotation--input-pathfor a single.chaor.jsonlfile
Other previously supported formats (.txt, .csv, .json, .xlsx) are rejected in adapter-only deployment mode.
Colab quickstart
See examples/colab_quickstart.ipynb for a minimal setup flow.
Metadata
Release files for talk-tag 0.5.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| talk_tag-0.5.2.tar.gz | 38.5 kB | Without provenance | Details for talk_tag-0.5.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| talk_tag-0.5.2-py3-none-any.whl | Python 3 | none | any | Details for talk_tag-0.5.2-py3-none-any.whl |
Total release size: 72.6 kB
Release files / talk_tag-0.5.2.tar.gz
| Download URL | talk_tag-0.5.2.tar.gz |
|---|---|
| Size | 38.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
da64712ad09e14c2e0a35faa6fbc090ce38b4e7c43149ce1a0b0e3cfcd9d3bf5
|
|
BLAKE2b-256 checksum How to use checksums |
f33343d3b66b26c281b77dd76fb509775a4ab4b772c8292191c54471fa307afa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.9 {"installer":{"name":"uv","version":"0.9.9"},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / talk_tag-0.5.2-py3-none-any.whl
| Download URL | talk_tag-0.5.2-py3-none-any.whl |
|---|---|
| Size | 34.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c3e31b83040f61c72990f9ea0d240a856e727a69f294d9d673286abca0d81b21
|
|
BLAKE2b-256 checksum How to use checksums |
58b4c22168c56fea6b70cc1d726bccfa5eaf0b33f3b04200aeeee4d4d38a5df6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.9 {"installer":{"name":"uv","version":"0.9.9"},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for talk-tag 0.5.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.