System Requirements for Running Needle 2: Minimal Setup Guide

Needle 2 requires only Python 3.9+, approximately 28 MiB of RAM, and a single 14 MiB binary file to run 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 published by cactus-compute/needle on PyPI as cactus-needle. Understanding the system requirements for running Needle 2 ensures you can deploy this lightweight engine for tool-calling and structured extraction on anything from embedded devices to cloud servers without managing complex dependencies or external runtimes.

Minimum Hardware and Software Specifications

Python Version and Operating System

Needle 2 targets Python 3.9 or newer, as defined in the project's pyproject.toml build configuration. The package runs on any platform supported by Python, including Linux, macOS, and Windows. Because the inference engine is self-contained within the cactus-needle package, no additional system libraries or external runtimes are required.

Memory and Storage Footprint

The model is optimized for minimal resource consumption:

• RAM: Approximately 28 MiB for a full inference session
• Binary Size: A single 14 MiB engine file downloaded automatically from Hugging Face on first use
• Caching: The engine is cached locally after initial download, making subsequent runs instant

According to the README.md in the cactus-compute/needle repository, these specifications make Needle 2 suitable for edge devices and resource-constrained environments where larger frameworks like PyTorch or TensorFlow would be impractical.

CPU Requirements

Needle 2 runs entirely on the CPU using optimized inference code. As implemented in needle/model/run.py, the engine requires no GPU for standard inference tasks. The Needle class in needle/__init__.py handles all computation through pure-Python orchestration with minimal overhead, making it compatible with any modern processor architecture.

Optional GPU and Metal Acceleration

While CPU inference is sufficient for most use cases, you can install optional extras for faster training and large-scale inference workloads.

CUDA Support for NVIDIA GPUs

For CUDA-enabled systems, install the GPU variant to accelerate training and batch inference:

pip install "cactus-needle[gpu]"

This extra dependency enables CUDA acceleration during fine-tuning workflows defined in doc/finetuning.md, though the base inference engine remains CPU-only unless specifically configured for GPU execution during training.

Apple Silicon Optimization

On Apple M1, M2, or M3 devices, use the Metal backend for optimized performance:

pip install "cactus-needle[metal]"

This configuration leverages the Metal Performance Shaders framework for LoRA fine-tuning, allowing you to train custom adapters directly on Mac hardware without external cloud resources.

Installation and Dependencies

The base package installs via pip with a minimal dependency tree defined in requirements.txt:

pip install cactus-needle

The package automatically pulls in pure-Python dependencies including:

• pydantic: For structured data validation in needle.extract()
• numpy: For numerical operations in the inference engine
• jax: Optional training dependency for gradient computation

All dependencies are installed automatically, and the 14 MiB binary engine downloads on first import, requiring no manual configuration.

Verifying Your Setup with Code Examples

Test your installation with these practical examples that demonstrate Needle 2's core capabilities within the minimal resource footprint.

Tool-Calling with 28 MiB RAM

This example uses the needle.tool decorator and Needle class from needle/__init__.py to execute functions:

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 Extraction

Use needle.extract() with Pydantic models for type-safe data parsing:

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

Fine-Tuning with Optional GPU

After installing GPU or Metal extras, run LoRA fine-tuning:

# Install acceleration first

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

# Fine-tune and build custom weights

needle finetune data.jsonl --epochs 10
needle build checkpoints/needle2.pkl \
    --lora checkpoints/needle_lora.pkl \
    --out my_needle.cact

Load custom weights in Python:

import needle
agent = needle.Needle(weights="my_needle.cact", tools=[...])
agent.run("...")

Behind the Scenes: Key Implementation Files

Understanding the architecture helps clarify why the system requirements remain minimal:

• needle/__init__.py: Contains the core Needle class, tool decorator, and extract() helper functions that orchestrate the 45M-parameter model
• needle/model/run.py: Implements the lightweight inference engine entry point that executes within the 28 MiB memory constraint
• requirements.txt: Lists minimal pure-Python dependencies ensuring broad compatibility
• pyproject.toml: Defines Python 3.9+ version constraints and package metadata for cactus-needle
• doc/apis.md: Documents system facts handling and API configuration
• doc/finetuning.md: Provides guidance for optional GPU/Metal acceleration during training

Summary

• Python 3.9 or newer is required to run Needle 2, available on Linux, macOS, and Windows
• 28 MiB of RAM and 14 MiB of storage are sufficient for full inference sessions
• CPU-only operation is supported out of the box with no external runtime dependencies
• Optional GPU extras ([gpu] for CUDA, [metal] for Apple Silicon) accelerate training but are not required for inference
• The cactus-needle package from cactus-compute/needle installs all dependencies automatically via pip

Frequently Asked Questions

How much RAM is actually required to run Needle 2?

Needle 2 requires approximately 28 MiB of RAM for a complete inference session. The 14 MiB binary engine loads into memory while maintaining a minimal footprint suitable for containerized deployments and edge devices. According to the cactus-compute/needle README, this makes it one of the smallest functional language model implementations available via PyPI.

Can I run Needle 2 without a GPU?

Yes. Needle 2 is designed to run entirely on CPU using the self-contained engine in needle/model/run.py. The GPU and Metal extras are only necessary if you plan to perform LoRA fine-tuning or require accelerated inference for high-throughput applications. Standard tool-calling and structured extraction work efficiently on any modern CPU.

What Python version do I need to install?

You need Python 3.9 or newer, as specified in the project's pyproject.toml. The package is published on PyPI as cactus-needle and supports all platforms where Python runs, including ARM64 and x86-64 architectures. The needle/__init__.py module uses modern Python typing features that require 3.9+.

How large is the model file that gets downloaded?

The engine file is approximately 14 MiB and downloads automatically from Hugging Face on first use. The file is cached locally after initial download, meaning subsequent runs start instantly without additional network requests or storage overhead. This single binary contains the full 45-million-parameter model weights optimized for the inference runtime.

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