# Understanding the .cact File Format and Engine Version Linkage in Needle

> Explore the .cact file format for Needle, an inference-ready package bundling model weights, config, and tokenizer. Understand its engine version linkage for seamless deployment.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: internals
- Published: 2026-08-20

---

**The `.cact` file is a binary archive format that bundles model weights, configuration, and tokenizer data into a single inference-ready package tied to a specific Needle engine version.**

The `.cact` file format serves as the deployment artifact for models built with **Needle**, an open-source inference engine developed by Cactus Compute. When you run `needle build`, the framework produces this binary archive from a checkpoint or LoRA adapter, embedding version metadata that ensures compatibility with the downloaded inference engine.

## What Gets Stored Inside a .cact Archive

The `.cact` format is defined in [`needle/model/export.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/export.py), specifically within the `_pack_cact` routine. The archive contains the following components:

- **Model weights** — either quantized weights or merged LoRA adapters
- **Model configuration** — attention heads, hidden size, and other architectural parameters
- **Tokenizer data** — vocabulary, merge rules, and special tokens
- **`head_dim` value** — a single scalar stored at line 108
- **KV-window value** — a single `kv_window` written to the header at line 117

Notably, the format **does not include a lexicon section**, as explicitly commented at line 113 in [`needle/model/export.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/export.py):

```python

# No lexicon section – the format has no lexicon section (line 113)

```

This lean binary structure prioritizes fast loading and minimal memory overhead during inference.

## Engine Version Coupling and Cache Management

The `.cact` format is **engine-version-aware**. When Needle initializes, it determines the `ENGINE_VERSION` from [`needle/fetch.py`](https://github.com/cactus-compute/needle/blob/main/needle/fetch.py) and constructs a version-specific cache directory:

```python
cache = os.path.join(
    os.path.expanduser("~"),
    ".cache",
    "cactus-needle",
    fetch.ENGINE_VERSION,
)

```

This logic appears at line 25 of [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py). The engine binary—a roughly 14MB compiled artifact—is downloaded once per version from Hugging Face and stored under this path, as documented in [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md) (lines 158-164).

### Version Mismatch Prevention

Needle enforces strict version compatibility between `.cact` archives and the runtime engine. If you attempt to load a `.cact` file exported by an older Needle release, the framework raises an explicit error. From [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) (lines 86-88):

```text
failed to load weights from <path> – the .cact exported by an older cactus-needle will not load; re-run …

```

This guard prevents silent failures from binary format incompatibilities. The resolution is straightforward: rebuild the `.cact` file using the current package version via `needle build`, as noted in [`doc/finetuning.md`](https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md) (line 84).

## Building and Loading .cact Files

### Creating a .cact Archive from Checkpoint + LoRA

The `needle build` command, implemented in [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py) (line 165), supports exporting checkpoints with optional LoRA adapters:

```bash

# Export a checkpoint (or checkpoint + LoRA) to a .cact archive

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

```

The `--out` flag specifies the target `.cact` path. Without it, the command uses a default naming convention based on input files.

### Loading a .cact into an Inference Agent

```python
import needle

# Load the tuned model – the engine version is resolved automatically

agent = needle.Needle(
    tools=[...],               # your tool definitions

    weights="tuned.cact"      # path to the .cact archive

)

# Use the agent

response = agent.complete("Summarize the latest sales report")

```

The `Needle` class handles engine version validation transparently. If `tuned.cact` was built with a different engine version, the initialization fails fast with the error message shown above.

### Verifying Your Engine Version

To inspect which engine version your installation will use:

```python
from needle import fetch
print("Engine version:", fetch.ENGINE_VERSION)

# The engine binary will be cached at:

# ~/.cache/cactus-needle/<ENGINE_VERSION>/...

```

This is useful for debugging version mismatches across development environments or CI pipelines.

## Key Source Files for .cact Format Details

| File | Relevance |
|------|-----------|
| [`needle/model/export.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/export.py) | Defines `_pack_cact()` and the on-disk layout of `.cact` archives |
| [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) | Sets up `fetch.ENGINE_VERSION` cache path and version-mismatch guard |
| [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py) | Implements `needle build` command that produces `.cact` files |
| [`needle/fetch.py`](https://github.com/cactus-compute/needle/blob/main/needle/fetch.py) | Declares `ENGINE_VERSION` constant used for cache segmentation |
| [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md) | Documents engine caching strategy and version relationships |
| [`doc/finetuning.md`](https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md) | Explains version incompatibility resolution workflow |

## Summary

- **`.cact` is a binary archive** containing weights, config, tokenizer data, `head_dim`, and `kv_window`—but no lexicon section
- **Engine version linkage** is enforced via `fetch.ENGINE_VERSION` and cached at `~/.cache/cactus-needle/<version>/`
- **Version mismatches are rejected** with explicit errors; rebuild with `needle build` to resolve
- **Source of truth** for format layout is [`needle/model/export.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/export.py), specifically lines 108, 113, and 117

## Frequently Asked Questions

### What happens if I try to load a .cact file from an older Needle version?

Needle raises a runtime error stating the `.cact` was exported by an older release and will not load. You must rerun `needle build` with your current package version to regenerate a compatible archive. This enforcement lives in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) (lines 86-88).

### Is the .cact format documented as a stable interchange format?

No—`.cact` is explicitly coupled to the engine version. The documentation in [`doc/finetuning.md`](https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md) (line 84) treats version mismatches as expected behavior rather than bugs, indicating the format evolves with the engine binary.

### Where does Needle download the inference engine binary?

The ~14MB engine binary is fetched once per `ENGINE_VERSION` from Hugging Face and cached at `~/.cache/cactus-needle/<ENGINE_VERSION>/`. This path construction is hardcoded in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) (line 25) and explained in [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md) (lines 158-164).

### Can I inspect or modify a .cact file manually?

The format is a packed binary archive without a public specification. The internal layout—single `head_dim`, no lexicon section, header-stored `kv_window`—is only documented in source comments within [`needle/model/export.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/export.py). Direct manipulation is not supported.