System Requirements for Running Needle 2: Minimal Hardware and Software Specs

Needle 2 requires only Python 3.9+, approximately 28 MiB of RAM, and a 14 MiB binary download to run inference on any modern CPU, with optional GPU acceleration available for CUDA and Apple Silicon devices.

Needle 2 is a tiny, self-contained 45-million-parameter language model developed by Cactus Compute that delivers efficient inference without external runtimes. This guide explains the system requirements for running Needle 2 on your local machine, covering hardware specifications, Python environment constraints, and optional acceleration methods defined in the cactus-compute/needle repository.

Minimum Hardware Specifications

Needle 2 is designed to run on virtually any modern computer with minimal resource overhead. The base inference engine requires no specialized hardware to execute.

Memory and Storage Requirements

The complete runtime footprint for Needle 2 is exceptionally small compared to contemporary language models:

• RAM: Approximately 28 MiB of RAM for a full inference session
• Binary Size: The engine file is approximately 14 MiB and downloads automatically from Hugging Face on first use
• Caching: After the initial download, the inference engine is cached locally, enabling instant subsequent starts without repeated network requests

CPU Requirements

As implemented in needle/model/run.py, Needle 2 runs entirely on the CPU with no external runtime dependencies. The 45M-parameter model executes efficiently on any modern processor architecture, making it suitable for edge devices and resource-constrained environments where GPU acceleration is unavailable.

Software Prerequisites

The primary constraint for running Needle 2 is the Python environment version and basic operating system compatibility.

Python Version Constraints

According to the pyproject.toml configuration in the cactus-compute/needle repository, the package requires Python 3.9 or newer. The package is published on PyPI as cactus-needle and installs via standard pip commands.

Operating System Support

Needle 2 works on any platform supported by Python, including:

• Linux distributions
• macOS (Intel and Apple Silicon)
• Windows

The pure-Python implementation ensures cross-platform compatibility without platform-specific binaries.

Installation and Dependencies

The base installation pulls in a minimal set of dependencies defined in requirements.txt, including pydantic and numpy. All dependencies install automatically via pip.

Base Package Installation

Install the core package using pip:

pip install cactus-needle

This command automatically downloads the 14 MiB engine file from Hugging Face and installs the pure-Python dependency stack. The needle/__init__.py file contains the core Needle class, tool decorator, and extract helper used for inference.

Dependency Structure

The requirements.txt specifies a small set of pure-Python packages:

• pydantic: For structured data validation and extraction
• numpy: For numerical operations
• jax: Installed automatically when using optional training features

Optional GPU Acceleration

While Needle 2 runs efficiently on CPU, the repository supports optional GPU acceleration for faster training and inference through extras packages.

CUDA Support

For NVIDIA GPUs, install the GPU extras:

pip install "cactus-needle[gpu]"

This configuration enables CUDA-accelerated operations as documented in doc/finetuning.md.

Apple Silicon Support

For M-series Macs, use the Metal extras:

pip install "cactus-needle[metal]"

This leverages Apple's Metal Performance Shaders for acceleration on M1, M2, and M3 processors.

Fine-Tuning Requirements

The optional training workflow documented in doc/finetuning.md supports LoRA (Low-Rank Adaptation) fine-tuning using the GPU or Metal backends. Fine-tuning requires the same base memory specifications but benefits significantly from acceleration hardware for training speed.

Running Needle 2: Implementation Examples

The following examples demonstrate practical usage within the specified system requirements.

Tool-Calling Inference

This example uses the default CPU-based engine installed via pip install cactus-needle:

import needle

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

agent = needle.Needle(tools=[get_weather])
print(agent.run("What's the weather like in Lagos?")["results"])

# → [{'city': 'Lagos', 'temp_c': 27, 'sky': 'clear'}]

Structured Data Extraction

Using Pydantic models for type-safe extraction as defined in needle/__init__.py:

from pydantic import BaseModel
import needle

class Invoice(BaseModel):
    vendor: str
    total: float
    due_date: str

text = "Invoice from Acme Corp, $1,200.00, due 2026-09-01"
invoice = needle.extract(text, Invoice)
print(invoice.vendor, invoice.total)   # → Acme Corp 1200.0

GPU-Accelerated Fine-Tuning

For systems with optional GPU support:

pip install "cactus-needle[gpu]"   # or [metal] on Apple Silicon

needle finetune data.jsonl --epochs 10   # LoRA training

needle build checkpoints/needle2.pkl \
    --lora checkpoints/needle_lora.pkl \
    --out my_needle.cact

Load the fine-tuned model:

import needle
agent = needle.Needle(weights="my_needle.cact", tools=[...])
agent.run("...")   # using the tuned model

Summary

• Needle 2 system requirements include Python 3.9+, 28 MiB RAM, and 14 MiB storage, making it one of the most lightweight language model deployments available.
• The cactus-needle package installs automatically via pip and caches the inference engine after the first download.
• CPU-only operation requires no external runtimes or GPU hardware, as implemented in needle/model/run.py.
• Optional acceleration is available through pip install "cactus-needle[gpu]" for CUDA or [metal] for Apple Silicon.
• The complete dependency stack is defined in requirements.txt and installs automatically with the base package.

Frequently Asked Questions

What is the minimum RAM needed to run Needle 2?

Needle 2 requires approximately 28 MiB of RAM for a full inference session. This minimal footprint allows the model to run on embedded devices, older hardware, or alongside memory-intensive applications without resource contention.

Does Needle 2 require a GPU to function?

No. Needle 2 runs entirely on CPU using the pure-Python implementation in needle/__init__.py. GPU acceleration is optional and available only for improving training speed or inference latency when using the [gpu] or [metal] extras packages.

Which Python versions are compatible with Needle 2?

The pyproject.toml specifies Python 3.9 or newer. The package is tested and distributed on PyPI as cactus-needle, with automatic dependency resolution for all supported Python versions.

How large is the Needle 2 model download?

The engine file is approximately 14 MiB and downloads automatically from Hugging Face when you first import the package. After the initial download, the binary is cached locally, eliminating network overhead for subsequent sessions.

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