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:
predict(module, text)[source]

Extract fields from a single text record.

Parameters:
Return type:

dict[str, str]

predict_batch(module, texts)[source]

Extract fields from a batch of text records.

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]

Serialize the extraction vocabulary, fields, and maximum sequence length.

Return type:

dict[str, Any]

classmethod from_spec(spec)[source]

Reconstruct extraction IO from an artifact spec.

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 local 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