Model card

README.md

@@ -1,201 +1,100 @@
 ---
+license: other
+license_name: lfm1.0
+license_link: LICENSE
+language:
+  - en
+pipeline_tag: text-generation
 library_name: transformers
+base_model: LiquidAI/LFM2-1.2B-Extract
 tags:
-- trl
-- sft
+  - liquid
+  - lfm2
+  - edge
+  - extraction
+  - spelling-creator
 ---
 
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
-
-
-
-## Model Details
-
-### Model Description
-
-<!-- Provide a longer summary of what this model is. -->
-
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
-
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
-
-### Model Sources [optional]
-
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
-
-## Uses
-
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
-### Direct Use
-
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
-
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
-
-### Out-of-Scope Use
-
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
-
-## Bias, Risks, and Limitations
-
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
-
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
-
-## Training Details
-
-### Training Data
-
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
-
-### Training Procedure
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
-
-## Evaluation
-
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
-
-#### Software
-
-[More Information Needed]
-
-## Citation [optional]
-
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
-
-**BibTeX:**
-
-[More Information Needed]
-
-**APA:**
-
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
-
-## Model Card Authors [optional]
-
-[More Information Needed]
-
-## Model Card Contact
-
-[More Information Needed]
+# LFM2-1.2B-Extract, fine-tuned for Spelling Creator lesson documents
+
+The merged weights (bf16, safetensors). For the browser or Node, use the ONNX
+export at
+[playforgecoding/LFM2-1.2B-Extract-lesson-ONNX](https://huggingface.co/playforgecoding/LFM2-1.2B-Extract-lesson-ONNX).
+
+## What it does
+
+Turns one section of a spelling lesson document, as a person might type it up
+or as the app's own Word export reads back as plain text, into the lesson's
+JSON: the passage paragraphs copied word for word, the spelling words, and
+every question with its printed answers and working-out. It is a fine-tune of
+[LiquidAI/LFM2-1.2B-Extract](https://huggingface.co/LiquidAI/LFM2-1.2B-Extract)
+for [Spelling Creator](https://github.com/Spelling-Creator/spelling-creator), a
+lesson builder for Spelling to Communicate (S2C), where lessons are read aloud
+to nonspeaking spellers.
+
+The stock Extract model handled this badly: it split paragraphs into
+sentences, invented answers for open questions, and often abandoned the
+schema. This fine-tune copies rather than invents.
+
+## Training
+
+LoRA (rank 16, learning rate 2e-4, 3 epochs, 4096-token context) on 412
+examples: the 13 published lessons on the Spelling Creator hub, each rendered
+in 7 document layouts (the app's Word export read as raw text, and six
+typed-up styles) and cut into sections, paired with the section's lesson JSON.
+84 sections from the two newest lessons were held out. The data generator and
+the training notebook are in the Spelling Creator repo under
+`packages/core/scripts/extract-eval/`.
+
+## Results
+
+On a sample of 20 held-out sections spread across both held-out lessons and
+all seven layouts:
+
+| metric                              | value |
+| ----------------------------------- | ----: |
+| sections parsed as JSON             |   95% |
+| spelling words exact                |   85% |
+| question prompts found              |   95% |
+| answers exact                       |   98% |
+| answers invented for open questions |     1 |
+
+For comparison, the stock model's answers were right about half the time on a
+tidy typed document and a quarter of the time on the Word export.
+
+Question types are not reliable from this or any small model; Spelling Creator
+derives the type from the answers and the wording instead. The app's rule-based
+parser still beats this model on every regular layout, so the model is for
+documents the parser cannot read. The full write-up is at
+[spellingcreator.org/docs/monorepo/document-import-experiment](https://spellingcreator.org/docs/monorepo/document-import-experiment).
+
+## Prompt
+
+The system prompt is `Return data as a JSON object with the following schema:`
+followed by the JSON Schema of a section (`name`, `paragraphs`,
+`spellingWords`, and `questions`, each with `prompt`, `type`, `answers` and
+`steps`), and the user turn is the section's text. Greedy decoding.
+
+## Use
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+repo = "playforgecoding/LFM2-1.2B-Extract-lesson"
+tok = AutoTokenizer.from_pretrained(repo)
+model = AutoModelForCausalLM.from_pretrained(repo, dtype="bfloat16", device_map="auto")
+
+messages = [
+    {"role": "system", "content": "Return data as a JSON object with the following schema:\n" + schema},
+    {"role": "user", "content": section_text},
+]
+text = tok.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
+ids = tok(text, return_tensors="pt", add_special_tokens=False).input_ids.to(model.device)
+out = model.generate(ids, max_new_tokens=1500, do_sample=False)
+print(tok.decode(out[0][ids.shape[1]:], skip_special_tokens=True))
+```
+
+## Licence
+
+Derived from LFM2-1.2B-Extract and released under the same LFM Open License
+v1.0 (see LICENSE).