README.md

metadata

language:
  - en
license: apache-2.0
datasets:
  - cactus-needle/base
metrics: []
model-index: []
pipeline_tag: text-generation
base_model: Cactus-Compute/needle2
tags:
  - needle
  - cactus-needle
  - tool-calling
  - named-entity-extraction
  - lora

Get Name — addressee/given-name extraction for cactus-needle

get-name is a small LoRA fine-tune of the cactus-needle base model (Cactus-Compute/needle2) that extracts the given (first) name of the intended person in a piece of text.

It was trained to answer one question: "which single person is this text about / addressed to, and what is that person's first name?" — and to call a tool only when such a person exists.

Input	Output
Nice to meet you, Alex	Alex
By the way, Alice, if you don't know, how old am I?	Alice
The birth certificate was issued to John Snow	John
Right now, there are me, Carl, Stephanie, and you, Greg, in the room.	Greg
Please let Maria know about the meeting.	Maria
Give this package to Lucas.	Lucas
Hi everyone, thanks for coming.	(no call)
My brother Carl lives in Boston.	(no call — mention, not target)

Behaviour

• Given name only. Full names are collapsed to the first name on purpose (John Snow → John, James Miller → James).
• Single target. In enumerations the person directly addressed (you, Greg) is preferred over names merely listed (the team was Carl, Stephanie, and Greg → no call).
• No call when there is no target: group greetings, place names, brands, assistants (Siri/Alexa), generic salutations, and passive mentions.

How to use

The archive is a needle .cact weights file for cactus-needle.

# pull the archive
needle download Qrzysztof/get-name

from needle import Needle

tool = {
    "name": "extract_name",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "The given (first) name of the intended person; never the surname.",
            }
        },
        "required": ["name"],
    },
}
system = (
    "You extract the given (first) name of the intended person. "
    "If the text has no intended person, do not call the tool."
)

agent = Needle(tools=[tool], weights="tuned.cact", system=system)
print(agent.complete("Nice to meet you, Alex"))
# {"name": "Alex"}

Note: the system prompt above is mandatory for best results — the model was trained with it in every example and the same string must be passed at inference.

Training

• Method: LoRA adapters (rank 16, alpha 32) on the five attention projections of every layer of a frozen Cactus-Compute/needle2 base; engine, tokenizer and confidence head untouched. Adapter merged into the weights at export.
• Data: ~1,100 hand-curated, template-augmented examples in needle's tool-calling JSONL format (data.jsonl in this repo), 88 % positive / 12 % negative, covering:
  • greetings & welcomes,
  • vocative / direct address (incl. titled forms, Dr. John Snow, …),
  • documents issued to a person (birth certificates, passports, licences…),
  • enumerations with an addressed member (…and you, Greg,…),
  • message targets and relays (Tell Maria…, Pass this note to Owen…),
  • off-topic no-call examples (groups, places, brands, assistants, generic salutations).
• Hyper-parameters: batch 16, lr 1e-4 with warmup + cosine decay, grad clip 1.0, epochs chosen so the held-out loss lands ~0.5 (see Known limitations), validation split 0.1, seq len 256.
• Recipe: needle finetune data.jsonl --epochs 9 --lora-rank 16 then needle build checkpoints/needle2.pkl --lora adapter.pkl --out tuned.cact.

Training ran on a single Colab T4 and took a few minutes per run.

Known limitations

• False-positive rejection is the weak point. The tuning budget between never calls the tool and calls a tool on everything is narrow for this "is it really addressed to a person?" discrimination. This release is tuned on the extraction side (strong recall on intended targets). If you need stricter rejection, retrain with a higher negative share (25 %+) and stop a little earlier on the validation curve.
• Sequential calls in one process: repeated complete() calls in the same long-lived process showed degraded output on later calls. For batch work, run one fresh process per text (one query each) or recreate the Needle object between batches.
• Confidence head is not tuned: tuned weights report confidence as None and a warning is emitted at construction (expected with needle LoRA blends).
• Non-English input: like the base model, out-of-domain text (and Spanish in particular) is not well calibrated.

Files

• tuned.cact — merged, exported weights (13.7 MB) for Needle(weights=...).
• data.jsonl — the training dataset (browser-search friendly, one JSON object per line).
• tool.json — the extract_name tool schema.
• README.md — this card.