Model card: how to use Carbon-X as a tool for an agent

.gitattributes

@@ -35,4 +35,3 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 tokenizer.json filter=lfs diff=lfs merge=lfs -text
 figures/carbon-x-banner.png filter=lfs diff=lfs merge=lfs -text
-figures/partner-logos.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -4,6 +4,7 @@ license: apache-2.0
 base_model: Qwen/Qwen3-14B
 language:
 - en
+- dna
 tags:
 - dna
 - genomics
@@ -15,12 +16,6 @@ pipeline_tag: text-generation
 
 ![](figures/carbon-x-banner.png)
 
-<p align="center">
-  <a href="https://huggingface.co/spaces/HuggingFaceBio/Carbon-X-Release"><b>Blog</b></a> |
-  <a href="https://huggingface.co/HuggingFaceBio"><b>Hugging Face Bio</b></a> |
-  <a href="https://github.com/huggingface/carbon/tree/main"><b>Code</b></a>
-</p>
-
 # Carbon-X
 
 An open 14B language model for DNA understanding and generation, from the **Carbon** family.
@@ -38,17 +33,11 @@ An open 14B language model for DNA understanding and generation, from the **Carb
 
 ## Model Summary
 
-<p align="center">
-    <img src="figures/score-vs-cost.png" alt="Average DNA benchmark score versus cost per problem relative to Carbon-X" width="800">
-</p>
-
-<p align="center"><em>Each comparison model is shown at the reasoning effort with its highest average score. Costs use standard API pricing; for Carbon-X, measured throughput per H200-hour at $5/hour.</em></p>
-
 **Carbon-X** is a 14.8B-parameter decoder-only language model trained jointly on DNA sequences and natural-language text. You give it raw DNA inside an ordinary chat conversation and it answers in English: it predicts whether mutations are benign or pathogenic, identifies regions that control gene activity, classifies sequences by organism group, predicts the next bases of a sequence, and explains its reasoning. Responses can contain both DNA and natural language.
 
 DNA and text share a single token stream in a single decoder. There is no separate DNA encoder. A hybrid tokenizer keeps a BPE vocabulary for text and encodes DNA as non-overlapping 6-mers, so one DNA token covers 6 base pairs.
 
