# AI use cases for Needle (AbuZar-Ansarii/Needle)

Repo: [AbuZar-Ansarii/Needle](https://github.com/AbuZar-Ansarii/Needle) | Use cases: 3 | Page: https://dedupedai.com/use-cases/abuzar-ansarii-needle/

A local, lightweight agentic assistant for Android/Termux that controls phone hardware and runs plain English commands through Cactus Needle 2 or Needle 3 models.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Control your phone by texting a Telegram bot: https://dedupedai.com/use-cases/abuzar-ansarii-needle/control-phone-from-telegram/
- Find contacts by meaning with a local semantic search: https://dedupedai.com/use-cases/abuzar-ansarii-needle/search-contacts-by-meaning/
- Pull structured contact fields out of messy text: https://dedupedai.com/use-cases/abuzar-ansarii-needle/extract-fields-from-text-with-needle/

## How to control your phone by texting a Telegram bot with Needle

Repo: [AbuZar-Ansarii/Needle](https://github.com/AbuZar-Ansarii/Needle) | Difficulty: Intermediate | Time: 60 minutes | Basis: From the README

Run a background Telegram listener so text commands like flashlight or battery status run on your phone.

**Who it is for:** A phone owner who is away from the device and wants to check battery or toggle hardware by sending a message from Telegram.

**The problem:** Checking or changing phone state, such as battery level or the flashlight, requires being physically near the phone.

**The outcome:** Texts sent to your bot return results from the phone, and you can switch models with /model from Telegram.

### Steps

1. In Termux, run `pkg update && pkg upgrade`, then `pkg install termux-api python git`, `pkg install proot-distro`, `proot-distro install ubuntu`, and `proot-distro login ubuntu`.
2. Inside Ubuntu, run `apt update && apt upgrade -y` and `apt install git python3 python3-pip python3-venv ca-certificates -y`.
3. Run `git clone https://github.com/AbuZar-Ansarii/Needle.git`, then `cd Needle`, `python3 -m venv myenv`, `source myenv/bin/activate`, and `pip3 install -r requirements.txt`.
4. Start the listener with `python3 app.py --model 3 --telegram YOUR_BOT_TOKEN`, replacing YOUR_BOT_TOKEN with your token.
5. Send your bot a message such as "what is the battery percentage and health?" and check that the reply contains battery details.

### Prompt to paste into your agent

```text
Using the Needle repo at <repo path>, set up the Termux environment, then start the Telegram listener with python3 app.py --model 3 --telegram <bot token>. Send the bot the message "turn on the flashlight" and report the reply. Verify that the reply confirms the torch action and that /model returns the current model.
```

### Caveat

The README does not describe the Telegram bot's access controls, so anyone who can message the bot may be able to trigger phone commands.

Risk, credentials: The Telegram bot token gives control over the phone's listener, so keep it private and do not paste it into shared logs or chats.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/abuzar-ansarii-needle/control-phone-from-telegram/

## How to find contacts by meaning with a local semantic search with Needle

Repo: [AbuZar-Ansarii/Needle](https://github.com/AbuZar-Ansarii/Needle) | Difficulty: Intermediate | Time: 60 minutes | Basis: From the README

Ask the Needle 3 model to search your contacts for a concept like doctor or emergency.

**Who it is for:** A user with a long contact list who remembers the role of a person but not their name.

**The problem:** Keyword lookup in a contact book fails when you only remember what someone does, such as a doctor or an emergency contact.

**The outcome:** A list of contacts that match the meaning of your query, produced by the on-device Needle 3 model.

### Steps

1. Complete the Termux and Ubuntu setup in the README, then run `git clone https://github.com/AbuZar-Ansarii/Needle.git`, `cd Needle`, and `pip3 install -r requirements.txt` inside an activated virtual environment.
2. Start the assistant with `python termux_needle.py --model 3`.
3. At the prompt, type "semantically search contacts for doctor or emergency".
4. Read the returned contacts and confirm that the matches fit the role you asked for.
5. To use the vector search directly, open app.py and check how the /api/embed endpoint expects its input before calling it. (inferred, check the README)

### Prompt to paste into your agent

```text
In the Needle repo, start python termux_needle.py --model 3 and send the prompt "semantically search contacts for doctor or emergency". Return the matched contacts as a list. Verify that each result actually matches the requested role before reporting it.
```

### Caveat

The README lists semantic contact search as a Needle 3 feature, but it does not say how contact data is loaded, so you may need to check the code to confirm results.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/abuzar-ansarii-needle/search-contacts-by-meaning/

## How to pull structured contact fields out of messy text with Needle

Repo: [AbuZar-Ansarii/Needle](https://github.com/AbuZar-Ansarii/Needle) | Difficulty: Intermediate | Time: 60 minutes | Basis: From the README

Use Needle 3 structured extraction to turn a sentence into fields like name, phone, and email.

**Who it is for:** A person who receives contact details in free text, such as a message or a note, and needs them in a structured form.

**The problem:** Contact details buried in a sentence have to be copied by hand into fields, which is slow and error prone.

**The outcome:** Structured contact information pulled from the input text by the on-device Needle 3 model.

### Steps

1. Complete the Termux and Ubuntu setup from the README, then clone the repo and install requirements.txt in an activated virtual environment.
2. Start the command-line assistant with `python termux_needle.py --model 3`.
3. Type "extract contact info from: Call Alex Vance at +15550199 alex@city17.org" at the prompt.
4. Compare the extracted name, phone number, and email with the original sentence.
5. Repeat with your own text, changing only the sentence after the colon.

### Prompt to paste into your agent

```text
In the Needle repo, run python termux_needle.py --model 3 and submit "extract contact info from: <text>" with the target text. Expect structured contact fields with name, phone, and email. Verify that each field appears verbatim in the input text before using the result.
```

### Caveat

The README gives one example of structured extraction and does not describe the output format, so check the returned fields against the source text each time.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/abuzar-ansarii-needle/extract-fields-from-text-with-needle/