How to Use Pre‑Built Environments Like smart_home with Needle

Needle provides ready‑made environments that bundle curated tools, constrained decoding, and frozen acceptance tests into importable Python modules, allowing you to issue natural‑language commands like "turn on the kitchen lights" through a simple agent.complete() call.

The cactus‑compute/needle repository ships with pre‑built environments that demonstrate how to constrain LLM outputs to valid function calls for specific domains. The smart_home environment models household automation scenarios using curated tool definitions and Literal enums, enabling safe natural‑language control of lights and thermostats without writing boilerplate agent code.

Architecture of the smart_home Environment

Internally, smart_home follows a consistent architectural pattern defined in needle/environments/smart_home.py. Understanding these components helps you debug behavior and adapt the pattern to your own domains.

Tool Definitions with Literal Constraints

The environment defines a small set of Tool objects—such as Light and Thermostat—that represent devices in a smart home. Their inputs are expressed as Literal enums (for rooms, actions, and brightness levels) so that Needle’s constrained decoder can safely generate function calls without hallucinating invalid parameters.

System Prompt and Domain Context

A concise system prompt describing the automation domain and enumerating available tools is stored in the module‑level constant SYSTEM. This prompt primes the LLM to generate structured outputs that map to the defined tools while respecting the household context.

Lazy Agent Initialization

When you import the module, Needle creates a lazily‑instantiated agent (an instance of needle.agent.Agent) using the SYSTEM prompt and the TOOLS list. This agent handles LLM‑driven planning and tool invocation automatically, exposing a simple complete() interface for natural‑language requests.

Frozen Acceptance Test Suite

The module bundles a run_tests(min_confidence=0.0) function that executes a frozen set of TEST_CASES. These tests verify the agent’s ability to correctly parse and execute diverse commands, raising AssertionError if any behavior deviates from expected outputs.

Importing and Using the smart_home Environment

Using the environment requires only a standard Python import. The agent is ready to accept commands immediately without additional configuration.

from needle.environments import smart_home

# Issue a natural‑language command; the agent selects and invokes the proper tool

response = smart_home.agent.complete("turn on the kitchen lights")
print(response)   # → "The kitchen lights are now on."

For dimming and other parameterized actions, pass the full natural‑language string describing the desired state:

result = smart_home.agent.complete("dim the study lights to 30 percent")
print(result)   # → "The study lights are set to 30 % brightness."

Running the Acceptance Suite

Validate that the environment behaves correctly on your platform using either programmatic or command‑line interfaces.

Programmatic execution:

smart_home.run_tests()  # raises AssertionError if any test fails

print("All smart‑home tests passed!")

Command‑line execution:

python -m needle.environments.smart_home   # exits with status 0 on success

Running the suite ensures that the constrained decoder and tool definitions in needle/environments/smart_home.py align with the frozen expectations stored in TEST_CASES.

Customizing the Environment for Your Domain

Developers adapting the smart home scenario to specific hardware products can swap the Literal values (rooms, contacts, categories) while preserving the same enum‑shaped definitions. This maintains Needle’s constrained decoding guarantees while reflecting your own domain terminology.

According to the repository documentation in doc/environments.md, you should keep the structure of the Literal types intact—only modify the string values—so that the decoder continues to generate valid function signatures for your specific device ecosystem.

Summary

• Import path: Use from needle.environments import smart_home to access the pre‑built agent and tools immediately.
• Core files: Tool definitions, prompts, and tests live in needle/environments/smart_home.py.
• Interaction model: Call smart_home.agent.complete() with natural‑language strings; the agent handles tool selection and invocation.
• Validation: Execute smart_home.run_tests() or run python -m needle.environments.smart_home to verify behavior against frozen acceptance criteria.
• Extensibility: Replace Literal enum values to adapt the environment to custom smart‑home hardware without breaking constrained decoding.

Frequently Asked Questions

How do I import the smart_home environment in Needle?

Import the module directly from the needle.environments package. The agent initializes lazily on first access, making it available immediately for command processing:

from needle.environments import smart_home
response = smart_home.agent.complete("your command here")

What tools are available in the smart_home environment?

The environment exposes tools such as Light and Thermostat, defined in needle/environments/smart_home.py. These tools accept parameters constrained by Literal enums representing rooms, actions, and numeric values, ensuring the LLM generates only valid function calls.

How do I run acceptance tests for the smart_home environment?

Call smart_home.run_tests(min_confidence=0.0) programmatically to execute the frozen TEST_CASES suite against the current agent configuration. Alternatively, run python -m needle.environments.smart_home from your shell; the process exits with status 0 on success and raises errors on failure.

Can I customize the rooms and devices in the smart_home environment?

Yes. You can modify the Literal string values in needle/environments/smart_home.py to reflect your specific rooms, device names, or categories while keeping the enum structure unchanged. This customization allows the constrained decoder to support your domain terminology while maintaining type safety.

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