Update README.md

README.md

@@ -1,7 +1,12 @@
 ---
+base_model: togethercomputer/Meta-Llama-3.3-70B-Instruct-Reference
+base_model_relation: adapter
 language:
   - en
+library_name: peft
 pipeline_tag: text-generation
+datasets:
+  - prathmeshadsod/bondshift-organic-chemistry
 tags:
   - chemistry
   - organic-chemistry
@@ -12,53 +17,55 @@ tags:
   - adaption-autoscientist
 ---
 
-<style>
-.bondshift-hero {
-  text-align: center;
-  padding: 28px 18px;
-  margin: 8px 0 24px;
-  border: 1px solid rgba(127,127,127,.22);
-  border-radius: 18px;
-  background: linear-gradient(135deg, rgba(99,102,241,.10), rgba(16,185,129,.07));
-}
-.bondshift-hero h1 { margin: 0 0 10px; font-size: 2.35em; line-height: 1.15; }
-.bondshift-hero .tagline { margin: 0 auto 8px; max-width: 920px; font-size: 1.08em; }
-.bondshift-hero .subline { margin: 0; opacity: .82; }
-.bondshift-image { text-align: center; margin: 22px 0 28px; }
-.bondshift-image img { max-width: 100%; border-radius: 14px; }
-</style>
-
-<div class="bondshift-hero" align="center">
-  <h1>BondShift Organic Chemistry</h1>
-  <p class="tagline"><strong>A mechanism-reasoning assistant for finding, explaining, and repairing errors in undergraduate organic chemistry.</strong></p>
-  <p class="subline">LoRA-adapted from Llama 3.3 70B Instruct with a 10,000-row, ground-truth-separated training set.</p>
+<div align="center" style="padding:46px 30px;border-radius:30px;background:linear-gradient(135deg,#ffffff 0%,#f8fbff 18%,#eef2ff 42%,#f4e8ff 66%,#e6fbff 100%);border:1px solid #c7d2fe;box-shadow:0 18px 46px rgba(30,64,175,0.13);">
+
+<div style="margin-bottom:14px;">
+  <span style="display:inline-block;width:15px;height:15px;border-radius:999px;background:#dbeafe;margin:0 5px;border:1px solid #93c5fd;"></span>
+  <span style="display:inline-block;width:15px;height:15px;border-radius:999px;background:#c4b5fd;margin:0 5px;border:1px solid #a78bfa;"></span>
+  <span style="display:inline-block;width:15px;height:15px;border-radius:999px;background:#a5b4fc;margin:0 5px;border:1px solid #818cf8;"></span>
+  <span style="display:inline-block;width:15px;height:15px;border-radius:999px;background:#a5f3fc;margin:0 5px;border:1px solid #67e8f9;"></span>
 </div>
 
-<div class="bondshift-image" align="center">
-  <img src="assets/bondshift-win-rate.png" alt="BondShift evaluation results">
+<h1 style="margin:0 0 12px 0;">BondShift: Organic Mechanism Reasoning</h1>
+
+<p style="font-size:19px;margin:0 0 12px 0;"><strong>A mechanism tutor that diagnoses why an answer is right or wrong, not merely which product appears at the end.</strong></p>
+
+<p style="max-width:920px;margin:0 auto;">LoRA-adapted from Llama 3.3 70B Instruct with a 10,000-row, ground-truth-separated training set.</p>
+
 </div>
 
+<p align="center"><img src="assets/bondshift-win-rate.png" alt="BondShift evaluation results" width="100%" style="border-radius:22px;border:1px solid #c7d2fe;box-shadow:0 14px 34px rgba(30,64,175,0.10);background:linear-gradient(180deg,#ffffff,#f8fbff);"></p>
+
 ## TL;DR
 
