Needle Constructor Parameters: Configuring the Cactus Needle Agent

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 agent framework. Defined in 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 defines the following interface:

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, these definitions are resolved into standardized schemas via the private _resolve method (lines 96-109 of 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, 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. 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. 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:

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:

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:

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:

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 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, 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 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.

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