README.md

---
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`.

```sh
# pull the archive
needle download Qrzysztof/get-name
```

```python
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.