-Across five DNA benchmarks, which cover variant-effect prediction, sequence understanding and next-base prediction, Carbon-X averages **66.7%** with thinking disabled. That is 27 points above Qwen3-14B, the model it starts from, and ahead of every other open model we evaluated. It is close to GPT-6.1 Sol (67.5%) at about 1/1,800 of the inference cost per problem, and it leads every model we tested on coding-variant effects and next-base prediction ([Evaluation](#evaluation)). Carbon-X answers directly, without extended reasoning, so each problem costs few output tokens. We estimate that analysing the 2.4 million variants of uncertain significance in ClinVar would cost about $300 with Carbon-X, compared with $32,000 to $4 million with the frontier models we evaluated. The weights fit on a single 80 GB GPU in bfloat16, so researchers can keep sensitive or unpublished sequences on their own infrastructure.
+Across five DNA benchmarks, which cover variant-effect prediction, sequence understanding and next-base prediction, Carbon-X averages **66.7%** with thinking disabled ([Evaluation](#evaluation)). It answers directly, without extended reasoning, so each problem costs few output tokens. We estimate that analysing the 2.4 million variants of uncertain significance in ClinVar would cost about $500 with Carbon-X. The weights fit on a single 80 GB GPU in bfloat16, so researchers can keep sensitive or unpublished sequences on their own infrastructure.
 
 ### Key features
 
@@ -145,24 +134,22 @@ The tokenizer switches between BPE for text and 6-mers for DNA. You can paste se
 
 ## Evaluation
 
-We evaluate Carbon-X on five benchmarks that test whether a model can use DNA knowledge to predict mutation effects, identify biological features and recover DNA bases. Carbon-X results use thinking disabled, the default sampling settings and one sample per problem. Each comparison model is shown at the reasoning effort with its highest average score. The best score on each benchmark is in bold.
+We evaluate Carbon-X on five benchmarks that test whether a model can use DNA knowledge to predict mutation effects, identify biological features and recover DNA bases. All results below are for the released checkpoint, with thinking disabled, the default sampling settings and one sample per problem.
 
-| Task | Benchmark | Carbon-X<br><sub>No reasoning</sub> | GPT-6.1 Sol<br><sub>Max</sub> | Opus 5.5<br><sub>Max</sub> | Gemini 4 Argon<br><sub>Low</sub> | GLM-5.3<br><sub>Low</sub> | Kimi K3<br><sub>Low</sub> | DeepSeek V4.1 Flash<br><sub>Low</sub> |
-|---|---|---:|---:|---:|---:|---:|---:|---:|
-| Coding variant effects | BioReason Coding | **74.9** | 71.0 | 70.3 | 6.5 | 52.1 | 53.9 | 51.4 |
-| Complex variant effects | BioReason Non-SNV | 85.1 | 91.7 | **94.8** | 90.3 | 60.1 | 65.3 | 55.9 |
-| DNA understanding | GenomeQA | 63.6 | **67.2** | 62.2 | 63.1 | 44.6 | 52.0 | 49.7 |
-| DNA prediction | NextBase | **39.4** | 32.9 | 1.1 | 31.2 | 9.7 | 30.6 | 27.2 |
-| Single-base variant effects | FrontierVEP | 70.4 | 74.9 | **76.2** | 58.0 | 32.7 | 50.1 | 51.3 |
-| **Average** | | 66.7 | **67.5** | 60.9 | 49.8 | 39.8 | 50.4 | 47.1 |
+| Task | Benchmark | Problems | Metric | Carbon-X |
+|---|---|---:|---|---:|
+| Coding variant effects | BioReason Coding | 1,018 | Balanced accuracy | 74.9 |
+| Complex variant effects | BioReason Non-SNV | 873 | Balanced accuracy | 85.1 |
+| DNA understanding | GenomeQA | 2,600 | Accuracy, mean over six tasks | 63.6 |
+| DNA prediction | NextBase | 600 | Per-base accuracy | 39.4 |
+| Single-base variant effects | FrontierVEP | 1,000 | Accuracy | 70.4 |
+| **Average** | | | | **66.7** |
 
-BioReason and GenomeQA come from the literature; we built FrontierVEP and NextBase.
-
-- **BioReason Coding** (1,018 variants, balanced accuracy): given original and mutated sequences from protein-coding regions, predict whether the mutation is benign or pathogenic. The gene name is removed from the prompt, so the model must work from the sequence alone.
-- **BioReason Non-SNV** (873 variants, balanced accuracy): predict whether insertions, deletions and other changes that are not single-nucleotide variants are benign or pathogenic.
-- **GenomeQA** (2,600 questions, accuracy averaged over six tasks): multiple-choice questions about sequence features: enhancer vs. promoter, splice sites, organism group, histone marks, transcription-factor binding sites and motifs.
-- **NextBase** (600 sequences, per-base accuracy): predict the next DNA bases of a sequence. The score is the fraction of bases predicted correctly.
-- **FrontierVEP** (1,000 variants, accuracy): given a long reference sequence (up to 8,192 bases) and a single-nucleotide variant, predict whether the variant is benign or pathogenic (500 benign, 500 pathogenic).
+- **BioReason Coding**: given original and mutated sequences from protein-coding regions, predict whether the mutation is benign or pathogenic. The gene name is removed from the prompt, so the model must work from the sequence alone.
+- **BioReason Non-SNV**: predict whether insertions, deletions and other changes that are not single-nucleotide variants are benign or pathogenic.
+- **GenomeQA**: multiple-choice questions about sequence features: enhancer vs. promoter, splice sites, organism group, histone marks, transcription-factor binding sites and motifs.
+- **NextBase**: predict the next DNA bases of a sequence. The score is the fraction of bases predicted correctly.
+- **FrontierVEP**: given a long reference sequence and a single-nucleotide variant, predict whether the variant is benign or pathogenic (500 benign, 500 pathogenic).
 
 <details>
 <summary>GenomeQA per-task accuracy</summary>
@@ -233,7 +220,7 @@ The mid-trained model is fine-tuned for 3 epochs on a mixture of 20 dataset subs
 The fine-tuned model is then trained with asynchronous GRPO and verifiable rewards in two rounds, with thinking disabled:
 
 1. One epoch over a blend of 98,433 prompts, selected from the fine-tuned model's own pass rates, for 150 steps.
-2. A second round from that checkpoint, on 58,249 prompts re-selected from its rollouts. The released weights come after about 2.2 passes over the blend.
+2. A second round from that checkpoint, on 58,249 prompts re-selected from its rollouts. The released weights are **step 210** of this round, about 2.2 passes over the blend.
 
 Both rounds use 16 samples per prompt, completions of up to 4,096 tokens, a learning rate of 1e-6, asymmetric clipping (ε = 0.2 / 0.28) and a maximum gradient norm of 0.2. Rewards are task-specific, code-checked verifiers. They cover variant-effect prediction (with a penalty for ungrounded rationales), sequence-feature classification, basic DNA operations, DNA skills, locating positions within sequences, biology multiple-choice questions and instruction following.
 
@@ -265,7 +252,7 @@ def ask_carbon(question: str, sequences: dict[str, str], context: str = "") -> s
     return response.choices[0].message.content
 ```
 
-The snippet above is a core call. We provide the options below as examples, each one is self-contained, so pick the one that fits your agent:
+Ready-to-run examples in this repository build on this function:
 
 - **Any agent with tool calling:** [`examples/agent_tool.py`](examples/agent_tool.py) describes `ask_carbon` as an
   OpenAI-style tool and runs a minimal agent loop. The agent refers to sequences by name and your code looks up the DNA,
@@ -273,21 +260,15 @@ The snippet above is a core call. We provide the options below as examples, each
 - **Inspect:** [`examples/inspect_agent.py`](examples/inspect_agent.py) wraps Carbon-X in an `@tool` for an
   [Inspect](https://inspect.aisi.org.uk/) `react()` agent, with each sample's DNA kept in metadata.
 - **Coding agents (Claude Code, Codex CLI):** [`skills/carbon-dna/`](skills/carbon-dna/) is a ready-made skill. Its
-  script needs only the Python standard library and has two commands: `ask` (a question about named DNA files) and
-  `compare` (rank equal-length variants by sequence likelihood). You need a GPU with about 80 GB of memory and vLLM
-  (`pip install -U vllm`); the skill itself needs no extra packages or API keys. Start Carbon-X, install the skill and
-  point it at the server:
+  standard-library script has two commands: `ask` (a question about named DNA files) and `compare` (rank equal-length
+  variants by sequence likelihood).
 
   ```bash
-  vllm serve HuggingFaceBio/Carbon-X --trust-remote-code              # one 80 GB GPU
   hf download HuggingFaceBio/Carbon-X --include "skills/*" --local-dir carbon-x
-  cp -r carbon-x/skills/carbon-dna ~/.claude/skills/                  # Codex CLI: ~/.codex/skills/
-  export CARBON_BASE_URL=http://localhost:8000/v1                     # or the address of your vLLM server
+  cp -r carbon-x/skills/carbon-dna ~/.claude/skills/    # Codex CLI: ~/.codex/skills/
+  export CARBON_BASE_URL=http://localhost:8000/v1        # your Carbon-X server
   ```
 
-  Carbon-X runs with vLLM or Transformers. llama.cpp and other GGUF runtimes are not supported: the DNA tokenizer is
-  custom Python code that they cannot load, so DNA would be tokenized incorrectly.
-
 ### Tips for agent use
 
 - **Pass DNA by reference.** Keep sequences in files or a lookup table and let the agent name them.
@@ -313,8 +294,4 @@ Apache 2.0.
 
 ## Acknowledgements
 
-Carbon-X is a joint collaboration between the research teams at [Hugging Face](https://huggingface.co), [Zhongguancun Academy](https://www.bza.edu.cn/en/), and the [Telethon Institute of Genetics and Medicine](https://www.tigem.it/)/[University of Naples “Federico II”](https://www.dicmapi.unina.it/).
-
-<p align="center">
-  <img src="figures/partner-logos.png" alt="Hugging Face, Zhongguancun Academy, Telethon Institute of Genetics and Medicine and University of Naples Federico II" width="800">
-</p>
+Carbon is a joint collaboration between the research teams at Hugging Face, Zhongguancun Academy, and TIGEM/University of Naples “Federico II”.