Move the agent-tool section to the end of the model card

README.md

@@ -24,12 +24,12 @@ An open 14B language model for DNA understanding and generation, from the **Carb
 
 1. [Model Summary](#model-summary)
 2. [How to use](#how-to-use)
-   - [Using Carbon-X as a tool for an agent](#using-carbon-x-as-a-tool-for-an-agent)
 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)
 
 ## Model Summary
 
@@ -132,92 +132,6 @@ The tokenizer switches between BPE for text and 6-mers for DNA. You can paste se
 - Include any context you already have, such as the gene, strand, coordinates or annotations. Without it, the model may guess at a sequence's identity or function.
 - For variant questions, give the reference and alternate sequences, or a reference sequence with the position and the base change.
 
-### 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.
-
-```python
-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
-```
-
-**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.
-
-```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)
-```
-
-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.
-
-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)).
-
 ## 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. All results below are for the released checkpoint, with thinking disabled, the default sampling settings and one sample per problem.
@@ -333,3 +247,89 @@ 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.
+
+```python
+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
+```
+
+**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.
+
+```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)
+```
+
+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.
+
+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)).