# What Are the Recognized System Fact Keys in Needle?

> Discover the recognized system fact keys in Needle. Learn how environment modules define keys via tool arguments and SYSTEM prompts for efficient extraction.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: api-reference
- Published: 2026-09-04

---

**Needle does not use a centralized registry; instead, each environment module in `needle/environments/` defines its own recognized system fact keys through tool function arguments and a SYSTEM prompt that guides the extraction model.**

The open-source Needle framework extracts structured data from natural language using environment-specific tool definitions. Unlike systems that rely on a centralized schema, Needle distributes its **recognized system fact keys** across individual environment modules, with each module declaring exactly which parameters its tools accept through Python function signatures.

## How Needle Defines System Fact Keys

In `cactus-compute/needle`, fact key recognition follows a decentralized pattern. Each environment module contains a **SYSTEM** string constant that instructs the language model to *“Copy … verbatim from the user … Map each explicit supported request to exactly one declared call”* while ensuring that *“Unsupported, ambiguous, and negated requests return no call.”*

Alongside this prompt, **@needle.tool** decorated functions declare the valid key set through their argument names. The model extracts values verbatim only when they match these declared tool signatures.

## Data Capture Environment Fact Keys

The Data Capture environment, defined in [`needle/environments/data_capture.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/data_capture.py), recognizes the most extensive set of fact keys. This module handles contact information, financial transactions, and biometric logging through tools that accept the following arguments:

- `name`, `phone`, `email` for contact management
- `amount`, `category`, `merchant`, `description` for expense tracking
- `meal_type` for meal logging
- `amount_ml` for fluid intake recording
- `weight_kg` for weight measurements

```python
from needle.environments import data_capture

# Keys: name, phone, email

result = data_capture.create_contact(
    name="Maya Chen",
    phone="+1-555-0134",
    email="maya@example.com"
)

# → {"ok": True, "name": "Maya Chen", "phone": "+1-555-0134", "email": "maya@example.com"}

```

You can also log expenses using the financial fact keys:

```python

# Keys: amount, category, merchant

result = data_capture.log_expense(
    amount=85.99,
    category="groceries",
    merchant="FreshMart"
)

# → {"ok": True, "amount": 85.99, "category": "groceries", "merchant": "FreshMart"}

```

For health tracking, the environment accepts biometric-specific keys:

```python

# Key: amount_ml

result = data_capture.log_water_intake(amount_ml=750)

# → {"ok": True, "amount_ml": 750}

```

## Wearable Environment Fact Keys

Located in [`needle/environments/wearable.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/wearable.py), this environment recognizes `action` and `value` as its primary fact keys. According to the source code, the specific interpretation of these keys depends on which wearable tool the model invokes, with each declared tool defining its own context for these parameters.

## Smart Home Environment Fact Keys

The Smart Home module ([`needle/environments/smart_home.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/smart_home.py)) recognizes four primary fact keys: `device`, `action`, `location`, and `value`. As implemented in `cactus-compute/needle`, these keys map to home automation controls where `device` identifies the target hardware and `action` specifies the operation to perform. The exact requirements for `value` and `location` vary by specific tool implementation within the module.

## Productivity Environment Fact Keys

For productivity tasks, [`needle/environments/productivity.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/productivity.py) declares `title`, `message`, `date`, `time`, and `recipients` as recognized system fact keys. These arguments support calendar events, reminders, and communication workflows, with each tool in the environment utilizing a subset of these parameters based on its specific function.

## Media Player Environment Fact Keys

The Media Player environment in [`needle/environments/media_player.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/media_player.py) recognizes `command`, `media`, `volume`, and `track` as valid fact keys. These parameters control playback operations, allowing the extraction model to identify specific instructions for media manipulation such as adjusting `volume` or selecting a `track`.

## Kitchen Appliance Environment Fact Keys

In [`needle/environments/kitchen_appliance.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/kitchen_appliance.py), the recognized system fact keys are `appliance`, `action`, `temperature`, and `duration`. This environment handles cooking instructions and appliance control, requiring these specific argument names to trigger the corresponding tool functions.

## Source Files and Implementation Pattern

Each environment follows an identical architectural pattern across the following key files:

- [`needle/environments/data_capture.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/data_capture.py) – Defines the **SYSTEM** prompt and the full list of data-capture fact keys including `name`, `phone`, `email`, `amount`, and `weight_kg`.
- [`needle/environments/wearable.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/wearable.py) – Contains tool definitions recognizing `action` and `value` keys.
- [`needle/environments/smart_home.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/smart_home.py) – Defines smart-home fact keys `device`, `action`, `location`, and `value` via tool signatures.
- [`needle/environments/productivity.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/productivity.py) – Lists productivity-related fact keys `title`, `message`, `date`, `time`, and `recipients`.
- [`needle/environments/media_player.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/media_player.py) – Enumerates media-player fact keys `command`, `media`, `volume`, and `track`.
- [`needle/environments/kitchen_appliance.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/kitchen_appliance.py) – Provides kitchen-appliance fact keys `appliance`, `action`, `temperature`, and `duration`.

In every file, the combination of the **SYSTEM** instruction string and the **@needle.tool** function signatures creates a strict boundary for which fact keys the model attempts to extract.

## Summary

- Needle distributes **system fact keys** across environment-specific modules rather than using a global registry.
- The Data Capture environment ([`needle/environments/data_capture.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/data_capture.py)) recognizes the broadest set, including `name`, `phone`, `email`, `amount`, `category`, `merchant`, `description`, `meal_type`, `amount_ml`, and `weight_kg`.
- Other environments define specialized keys: Wearable uses `action` and `value`; Smart Home uses `device`, `action`, `location`, and `value`; Productivity uses `title`, `message`, `date`, `time`, and `recipients`; Media Player uses `command`, `media`, `volume`, and `track`; Kitchen Appliance uses `appliance`, `action`, `temperature`, and `duration`.
- Each environment combines a **SYSTEM** prompt with **@needle.tool** function arguments to declare valid extraction keys.
- Unsupported or undefined keys trigger no extraction, ensuring the system returns no call rather than hallucinating values.

## Frequently Asked Questions

### Does Needle maintain a global list of recognized system fact keys?

No. As implemented in `cactus-compute/needle`, there is no centralized registry of valid keys. Each environment module in `needle/environments/` maintains its own schema through Python function arguments, making the system modular and allowing independent extension of fact key sets.

### How do I add custom system fact keys to a Needle environment?

To add custom keys, create or modify an environment file in `needle/environments/` and define a new function decorated with **@needle.tool**. The argument names of this function automatically become recognized system fact keys. You must also update the module's **SYSTEM** prompt to instruct the extraction model about the new capabilities and ensure it maps requests to your new tool.

### What happens when a user mentions a fact key that is not recognized?

The **SYSTEM** prompt in each environment explicitly directs the model to return no call for unsupported, ambiguous, or negated requests. If a user references a key not present in the tool signatures—such as an undefined parameter in [`needle/environments/wearable.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/wearable.py)—the system returns an empty response rather than attempting to map it to an invalid key or fabricating a value.

### Which Needle environment has the most comprehensive fact key coverage?

The Data Capture environment ([`needle/environments/data_capture.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/data_capture.py)) provides the broadest set of recognized keys, handling diverse data types including contact information (`name`, `phone`, `email`), financial data (`amount`, `category`, `merchant`), and biometric logging (`amount_ml`, `weight_kg`, `meal_type`).