Update README.md

README.md

@@ -22,27 +22,45 @@ library_name: transformers
 pipeline_tag: fill-mask
 ---
 
-# BRAIDBERTa
+---
+license: mit
+language:
+- en
+tags:
+- chemistry
+- molecular-property-prediction
+- cheminformatics
+- roberta
+- smiles
+- deepsmiles
+- selfies
+- molecular-representation
+datasets:
+- zinc
+library_name: transformers
+pipeline_tag: fill-mask
+---
 
-A RoBERTa-style masked language model pretrained on molecules encoded in **BRAID**, a
-machine-native molecular line notation, together with a **SMILES-pretrained control model
-(SMILESBERTa)** that is identical in every respect except the input notation.
+# BRAIDBERTa-v9
 
-The point of this repository is the *controlled comparison*, not the model. If you are
-looking for a strong chemical foundation model, use ChemBERTa-2 or MolFormer. If you want
-to know whether the choice of line notation actually changes downstream performance when
-everything else is held fixed, that is what this is for.
+A RoBERTa-style masked language model pretrained on ZINC 100k, with molecules encoded in
+**BRAID** — a machine-native molecular line notation in which every string decodes to a
+valid molecule.
 
-**Headline result: it does not.** BRAID and SMILES are statistically indistinguishable on
-BBBP under matched pretraining, matched architecture, and matched finetuning protocol.
+BRAIDBERTa exists to answer one question: does a guaranteed-validity notation cost you
+anything on downstream property prediction? Against a matched-budget SMILES control, the
+answer is **no** — the two are statistically indistinguishable on BBBP.
+
+This is a research model. If you want a strong chemical foundation model, use ChemBERTa-2 or
+MolFormer. If you want a model whose input notation cannot represent an invalid molecule,
+this is that.
 
 ---
 
 ## The BRAID notation
 
 BRAID (**B**ranch-counted, **R**elative-ring, **A**ttachment-native, **I**nvalid-free,
-**D**ense) is a line notation built from four mechanisms, all of which are recombined prior
-art:
+**D**ense) is built from four mechanisms, all of which are recombined prior art:
 
 | Mechanism | Syntax | Borrowed from |
 |---|---|---|
@@ -53,11 +71,10 @@ art:
 
 Only **atom tokens** advance the global index; `>k`, `^d`, bond symbols and `.` do not.
 
