How to Install Cactus Needle: Complete Setup Guide for Inference and Training

Install Cactus Needle with pip install cactus-needle for the lightweight 14 MB runtime, or add extras like [train] for LoRA fine-tuning and [gpu]/[metal] for hardware acceleration.

Cactus Needle is a compact Python package for tool-calling, inference, and LoRA fine-tuning of foundation models. Whether you need a minimal runtime or a full training pipeline on GPU or Apple Silicon, the installation process is straightforward through pip with flexible optional dependencies defined in the project's pyproject.toml.

Core Installation

The base runtime provides everything needed for inference and tool execution:

pip install cactus-needle

This installs:

• The Needle inference engine (model weights download lazily from Hugging Face)
• Core dependencies including huggingface_hub for model retrieval as specified in [pyproject.toml](https://github.com/cactus-compute/needle/blob/main/pyproject.toml#L8-L10)

Weights are not bundled with the package—your first inference call fetches only the required model files from Hugging Face.

Optional Installation Extras

Cactus Needle uses extras to keep the base install minimal while enabling advanced functionality through modular dependencies.

[train] — Training and Fine-Tuning

Installs the stack for LoRA fine-tuning, data generation, and model building:

pip install "cactus-needle[train]"

Adds: NumPy, JAX, Flax, Optax, and SentencePiece as declared in pyproject.toml#L13-L20

[gpu] — CUDA Acceleration

Enables GPU-accelerated training with JAX compiled for CUDA 12:

pip install "cactus-needle[gpu]"

Dependencies defined in pyproject.toml#L21-L22

[metal] — Apple Silicon Support

Supplies JAX-Metal builds for GPU acceleration on macOS:

pip install "cactus-needle[metal]"

Configuration in pyproject.toml#L22-L26

[test] — Development Dependencies

Installs testing utilities used by the repository's test suite:

pip install "cactus-needle[test]"

Includes pytest and pydantic per pyproject.toml#L27-L28

Combining Extras

Install multiple extras together with comma separation:

pip install "cactus-needle[train,gpu]"

Verify Your Installation

Confirm the package is properly installed and check its version:

import needle

print(needle.__version__)  # → 2.0.8 (as defined in pyproject.toml)

The version is declared in pyproject.toml#L2-L4.

Quick Start Examples

Basic Inference (No Training)

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 it like in Lagos right now?")["results"])

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

Example from the project README at README.md#L44-L55.

Fine-Tune with LoRA

pip install "cactus-needle[train,gpu]"

import needle

# Requires data file `data.jsonl`

needle.finetune("data.jsonl", epochs=10, lora_rank=16, lora_alpha=32)

Build and Deploy a Tuned Model

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

import needle

agent = needle.Needle(weights="my_needle.cact", tools=[get_weather])
print(agent.run("What's the weather in Paris?"))

Disable Telemetry

Cactus Compute sends anonymous usage telemetry (function name, package version, OS). Disable it with either environment variable:

export NEEDLE_TELEMETRY=0

# or

export DO_NOT_TRACK=1

Configuration documented in README.md#L55-L56.

Key Source Files

Understanding the package structure helps with troubleshooting and extension:

File	Purpose
[pyproject.toml](https://github.com/cactus-compute/needle/blob/main/pyproject.toml)	Package metadata, dependencies, and extras configuration
[README.md](https://github.com/cactus-compute/needle/blob/main/README.md)	User documentation and quickstart examples
[needle/__init__.py](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)	Public API: Needle, tool, extract, etc.
[needle/cli.py](https://github.com/cactus-compute/needle/blob/main/needle/cli.py)	Command-line entry point for needle commands
needle/model/	Core architecture, quantization, and inference logic
needle/environments/	Pre-built tool surfaces (smart home, media player, etc.)

Summary

• Minimal install: pip install cactus-needle — 14 MB runtime with lazy model downloads
• Training stack: Add [train] for JAX-based LoRA fine-tuning
• Hardware acceleration: Use [gpu] for CUDA 12 or [metal] for Apple Silicon
• Version verification: Import and check needle.__version__ confirms successful installation
• Privacy control: Set NEEDLE_TELEMETRY=0 or DO_NOT_TRACK=1 to disable analytics

Frequently Asked Questions

What Python version is required for Cactus Needle?

The package requires Python 3.9 or higher as specified in pyproject.toml. Ensure your environment runs a compatible version before installation.

Can I install Cactus Needle without GPU support?

Yes. The base pip install cactus-needle includes no GPU dependencies. GPU support is entirely optional through the [gpu] and [metal] extras, making the package suitable for CPU-only deployments.

How large is the Cactus Needle download?

The Python package itself is approximately 14 MB. Model weights are downloaded separately on first use from Hugging Face, so initial installation remains lightweight regardless of which model you intend to use.

What if my LoRA fine-tuning fails to import JAX?

Ensure you installed the appropriate extra for your hardware: [train] alone provides CPU JAX, [train,gpu] enables CUDA acceleration, and [train,metal] is required for Apple Silicon. The error typically indicates a missing hardware-specific JAX build.

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