# How to Use Pre‑Built Environments Like smart_home with Needle

> Learn how to use pre-built environments like smart_home with Needle. Issue natural language commands for complex tasks like controlling smart devices easily.

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

---

**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`](https://github.com/cactus-compute/needle/blob/main/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.

```python
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:

```python
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:**

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

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

```

**Command‑line execution:**

```bash
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`](https://github.com/cactus-compute/needle/blob/main/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`](https://github.com/cactus-compute/needle/blob/main/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`](https://github.com/cactus-compute/needle/blob/main/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:

```python
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`](https://github.com/cactus-compute/needle/blob/main/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`](https://github.com/cactus-compute/needle/blob/main/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.