Supported Constraints for needle.Field in Cactus Needle

The needle.Field class accepts 15 optional constructor arguments—including ge, le, pattern, enum, and const—that map directly to JSON-Schema validation keywords for automatic tool schema generation.

needle.Field is a helper class provided by the cactus-compute/needle repository to attach JSON-Schema constraints to function parameters in the tool-generation system. When you decorate a function with @tool, using Field as a default value allows you to enforce validation rules that are automatically translated into the generated schema according to the implementation in needle/agent/tools.py.

Overview of needle.Field Constraints

When a Field instance is created, its constructor accepts a set of optional arguments that map directly to JSON-Schema validation keywords. These arguments are then applied to the generated schema in the apply method. This approach bridges Python type hints with strict JSON-Schema validation without requiring manual schema writing.

The constructor signature is defined in needle/agent/tools.py at lines 18-32, with the constraint mapping logic implemented in the apply method at lines 36-49.

Complete List of Supported Constraints

The needle.Field constructor supports the following validation constraints, organized by data type:

Numeric Constraints:

• ge – Maps to minimum (inclusive minimum value)
• le – Maps to maximum (inclusive maximum value)
• gt – Maps to exclusiveMinimum (exclusive minimum value)
• lt – Maps to exclusiveMaximum (exclusive maximum value)
• multiple_of – Maps to multipleOf (value must be a multiple of this number)

String Constraints:

• min_length – Maps to minLength (minimum character count)
• max_length – Maps to maxLength (maximum character count)
• pattern – Maps to pattern (regular expression the string must match)
• format – Maps to format (JSON-Schema format hint such as "date-time")

Array Constraints:

• min_items – Maps to minItems (minimum number of elements)
• max_items – Maps to maxItems (maximum number of elements)
• unique_items – Maps to uniqueItems (if True, all array elements must be unique)

General Constraints:

• description – Maps to description (human-readable documentation)
• enum – Maps to enum (list of allowed values)
• const – Maps to const (constant value the field must equal)

How Constraints Map to JSON-Schema

According to the source code in needle/agent/tools.py, the constraint application occurs in two phases. First, the Field class constructor captures the validation parameters. Then, the apply method injects these values into the JSON-Schema dictionary using standard JSON-Schema keywords.

For example, when you specify gt=0 in the constructor, the apply method sets exclusiveMinimum: 0 in the resulting schema. This ensures that language models and validation tools receive properly formatted schema metadata.

Practical Code Examples

The following examples demonstrate how to use needle.Field constraints with the @tool decorator:

from needle.agent.tools import Field, tool

# Numeric range with exclusive bounds

@tool
def set_volume(level: int = Field(gt=0, lt=101)):
    """Set the speaker volume."""
    pass

# String with pattern and length limits

@tool
def create_username(name: str = Field(
    min_length=3, 
    max_length=12,
    pattern=r'^[a-zA-Z0-9_]+$',
    description="Alphanumeric username"
)):
    """Create a new user account."""
    pass

# Enum of allowed options

@tool
def select_color(color: str = Field(enum=["red", "green", "blue"])):
    """Choose a color from the allowed set."""
    pass

# Constant value for hidden parameters

@tool
def submit_job(job_id: str = Field(const="fixed-id")):
    """Submit a job with a predetermined identifier."""
    pass

Summary

• needle.Field supports 15 distinct constraints that map directly to JSON-Schema validation keywords.
• Constraints are defined in the constructor at needle/agent/tools.py lines 18-32 and applied via the apply method at lines 36-49.
• Supported categories include numeric ranges, string validation, array properties, and general metadata like enum and const.
• All constraints are optional and can be combined to create complex validation rules for tool parameters.

Frequently Asked Questions

What is the difference between ge/le and gt/lt in needle.Field?

The ge (greater than or equal) and le (less than or equal) arguments map to JSON-Schema's inclusive minimum and maximum keywords. In contrast, gt (greater than) and lt (less than) map to exclusiveMinimum and exclusiveMaximum, which exclude the boundary value itself. Use ge/le when the endpoint is valid, and gt/lt when it is not.

Can I combine multiple constraints on a single needle.Field?

Yes, you can combine multiple constraints in a single Field instantiation. For example, you can specify both min_length and pattern for string validation, or gt and multiple_of for numeric constraints. The apply method processes all provided constraints and injects them into the generated schema.

How does needle.Field validate array parameters?

For array parameters, use min_items and max_items to control the array size, and unique_items to enforce element uniqueness. When set to True, unique_items maps to JSON-Schema's uniqueItems keyword, ensuring no duplicate values exist in the array.

Where is the needle.Field class implemented?

The Field class is implemented in needle/agent/tools.py within the cactus-compute/needle repository. The constructor handling the supported constraints appears at lines 18-32, while the schema generation logic resides in the apply method at lines 36-49.

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