Update README.md

README.md

@@ -114,26 +114,23 @@ at this scale reporting a single seed is measuring noise.
 
 ## Usage
 
-The model consumes **BRAID strings, not SMILES.** You must encode first. The codec is
-vendored into this repository so the snippet below runs standalone:
+The model consumes **BRAID strings, not SMILES**, so you need the codec:
+
+```bash
+pip install rdkit transformers
+pip install git+https://github.com/aakothari/braids.git
+```
 
 ```python
-import importlib.util
-from huggingface_hub import hf_hub_download
+from braids import smiles_to_braid
 from transformers import AutoTokenizer, AutoModelForSequenceClassification
 
-# load the BRAID codec shipped with this repo (requires: pip install rdkit)
-path = hf_hub_download("aakothari/BRAIDBERTa-v9", "braids_codec.py")
-spec = importlib.util.spec_from_file_location("braids_codec", path)
-braids = importlib.util.module_from_spec(spec)
-spec.loader.exec_module(braids)
-
 tok = AutoTokenizer.from_pretrained("aakothari/BRAIDBERTa-v9")
 model = AutoModelForSequenceClassification.from_pretrained(
     "aakothari/BRAIDBERTa-v9", num_labels=2
 )
 
-braid = braids.smiles_to_braid("CC(=O)Oc1ccccc1C(=O)O")   # encode SMILES -> BRAID
+braid = smiles_to_braid("CC(=O)Oc1ccccc1C(=O)O")   # -> CC>1=OOC=CC=CC=C^5C>1=OO
 inputs = tok(braid, return_tensors="pt", truncation=True, max_length=128)
 logits = model(**inputs).logits
 ```
@@ -142,10 +139,16 @@ logits = model(**inputs).logits
 > characters — it will simply produce a meaningless tokenization and a plausible-looking,
 > wrong prediction. Always encode with `smiles_to_braid` first.
 
-The full reference implementation (encoder, decoder, valence state machine, stereo handling,
-tokenizer/`Vocab` builder, and the test suites) lives at:
+**Encode in the same mode the model was pretrained in.** The codec has Kekulé (default) and
+aromatic modes, and they produce different strings for the same molecule
+(`C=CC=CC=C^5` vs `cccccc^5`). Mixing modes between pretraining and inference silently
+degrades performance.
+
+<!-- TODO: state which mode the ZINC 100k pretraining corpus used -->
 
-<!-- TODO: link the GitHub repo, or delete this line if the vendored codec is the only distribution -->
+The reference implementation — encoder, decoder, valence state machine, stereo handling,
+tokenizer/`Vocab` builder, and the test suites — lives at
+**[github.com/aakothari/braids](https://github.com/aakothari/braids)**.
 
 ### Verified codec behaviour