# What Are Needle's Build Tools? A Complete Guide to Packaging and Model Compilation

> Explore Needle's build tools for efficient Python packaging and model compilation. Learn how to package libraries and convert checkpoints into portable .cact archives with our complete guide.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: how-to-guide
- Published: 2026-08-27

---

**Needle's build tools comprise two distinct toolchains: Python packaging utilities (setuptools, build, and twine) for library distribution, and a specialized model compiler (`needle build`) that converts trained checkpoints into portable `.cact` runtime archives.**

The `cactus-compute/needle` repository employs separate build systems for different stages of the workflow. One set handles the standard Python package distribution to PyPI, while another orchestrates the conversion of JAX-based machine learning models into quantized, self-contained deployment artifacts.

## Python Package Build Tools

Needle uses standard Python packaging infrastructure to create distributable wheels and source distributions for the `cactus-needle` package.

### The Build Backend Configuration

According to the source code in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml), **setuptools** serves as the build backend. This configuration defines how the source tree transforms into installable Python packages, specifying dependencies, entry points, and build-time requirements.

The CI pipeline defined in [`.github/workflows/release.yaml`](https://github.com/cactus-compute/needle/blob/main/.github/workflows/release.yaml) leverages two additional tools:

- **`build`**: Invoked via `python -m build`, this tool generates both source distributions (*sdist*) and platform-specific wheels.
- **`twine`**: Validates and uploads artifacts to PyPI using `twine check` followed by `twine upload`.

### CI/CD Publishing Workflow

The release automation ensures reproducible builds. When triggered, the workflow executes `python -m build` to create distribution archives, verifies them with `twine check dist/*`, and publishes to the package index. This process is fully implemented in the repository's GitHub Actions configuration.

## Model Compilation Build Tools

Beyond package distribution, Needle provides a sophisticated build system for preparing models for edge deployment. This toolchain converts JAX checkpoints into the compact `.cact` format.

### The CLI Entry Point

The `needle build` sub-command is implemented in [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py). This interface accepts a base checkpoint (`.pkl`) and optional LoRA adapters, delegating the heavy lifting to internal build routines.

Key parameters include:
- `--lora`: Path to an optional LoRA adapter to merge before export
- `--bits`: Quantization precision (2 or 4 bits; default is 4)
- `--out`: Destination path for the generated `.cact` archive

### Core Build Orchestration

The `build_main` function in [`needle/model/finetune.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/finetune.py) serves as the high-level coordinator. This routine orchestrates the entire pipeline: loading base weights, merging adapters, applying quantization, and invoking the export layer.

The function accepts a configuration namespace specifying the checkpoint path, LoRA adapter, output filename, bit precision, and upload flags. According to the implementation in [`finetune.py`](https://github.com/cactus-compute/needle/blob/main/finetune.py), `build_main` manages the transition from training artifacts to deployment-ready binaries.

### Export and Quantization

Three critical modules handle the low-level conversion:

- **`build_export`** (in [`needle/model/export.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/export.py)): Converts JAX parameters into the `.cact` archive format, handling the physical serialization of tensors and metadata.
- **`quantize`** (in [`needle/model/quantize.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/quantize.py)): Provides weight-quantization utilities that reduce precision to 2-bit or 4-bit representations, significantly shrinking file sizes for mobile and edge deployment.
- **[`needle/model/architecture.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py)**: Supplies model metadata required by the export format, ensuring the runtime engine can correctly interpret the compiled graph.

## Practical Usage Examples

### Building Models via CLI

Export a checkpoint with optional LoRA merging and quantization:

```bash

# Basic build with 4-bit quantization (default)

needle build checkpoint.pkl --lora adapter.pkl --out tuned.cact

# Aggressive compression with 2-bit weights

needle build checkpoint.pkl --bits 2 --out tiny.cact

```

### Programmatic Model Building

Invoke the build pipeline directly from Python using the same routines called by the CLI:

```python
from types import SimpleNamespace
from needle.model.finetune import build_main

# Configure build arguments

args = SimpleNamespace(
    checkpoint="checkpoint.pkl",   # Base model weights

    lora="adapter.pkl",           # Optional LoRA adapter

    out="tuned.cact",             # Output archive path

    bits="4",                     # Quantization bits (2 or 4)

    upload=False,                 # Set True to push to Hugging Face

)

# Execute the build

build_main(args)

```

### Packaging the Library for Distribution

Build and publish the Needle package itself using standard Python tooling:

```bash

# Install build dependencies

pip install build twine

# Generate sdist and wheel

python -m build

# Validate distribution artifacts

twine check dist/*

# Publish to PyPI (requires credentials)

twine upload dist/*

```

The test suite in [`tests/test_build.py`](https://github.com/cactus-compute/needle/blob/main/tests/test_build.py) validates the end-to-end build process, ensuring that both the packaging logic and model compilation paths remain functional across changes.

## Summary

- **Needle's build tools** cover both Python package distribution and model compilation workflows.
- **setuptools**, **`build`**, and **twine** handle PyPI distribution as configured in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) and [`.github/workflows/release.yaml`](https://github.com/cactus-compute/needle/blob/main/.github/workflows/release.yaml).
- The **`needle build`** CLI command (implemented in [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py)) triggers the model compilation pipeline.
- **`build_main`** in [`needle/model/finetune.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/finetune.py) orchestrates checkpoint loading, LoRA merging, and export preparation.
- **`build_export`** in [`needle/model/export.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/export.py) and **`quantize`** in [`needle/model/quantize.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/quantize.py) handle the conversion to the portable `.cact` format with optional 2-bit or 4-bit quantization.
- **[`needle/model/architecture.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py)** provides the metadata schemas required by the runtime engine.

## Frequently Asked Questions

### What is the `.cact` file format used by Needle?

The `.cact` format is Needle's proprietary runtime archive that encapsulates quantized model weights and metadata. According to the implementation in [`needle/model/export.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/export.py), this format stores JAX parameters at reduced precision (2-bit or 4-bit) alongside architecture information from [`needle/model/architecture.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py), enabling efficient deployment on resource-constrained devices.

### Can I use Needle's build tools without the CLI?

Yes. The `build_main` function in [`needle/model/finetune.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/finetune.py) exposes the complete build pipeline as a Python API. By importing this function and passing a configuration namespace (as shown in the programmatic example above), you can integrate model compilation directly into training scripts or automated workflows without invoking the command line.

### What quantization options does Needle support?

Needle supports **2-bit** and **4-bit** quantization for weight compression. The quantization logic resides in [`needle/model/quantize.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/quantize.py), and you can specify the precision via the `--bits` parameter in the CLI or the `bits` attribute in the `build_main` arguments. The default configuration uses 4-bit precision to balance model size and accuracy.

### How are Needle's Python packages built for distribution?

The project uses **setuptools** as the build backend, declared in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml). The CI pipeline in [`.github/workflows/release.yaml`](https://github.com/cactus-compute/needle/blob/main/.github/workflows/release.yaml) uses `python -m build` to create standard Python wheels and source distributions, which are then validated and uploaded to PyPI using `twine`. This follows the PEP 517/518 build system standards.