Clarify intended use and verified JSON limitations

Add a plain-language scope section before usage examples and detailed limitations beside evaluation results. Synchronize the run guide, source archive and checksums. Model weights, tokenizer and native inference algorithm are unchanged.

PACKAGING_VERIFICATION.json

@@ -5,7 +5,7 @@
   "weight_file": "model.safetensors",
   "weight_bytes": 351242342,
   "weight_sha256": "781597baeb9b51d535fc27cd6f941dbc202e01d62c8d963587a3f3d565128560",
-  "native_bundle_sha256": "c54fd408f6b7ec0c6e80377ee8b6eeffe3bfbf76389e56fdad4c78f54828e2d1",
+  "native_bundle_sha256": "c5bb8eaa1dd4e3bbfb094192c3b91203f20aba776eb73dc29fc47831fa043087",
   "runtime": "stock MLX 0.32.3; Apple Silicon; Python 3.11",
   "requests": 60,
   "raw_runtime_matches": 60,
@@ -14,5 +14,10 @@
   "root_runner_verification": "source archive hash and snapshot verified; live CLI receipt saved separately",
   "json_assembly": false,
   "output_repair": false,
-  "tokenizer_root_matches_bundle": true
+  "tokenizer_root_matches_bundle": true,
+  "documentation_update": {
+    "date": "2026-10-20",
+    "scope": "Intended use and limitations; updated documentation archive",
+    "model_tokenizer_and_native_inference_algorithm_unchanged": true
+  }
 }

README.md

