# Supported Constraints for needle.Field in Cactus Needle

> Explore supported constraints for needle.Field in Cactus Needle, including ge, le, pattern, enum, and const, for automatic tool schema generation. Learn how to validate your fields.

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

---

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

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

```

```python

# 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

```

```python

# Enum of allowed options

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

```

```python

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