# How to Use the Needle Class Constructor Parameters: Complete Guide

> Master Needle class constructor parameters like tools system weights and buffer size. Configure your agent's behavior and memory allocation effortlessly with this complete guide.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: how-to-guide
- Published: 2026-09-08

---

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

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

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

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

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

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