@@ -33,6 +33,16 @@ datasets:
 
 The model was fine-tuned for grounded question answering, exact and focused field extraction, and direct JSON generation. Its final joint JSON extraction stage combines original training replay, multiple-value examples and authored prose. Weights are provided as `model.safetensors`. The pretrained ancestor is [OpenSML-Base-175M](https://huggingface.co/OpenSML/OpenSML-Base-175M).
 
+## Intended use and limitations
+
+This is a research model for **extracting information that is explicitly stated in short English text** and placing it into one flat JSON object. Supply a schema with clear field descriptions. The verified runner accepts 1–8 required fields containing strings, nullable strings or arrays of strings. Dates and numbers are copied as text rather than normalized or converted.
+
+**Expect extraction mistakes.** The model can shorten a name or title, miss or merge list items, confuse who or what a value belongs to, or supply a value when the right answer is empty. Unfamiliar field names and domains need their own testing. There is no established number of entities it will always extract correctly; only 3 of the 6 observed three/four/five-item probes were completely correct.
+
+**Outside the verified scope:** nested objects, arrays of objects, numeric or Boolean outputs, optional-property logic, enums, references and advanced schema constraints. General chat, multilingual input and long-document extraction are also unverified. This describes the released runner's tested contract, not a claim that the weights can never produce these formats.
+
+**Check both structure and meaning.** Parse the output, validate it against the schema, and check the values against the source. The reported 100% schema validity applies to the observed 1,444-request evaluation; complete correctness there was 88.02%. It is not a promise for new inputs. The instruction, source, schema and generated answer must share the 2,048-token context; the supplied runner allows up to 256 output tokens.
+
 ## Run locally
 
 ```bash

RUN_GUIDE.md

@@ -6,6 +6,16 @@ The runnable package includes model.safetensors, tokenizer/config, native MLX
 model source, a source archive, 60 examples, results and verification records.
 Verified platform: Apple Silicon macOS, Python 3.11, stock MLX 0.32.3.
 
+## Intended use and limitations
+
+This is a research model for **extracting information that is explicitly stated in short English text** and placing it into one flat JSON object. Supply a schema with clear field descriptions. The verified runner accepts 1–8 required fields containing strings, nullable strings or arrays of strings. Dates and numbers are copied as text rather than normalized or converted.
+
+**Expect extraction mistakes.** The model can shorten a name or title, miss or merge list items, confuse who or what a value belongs to, or supply a value when the right answer is empty. Unfamiliar field names and domains need their own testing. There is no established number of entities it will always extract correctly; only 3 of the 6 observed three/four/five-item probes were completely correct.
+
+**Outside the verified scope:** nested objects, arrays of objects, numeric or Boolean outputs, optional-property logic, enums, references and advanced schema constraints. General chat, multilingual input and long-document extraction are also unverified. This describes the released runner's tested contract, not a claim that the weights can never produce these formats.
+
+**Check both structure and meaning.** Parse the output, validate it against the schema, and check the values against the source. The reported 100% schema validity applies to the observed 1,444-request evaluation; complete correctness there was 88.02%. It is not a promise for new inputs. The instruction, source, schema and generated answer must share the 2,048-token context; the supplied runner allows up to 256 output tokens.
+
 ```bash
 python3 -m venv .venv
 source .venv/bin/activate

SHA256SUMS

@@ -3,19 +3,19 @@
 9a4fb5f559d82ed0120a57139eb1e1c616bfdb18c39cca7b1e9bcab24ef968bc  INFERENCE_VERIFICATION.json
 74a074f90bd5e7a26d5f6cd5757ddc1fbfcc72e259e0b23a210fa48d91b35fdb  JSONLITE_RESULTS.json
 c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4  LICENSE
-f53194e53a2af5ec857337e8213397ea4f81a7e02d2dbcf0384a00cf1cf7f76f  PACKAGING_VERIFICATION.json
-e4904f5bfd95f87e67a8de6cb0874c397babef23c44a16ed53ec73e5480a5407  README.md
-5ee8f11f0e87becf1a29c44e2b0f3dacc2c779712b635558be57dd7ef44455d3  RUN_GUIDE.md
+7e092bbf3d2e770493e1e31cee471e04f59f2b26355d4ded86565e3e39bc8ade  PACKAGING_VERIFICATION.json
+5e828c09db086de986dad8eafebebeb6ce21185934a6e8e6236cab049741ff2d  README.md
+e54ba0ed507dd5da8a6fe54cd420f91f0db1bed31e75fc8ff5934fe883f638bc  RUN_GUIDE.md
 c6191baf937bce61f1b747acfbcb975a17eef6e8a598682a751a1031d1cfee23  SOURCE_NOTICE.md
-6088771ab13fa1080c0ca0f31649deb9f417597d7c2055b0f388e86f41f2c415  TECHNICAL_REPORT.md
+7bb05614604bf206027f8897409959dae8fbd67e417addc63da55d8f3eac3fb8  TECHNICAL_REPORT.md
 e4e44da050abbd930748ec91731ddf1be16be83a4aa59bd8c4fc63478b384a03  THIRD_PARTY_NOTICES.md
 663087d32872824f7f2fec425ad4054f308913c43da7c3f83521c7011967fdbe  checkpoint_metadata.json
 a365a7697b463bacc6e44e26d11a1e62d43d96b5d52c70c2e9df8d4513f86537  checkpoint_provenance.json
 ecec6f191822d16a3da0b571fa129f5016e1243ca7d567de476a9d0e8ad66646  complete-request-exact.svg
 981e02e7777980705770cacf19f16d76ea74e85e7edb018f875ddb4766afe19d  config.json
-8c0f0f5a91079699d090986d5d241385309b10579f34f271c02f05dca6ddd4bf  inference.py
+6c8e504441f93b0d1ed428bc0cd7973788b7be8b7b7983d47ad20ce8b7a1ddeb  inference.py
 781597baeb9b51d535fc27cd6f941dbc202e01d62c8d963587a3f3d565128560  model.safetensors
-c54fd408f6b7ec0c6e80377ee8b6eeffe3bfbf76389e56fdad4c78f54828e2d1  native_bundle.zip
+c5bb8eaa1dd4e3bbfb094192c3b91203f20aba776eb73dc29fc47831fa043087  native_bundle.zip
 641fe860d6fd24547fe4d15bd852190f00ddec31bd74eb7ca9eeae74031c2f0c  pretraining-training-loss.png
 c7b1a3c0efb09ef3b5416a24072e48b25e2cc1f122fb5ed638c0f95b72594af9  requirements.txt
 e095f0413a11fa91fbb58f37d00e4c6bcda59beb89b28f6f680db1436a7e8891  tokenizer.json

TECHNICAL_REPORT.md

@@ -12,6 +12,16 @@ This is a custom native MLX architecture, not a Transformers/MLX-LM auto-loader
 
 This report supersedes the earlier fieldwise SFT-093 release. Its historical report is retained as `HISTORICAL_SFT093_REPORT.md`; those adapter-assisted scores are not current native JSON scores. No release-readiness or arbitrary-schema reliability claim is made.
 
+### Intended use in plain language
+
+This is a research model for **extracting information that is explicitly stated in short English text** and placing it into one flat JSON object. Supply a schema with clear field descriptions. The verified runner accepts 1–8 required fields containing strings, nullable strings or arrays of strings. Dates and numbers are copied as text rather than normalized or converted.
+
+**Expect extraction mistakes.** The model can shorten a name or title, miss or merge list items, confuse who or what a value belongs to, or supply a value when the right answer is empty. Unfamiliar field names and domains need their own testing. There is no established number of entities it will always extract correctly; only 3 of the 6 observed three/four/five-item probes were completely correct.
+
+**Outside the verified scope:** nested objects, arrays of objects, numeric or Boolean outputs, optional-property logic, enums, references and advanced schema constraints. General chat, multilingual input and long-document extraction are also unverified. This describes the released runner's tested contract, not a claim that the weights can never produce these formats.
+
+**Check both structure and meaning.** Parse the output, validate it against the schema, and check the values against the source. The reported 100% schema validity applies to the observed 1,444-request evaluation; complete correctness there was 88.02%. It is not a promise for new inputs. The instruction, source, schema and generated answer must share the 2,048-token context; the supplied runner allows up to 256 output tokens.
+
 ## 2. Exact inherited lineage
 
 `Stage A → grounded QA → requested-field extraction → focused extraction → native JSON foundation → cardinality/replay extraction → joint JSON extraction SFT`
@@ -203,7 +213,7 @@ The run uses full-weight BF16 compute with FP32-master AdamW, batch 64, microbat
 
 ## 8. Prompt, schema and native inference
 
-Supply source text and a flat closed JSON Schema with 1–8 required fields. Supported properties are strings, nullable strings and arrays of strings. Every required key is returned; absent arrays target [] and absent nullable strings target null. Copy case/spelling and complete values; preserve source order. Nested schemas, numbers/booleans, enums and advanced constraints are outside the verified runner contract. The supplied runner rejects overlong inputs without truncation.
+Supply source text and a flat closed JSON Schema with 1–8 required fields. Supported properties are strings, nullable strings and arrays of strings. The requested behavior is to return every required key, with [] for absent arrays and null for absent nullable strings; generated answers can still be incorrect. Copy case/spelling and complete values; preserve source order. Nested schemas, numbers/booleans, enums and advanced constraints are outside the verified runner contract. The supplied runner rejects overlong inputs without truncation.
 
 The fixed instruction is followed by compact `{"source_text":...,"schema":...}` and native SFT role tokens. It issues exactly one autoregressive whole-object generation with temperature 0, repetition penalty 1 and at most 256 output tokens. No fieldwise assembly, repair, schema-constrained decoder, normalization, reference answer, frozen teacher or secondary model is used at inference. Parsing/schema checks only annotate the raw generated text afterward.
 
@@ -255,6 +265,29 @@ The 1,444 requests comprise the original canonical and schema-stress views; some
 
 ## 10. Failure audit and limitations
 
+### What the released model is intended to do
+
+The intended task is short English text extraction into a supplied, flat object schema: copy stated values into the requested fields, keep separate entities as separate string-array items, and use empty arrays or nullable strings for absent information where the schema allows it. Clear field descriptions matter. The runner accepts 1–8 required fields with strings, nullable strings or arrays of strings; dates and numeric expressions remain strings. Those input limits describe the runner contract and do not guarantee that every accepted request will be answered correctly.
+
+### What can still go wrong
+
+The model can shorten names or titles, omit or merge list members, confuse roles or field meanings, and fill a missing field with an unsupported value. Corrections, unfamiliar field names, new domains and complex associations require application-specific evaluation. No tested field count or entity count establishes a reliable extraction maximum. Optional-property logic, nesting, arrays of records, numeric/Boolean outputs, enums, references and advanced constraints are outside the released runner's verified contract. Root-level arrays or primitives, general chat, multilingual use and long-document extraction are not supported claims of this release. Unverified does not mean impossible for the weights; it means the supplied runner and release evidence do not establish dependable support.
+
+| Evidence for this released checkpoint | What it establishes | What it does not establish |
+| --- | --- | --- |
+| 1,271/1,444 complete requests correct (88.02%) | Exact whole-answer performance on the documented, previously observed SNIPS-derived panel | Equivalent accuracy on arbitrary schemas or new domains |
+| 1,444/1,444 schema-valid outputs | All outputs met the tested flat schemas in that evaluation | Correct extracted values, or universal schema compliance |
+| 49/60 complete playground requests correct (81.67%) | Performance on a separate observed diagnostic panel | A fresh blind benchmark or a general production reliability rate |
+| 3/6 complete three/four/five-item probes correct | Larger lists remain inconsistent | A guaranteed maximum number of extractable entities |
+
+These measurements use the released checkpoint identified in section 1. Local research checkpoints are separate artifacts; their broader-schema or per-family scores are not measurements of this release. The panels have prior research exposure and must not be pooled into one accuracy number.
+
+### Checks required in an application
+
+Parse the raw output, validate it against the supplied schema, then check that extracted values are supported by the source and assigned to the right fields. A valid string can still name the wrong person, omit an item or invent a value; schema validation cannot detect all such errors. The runner's `success` flag means structural validity and natural completion, not semantic correctness. The full instruction, source, schema and answer share a 2,048-token context, and the released runner allows up to 256 generated tokens. Overlong inputs are rejected rather than truncated. Validate the complete workflow on representative application data before relying on its outputs.
+
+### Additional failure-audit observations
+
 There are 173 entirely incorrect original-test requests and 24 previously correct requests become incorrect. Errors include incomplete copying, wrong roles, missing or extra values and unsupported values. All seven domain totals improve, but per-request retention is not perfect. On the six longer-list probes only three are correct. Flat schema validity is 100% on this test, not a guarantee for arbitrary prompts, schema types or novel domains. No general chat, reasoning, code, multilingual, long-document or safety readiness claim is made. The authored development panel is small and repeatedly observed.
 
 ## 11. Packaging, verification and reproduction

inference.py

@@ -12,7 +12,7 @@ import tempfile
 import zipfile
 
 ROOT = Path(__file__).resolve().parent
-BUNDLE_SHA256 = "c54fd408f6b7ec0c6e80377ee8b6eeffe3bfbf76389e56fdad4c78f54828e2d1"
+BUNDLE_SHA256 = "c5bb8eaa1dd4e3bbfb094192c3b91203f20aba776eb73dc29fc47831fa043087"
 
 def main():
     archive = ROOT / "native_bundle.zip"

native_bundle.zip

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:c54fd408f6b7ec0c6e80377ee8b6eeffe3bfbf76389e56fdad4c78f54828e2d1
-size 12831619
+oid sha256:c5bb8eaa1dd4e3bbfb094192c3b91203f20aba776eb73dc29fc47831fa043087
+size 12835333