How to Provide System Facts for Contextual Grounding in Needle

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 registers the agent by passing these symbols to the Needle constructor:

# 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, 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, 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, the system maps "each watch action to a single call" while preserving text capitalization.

A typical SYSTEM string looks like this:

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:

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

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:

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 automatically binds SYSTEM and TOOLS to create the agent instance.
• Default environments like data_capture.py, smart_home.py, and 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 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 for structured data extraction, smart_home.py for home automation, and productivity.py for calendar and task management. Each file contains a SYSTEM string tailored to that domain's specific grounding requirements.

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