What Are the Recognized System Fact Keys in Needle?

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, 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

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:

# 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:

# 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, 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) 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 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 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, 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 – 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 – Contains tool definitions recognizing action and value keys.
• needle/environments/smart_home.py – Defines smart-home fact keys device, action, location, and value via tool signatures.
• needle/environments/productivity.py – Lists productivity-related fact keys title, message, date, time, and recipients.
• needle/environments/media_player.py – Enumerates media-player fact keys command, media, volume, and track.
• 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) 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—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) 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).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}