docs: specialist card with usage, examples and family index

README.md

@@ -1,26 +1,143 @@
 ---
-base_model: meta-llama/Llama-3.1-8B-Instruct
 library_name: peft
+base_model: meta-llama/Llama-3.1-8B-Instruct
+pipeline_tag: text-generation
+language:
+- en
+license: cc-by-nc-4.0
 tags:
 - lora
+- peft
 - molly-os
 - specialist
-- physics
-license: llama3.1
+- quantum-software-architect
+- llama-3.1
+- domain-adaptation
 ---
 
-# Molly OS — Specialist Adapter: Quantum Software Architect
+# Molly Specialist — Quantum Software Architect
+
+Generates correct Qiskit and Cirq circuit code, identifies gate decomposition errors, and explains quantum algorithm trade-offs more accurately than the base model.
+
+Part of **[Molly](https://iamolly.ai/?utm_source=huggingface&utm_medium=model_card&utm_campaign=specialists&utm_content=molly-quantum-software-architect)**, an orchestrator that keeps a library of small domain
+specialists over one quantized base and routes each request to the right one, so a
+single machine answers across many fields without loading a separate large model
+for each.
+
+## What this specialist handles well
+
+- Translates quantum algorithms into optimized Qiskit or Cirq circuit code
+- Identifies errors in quantum gate decompositions and circuit depth optimization
+- Explains quantum error correction scheme trade-offs for specific hardware topologies
+
+## Try it with
+
+- "How do I implement Shor's algorithm in Qiskit with minimal circuit depth?"
+- "What error correction code works best for a 127-qubit heavy-hex topology?"
+- "Convert this QAOA circuit from Cirq to Qiskit preserving gate fidelity"
+
+## Before you run: the base model is gated
+
+This adapter needs the base weights, and the base is **access-gated**. Do this **once**:
+
+1. Accept the base licence: <https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct>
+2. Create a **read token**: <https://huggingface.co/settings/tokens>
+3. Make the token available:
+   - **Google Colab:** Secrets panel (key icon) → *Add new secret* → name `HF_TOKEN`, enable **Notebook access**.
+   - **Kaggle:** *Add-ons → Secrets* → add `HF_TOKEN`.
+   - **Local:** `huggingface-cli login` or `export HF_TOKEN=...`
+
+Skipping this gives `GatedRepoError` / `401 Unauthorized` when the **base** loads. A stored
+Colab secret is **not** applied automatically — authenticate in code, as below.
+
+## Quickstart
+
+```python
+# pip install -U transformers peft accelerate
+import os, torch
+from huggingface_hub import login
+try:
+    from google.colab import userdata
+    login(userdata.get("HF_TOKEN"))
+except Exception:
+    tok = os.environ.get("HF_TOKEN")
+    login(tok) if tok else login()
+
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+BASE = "meta-llama/Llama-3.1-8B-Instruct"
+ADAPTER = "BoomJules/molly-quantum-software-architect"
+
+tok = AutoTokenizer.from_pretrained(BASE)
+base = AutoModelForCausalLM.from_pretrained(BASE, torch_dtype=torch.bfloat16, device_map="auto")
+model = PeftModel.from_pretrained(base, ADAPTER).eval()
+
+msgs = [{"role": "user", "content": "Your question here"}]
+ids = tok.apply_chat_template(msgs, add_generation_prompt=True, return_tensors="pt").to(model.device)
+out = model.generate(ids, max_new_tokens=300)
+print(tok.decode(out[0][ids.shape[1]:], skip_special_tokens=True))
+```
+
+## Low-VRAM (4-bit) — fits a free Colab/Kaggle GPU (~6–7 GB)
+
+```python
+# pip install -U transformers peft accelerate bitsandbytes
+import os, torch
+from huggingface_hub import login
+try:
+    from google.colab import userdata
+    login(userdata.get("HF_TOKEN"))
+except Exception:
+    login(os.environ.get("HF_TOKEN"))
+
+from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+from peft import PeftModel
+
+bnb = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4",
+                         bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True)
+tok = AutoTokenizer.from_pretrained("meta-llama/Llama-3.1-8B-Instruct")
+base = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.1-8B-Instruct", quantization_config=bnb, device_map="auto")
+model = PeftModel.from_pretrained(base, "BoomJules/molly-quantum-software-architect").eval()
+```
+
+## Adapter details
+
+| | |
+|---|---|
+| Base model | `meta-llama/Llama-3.1-8B-Instruct` |
+| Method | LoRA (PEFT) |
+| Rank / alpha | 32 / 64 |
+| Domain | Quantum Software Architect |
+
+## Troubleshooting
+
+- **`GatedRepoError` / `401 Unauthorized`** — base licence not accepted, or `HF_TOKEN` missing,
+  or the Colab secret was stored but `login(...)` was never called.
+- **CUDA out of memory** — use the 4-bit snippet on a GPU runtime.
+- **Adapter seems to have no effect** — confirm the base id matches `base_model` above.
+
+## Other Molly specialists
+
+- [Quantum Communication Systems Engineer](https://huggingface.co/BoomJules/molly-quantum-communication-systems-engineer)
+- [Infectious Disease Physician Antimicrobial Stewardship](https://huggingface.co/BoomJules/molly-infectious-disease-physician-antimicrobial-stewardship)
+- [Health Informatics Medical AI Specialist](https://huggingface.co/BoomJules/molly-health-informatics-medical-ai-specialist)
+- [Clinical Trial Pharmacologist](https://huggingface.co/BoomJules/molly-clinical-trial-pharmacologist)
+- [Immunopharmacologist](https://huggingface.co/BoomJules/molly-immunopharmacologist)
+- [Climate Analytics Manager](https://huggingface.co/BoomJules/molly-climate-analytics-manager)
+- [Language Technology Consultant](https://huggingface.co/BoomJules/molly-language-technology-consultant)
+- [Polymer Chemist](https://huggingface.co/BoomJules/molly-polymer-chemist)
+- [Composite Materials Engineer](https://huggingface.co/BoomJules/molly-composite-materials-engineer)
+- [Computer Science AI](https://huggingface.co/BoomJules/molly-cs-ai)
+- [Computer Science Algorithms](https://huggingface.co/BoomJules/molly-cs-algorithms)
+- [Computer Science Computer Vision](https://huggingface.co/BoomJules/molly-cs-cv)
 
-LoRA specialist adapter for the **Molly OS** model-agnostic orchestration layer.
+Running several of these at once, with the routing decided for you, is what
+[Molly](https://iamolly.ai/?utm_source=huggingface&utm_medium=model_card&utm_campaign=specialists&utm_content=molly-quantum-software-architect) does.
 
-- **Domain:** Physics
-- **Role:** Quantum Software Architect
-- **Base model:** `meta-llama/Llama-3.1-8B-Instruct`
-- **Adapter type:** LoRA (PEFT), rank **32**, alpha **64**
-- **Training records:** 177
+## Licence & intended use
 
-This adapter is one of a curated set of domain specialists orchestrated by Molly.
-Load it on top of the base model via PEFT or serve it through a multi-LoRA vLLM
-endpoint. Intended for research/demo use alongside the Molly OS whitepaper.
+Adapter: **CC BY-NC 4.0** (attribution, non-commercial). Base model: its own licence.
+Intended for research and evaluation in Quantum Software Architect.
 
-© 2026 Corelabs Group.
+© 2026 Core Labs R&D.