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

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, 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 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. 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 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, 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): Converts JAX parameters into the .cact archive format, handling the physical serialization of tensors and metadata.
• quantize (in 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: 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:

# 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:

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:

# 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 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 and .github/workflows/release.yaml.
• The needle build CLI command (implemented in needle/cli.py) triggers the model compilation pipeline.
• build_main in needle/model/finetune.py orchestrates checkpoint loading, LoRA merging, and export preparation.
• build_export in needle/model/export.py and quantize in needle/model/quantize.py handle the conversion to the portable .cact format with optional 2-bit or 4-bit quantization.
• 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, this format stores JAX parameters at reduced precision (2-bit or 4-bit) alongside architecture information from 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 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, 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. The CI pipeline in .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.

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