How to Install the Needle 2 Model: Complete Setup Guide

Install Needle 2 by running pip install cactus-needle; the 45M-parameter weights auto-download from Hugging Face when you first instantiate needle.Needle().

The cactus-compute/needle repository ships Needle 2 as a compact Python distribution that bundles the inference engine and a pre-quantized checkpoint into a single workflow. With a standard installation size of approximately 14 MB and no manual weight management required, you can deploy this tool-calling model on CPU, CUDA, or Apple Silicon in minutes.

Installing the Core Package

The base installation pulls in the runtime and all required dependencies via a single command. According to the source code in pyproject.toml [source], the package declares dependencies such as jax, flax, and numpy automatically.

pip install cactus-needle

After installation, the needle CLI becomes available, and the Python API in needle/__init__.py exposes the core Needle class for agent construction and weight loading.

Adding Hardware Acceleration (Optional)

For platforms with GPU support, install the appropriate extras to enable hardware acceleration. The optional dependency groups are defined in pyproject.toml [source].

• NVIDIA GPUs: Install CUDA support using the [gpu] extra.

pip install "cactus-needle[gpu]"

• Apple Silicon: Enable Metal Performance Shaders with the [metal] extra.

pip install "cactus-needle[metal]"

Downloading the Model Weights

Needle 2 eliminates manual weight management. The first time you instantiate needle.Needle or run a CLI command that requires inference, the engine automatically downloads the 45M-parameter checkpoint from Hugging Face (Cactus-Compute/needle2) and caches it locally.

To trigger the download explicitly or verify the cache, use the CLI command defined in needle/cli.py:

needle build

The downloaded artifact is a single .cact binary file. As noted in the README.md [source], the inference engine memory-maps this file directly, maintaining a constant RAM footprint of approximately 28 MB regardless of conversation length.

Verifying the Installation

Create a minimal agent to confirm that the package and weights are functioning. The following example, adapted from needle/__init__.py and the repository documentation, defines a simple tool and runs a structured query:

import needle

@needle.tool
def get_weather(city: str):
    """Get the current weather for a city."""
    return {"city": city, "temp_c": 27, "sky": "clear"}

# Weights auto-download on first use if not cached

agent = needle.Needle(tools=[get_weather])
result = agent.run("What's the temperature in Tokyo?")
print(result["results"])

# Output: [{'city': 'Tokyo', 'temp_c': 27, 'sky': 'clear'}]

Successful execution confirms that the cactus-needle package, its dependencies, and the .cact weight file are correctly installed.

Loading Custom Weights (Optional)

If you possess a fine-tuned checkpoint, supply the path directly to the Needle constructor instead of using the auto-cached base weights. This behavior is handled in needle/__init__.py via the weights parameter:

agent = needle.Needle(weights="my_fine_tuned.cact", tools=[get_weather])
response = agent.run("Tell me about the sky in Berlin.")

Summary

• Install via PyPI: Run pip install cactus-needle to install the core package (~14 MB) with all Python dependencies listed in pyproject.toml.
• Enable acceleration: Add [gpu] for CUDA or [metal] for Apple Silicon extras during installation.
• Auto-download weights: The 45M-parameter checkpoint downloads automatically from Hugging Face on first use; manually trigger with needle build.
• Zero-config caching: Weights are stored as a single .cact file and memory-mapped for efficient 28 MB RAM usage.
• Custom models: Pass a local path to the weights parameter in needle.Needle() to load fine-tuned variants.

Frequently Asked Questions

How large is the Needle 2 model download?

The Needle 2 checkpoint contains 45 million parameters and is distributed as a single .cact binary file. The Python package itself is approximately 14 MB, and the total installation footprint remains under 50 MB, making it suitable for edge devices and containerized deployments.

Does Needle 2 require a GPU to run?

No. Needle 2 runs efficiently on CPU-only systems using the base pip install cactus-needle command. However, for improved inference speed on NVIDIA GPUs or Apple Silicon Macs, install the optional [gpu] or [metal] extras to enable hardware acceleration via JAX.

Where are the model weights cached locally?

The weights are downloaded from Hugging Face (Cactus-Compute/needle2) and cached automatically the first time you instantiate needle.Needle() or execute needle build. The engine manages the cache location internally; you do not need to specify a directory unless loading a custom .cact file via the weights argument.

Can I use Needle 2 with fine-tuned checkpoints?

Yes. While the library defaults to the pre-trained base weights, you can load custom fine-tuned models by providing a file path to the weights parameter when initializing the Needle class: needle.Needle(weights="path/to/custom.cact", tools=[...]). This allows you to deploy specialized agents without modifying the core package.

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