How to Use the Needle Class Constructor Parameters: Complete Guide

The Needle class constructor accepts optional parameters for tools, system, weights, tool_index_path, and buffer_size to configure the agent's behavior, toolset, system prompts, and memory allocation without requiring any mandatory arguments.

The Needle class serves as the primary entry point for the Needle engine in the cactus-compute/needle repository. Understanding the constructor parameters allows you to customize everything from available function calling tools to fine-tuned model weights and memory buffers. These parameters determine whether the engine runs the bundled native library or loads custom fine-tuned weights in user space.

Constructor Parameters Reference

The Needle.__init__ method defined in needle/__init__.py accepts the following optional arguments:

Parameter	Type	Default	Description
tools	list | str | None	None	Tool specifications the agent can invoke. Accepts Python callables, Pydantic models, raw JSON schemas, or JSON strings. The constructor stores original callables in self._functions and resolves entries into JSON schemas.
system	str | None	None	System prompt prepended to every request. Encoded as UTF-8 and passed to the native library during initialization.
weights	str | PathLike | None	None	Path to a fine-tuned .cact weight file. Triggers generation detection (2 or 3) and creates a FineTuneWorker instance in user space.
tool_index_path	str | PathLike | None	None	Path to a tool-index file for fast schema lookup. Passed to the underlying C library as a UTF-8 byte string.
buffer_size	int	65536	Size of the internal C string buffer for raw JSON responses. Increase for longer completions.

Initialization Workflow

During construction, the class executes a four-step initialization sequence in needle/__init__.py:

Weight Detection

If weights is supplied, _weight_generation reads the first four bytes of the file to determine the engine generation (lines 29-38). This detection switches the runtime between the bundled native library and a FineTuneWorker instance.

Tool Resolution

The _resolve method converts each supplied tool into a JSON schema. This handler manages Pydantic models, Python callables, and raw dictionaries, populating self._functions with the original callables for later invocation.

Engine Binding

When no fine-tuned weights are supplied, _bind loads the generation-specific native shared library and calls needle_init with the system prompt, tool JSON, and optional tool_index_path. This step establishes the connection to the underlying C++ engine.

Buffer Allocation

A C string buffer of size buffer_size (default 65536 bytes) is created to hold the engine's raw output. This buffer receives the complete JSON response before Python parsing.

Practical Usage Examples

Minimal Default Configuration

Run the bundled Needle 2 model with no extra configuration:

from needle import Needle

with Needle() as agent:
    response = agent.complete("Write a short poem about clouds.")
    print(response["completion"])

System Prompt Configuration

Set a persistent personality or instruction set:

agent = Needle(system="You are a helpful assistant that speaks like Shakespeare.")
print(agent.complete("Describe the sunrise.")["completion"])

Custom Tool Registration

Enable function calling by passing Python callables:

def get_weather(city: str) -> str:
    """Return a dummy weather description."""
    return f"The weather in {city} is sunny."

agent = Needle(tools=[get_weather])
resp = agent.run("What’s the weather in Paris?")
print(resp["results"])

Fine-Tuned Weights Loading

Load custom .cact weight files for specialized generation:

agent = Needle(weights="path/to/fine_tuned.cact")
print(agent.complete("Summarize the following article…")["completion"])

Tool Index Optimization

Provide pre-built indices for large toolsets:

agent = Needle(tools=[get_weather], tool_index_path="path/to/index.json")
print(agent.run("Tell me the weather in Tokyo.")["results"])

Summary

• The Needle constructor requires no mandatory arguments; defaults instantiate a ready-to-use agent with the bundled model.
• The tools parameter accepts heterogeneous inputs (functions, Pydantic models, JSON) and stores callables in self._functions while converting schemas for the engine.
• Supplying weights triggers _weight_generation detection and instantiates FineTuneWorker from needle/_worker.py instead of the native library.
• buffer_size controls the C-level response buffer at needle_init time; the default 65536 bytes accommodates most completion lengths.
• tool_index_path optimizes schema lookup for large tool registries by passing a binary index directly to the C++ backend.

Frequently Asked Questions

What is the default buffer size for the Needle class?

The default buffer_size is 65536 bytes (64 KB). This allocates the internal C string buffer that receives the engine's raw JSON response. You should increase this value only when processing exceptionally long completions that exceed the default allocation.

How does the weights parameter affect the Needle engine?

When weights points to a valid .cact file, the constructor reads the first four bytes to detect the generation (2 or 3) and creates a FineTuneWorker instance that runs the model in user space. Without weights, _bind loads the bundled native shared library through needle_init instead.

Can I pass Pydantic models as tools to the Needle constructor?

Yes. The _resolve method in needle/__init__.py handles Pydantic models, Python callables, raw dictionaries, and JSON strings. The constructor converts these into JSON schemas for the engine while preserving the original callables in self._functions for execution.

Is the system parameter required?

No. The system parameter is optional (str | None). When provided, the string is encoded as UTF-8 and sent to the native library during initialization, prepending the system prompt to every subsequent request. Omitting it results in prompt-only interactions without system-level instructions.

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