# How to Provide System Facts for Contextual Grounding in Needle

> Learn how to provide system facts for contextual grounding in Needle. Utilize the SYSTEM string in environment modules to define LLM mappings and handle ambiguous inputs effectively.

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

---

**In Needle, system facts for contextual grounding are provided through the `SYSTEM` string in environment modules, which defines how the LLM maps user requests to tool calls and handles ambiguous inputs.**

Needle is an open-source framework from cactus-compute for building conversational agents that invoke specific tools based on natural language input. To ground the LLM's behavior in deterministic rules, you provide **system facts for contextual grounding in Needle** through declarative environment modules that declare both available tools and behavioral constraints.

## Understanding the Three Core Symbols

Every Needle environment module exports three essential symbols that work together to provide contextual grounding:

- **TOOLS** – A list of `@needle.tool`‑decorated functions that the model may invoke.
- **SYSTEM** – The system prompt string containing the system facts that guide the model’s behavior and grounding.
- **agent** – A ready‑to-use `needle.Needle` instance created automatically from the `TOOLS` and `SYSTEM` symbols.

When an environment module is imported, the private harness in [`needle/environments/_harness.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/_harness.py) registers the agent by passing these symbols to the Needle constructor:

```python

# needle/environments/_harness.py (excerpt)

_agents[key] = needle.Needle(tools=module.TOOLS, system=module.SYSTEM)

```

Thus, the system facts you write in `SYSTEM` are automatically supplied to the LLM each time the environment’s `agent` is accessed.

## How System Facts Are Structured

Each environment provides a concise, declarative system prompt that defines the rules of engagement. According to the source code, effective system facts in Needle follow specific patterns:

- **Verbatim preservation** – In [`needle/environments/data_capture.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/data_capture.py), the system instructs the model to "Copy names, merchants, and descriptions verbatim from the user" to ensure downstream data consistency.
- **Deterministic mapping** – In [`needle/environments/smart_home.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/smart_home.py), the system enforces a "one‑to‑one mapping of home actions" to prevent the model from guessing targets or values.
- **Explicit action rules** – In [`needle/environments/wearable.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/wearable.py), the system maps "each watch action to a single call" while preserving text capitalization.

A typical `SYSTEM` string looks like this:

```python
SYSTEM = ("Copy names, merchants, and descriptions verbatim from the user. "
          "Record only values the user stated; never estimate. "
          "Map each explicit supported record to exactly one declared call. "
          "Unsupported, incomplete, ambiguous, and negated requests return no call.")

```

These constraints act as safety guardrails, preventing the model from hallucinating data when requests are ambiguous or negated.

## Creating Custom System Facts

To provide custom system facts for a new domain, create a new environment module in `needle/environments/`. For example, to create a **Finance** environment:

```python

# needle/environments/finance.py

import needle
from needle.environments import _harness

@needle.tool
def log_invoice(amount: float, client: str):
    """Record an invoice amount for a client."""
    return {"ok": True, "amount": amount, "client": client}

TOOLS = [log_invoice]

SYSTEM = (
    "Copy client names verbatim. Log only the amount the user explicitly states. "
    "Map each invoice log request to exactly one declared call. "
    "Do not guess missing amounts or clients; unsupported or negated requests return no call."
)

```

Once the module is added, the harness automatically exposes the `agent` attribute, allowing you to use it via:

```python
from needle.environments import finance

response = finance.agent.run("Create an invoice for Acme Corp of $2,500")

# → {"ok": True, "amount": 2500.0, "client": "Acme Corp"}

```

## Overriding System Facts at Runtime

If you need to override the system prompt for a specific use case without creating a new environment module, instantiate a custom `Needle` instance directly:

```python
import needle
from needle.environments.data_capture import TOOLS

custom_system = (
    "Copy only the name; ignore phone numbers even if provided. "
    "Map to the create_contact tool."
)

custom_agent = needle.Needle(tools=TOOLS, system=custom_system)
print(custom_agent.run("Add John Doe, phone 555‑0000"))

# → {'ok': True, 'name': 'John Doe', 'phone': None, 'email': None}

```

This approach allows you to provide contextual grounding variations while reusing the same tool definitions from existing environments.

## Summary

- **System facts** are defined as the `SYSTEM` string in environment modules, providing the behavioral constraints that ground the LLM's decision-making.
- The **harness mechanism** in [`needle/environments/_harness.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/_harness.py) automatically binds `SYSTEM` and `TOOLS` to create the `agent` instance.
- Default environments like [`data_capture.py`](https://github.com/cactus-compute/needle/blob/main/data_capture.py), [`smart_home.py`](https://github.com/cactus-compute/needle/blob/main/smart_home.py), and [`wearable.py`](https://github.com/cactus-compute/needle/blob/main/wearable.py) demonstrate patterns for verbatim copying, deterministic mapping, and action isolation.
- You can create **custom environments** by defining new modules with `SYSTEM` and `TOOLS` symbols, or **override system facts at runtime** by instantiating `needle.Needle` directly.

## Frequently Asked Questions

### What is the SYSTEM variable in Needle?

The `SYSTEM` variable is a string constant defined in environment modules that contains the system prompt or "system facts" instructing the LLM how to behave. It specifies rules for mapping user requests to tool calls, handling verbatim text extraction, and managing ambiguous or negated inputs.

### How does the harness use system facts?

The harness in [`needle/environments/_harness.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/_harness.py) imports environment modules and constructs a `needle.Needle` instance by passing `module.TOOLS` and `module.SYSTEM` to the constructor. It then caches this instance as the `agent` attribute on the module, making the grounded agent available for immediate use.

### Can I override system facts for a single request?

Yes, you can bypass the pre-built environment `agent` and instantiate `needle.Needle` directly with a custom `system` parameter. This allows you to reuse existing `TOOLS` while providing alternative grounding instructions for specific scenarios without modifying the source environment module.

### Where are the default system facts defined?

Default system facts are defined in the individual environment files within `needle/environments/`, such as [`data_capture.py`](https://github.com/cactus-compute/needle/blob/main/data_capture.py) for structured data extraction, [`smart_home.py`](https://github.com/cactus-compute/needle/blob/main/smart_home.py) for home automation, and [`productivity.py`](https://github.com/cactus-compute/needle/blob/main/productivity.py) for calendar and task management. Each file contains a `SYSTEM` string tailored to that domain's specific grounding requirements.