How to Install the cactus-needle Python Package: A Complete Guide

Install cactus-needle with pip install cactus-needle for CPU, pip install "cactus-needle[gpu]" for NVIDIA CUDA 12, or pip install "cactus-needle[metal]" for Apple Silicon.

The cactus-needle package provides a self-contained 14 MB inference engine for the Needle 2 model, including LoRA fine-tuning utilities and a command-line interface. This guide covers installation from PyPI, verification steps, and backend-specific configurations based on the source code in the cactus-compute/needle repository.

Prerequisites

Before installing cactus-needle, ensure your environment meets these requirements:

• Python ≥ 3.9 — specified in the [project.requires-python] field of pyproject.toml【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L5】
• A working pip environment (virtual environment recommended)

Basic Installation

The core package installs the inference engine with all required runtime dependencies. According to the dependencies section in pyproject.toml【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L8-L16】, this pulls in huggingface_hub, numpy, jax, jaxlib, flax, optax, and sentencepiece.

pip install cactus-needle

This gives you:

• The Needle class for tool-calling and extraction
• The @needle.tool decorator for defining callable tools
• The needle CLI entry point

Optional GPU and Apple Silicon Acceleration

The package defines two extra dependency groups for hardware acceleration, declared in pyproject.toml【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L19-L20】:

Extra	Hardware	Command
gpu	NVIDIA GPUs (CUDA 12)	pip install "cactus-needle[gpu]"
metal	Apple Silicon (MPS)	pip install "cactus-needle[metal]"

NVIDIA GPU Installation

The gpu extra installs jax[cuda12] for CUDA 12 acceleration:

pip install "cactus-needle[gpu]"

Apple Silicon (Metal) Installation

The metal extra installs jax-metal with pinned compatible versions of jax, jaxlib, flax, and optax:

pip install "cactus-needle[metal]"

Verifying Your Installation

After installation, verify the package and CLI are correctly registered. The needle console script is defined under [tool.setuptools.scripts] in pyproject.toml【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L23-L25】.

Check the installed version:

python -c "import needle, sys; print('needle version', needle.__version__)"

Verify the CLI entry point:

needle --help

Quick Start After Installation

The public API is exposed through needle/__init__.py, which includes the Needle class and tool decorator used in quick-start examples【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/cactus-compute/needle/main/needle/init.py】.

Example: Tool-Calling in Python

import needle

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

# Create agent with your tools

agent = needle.Needle(tools=[get_weather])

# The model automatically calls the tool when needed

response = agent.run("What's it like in Lagos right now?")
print(response["results"])

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

Example: Using the CLI

The CLI implementation resides in needle/cli.py【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/cactus-compute/needle/main/needle/cli.py】:

# Run a query without writing Python code

needle "Summarize the benefits of tool calling in Needle"

Example: LoRA Fine-Tuning

Fine-tuning requires JAX; use the [gpu] or [metal] extras for acceleration:

# Prepare a JSONL dataset per doc/finetuning.md, then:

needle finetune my_data.jsonl --epochs 5

Key Files and Their Roles

File	Purpose
pyproject.toml【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml】	Package metadata, dependencies, and needle console script
needle/__init__.py【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/cactus-compute/needle/main/needle/init.py】	Public API: Needle, tool, extract
needle/cli.py【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/cactus-compute/needle/main/needle/cli.py】	CLI implementation
needle/model/	Core inference engine (tokenizer, run loop, quantization)
doc/finetuning.md	LoRA fine-tuning instructions

Summary

• cactus-needle is distributed on PyPI and requires Python ≥ 3.9
• Base install: pip install cactus-needle — includes JAX CPU backend
• GPU extras: Use [gpu] for NVIDIA CUDA 12 or [metal] for Apple Silicon
• Verify with python -c "import needle; print(needle.__version__)" and needle --help
• The package exposes tools for inference, tool-calling, extraction, and fine-tuning with minimal dependencies

Frequently Asked Questions

What Python versions are compatible with cactus-needle?

Python 3.9 and later. This requirement is explicitly declared in pyproject.toml under [project.requires-python]【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L5】.

Do I need a GPU to use cactus-needle?

No. The base installation includes JAX with CPU support. GPU acceleration is optional via the [gpu] or [metal] extras for improved fine-tuning and inference performance.

How do I check if my installation detected the GPU?

After installing with [gpu] or [metal], run:

import jax
print(jax.devices())

This should list your available accelerators. If only CPUs appear, revisit your JAX installation for your specific platform.

Where is the CLI entry point defined?

The needle command is registered as a console script in pyproject.toml under [tool.setuptools.scripts]【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L23-L25】, which points to the implementation in needle/cli.py【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/cactus-compute/needle/main/needle/cli.py】.

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