Move the agent-tool section before Limitations; link example files instead of inlining them

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,151 +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.
-
-```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)
-```
-
+Ready-to-run examples in this repository build on this function:
 
-### With Inspect
+- **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).
 
-In [Inspect](https://inspect.aisi.org.uk/), wrap Carbon-X in an `@tool` and give it to a `react()` agent. Each sample
-keeps its DNA in metadata, so the agent refers to sequences by name.
-
-```python
-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())
+  ```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
 
-eval(carbon_agent(), model="openai/gpt-5")  # any Inspect model with tool calling as the agent
-```
+- **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.
+- **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)).
 
-### As a skill for coding agents
+## Limitations
 
-This repository includes a ready-made skill in [`skills/carbon-dna/`](skills/carbon-dna/): a `SKILL.md` that tells the
-agent when and how to consult Carbon-X, and a standard-library Python script with two commands, `ask` (a question about
-named DNA files) and `compare` (rank equal-length variants by sequence likelihood).
+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.
 
-```bash
-hf download HuggingFaceBio/Carbon-X --include "skills/*" --local-dir carbon-x
-cp -r carbon-x/skills/carbon-dna ~/.claude/skills/    # Claude Code; Codex CLI: ~/.codex/skills/
-export CARBON_BASE_URL=http://localhost:8000/v1        # your Carbon-X server
-```
+- ⚠️ **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.
 
-The script also runs on its own:
+## License
 
-```bash
-python carbon-x/skills/carbon-dna/scripts/carbon.py ask --sequence reference=ref.fa --sequence variant=alt.fa \
-  --question "Is the variant benign or pathogenic?" --context "Position 20: A>T"
-```
+Apache 2.0.
 
-### Tips for agent use
+## Acknowledgements
 
-- **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)).
+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