Supported Validation Parameters for needle.Field: Complete Reference Guide

The needle.Field class supports 16 validation parameters—including numeric bounds (ge, le, gt, lt), string constraints (pattern, format), array limits (min_items, unique_items), and value restrictions (enum, const)—that automatically map to JSON-Schema keywords for AI tool argument validation.

The needle.Field class in the cactus-compute/needle repository provides a lightweight mechanism for enriching Python type hints with validation rules that become enforceable JSON-Schema constraints. Understanding these supported validation parameters for needle.Field allows developers to define precise boundaries for tool arguments consumed by large language models.

Complete List of Validation Parameters

The Field constructor in needle/agent/tools.py accepts keyword arguments that populate the generated schema during the apply() method. These parameters fall into five distinct categories based on their JSON-Schema mappings.

Numeric Constraints

These parameters validate integer and float values by translating to boundary keywords:

• ge – Greater than or equal to; maps to minimum (inclusive)
• le – Less than or equal to; maps to maximum (inclusive)
• gt – Greater than; maps to exclusiveMinimum
• lt – Less than; maps to exclusiveMaximum
• multiple_of – Value must be divisible by this number; maps to multipleOf

String Constraints

Use these parameters to enforce text length, patterns, and formats:

• min_length – Minimum character count; maps to minLength
• max_length – Maximum character count; maps to maxLength
• pattern – Regular expression the string must match; maps to pattern
• format – Semantic format hint (e.g., email, date-time, uri); maps to format

Array Constraints

When the annotated type is a list, these parameters control collection properties:

• min_items – Minimum number of elements; maps to minItems
• max_items – Maximum number of elements; maps to maxItems
• unique_items – Requires all array elements to be distinct; maps to uniqueItems

Value Restrictions

These parameters constrain the specific values a field may accept:

• enum – List of allowed values; maps to enum (automatically converted to a list by Field.apply())
• const – Fixed constant value the field must equal; maps to const

Metadata Fields

• description – Human-readable documentation string copied into the schema's description field
• default – Default value used by Needle at call time; not included in the JSON-Schema validation logic

How Validations Map to JSON-Schema

According to the cactus-compute/needle source code, the Field class stores these parameters as instance attributes and applies them inside the apply() method at lines 18-49 of needle/agent/tools.py. The implementation iterates through the validation parameters, filters out None values, and constructs a dictionary where Python parameter names map directly to their JSON-Schema equivalents.

For example, when you pass ge=15 to a Field, the generated schema contains "minimum": 15. The method handles special cases like enum by ensuring it is serialized as a JSON array regardless of the input type.

Practical Usage Examples

Enforcing Numeric Ranges with Inclusive Bounds

Use ge and le to define acceptable ranges for thermostat-style controls:

from needle.agent.tools import Field, tool

@tool
def set_temperature(
    value: int = Field(ge=15, le=30, description="Target temperature in °C")
):
    """Set the thermostat to a specific temperature."""
    pass

This generates the following schema fragment:

{
  "type": "integer",
  "minimum": 15,
  "maximum": 30,
  "description": "Target temperature in °C"
}

Validating String Patterns and Allowed Values

Combine enum with pattern to restrict inputs to specific lowercase color names:

@tool
def choose_color(
    color: str = Field(
        enum=["red", "green", "blue"],
        pattern="^[a-z]+$",
        description="Pick a primary color"
    )
):
    """Select a color from the allowed list."""
    pass

Resulting schema:

{
  "type": "string",
  "enum": ["red", "green", "blue"],
  "pattern": "^[a-z]+$",
  "description": "Pick a primary color"
}

Constraining Array Contents

Use min_items, max_items, and unique_items to validate tag collections:

@tool
def add_tags(
    tags: list = Field(
        min_items=1,
        max_items=5,
        unique_items=True,
        description="List of unique tags"
    )
):
    """Add between 1 and 5 unique tags to an item."""
    pass

Generated schema:

{
  "type": "array",
  "items": {"type": "string"},
  "minItems": 1,
  "maxItems": 5,
  "uniqueItems": true,
  "description": "List of unique tags"
}

Summary

• needle.Field supports 16 validation parameters spanning numeric, string, array, and value constraints.
• Parameters map directly to JSON-Schema keywords inside Field.apply() at lines 18-49 of needle/agent/tools.py.
• Numeric bounds use ge, le, gt, lt, and multiple_of for range validation.
• String validation employs min_length, max_length, pattern, and format for text constraints.
• Array controls include min_items, max_items, and unique_items for collection validation.
• enum and const restrict values to specific allowed sets or fixed constants.
• The default parameter is handled at runtime by Needle, not exposed in the JSON-Schema.

Frequently Asked Questions

What is needle.Field used for in the Needle SDK?

The needle.Field class annotates Python function parameters with validation metadata that the Needle SDK converts into OpenAI-compatible JSON-Schema definitions. This allows language models to understand constraints like minimum values or allowed enums before generating tool calls.

How does needle.Field differ from Pydantic's Field?

While Pydantic's Field is tightly coupled to Pydantic model validation, needle.Field in cactus-compute/needle is a lightweight helper specifically designed for generating function schemas for AI agents. It focuses exclusively on JSON-Schema generation rather than runtime Python validation.

Where are validation parameters applied in the source code?

Validation parameters are processed in the Field.apply() method located at lines 18-49 of needle/agent/tools.py. This method builds the schema dictionary by mapping Python parameter names to their JSON-Schema equivalents and injecting non-None values.

Can I combine multiple validation parameters in a single Field definition?

Yes. You can combine any compatible parameters (e.g., ge with le, or pattern with min_length) within a single Field() call. The apply() method aggregates all provided constraints into a single comprehensive JSON-Schema object.

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