-```bash
-pip install rdkit
-python -m braids encode "CC(=O)Oc1ccccc1C(=O)O"            # -> CC>1=OOC=CC=CC=C^5C>1=OO
-python -m braids encode "CC(=O)Oc1ccccc1C(=O)O" --aromatic # -> CC>1=OOcccccc^5C>1=OO
-python -m braids decode "CC>1=OOcccccc^5C>1=OO"            # -> CC(=O)Oc1ccccc1C(=O)O
+```
+aspirin   SMILES  CC(=O)Oc1ccccc1C(=O)O
+          BRAID   CC>1=OOcccccc^5C>1=OO        (aromatic mode)
+          BRAID   CC>1=OOC=CC=CC=C^5C>1=OO     (kekulé mode, default)
 ```
 
 ### Novelty: none claimed
@@ -67,6 +84,7 @@ BRAID is **not novel at the mechanism level.** Relative ring closure is DeepSMIL
 2020) with the brackets stripped. Guaranteed-valid decoding via a valence state machine is
 the entire point of SELFIES. The fragment separator is SAFE (Noutahi et al., 2023).
 
+Please treat BRAID as a recombination, and do not cite it as a new notation.
 
 ### The property BRAID does have
 
@@ -89,59 +107,113 @@ A Markov model is far weaker than a real CLM, so treat validity% as the meaningf
 
 ---
 
-## Models
+## Model details
 
-| Model | Pretraining corpus | Notation | Architecture |
-|---|---|---|---|
-| `BRAIDBERTa-v9` | ZINC 100k | BRAID | RoBERTa (MLM) |
-| `SMILESBERTa-v9` | ZINC 100k | SMILES | RoBERTa (MLM), identical config |
+- **Architecture:** RoBERTa (masked language modelling)
+- **Pretraining corpus:** ZINC 100k, encoded in BRAID
+- **Tokenizer:** BPE trained on the BRAID corpus
+- **Objective:** MLM
 
-The two models differ **only** in the notation used to encode the pretraining corpus and in
-the tokenizer trained on it. Same molecules, same architecture, same MLM objective, same
-pretraining budget. This is what makes the downstream comparison interpretable.
+<!-- TODO: fill in layers / heads / hidden size / vocab size / pretraining steps -->
 
 ---
 
-## Downstream ablation: BBBP
+## Downstream evaluation: BBBP
 
 Finetuned for binary classification (blood–brain barrier penetration) with a fresh 2-logit
-head and cross-entropy loss. Hyperparameters (learning rate, epochs) were selected per model
-by Optuna on the validation split, then the best configuration was retrained across 5 seeds.
-Reported metric is test ROC-AUC.
+head and cross-entropy loss. Hyperparameters (learning rate, epochs) were selected by Optuna
+on the validation split, then the best configuration was retrained across 5 seeds. Metric is
+test ROC-AUC.
 
-| Model | Dataset | BBBP ROC-AUC | Seed 0 | Seed 1 | Seed 2 | Seed 3 | Seed 4 |
+| Model | Notation | BBBP ROC-AUC | Seed 0 | Seed 1 | Seed 2 | Seed 3 | Seed 4 |
 |---|---|---|---|---|---|---|---|
-| BRAIDBERTa-v9 | ZINC 100k | 0.725 ± 0.017 | 0.727 | 0.710 | 0.751 | 0.710 | 0.727 |
-| SMILESBERTa-v9 | ZINC 100k | 0.720 ± 0.010 | 0.719 | 0.738 | 0.715 | 0.714 | 0.712 |
+| **BRAIDBERTa-v9** | BRAID | **0.725 ± 0.017** | 0.727 | 0.710 | 0.751 | 0.710 | 0.727 |
+| *SMILES control* | SMILES | *0.720 ± 0.010* | 0.719 | 0.738 | 0.715 | 0.714 | 0.712 |
 
 (± is the sample standard deviation across seeds.)
 
+### The SMILES control
+
+The control is an internal baseline, **not a released model.** It is identical to
+BRAIDBERTa in every respect — same ZINC 100k molecules, same RoBERTa architecture and
+config, same MLM objective, same pretraining budget, same finetuning protocol — differing
+only in the notation used to encode the corpus and the tokenizer trained on it. It is
+reported here solely to make the BRAID number interpretable.
+
 ### Interpretation
 
 **The two are statistically indistinguishable.** Welch's *t*-test on the five seeds per
-model gives *t* ≈ 0.61, *p* ≈ 0.56. The 0.005 gap in favour of BRAID is well within seed
-noise, and the per-seed ranges overlap almost completely (BRAID 0.710–0.751, SMILES
+model gives *t* ≈ 0.61, *p* ≈ 0.56. The 0.005 gap in favour of BRAID sits well inside seed
+noise, and the per-seed ranges overlap almost completely (BRAID 0.710–0.751, control
 0.712–0.738).
 
 The correct reading is **not** "BRAID beats SMILES." It is:
 
-> Under matched pretraining and finetuning, BRAID's guaranteed-validity property is obtained
+> Under matched pretraining and finetuning, BRAID's guaranteed-validity property comes
 > **at no measurable cost to downstream predictive performance** on BBBP.
 
 That is the useful claim. A notation that buys 100% generative validity while leaving
 property prediction unchanged is worth having; a notation that claims a 0.005 AUC win on
-n=5 is not.
+n = 5 is not.
+
+Note that seed-to-seed spread (±0.017) exceeds the between-model difference. Any comparison
+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:
 
-Note also that the seed-to-seed spread (±0.017) is larger than the between-model difference.
-Any comparison at this scale that reports a single seed is measuring noise.
+```python
+import importlib.util
+from huggingface_hub import hf_hub_download
+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
+inputs = tok(braid, return_tensors="pt", truncation=True, max_length=128)
+logits = model(**inputs).logits
+```
+
+> **Do not feed raw SMILES to this tokenizer.** It will not error — BPE always backs off to
+> 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:
+
+<!-- TODO: link the GitHub repo, or delete this line if the vendored codec is the only distribution -->
+
+### Verified codec behaviour
+
+- **Round-trip:** 42/42 molecules recover their constitution in both Kekulé and aromatic
+  modes — including fused/bridged systems (naphthalene, indole, adamantane, caffeine,
+  purine, quinoline, nicotine) and ions (nitromethane, acetate, ammonium, Na⁺·Cl⁻).
+- **Stereo:** 26/26 chiral / E-Z molecules round-trip in both modes — L-alanine,
+  (S)-ibuprofen, meso vs. L-tartaric acid, menthol, L-DOPA, adrenaline, carvone,
+  fumaric/maleic acid, conjugated dienes, mixed chiral + E/Z.
+- **Validity:** 10,000/10,000 random and mutated strings decode to a sanitizable molecule
+  with 0 crashes.
 
 ---
 
 ## Limitations
 
 1. **Not actually more compact.** The "D" in BRAID is aspirational. BRAID is never the
-   shortest of the four notations — `>k` and `^d` are two characters where SMILES uses one.
-   Aromatic mode reaches parity with SMILES, not dominance.
+   shortest notation — `>k` and `^d` are two characters where SMILES uses one. Aromatic mode
+   reaches parity with SMILES, not dominance.
 
    | molecule | SMILES | DeepSMILES | SELFIES(tok) | BRAID(kekulé) | BRAID(aromatic) |
    |---|--:|--:|--:|--:|--:|
@@ -171,7 +243,7 @@ Any comparison at this scale that reports a single seed is measuring noise.
 7. **Depends on RDKit** for parsing and sanitization. This is a reference implementation,
    not a self-contained spec.
 
-### Limitations of the ablation specifically
+### Limitations of the evaluation specifically
 
 - **One dataset, one split.** BBBP only. No claim is made about BACE, HIV, Tox21, SIDER, or
   ClinTox. Results on a single scaffold split of a ~2k-molecule dataset are fragile.
@@ -185,31 +257,10 @@ Any comparison at this scale that reports a single seed is measuring noise.
 
 ---
 
-## Usage
-
-```python
-from transformers import AutoTokenizer, AutoModelForSequenceClassification
-
-tok = AutoTokenizer.from_pretrained("<your-org>/BRAIDBERTa-v9")
-model = AutoModelForSequenceClassification.from_pretrained(
-    "<your-org>/BRAIDBERTa-v9", num_labels=2
-)
-
-from braids import smiles_to_braid
-braid = smiles_to_braid("CC(=O)Oc1ccccc1C(=O)O")
-inputs = tok(braid, return_tensors="pt", truncation=True, max_length=128)
-logits = model(**inputs).logits
-```
-
-**Inputs must be BRAID strings, not SMILES.** The tokenizer is a BPE vocabulary trained on
-BRAID; feeding it raw SMILES will not error — BPE always backs off to characters — it will
-simply produce meaningless tokenizations and a plausible-looking, wrong prediction. Encode
-with `braids.smiles_to_braid` first.
-
 ## Citation
 
 BRAID is a recombination of published mechanisms and should not be cited as a novel
-notation. Please cite the underlying work instead:
+notation. Please cite the underlying work:
 
 - O'Boyle, N. & Dalke, A. *DeepSMILES: An Adaptation of SMILES for Use in Machine-Learning
   of Chemical Structures.* ChemRxiv, 2018.