Model card: move the agent-tool section before Limitations; add examples and the carbon-dna skill

Follow-up to #1, which was merged before these changes:

- Moves **Using Carbon-X as a tool for an agent** before Limitations (and in the table of contents).
- Keeps only the short `ask_carbon` function inline and links ready-to-run examples instead of inlining them.
- Removes the A/C/G/T tip.

New files:
- `examples/agent_tool.py`: an OpenAI-style tool that passes DNA by reference, plus a minimal agent loop, for any chat model with tool calling.
- `examples/inspect_agent.py`: an Inspect `@tool` and `react()` agent, with each sample's DNA kept in metadata.
- `skills/carbon-dna/`: a skill for Claude Code and Codex CLI. `SKILL.md` plus a standard-library script with `ask` and `compare`, configured with `CARBON_BASE_URL`.

README.md

@@ -26,10 +26,10 @@ An open 14B language model for DNA understanding and generation, from the **Carb
 2. [How to use](#how-to-use)
 3. [Evaluation](#evaluation)
 4. [Training](#training)
-5. [Limitations](#limitations)
-6. [License](#license)
-7. [Acknowledgements](#acknowledgements)
-8. [Using Carbon-X as a tool for an agent](#using-carbon-x-as-a-tool-for-an-agent)
+5. [Using Carbon-X as a tool for an agent](#using-carbon-x-as-a-tool-for-an-agent)
+6. [Limitations](#limitations)
+7. [License](#license)
+8. [Acknowledgements](#acknowledgements)
 
 ## Model Summary
 
@@ -228,31 +228,10 @@ Both rounds use 16 samples per prompt, completions of up to 4,096 tokens, a lear
 
 - **Post-training:** [TRL](https://github.com/huggingface/trl) for supervised fine-tuning and asynchronous GRPO, with [vLLM](https://github.com/vllm-project/vllm) for generation.
 
-## Limitations
-
-Carbon-X is a starting point for research on connecting DNA and language. It has **not been clinically validated**, and it should not be used to make medical decisions.
-
-- ⚠️ **Genetic data is highly sensitive.** Depending on how you use this model (local download, inference API or endpoints, third-party inference providers, Spaces demos or others), input and output data may be processed or handled differently by different providers or Space owners. Make sure you understand and agree with how your data is handled before using the model.
-- **Exact sequence operations.** The model can miscount bases, confuse coordinates or make incorrect edits, particularly when it locates exact positions in long sequences. For tasks that need exact operations, pair it with tools that perform them.
-- **Missing context and hallucinations.** The model may invent a sequence's identity or function when the prompt does not give enough information. Include known annotations and context where available, and verify its biological claims.
-- **Uneven task coverage.** Splice-site and histone-mark questions remain weak (29.8% and 34.6% on GenomeQA). Carbon-X is also less reliable on short DNA exercises and textbook biology than on its core variant-effect and sequence-recovery tasks.
-- **Long sequence generation.** Quality degrades when the model is asked to generate long DNA sequences. Carbon-X reads and explains existing sequences. It was not trained to design new ones.
-- **Long inputs.** Mid-training used 8,192-token sequences (up to ≈ 49 kbp of DNA), and post-training examples were shorter than 16k tokens. The model accepts up to 40,960 tokens, but we have not evaluated inputs much longer than those seen in training.
-- **Thinking mode.** The chat template supports `enable_thinking=True`, but Carbon-X was post-trained and evaluated with thinking disabled.
-
-## License
-
-Apache 2.0.
-
-## Acknowledgements
-
-Carbon is a joint collaboration between the research teams at Hugging Face, Zhongguancun Academy, and TIGEM/University of Naples “Federico II”.
-
 ## Using Carbon-X as a tool for an agent
 
-A general-purpose assistant can call Carbon-X when a question involves DNA. Serve Carbon-X with vLLM as above, wrap it in a function, and give that function to any chat model that supports tool calling.
-
-**1. Wrap Carbon-X in a function.** The function takes a question and named DNA sequences, and returns Carbon-X's answer.
+A general-purpose assistant can call Carbon-X when a question involves DNA. Serve Carbon-X with vLLM
+([Serving with vLLM](#serving-with-vllm)) and wrap it in a function that takes a question and named DNA sequences:
 
 ```python
 from openai import OpenAI
@@ -273,63 +252,46 @@ def ask_carbon(question: str, sequences: dict[str, str], context: str = "") -> s
     return response.choices[0].message.content
 ```
 
-**2. Describe it to the agent as a tool.** Let the agent refer to sequences by name, and have your code look up the DNA. Language models often miscopy long sequences, so the agent should never retype them.
-
-```python
-import json
-
-sequences = {"reference.fa": "ATGGTGCATCTGACTCCTGAGGAGAAGTCTGCCGTTACTGCCCTGTGGGGCAAGG",
-             "variant.fa": "ATGGTGCATCTGACTCCTGTGGAGAAGTCTGCCGTTACTGCCCTGTGGGGCAAGG"}
-
-carbon_tool = {
-    "type": "function",
-    "function": {
-        "name": "ask_carbon",
-        "description": (
-            "Ask Carbon-X, a DNA language model, a question about DNA sequences: variant effects, "
-            "regulatory elements, organism of origin, sequence features. Refer to sequences by name; "
-            "do not paste DNA. Its answers are model predictions, not verified facts."
-        ),
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "question": {"type": "string", "description": "One self-contained question."},
-                "sequences": {"type": "array", "items": {"type": "string", "enum": list(sequences)}},
-                "context": {"type": "string", "description": "Known gene, coordinates or annotations, if any."},
-            },
-            "required": ["question", "sequences"],
-        },
-    },
-}
-```
-
-**3. Run the agent loop.** Any OpenAI-compatible chat model with tool calling works as the agent.
+Ready-to-run examples in this repository build on this function:
 
-```python
-agent = OpenAI()  # the agent model's provider
-messages = [
-    {"role": "system", "content": "For questions about DNA, consult Carbon-X with the ask_carbon tool before answering."},
-    {"role": "user", "content": "variant.fa differs from reference.fa by one base. Is the change likely benign or pathogenic?"},
-]
-while True:
-    reply = agent.chat.completions.create(model="<agent model>", messages=messages, tools=[carbon_tool])
-    message = reply.choices[0].message
-    messages.append(message)
-    if not message.tool_calls:
-        break
-    for call in message.tool_calls:
-        args = json.loads(call.function.arguments)
-        answer = ask_carbon(args["question"], {name: sequences[name] for name in args["sequences"]}, args.get("context", ""))
-        messages.append({"role": "tool", "tool_call_id": call.id, "content": answer})
-print(message.content)
-```
+- **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,
+  because language models often miscopy long sequences.
+- **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
+  standard-library script has two commands: `ask` (a question about named DNA files) and `compare` (rank equal-length
+  variants by sequence likelihood).
 
-Coding agents such as Claude Code or Codex CLI can use the same function as a skill: a short `SKILL.md` that says when to consult Carbon-X, plus a script that calls `ask_carbon` on sequence files in the workspace.
+  ```bash
+  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        # your Carbon-X server
+  ```
 
-Tips for agent use:
+### Tips for agent use
 
 - **Pass DNA by reference.** Keep sequences in files or a lookup table and let the agent name them.
 - **Ask for Carbon-X explicitly.** Agents often answer DNA questions on their own instead of calling a tool. If you want Carbon-X's view, say so in the system prompt.
-- **Send only A, C, G and T.** Trim padding such as leading or trailing `N`s. Other characters become `<oov>` tokens.
 - **Leave exact operations to code.** Counting, coordinates and edits are more reliable in Python than in either model. For variants, compute the position and the reference and alternate bases in code and pass them as `context`.
 - **Cap generation length.** For next-base and continuation questions, set `max_tokens` to what you need and a client timeout, since long DNA generations are slow (see [Limitations](#limitations)).
+
+## Limitations
+
+Carbon-X is a starting point for research on connecting DNA and language. It has **not been clinically validated**, and it should not be used to make medical decisions.
+
+- ⚠️ **Genetic data is highly sensitive.** Depending on how you use this model (local download, inference API or endpoints, third-party inference providers, Spaces demos or others), input and output data may be processed or handled differently by different providers or Space owners. Make sure you understand and agree with how your data is handled before using the model.
+- **Exact sequence operations.** The model can miscount bases, confuse coordinates or make incorrect edits, particularly when it locates exact positions in long sequences. For tasks that need exact operations, pair it with tools that perform them.
+- **Missing context and hallucinations.** The model may invent a sequence's identity or function when the prompt does not give enough information. Include known annotations and context where available, and verify its biological claims.
+- **Uneven task coverage.** Splice-site and histone-mark questions remain weak (29.8% and 34.6% on GenomeQA). Carbon-X is also less reliable on short DNA exercises and textbook biology than on its core variant-effect and sequence-recovery tasks.
+- **Long sequence generation.** Quality degrades when the model is asked to generate long DNA sequences. Carbon-X reads and explains existing sequences. It was not trained to design new ones.
+- **Long inputs.** Mid-training used 8,192-token sequences (up to ≈ 49 kbp of DNA), and post-training examples were shorter than 16k tokens. The model accepts up to 40,960 tokens, but we have not evaluated inputs much longer than those seen in training.
+- **Thinking mode.** The chat template supports `enable_thinking=True`, but Carbon-X was post-trained and evaluated with thinking disabled.
+
+## License
+
+Apache 2.0.
+
+## Acknowledgements
+
+Carbon is a joint collaboration between the research teams at Hugging Face, Zhongguancun Academy, and TIGEM/University of Naples “Federico II”.

examples/agent_tool.py

@@ -0,0 +1,65 @@
+"""Use Carbon-X as a tool for any chat model with OpenAI-style tool calling.
+
+Serve Carbon-X first: vllm serve HuggingFaceBio/Carbon-X --trust-remote-code
+Then set the agent client and model below and run: python agent_tool.py
+"""
+import json
+
+from openai import OpenAI
+
+carbon = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")
+
+
+def ask_carbon(question: str, sequences: dict[str, str], context: str = "") -> str:
+    """Ask Carbon-X a question about one or more named DNA sequences."""
+    parts = [context, question] if context else [question]
+    parts += [f"{name}: <dna>{seq}</dna>" for name, seq in sequences.items()]
+    response = carbon.chat.completions.create(
+        model="HuggingFaceBio/Carbon-X",
+        messages=[{"role": "user", "content": "\n\n".join(parts)}],
+        max_tokens=4096,
+        extra_body={"chat_template_kwargs": {"enable_thinking": False}},
+    )
+    return response.choices[0].message.content
+
+
+sequences = {"reference.fa": "ATGGTGCATCTGACTCCTGAGGAGAAGTCTGCCGTTACTGCCCTGTGGGGCAAGG",
+             "variant.fa": "ATGGTGCATCTGACTCCTGTGGAGAAGTCTGCCGTTACTGCCCTGTGGGGCAAGG"}
+
+carbon_tool = {
+    "type": "function",
+    "function": {
+        "name": "ask_carbon",
+        "description": (
+            "Ask Carbon-X, a DNA language model, a question about DNA sequences: variant effects, "
+            "regulatory elements, organism of origin, sequence features. Refer to sequences by name; "
+            "do not paste DNA. Its answers are model predictions, not verified facts."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "question": {"type": "string", "description": "One self-contained question."},
+                "sequences": {"type": "array", "items": {"type": "string", "enum": list(sequences)}},
+                "context": {"type": "string", "description": "Known gene, coordinates or annotations, if any."},
+            },
+            "required": ["question", "sequences"],
+        },
+    },
+}
+
+agent = OpenAI()  # the agent model's provider
+messages = [
+    {"role": "system", "content": "For questions about DNA, consult Carbon-X with the ask_carbon tool before answering."},
+    {"role": "user", "content": "variant.fa differs from reference.fa by one base. Is the change likely benign or pathogenic?"},
+]
+while True:
+    reply = agent.chat.completions.create(model="<agent model>", messages=messages, tools=[carbon_tool])
+    message = reply.choices[0].message
+    messages.append(message)
+    if not message.tool_calls:
+        break
+    for call in message.tool_calls:
+        args = json.loads(call.function.arguments)
+        answer = ask_carbon(args["question"], {name: sequences[name] for name in args["sequences"]}, args.get("context", ""))
+        messages.append({"role": "tool", "tool_call_id": call.id, "content": answer})
+print(message.content)

examples/inspect_agent.py

@@ -0,0 +1,67 @@
+"""Use Carbon-X as a tool for an Inspect react() agent.
+
+Serve Carbon-X first: vllm serve HuggingFaceBio/Carbon-X --trust-remote-code
+Then run: python inspect_agent.py
+"""
+from inspect_ai import Task, eval, task
+from inspect_ai.agent import as_solver, react
+from inspect_ai.dataset import Sample
+from inspect_ai.scorer import includes
+from inspect_ai.solver import solver
+from inspect_ai.tool import ToolError, tool
+from inspect_ai.util import store
+from openai import AsyncOpenAI
+
+carbon = AsyncOpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")
+
+
+@tool
+def ask_carbon():
+    async def execute(question: str, sequences: list[str], context: str = "") -> str:
+        """Ask Carbon-X, a DNA language model, about this task's DNA sequences. Its answers are predictions.
+
+        Args:
+            question: One self-contained question.
+            sequences: Names of the sequences to send, as given in the task.
+            context: Known facts, such as the gene, positions or alleles.
+        """
+        dna = store().get("sequences")
+        if missing := [name for name in sequences if name not in dna]:
+            raise ToolError(f"Unknown sequence names: {missing}. Available: {list(dna)}")
+        parts = [context, question] if context else [question]
+        parts += [f"{name}: <dna>{dna[name]}</dna>" for name in sequences]
+        response = await carbon.chat.completions.create(
+            model="HuggingFaceBio/Carbon-X",
+            messages=[{"role": "user", "content": "\n\n".join(parts)}],
+            max_tokens=4096,
+            extra_body={"chat_template_kwargs": {"enable_thinking": False}},
+        )
+        return response.choices[0].message.content
+
+    return execute
+
+
+@solver
+def load_sequences():
+    async def solve(state, generate):
+        store().set("sequences", state.metadata["sequences"])  # the tool reads DNA from here
+        return state
+
+    return solve
+
+
+@task
+def carbon_agent():
+    sample = Sample(
+        input="Sequence `variant` differs from `reference` at position 20 (A>T). Is the variant benign or pathogenic?",
+        target="pathogenic",
+        metadata={"sequences": {
+            "reference": "ATGGTGCATCTGACTCCTGAGGAGAAGTCTGCCGTTACTGCCCTGTGGGGCAAGG",
+            "variant": "ATGGTGCATCTGACTCCTGTGGAGAAGTCTGCCGTTACTGCCCTGTGGGGCAAGG",
+        }},
+    )
+    agent = react(prompt="Consult Carbon-X with the ask_carbon tool before you answer.", tools=[ask_carbon()])
+    return Task(dataset=[sample], solver=[load_sequences(), as_solver(agent)], scorer=includes())
+
+
+eval(carbon_agent(), model="openai/gpt-5")  # any Inspect model with tool calling as the agent

skills/carbon-dna/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: carbon-dna
+description: "Consult Carbon-X, a DNA language model, about DNA sequences in files: variant effects, regulatory elements, organism of origin, sequence features, and likelihood comparisons between variants."
+---
+
+# Consult Carbon-X about DNA
+
+Carbon-X is a DNA language model. Use it for biological interpretation of DNA alongside your own analysis. Its answers
+are model predictions, not verified facts or clinical classifications.
+
+`scripts/carbon.py` (next to this file) talks to a server running Carbon-X. It needs only Python 3.10+. The user
+configures the server with `CARBON_BASE_URL` (default `http://localhost:8000/v1`), `CARBON_MODEL` and, if needed,
+`CARBON_API_KEY`. Resolve the script's absolute path from this skill's directory.
+
+Put each sequence in its own file (plain DNA or one FASTA record) and refer to files by name. Do not retype DNA into
+commands: copying long sequences by hand introduces errors.
+
+Ask a question about one or more sequences:
+
+```sh
+python3 /path/to/carbon-dna/scripts/carbon.py ask \
+  --sequence reference=reference.fa --sequence variant=variant.fa \
+  --question "variant differs from reference at one base. Is the change likely benign or pathogenic?" \
+  --context "Position 20 (1-based): A>T. Gene and coordinates, if known."
+```
+
+Rank equal-length variants by how typical Carbon-X finds each sequence (a likelihood, not a pathogenicity score):
+
+```sh
+python3 /path/to/carbon-dna/scripts/carbon.py compare --reference reference.fa --alternative variant=variant.fa
+```
+
+From Python, add `scripts/` to `sys.path` and call `ask(question, {name: dna}, context)` or
+`compare(reference_dna, {name: dna})`.
+
+Guidance:
+
+- Work out exact facts in code first (positions, reference and alternate bases, reading frame, lengths) and pass them
+  as `--context`. Carbon-X can miscount positions in long sequences.
+- Ask one self-contained question per call, and keep any answer choices from the user's question.
+- Carbon-X reads A/C/G/T only. The script trims `N` padding at the ends and refuses other characters.
+- Check `truncated` in the result; for next-base or continuation questions, ask for only the length you need.

skills/carbon-dna/scripts/carbon.py

@@ -0,0 +1,105 @@
+"""Ask Carbon-X about DNA files, or compare DNA variants by model likelihood.
+
+Talks to any OpenAI-compatible server running Carbon-X, such as `vllm serve HuggingFaceBio/Carbon-X --trust-remote-code`.
+Configure it with environment variables:
+    CARBON_BASE_URL  server URL including /v1 (default http://localhost:8000/v1)
+    CARBON_MODEL     served model name (default HuggingFaceBio/Carbon-X)
+    CARBON_API_KEY   bearer token, if the server needs one (for example an HF token for an Inference Endpoint)
+
+Usage:
+    python carbon.py ask --question "..." --sequence reference=ref.fa --sequence variant=alt.fa [--context "..."]
+    python carbon.py compare --reference ref.fa --alternative alt1=alt1.fa [--alternative alt2=alt2.fa]
+Only the Python standard library is needed. Output is JSON.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.request
+from pathlib import Path
+
+BASE_URL = os.environ.get("CARBON_BASE_URL", "http://localhost:8000/v1").rstrip("/")
+MODEL = os.environ.get("CARBON_MODEL", "HuggingFaceBio/Carbon-X")
+API_KEY = os.environ.get("CARBON_API_KEY", "")
+
+
+def read_dna(path: str) -> str:
+    """Read plain DNA or one FASTA record; keep only A/C/G/T after trimming N padding at the ends."""
+    lines = [line.strip() for line in Path(path).read_text().splitlines() if line.strip()]
+    if lines and lines[0].startswith(">"):
+        lines = lines[1:]
+    if any(line.startswith(">") for line in lines):
+        sys.exit(f"{path}: one sequence per file, please (multi-record FASTA found).")
+    dna = "".join(lines).upper().strip("N")
+    if not re.fullmatch("[ACGT]+", dna):
+        sys.exit(f"{path}: Carbon-X reads A/C/G/T; remove other characters first.")
+    return dna
+
+
+def post(route: str, payload: dict) -> dict:
+    request = urllib.request.Request(f"{BASE_URL}/{route}", json.dumps({"model": MODEL, **payload}).encode(),
+                                     {"Content-Type": "application/json", **({"Authorization": f"Bearer {API_KEY}"} if API_KEY else {})})
+    with urllib.request.urlopen(request, timeout=600) as response:
+        return json.load(response)
+
+
+def ask(question: str, sequences: dict[str, str], context: str = "", max_tokens: int = 4096) -> dict:
+    """Ask a question about named DNA sequences. Returns Carbon-X's answer, a model prediction."""
+    parts = [context, question] if context else [question]
+    parts += [f"{name}: <dna>{dna}</dna>" for name, dna in sequences.items()]
+    response = post("chat/completions", {"messages": [{"role": "user", "content": "\n\n".join(parts)}],
+                                         "max_tokens": max_tokens, "chat_template_kwargs": {"enable_thinking": False}})
+    choice = response["choices"][0]
+    return {"answer": choice["message"]["content"], "truncated": choice["finish_reason"] == "length"}
+
+
+def log_likelihood(dna: str) -> float:
+    """Total log-likelihood (nats) of the DNA tokens of `<dna>{dna}</dna>` under Carbon-X."""
+    response = post("completions", {"prompt": f"<dna>{dna}</dna>", "max_tokens": 1, "temperature": 1.0,
+                                    "prompt_logprobs": 0, "add_special_tokens": False, "return_token_ids": True})
+    choice = response["choices"][0]
+    ids, logprobs = choice["prompt_token_ids"], choice["prompt_logprobs"]
+    n = (len(dna) + 5) // 6  # one token per 6 bases; a shorter tail gets its own token
+    if len(ids) != n + 2:  # <dna>, n DNA tokens, </dna>
+        sys.exit("The server did not tokenize the DNA as expected; is it serving Carbon-X with --trust-remote-code?")
+    return sum(logprobs[i][str(ids[i])]["logprob"] for i in range(1, n + 1))
+
+
+def compare(reference: str, alternatives: dict[str, str]) -> dict:
+    """Rank equal-length alternatives by log-likelihood relative to the reference (higher is more typical DNA).
+
+    This is sequence likelihood, not a calibrated pathogenicity score.
+    """
+    if any(len(dna) != len(reference) for dna in alternatives.values()):
+        sys.exit("compare needs equal-length sequences; for insertions or deletions, use ask.")
+    base = log_likelihood(reference)
+    rows = [{"name": name, "delta_log_likelihood": log_likelihood(dna) - base,
+             "substitutions": sum(a != b for a, b in zip(reference, dna))} for name, dna in alternatives.items()]
+    return {"reference_log_likelihood": base, "alternatives": sorted(rows, key=lambda r: -r["delta_log_likelihood"])}
+
+
+def named(items: list[str]) -> dict[str, str]:
+    pairs = [item.split("=", 1) for item in items]
+    if any(len(pair) != 2 for pair in pairs):
+        sys.exit("Use NAME=FILE for each sequence.")
+    return {name: read_dna(path) for name, path in pairs}
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    a = sub.add_parser("ask")
+    a.add_argument("--question", required=True)
+    a.add_argument("--sequence", action="append", default=[], metavar="NAME=FILE")
+    a.add_argument("--context", default="")
+    c = sub.add_parser("compare")
+    c.add_argument("--reference", required=True, metavar="FILE")
+    c.add_argument("--alternative", action="append", required=True, metavar="NAME=FILE")
+    args = parser.parse_args()
+    if args.command == "ask":
+        result = ask(args.question, named(args.sequence), args.context)
+    else:
+        result = compare(read_dna(args.reference), named(args.alternative))
+    print(json.dumps(result, indent=2))