mixle.task.extract module

Structured extraction: distill a teacher into a compact sequence tagger for typed text fields.

Use this module when brittle regular expressions or hand-written parsers are no longer enough for semi-structured text such as invoices, support tickets, orders, or clinical notes. The student model learns to extract fields such as id, amount, or date from labeled examples and can be retrained when the source format changes. The model is token-level: tokenizer and orthographic features, then an embedding, bidirectional GRU, per-token BIO tags, and a decoder back to {field: value}. Labels can come from an LLM teacher, a rule-based teacher, or gold annotations.

distill_extractor(teacher, texts, fields) returns a callable TaskModel: model(text) -> {field: value}. It saves through the same durable artifact (vocab + tag scheme in the manifest, weights in safetensors) and loads in a fresh process. extraction_f1 scores span-level fidelity.

tokenize(text)[source]

Split text into (token, start, end) triples: runs of digits, letters, or single punctuation.

Parameters:

text (str)

Return type:

list[tuple[str, int, int]]

build_seq_tagger(vocab_size, n_tags, *, d_model=64, hidden=64, n_feats=_N_FEATS)[source]

A bidirectional-GRU sequence tagger: (token_ids, features) -> per-token tag logits.

Parameters:
class ExtractionIO(vocab, fields, *, max_len=128)[source]

Bases: object

text -> {field: value}: tokenize, tag (BIO), decode spans back to substrings of the original text.

Parameters:
kind = 'extraction'
predict(module, text)[source]
Parameters:
Return type:

dict[str, str]

predict_batch(module, texts)[source]
Parameters:
Return type:

list[dict[str, str]]

predict_with_confidence(module, texts)[source]

Extract each record and a confidence in [0, 1]: the min per-token tag probability over tagged tokens.

A low confidence or a missing field is an explicit signal that the format may be unfamiliar and should be escalated. Returns 0.0 when nothing was tagged.

Parameters:
Return type:

list[tuple[dict[str, str], float]]

to_spec()[source]
Return type:

dict[str, Any]

classmethod from_spec(spec)[source]
Parameters:

spec (dict[str, Any])

Return type:

ExtractionIO

distill_extractor(teacher, texts, fields, *, max_vocab=5000, d_model=64, hidden=64, epochs=60, lr=5e-3, max_len=128, seed=0, device='cpu', task='')[source]

Distill a teacher’s extractions into a tiny sequence tagger; return model(text) -> {field: value}.

Parameters:
Return type:

TaskModel

extraction_f1(model, gold, texts)[source]

Micro-averaged field-level F1: a field counts as correct when the extracted value exactly matches gold.

Parameters:
Return type:

float