Preset Model Configurations for Needle 2: Smart Home, Robot, and Device Explained

Needle 2 ships with three preset model configurations—Smart Home, Robot, and Device—that pre-define JSON tool schemas and starter queries in needle/playground/app.js, allowing you to test multi-tool agents instantly without writing custom schemas.

The cactus-compute/needle repository provides these preset model configurations for Needle 2 to accelerate prototyping. Each preset bundles domain-specific tool definitions and a sample prompt, demonstrating how the library handles parallel function calling for home automation, robotics, and device control scenarios.

Available Preset Model Configurations in Needle 2

The playground exposes three distinct presets via the PRESETS object defined in needle/playground/app.js. Each key maps to a tool list and default query string.

Smart Home (home)

The home preset models a voice-controlled home-automation assistant. It exposes three tools with strict JSON schemas:

• set_lights — Controls lighting state and brightness
• set_thermostat — Adjusts target temperature
• lock_door — Secures entry points

The default query demonstrates multi-tool orchestration: "dim the bedroom lights to 20 percent and lock the front door".

Robot (robot)

The robot preset simulates a mobile manipulator controller. The tool set includes:

• move — Drives the robot forward, backward, left, or right by a specified distance in meters
• rotate — Pivots left or right by degrees
• gripper — Opens or closes the end effector

This preset's starter prompt chains sequential actions: "move forward 2 meters, turn left 90 degrees, then close the gripper".

Device (device)

The device preset handles generic device-control tasks. It currently surfaces:

• open_website — Launches a URL in a new browser tab

Additional device-specific tools are defined within the same configuration object, though the example query varies based on the playground UI state.

How Presets Are Implemented in the Source Code

Preset definitions live in the global PRESETS variable inside needle/playground/app.js. The object structure maps string keys to configuration objects containing a tools array and a q string:

// Located in needle/playground/app.js
var PRESETS = {
  "home": {
    "tools": [
      { 
        "name": "set_lights", 
        "description": "Turn lights on or off or dim them.",
        "parameters": {
          "type": "object",
          "properties": {
            "room": { "type": "string", "description": "Which room." },
            "state": { "type": "string", "enum": ["on","off"] },
            "brightness": { "type": "integer", "description": "Percent 1-100." }
          },
          "required": ["room","state"]
        }
      }
      // ... additional tools ...
    ],
    "q": "dim the bedroom lights to 20 percent and lock the front door"
  }
  // ... robot and device presets ...
};

When a user clicks a preset button in needle/playground/index.html, the applyPreset(key) function hydrates the UI:

function applyPreset(key) {
  var p = PRESETS[key];
  document.getElementById("tools").value = JSON.stringify(p.tools, null, 2);
  document.getElementById("query").value = p.q;
  newChat();
  document.getElementById("query").focus();
}

This copies the JSON schema into the Tools textarea, populates the Query box, and resets the conversation context.

Using Needle 2 Presets Programmatically

You can replicate any preset configuration in Python by passing the identical tool schema to the Needle agent class. This decouples the preset definitions from the web UI, allowing server-side automation:

import needle

# Replicating the Smart Home preset model configuration

tools = [
    {
        "name": "set_lights",
        "description": "Turn lights on or off or dim them.",
        "parameters": {
            "type": "object",
            "properties": {
                "room": {"type": "string", "description": "Which room."},
                "state": {"type": "string", "enum": ["on", "off"]},
                "brightness": {"type": "integer", "description": "Percent 1-100."},
            },
            "required": ["room", "state"],
        },
    },
    # Add set_thermostat and lock_door schemas here...

]

agent = needle.Needle(tools=tools)
resp = agent.run("dim the bedroom lights to 20 percent and lock the front door")
print(resp["results"])

# Output: [{'room': 'bedroom', 'state': 'on', 'brightness': 20}, {'door': 'front'}]

The needle/cli.py entry point also accepts custom tool schemas that mirror these preset structures, enabling command-line experimentation with the same domain-specific tool sets.

Summary

• Needle 2 provides three preset model configurations: Smart Home (home), Robot (robot), and Device (device), each defined in needle/playground/app.js.
• Each preset bundles tool schemas and a starter query, pre-loading the playground UI via the applyPreset() function.
• Smart Home controls lights, thermostats, and locks; Robot handles movement, rotation, and grippers; Device manages generic control tasks like opening URLs.
• You can reuse these configurations programmatically by passing the identical JSON schema to the needle.Needle() constructor in Python or via the CLI.

Frequently Asked Questions

What are the preset model configurations for Needle 2?

Needle 2 includes three preset model configurations: Smart Home (home automation with lights, thermostats, and locks), Robot (mobile robot control with movement and grippers), and Device (generic device control including website opening). These are defined in the PRESETS object within needle/playground/app.js.

How do I load a preset in the Needle 2 playground?

Click any preset button in the web interface rendered by needle/playground/index.html. This triggers applyPreset(key), which copies the tool JSON into the Tools textarea and the example query into the Query box, then resets the chat context.

Can I use Needle 2 presets outside the web UI?

Yes. Copy the tool schema array from needle/playground/app.js and pass it to the needle.Needle(tools=...) constructor in Python, or supply it via needle/cli.py. The presets are simply JSON configurations that work anywhere the library runs.

Where are the preset definitions stored?

All preset model configurations are stored in needle/playground/app.js as the PRESETS JavaScript object. The UI wiring lives in the same file via the applyPreset() function, while the HTML structure is defined in needle/playground/index.html.

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