# Needle Constructor Parameters: Configuring the Cactus Needle Agent

> Configure the Cactus Needle Agent constructor parameters. Learn about tools, system prompts, weights, tool indexing, and buffer size for needle.Needle.

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

---

**The `Needle` class accepts five optional parameters—`tools`, `system`, `weights`, `tool_index_path`, and `buffer_size`—that configure tool availability, system prompts, custom model weights, tool indexing, and native buffer allocation.**

The `Needle` class serves as the core entry point for the [cactus-compute/needle](https://github.com/cactus-compute/needle) agent framework. Defined in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), its constructor provides a streamlined interface for instantiating AI agents with customized tool sets and model configurations. Understanding the available `needle.Needle constructor parameters` enables precise control over agent behavior, memory usage, and inference capabilities.

## Needle Constructor Signature

The `__init__` method signature at lines 55-57 of [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) defines the following interface:

```python
def __init__(self,
             tools=None,
             system=None,
             weights=None,
             tool_index_path=None,
             buffer_size=65536):

```

Each parameter controls a specific aspect of the agent's runtime environment and capabilities.

## Parameter Reference

### tools

The **`tools`** parameter accepts a `list` or `str` (optional) containing tool definitions the agent can invoke during inference. Valid entries include **Pydantic models**, callables decorated with `@tool`, or plain JSON schema dictionaries. If a string is supplied, the constructor assumes it is a pre-encoded JSON schema. According to the source code in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py), these definitions are resolved into standardized schemas via the private `_resolve` method (lines 96-109 of [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)) before being passed to the native engine.

### system

The **`system`** parameter takes an optional `str` that primes the language model with contextual instructions. If omitted, the constructor defaults to an empty string. This system prompt influences the agent's personality, constraints, and domain expertise throughout the conversation lifecycle.

### weights

The **`weights`** parameter specifies an optional path to a `.cact` weight archive file. Loading custom weights enables fine-tuned model behavior; however, the source code notes that confidence scores are set to `None` when custom weights are loaded because the confidence head is not updated during fine-tuning. This parameter interacts closely with [`needle/model/architecture.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py), which describes the underlying model structure.

### tool_index_path

The **`tool_index_path`** parameter accepts an optional `str` pointing to a pre-built index of tools for fast lookup. When provided, the constructor encodes this path to UTF-8 and passes it directly to the native `needle_init` function, optimizing tool retrieval performance during agent execution.

### buffer_size

The **`buffer_size`** parameter defines the size of the C-type string buffer (default: **65536**) that receives the engine's JSON response. This integer value determines the maximum output length the agent can generate in a single inference call. Larger buffers accommodate longer generated outputs but increase memory allocation requirements.

## Internal Initialization Process

Beyond parameter storage, the constructor performs several critical setup operations defined in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py). It encodes string parameters as UTF-8, allocates the C-level response buffer using the specified `buffer_size`, and invokes the native `needle_init` function to initialize the underlying runtime defined in [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py). The `_resolve` method processes the `tools` parameter to ensure all tool definitions conform to the expected JSON schema format before engine initialization.

## Configuration Examples

### Basic Usage with System Prompt

Instantiate a simple agent with contextual instructions:

```python
from needle import Needle

agent = Needle(system="You are a helpful assistant.")
response = agent.complete("What is the capital of France?")
print(response["choices"][0]["text"])

```

### Registering Custom Tools

Define and register callable tools using the `@tool` decorator:

```python
from needle import Needle, tool, Field

@tool
def add(a: int, b: int) -> int:
    """Return the sum of two integers."""
    return a + b

agent = Needle(
    tools=[add],
    system="You can perform arithmetic operations using the provided tools."
)
result = agent.run("What is 7 plus 5?")
print(result["results"])  # → [{'result': 12}]

```

### Loading Fine-Tuned Weights

Deploy a domain-specific model by specifying a `.cact` archive:

```python
agent = Needle(
    weights="/home/user/models/my_finetuned_model.cact",
    system="You are a domain-specific assistant for medical queries."
)
print(agent.complete("What are the symptoms of hypertension?"))

```

### Using Pre-Built Tool Indices

Optimize tool lookup with a serialized index:

```python
agent = Needle(
    tool_index_path="/tmp/tool_index.json",
    system="You have quick access to a large library of tools."
)

```

## Summary

- The `Needle` constructor in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) accepts five optional parameters: `tools`, `system`, `weights`, `tool_index_path`, and `buffer_size`.
- The `tools` parameter supports Pydantic models, decorated functions, or JSON schemas, resolved internally via the `_resolve` method.
- Custom `.cact` weights files load fine-tuned models but disable confidence score generation.
- The default `buffer_size` of 65536 bytes controls the maximum JSON response size from the native engine.
- String parameters are UTF-8 encoded before passing to the native `needle_init` function.

## Frequently Asked Questions

### What is the default buffer size for the Needle constructor?

The default `buffer_size` is **65536** bytes (64 KB). This value determines the C-type string buffer size that receives the engine's JSON response. If your application generates outputs longer than this limit, increase the value to prevent truncation errors.

### How do I load fine-tuned weights in Needle?

Pass the file path to your `.cact` archive via the `weights` parameter. When custom weights are loaded, the agent uses the fine-tuned model defined in [`needle/model/architecture.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py), though confidence scores return as `None` because the confidence head is not updated during fine-tuning.

### What formats does the tools parameter accept?

The `tools` parameter accepts a list containing **Pydantic models**, Python callables decorated with `@tool`, or dictionaries representing JSON schemas. Alternatively, you may pass a single string containing a pre-encoded JSON schema. The constructor internally validates and resolves these into standardized formats via the `_resolve` helper method.

### Where is the Needle class constructor defined?

The constructor is defined in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) at lines 55-57. This file also contains the `_resolve` method (lines 96-109) for processing tool definitions and the logic for invoking the native `needle_init` function.