-BondShift focuses on the reasoning that connects reagents, electron movement, intermediates, stereochemical constraints,
-and products. It is designed to do more than name a reaction: it explains why a proposed step works, identifies where a
-mechanism goes wrong, and gives a corrected path in natural language.
+<div style="padding:22px 24px;border-radius:22px;background:linear-gradient(135deg,#ffffff 0%,#eef5ff 32%,#f5ecff 67%,#ecfeff 100%);border:1px solid #c7d2fe;box-shadow:0 10px 26px rgba(30,64,175,0.07);">
 
-> The submitted model is a **LoRA adapter**, not a standalone 70B checkpoint. It must be used with the exact base-model
-> family recorded in the AutoScientist configuration.
+BondShift targets a common failure in organic-chemistry assistance: producing a plausible product while giving an
+invalid electron-flow story. It connects reagents and conditions to electron movement, charge, intermediates,
+stereochemical constraints, pathway choice, and the final outcome.
 
+The target behavior is diagnostic. BondShift should identify the first invalid step, explain the controlling chemical
+principle, repair the mechanism, and state what additional structural or condition information is needed when the answer
+is genuinely underdetermined.
 
----
+The submitted model is a **LoRA adapter**, not a standalone 70B checkpoint. It must be used with the exact base-model
+family recorded in the AutoScientist configuration.
+
+</div>
+
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Contents
 
 - [Why BondShift](#why-bondshift)
+- [The design response](#the-design-response)
 - [Supported capabilities](#supported-capabilities)
 - [Example](#example)
 - [Evaluation](#evaluation)
 - [Model details](#model-details)
 - [Training configuration](#training-configuration)
 - [Training data](#training-data)
+- [What Adaption improved](#what-adaption-improved)
 - [Ground-truth architecture](#ground-truth-architecture)
 - [How to use](#how-to-use)
 - [Intended use](#intended-use)
@@ -66,22 +73,49 @@ mechanism goes wrong, and gives a corrected path in natural language.
 - [Reproducibility](#reproducibility)
 - [Citation](#citation)
 
-
----
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Why BondShift
 
-Organic chemistry students often know the reaction label but still struggle with the causal details: where an arrow
-starts, why a leaving group can depart, which beta hydrogen is geometrically available, or why a tempting alternative
-pathway is invalid. General assistants can answer these questions, but they may skip the decisive mechanistic step or
-state a condition-sensitive outcome too confidently.
+<div style="padding:20px 22px;border-radius:22px;background:linear-gradient(135deg,#ffffff,#f8fbff,#eef2ff);border:1px solid #c7d2fe;box-shadow:0 8px 22px rgba(30,64,175,0.06);">
 
-BondShift was trained around explicit, separately constructed chemistry answer keys. The target behavior is an
-instruction-following tutor that gives the direct answer first, then explains the smallest set of mechanistic facts
-needed to make the conclusion understandable.
+Organic chemistry is not solved by reaction-name recall alone. A student can memorize "strong base means E2" and still
+draw an impossible arrow, remove the wrong beta hydrogen, miss an anti-periplanar requirement, create an unstable
+carbocation, or treat resonance contributors as rapidly interconverting molecules.
 
+These are high-value tutoring failures because the final product can look correct even when the reasoning that produced
+it is not. Conventional answer-only data rewards the destination and may never teach the model to locate the broken
+step.
 
----
+BondShift therefore trains the reasoning layer between problem and conclusion:
+
+| Failure mode | Desired BondShift behavior |
+|---|---|
+| Correct product, invalid mechanism | Find and repair the first chemically invalid step |
+| Mechanism chosen from one keyword | Weigh substrate, nucleophile/base, solvent, geometry, and conditions together |
+| Strong reagent treated as overriding structure | Explain the geometric or orbital constraint that still applies |
+| Missing structure or conditions | Give a bounded answer or ask for the decisive missing fact |
+| Resonance or charge misconception | Track electron and charge conservation explicitly |
+| Unsupported selectivity claim | Avoid false precision and state the decision-changing conditions |
+
+</div>
+
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
+
+## The design response
+
+<div style="padding:20px 22px;border-radius:22px;background:linear-gradient(135deg,#ffffff,#f8f5ff,#f3e8ff);border:1px solid #ddd6fe;box-shadow:0 8px 22px rgba(88,28,135,0.06);">
+
+BondShift was built around independently constructed chemistry answer keys instead of allowing one language model to
+invent the question, answer, and validation truth together. The response target is still natural tutoring prose: answer
+first, explain the decisive mechanism, correct the misconception, and add caveats only when they matter.
+
+The production design also deliberately restricted V1 to chemistry families whose ground truth could be represented
+reliably. Breadth was postponed when it would have required fragile or overconfident answer keys.
+
+</div>
+
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Supported capabilities
 
@@ -98,8 +132,7 @@ needed to make the conclusion understandable.
 The validated V1 training scope contains six families: **acid-base**, **resonance/formal charge**, **S<sub>N</sub>1**,
 **S<sub>N</sub>2**, **E1**, and **E2**.
 
-
----
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Example
 
@@ -123,12 +156,13 @@ This is an actual prompt-response pair from the frozen training snapshot.
 > group, cannot react because the orbital overlap is wrong. So, despite ethoxide being a strong base, only the
 > trans-diaxial hydrogens are geometrically competent, and the product is cyclohexene.
 
-
----
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Evaluation
 
-### AutoScientist win rates
+<a id="autoscientist-win-rates"></a>
+<details open style="margin:16px 0;border:1px solid #c7d2fe;border-radius:18px;padding:0 16px;background:linear-gradient(135deg,#ffffff,#f8fbff,#f7f2ff);">
+<summary style="cursor:pointer;padding:14px 0;"><strong>AutoScientist win rates</strong></summary>
 
 | Evaluation slice | Base model | Adapted model |
 |---|---:|---:|
@@ -140,7 +174,11 @@ experiment `c7f0a1b0-8286-4387-8f08-f2e0a4b74998`. The interface did not expose
 or a public item-level evaluation set. The values should therefore be read as platform-reported preference results,
 not as universal chemistry accuracy estimates. The own-dataset labels may also reflect display rounding.
 
-### Dataset adaptation signals
+</details>
+
+<a id="dataset-adaptation-signals"></a>
+<details open style="margin:16px 0;border:1px solid #ddd6fe;border-radius:18px;padding:0 16px;background:linear-gradient(135deg,#ffffff,#f8fbff,#f7f2ff);">
+<summary style="cursor:pointer;padding:14px 0;"><strong>Dataset adaptation signals</strong></summary>
 
 The dataset used for this run was also measured before and after Adaption processing:
 
@@ -153,15 +191,18 @@ The dataset used for this run was also measured before and after Adaption proces
 The platform reports the quality-score change as **18.8% relative improvement**. These are platform measurements of
 the submitted dataset, not independent chemistry benchmarks.
 
-<div class="bondshift-image" align="center">
-  <img src="assets/bondshift-training.png" alt="BondShift training telemetry">
-</div>
+The improvement is visible beyond the score. The adapted records add clearer task framing, more explicit deliverables,
+better organized explanations, and stronger misconception-focused teaching while preserving the chemical problem being
+solved.
+
+<p align="center"><img src="assets/bondshift-training.png" alt="BondShift training telemetry" width="100%" style="border-radius:22px;border:1px solid #ddd6fe;box-shadow:0 14px 34px rgba(88,28,135,0.09);background:linear-gradient(180deg,#ffffff,#faf7ff);"></p>
 
 Training curves document the run's optimization telemetry. They do not, by themselves, establish chemical correctness
 or out-of-distribution generalization.
 
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
----
+</details>
 
 ## Model details
 
@@ -171,14 +212,14 @@ or out-of-distribution generalization.
 | Training method | Supervised fine-tuning (SFT) |
 | Data format | Chat |
 | Base model recorded by AutoScientist | `meta-llama/Llama-3.3-70B-Instruct-Reference` |
+| Base path recorded by exported adapter | `togethercomputer/Meta-Llama-3.3-70B-Instruct-Reference` |
 | Base model size | 70B |
 | AutoScientist training model label | `adaption_llama_3_3_70b_instru_bondshift_organic_chemis_c7f0a1b0` |
 | Trained model name | `adaption_organic_mechanism_qa` |
 | Training experiment ID | `c7f0a1b0-8286-4387-8f08-f2e0a4b74998` |
 | Fine-tune job ID | `a49eb748-1696-466a-8755-9c2952376891` |
 
-
----
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Training configuration
 
@@ -202,12 +243,12 @@ The AutoScientist-selected configuration was used unchanged.
 | Trainable modules | `all-linear` |
 | Train on inputs | `false` |
 
-
----
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Training data
 
-BondShift was trained on exactly **10,000 English prompt-response records**:
+BondShift was trained from exactly **10,000 English chemistry records**. The public dataset exposes the audited source
+pair and the Adaption-remastered pair side by side:
 
 | Slice | Rows |
 |---|---:|
@@ -223,11 +264,34 @@ Every row earns its place: the final 10,000 were selected from a deterministic 1
 scope and answer-key alignment, screened for internal leakage, and deduplicated before the immutable release snapshot
 was created.
 
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
----
+## What Adaption improved
+
+<div style="padding:20px 22px;border-radius:22px;background:linear-gradient(135deg,#f8fbff,#eef2ff,#f5ecff,#ecfeff);border:1px solid #c7d2fe;box-shadow:0 10px 26px rgba(67,56,202,0.07);">
+
+The source corpus already supplied natural questions, grounded answers, and strict mechanism validation. Adaption then
+added a second, enhanced view of every record:
+
+| Dataset field | Role |
+|---|---|
+| `prompt` | Original natural user question |
+| `response` | Original validated answer |
+| `enhanced_prompt` | Adaption-remastered instruction with clearer task framing |
+| `enhanced_completion` | Adaption-remastered teaching response |
+| `reasoning_trace` | Auxiliary platform-generated reasoning data |
+
+The adapted AutoScientist run is associated with the enhanced instruction/completion view. The auxiliary reasoning
+trace is not BondShift's deterministic answer key and is not the archival MechanismIR sidecar.
+
+</div>
+
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Ground-truth architecture
 
+<div style="padding:20px 22px;border-radius:22px;background:linear-gradient(135deg,#ffffff,#eef2ff,#ecfeff);border:1px solid #bae6fd;box-shadow:0 10px 26px rgba(8,145,178,0.06);">
+
 The data pipeline deliberately separates five concerns:
 
 1. A deterministic **scenario blueprint** contains only facts that may be shown to the prompt author.
@@ -240,45 +304,46 @@ The data pipeline deliberately separates five concerns:
 The training response contains the user-facing explanation and conclusion. No private chain-of-thought was generated or
 exported. MechanismIR-lite is archival validation metadata and is not forced into the model's natural-language answer.
 
+</div>
 
----
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## How to use
 
-### Adaption interface
+<a id="adaption-interface"></a>
+<details open style="margin:16px 0;border:1px solid #bae6fd;border-radius:18px;padding:0 16px;background:linear-gradient(135deg,#ffffff,#f8fbff,#f7f2ff);">
+<summary style="cursor:pointer;padding:14px 0;"><strong>Adaption interface</strong></summary>
 
 Open dataset ID `9e740edb-5d61-49c0-9510-b37919676e4a` in Adaption, select **Interfaces**, and use the BondShift
 organic-chemistry mechanism companion. A strong query includes the substrate, reagents, solvent or medium, conditions,
 and the exact step or conclusion that is confusing.
 
-<div class="bondshift-image" align="center">
-  <img src="assets/bondshift-demo.png" alt="BondShift interface">
-</div>
-
-### Local adapter inference
+</details>
 
-This release is a LoRA adapter. It cannot be loaded as a standalone causal language model.
+<a id="local-adapter-inference"></a>
+<details open style="margin:16px 0;border:1px solid #c4b5fd;border-radius:18px;padding:0 16px;background:linear-gradient(135deg,#ffffff,#f8fbff,#f7f2ff);">
+<summary style="cursor:pointer;padding:14px 0;"><strong>Local adapter inference</strong></summary>
 
-The example below applies when the extracted release contains the standard PEFT adapter files. Set both environment
-variables to local, access-authorized paths and keep the tokenizer paired with the same compatible base checkpoint used
-for training.
+This release is a 1.66 GB LoRA adapter and cannot be loaded as a standalone causal language model. The repository now
+contains the adapter weights, adapter configuration, tokenizer, and chat template. PEFT can read the exact base path
+from `adapter_config.json`.
 
 ```python
-import os
 import torch
-from peft import PeftModel
+from peft import PeftConfig, PeftModel
 from transformers import AutoModelForCausalLM, AutoTokenizer
 
-base_model_path = os.environ["BONDSHIFT_BASE_MODEL"]
-adapter_path = os.environ["BONDSHIFT_ADAPTER_DIR"]
+adapter_id = "prathmeshadsod/BondShift-Llama-3.3-70B-Instruct"
+peft_config = PeftConfig.from_pretrained(adapter_id)
+base_model_path = peft_config.base_model_name_or_path
 
-tokenizer = AutoTokenizer.from_pretrained(base_model_path)
+tokenizer = AutoTokenizer.from_pretrained(adapter_id)
 base = AutoModelForCausalLM.from_pretrained(
     base_model_path,
     torch_dtype=torch.bfloat16,
     device_map="auto",
 )
-model = PeftModel.from_pretrained(base, adapter_path)
+model = PeftModel.from_pretrained(base, adapter_id)
 
 messages = [{
     "role": "user",
@@ -289,21 +354,26 @@ messages = [{
 }]
 inputs = tokenizer.apply_chat_template(
     messages,
+    tokenize=True,
     add_generation_prompt=True,
+    return_dict=True,
     return_tensors="pt",
 ).to(model.device)
 
 with torch.inference_mode():
-    output = model.generate(inputs, max_new_tokens=384, do_sample=False)
+    output = model.generate(**inputs, max_new_tokens=384, do_sample=False)
 
-print(tokenizer.decode(output[0][inputs.shape[-1]:], skip_special_tokens=True))
+new_tokens = output[0][inputs["input_ids"].shape[-1]:]
+print(tokenizer.decode(new_tokens, skip_special_tokens=True))
 ```
 
-`BONDSHIFT_BASE_MODEL` must point to the compatible Llama 3.3 70B Instruct base checkpoint, and
-`BONDSHIFT_ADAPTER_DIR` must point to the extracted adapter directory.
+The exported configuration currently records `togethercomputer/Meta-Llama-3.3-70B-Instruct-Reference`. Access to a
+compatible base checkpoint and hardware capable of serving a 70B model are still required. Quantization and adapter
+merging should be tested separately; this repository is not a merged full checkpoint.
 
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
----
+</details>
 
 ## Intended use
 
@@ -318,8 +388,7 @@ BondShift is intended for:
 It is not intended to replace an instructor, validate a synthesis, provide laboratory safety instructions, or support
 clinical, industrial, or high-stakes chemical decisions.
 
-
----
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Limitations
 
@@ -338,8 +407,7 @@ clinical, industrial, or high-stakes chemical decisions.
 - The reported win rates come from the Adaption interface. No confidence intervals or public item-level evaluation set
   were available for independent statistical analysis.
 
-
----
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Reproducibility
 
@@ -357,8 +425,7 @@ Only one prompt-author model and one response-teacher model were used in the acc
 attempts, validation records, deterministic provenance, repair reports, and the full metadata snapshot were retained for
 auditability.
 
-
----
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Citation
 
@@ -371,8 +438,7 @@ auditability.
 }
 ```
 
-
----
+<div style="height:3px;border-radius:999px;background:linear-gradient(90deg,#e0e7ff 0%,#93c5fd 22%,#818cf8 48%,#c084fc 70%,#67e8f9 88%,#f8fafc 100%);margin:32px 0 20px 0;"></div>
 
 ## Acknowledgements