# Needle System Facts: Complete List of Recognized Keys and Usage Guide

> Explore the eight recognized system facts keys in Needle: date, locale, device, battery, network, location, user, and assistant. Learn how to use them effectively.

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

---

**Needle recognizes eight specific keys for system facts—`date`, `locale`, `device`, `battery`, `network`, `location`, `user`, and `assistant`—and silently ignores any other keys you provide.**

The **Needle** inference engine from Cactus Compute lets you supply contextual environment information through a *system turn*. This feature helps the model resolve relative references, adapt to device constraints, and personalize responses. According to the `cactus-compute/needle` source code, only a closed set of keys triggers special model behavior; unrecognized keys pass through as plain text without affecting grammar or tool selection.

## How System Facts Work in Needle

When you initialize a `Needle` instance, the `system` parameter accepts a UTF-8 string that the native engine parses into structured facts. In [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) (lines 55-64), the Python binding encodes this string and passes it to `needle_init`. The engine expects semicolon-separated `key: value` pairs, then extracts only the recognized keys for its internal context.

This design means you can safely experiment with custom metadata—anything outside the eight official keys simply won't influence the model's reasoning.

## Complete List of Needle System Fact Keys

Based on the canonical documentation in [`llms.txt`](https://github.com/cactus-compute/needle/blob/main/llms.txt) (lines 36-40) and [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md) (lines 36-45), Needle supports the following keys:

| Key | Purpose | Example Value |
|-----|---------|---------------|
| `date` | Current date and time | `2026-07-21 Tue 14:30` |
| `locale` | Language and region code | `en-US`, `fr-FR` |
| `device` | Hardware form factor | `phone`, `laptop`, `tablet` |
| `battery` | Power level or charging status | `62%`, `charging` |
| `network` | Connectivity state | `wifi`, `offline`, `cellular` |
| `location` | Geographic identifier | `NYC`, `Paris` |
| `user` | End-user identifier | `alice@example.com` |
| `assistant` | Assistant persona name | `my-assistant` |

These keys are **case-sensitive** and must match exactly. The model uses this context to resolve ambiguities—for example, interpreting "tomorrow" relative to the provided `date` or selecting tools based on `device` capabilities.

## Code Examples

### Basic Usage with Common Facts

```python
import needle

# Initialize with essential context

agent = needle.Needle(
    tools=[my_tool],
    system="date: 2026-07-21 Tue 14:30; locale: en-US; device: phone; battery: 78%"
)

# The model resolves "tomorrow at 7" using the provided date

response = agent.complete("Remind me tomorrow at 7 to call Mom")
print(response["function_calls"])

```

### Full System Turn with All Recognized Keys

```python

# Comprehensive environment description

system_facts = (
    "date: 2026-09-15 Thu 09:00; "
    "locale: fr-FR; "
    "device: laptop; "
    "battery: 45%; "
    "network: wifi; "
    "location: Paris; "
    "user: jean@example.com; "
    "assistant: my-assistant"
)

agent = needle.Needle(tools=my_schema, system=system_facts)
print(agent.run("What's the weather like tomorrow?"))

```

### Omitting System Facts Entirely

```python

# Safe to initialize without context

agent = needle.Needle(tools=my_schema)
print(agent.complete("What time is it?"))

```

## Key Implementation Files

Understanding the source helps avoid common pitfalls:

- **[`llms.txt`](https://github.com/cactus-compute/needle/blob/main/llms.txt)** – The authoritative reference listing recognized keys and their semantics.
- **[`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md)** – Public API documentation with usage patterns and validation rules.
- **[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)** – Python binding implementation showing how `system` strings are encoded and validated before native engine handoff.

## Common Mistakes to Avoid

- **Typos in keys**: `battery_level` will not trigger battery-aware behavior—use `battery` exactly.
- **Wrong separator**: Use semicolons between pairs, not commas or newlines.
- **Over-quoting**: Pass the raw string; the library handles UTF-8 encoding internally.

## Summary

- Needle recognizes **eight system fact keys**: `date`, `locale`, `device`, `battery`, `network`, `location`, `user`, and `assistant`.
- Format facts as **semicolon-separated `key: value` pairs** in the `system` parameter.
- Unrecognized keys are **silently ignored**—they don't cause errors but don't affect model behavior either.
- Source documentation lives in **[`llms.txt`](https://github.com/cactus-compute/needle/blob/main/llms.txt)** and **[`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md)**, with implementation details in **[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)**.

## Frequently Asked Questions

### What happens if I use a key that's not in the recognized list?

Unrecognized keys are treated as plain text and ignored by the model's context system. They pass through to the native engine without influencing grammar, tool selection, or reasoning. The [`llms.txt`](https://github.com/cactus-compute/needle/blob/main/llms.txt) specification explicitly states this behavior for forward compatibility.

### Can I update system facts after creating a Needle instance?

No. The `system` parameter is processed once during initialization in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py). To change facts, create a new `Needle` instance with updated values. This design keeps the native engine context immutable during inference.

### Does the `date` key require a specific format?

While the examples show `YYYY-MM-DD Ddd HH:MM`, the engine accepts any reasonably unambiguous datetime string. The model extracts temporal references relative to whatever timestamp you provide, so consistency matters more than strict formatting.

### Is the `system` parameter optional?

Yes. As shown in the third code example, `needle.Needle()` initializes successfully without a `system` argument. The model simply operates without environmental context, which may reduce accuracy for time-sensitive or location-dependent queries.