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

Adds a 'Using Carbon-X as a tool for an agent' subsection under How to use: wrapping the vLLM endpoint in a function, an OpenAI-style tool schema that passes DNA by reference, a minimal agent loop, a note on coding-agent skills, and tips. The snippets were tested end to end against the Carbon v26.00 endpoint with Kimi K3 as the agent.

README.md

@@ -24,6 +24,7 @@ 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)
@@ -109,6 +110,92 @@ print(response.choices[0].message.content)
 
 vLLM also applies the sampling defaults from `generation_config.json` unless you override them in the request.
 
+### 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)).
+
 ### Tokenizer: working with DNA inputs
 
 The tokenizer switches between BPE for text and 6-mers for DNA. You can paste sequences directly into a message: