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

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

# 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 and constructs a version-specific cache directory:

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

This logic appears at line 25 of 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 (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 (lines 86-88):

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 (line 84).

Building and Loading .cact Files

Creating a .cact Archive from Checkpoint + LoRA

The needle build command, implemented in needle/cli.py (line 165), supports exporting checkpoints with optional LoRA adapters:

# 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

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:

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	Defines _pack_cact() and the on-disk layout of .cact archives
needle/__init__.py	Sets up fetch.ENGINE_VERSION cache path and version-mismatch guard
needle/cli.py	Implements needle build command that produces .cact files
needle/fetch.py	Declares ENGINE_VERSION constant used for cache segmentation
doc/apis.md	Documents engine caching strategy and version relationships
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, 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 (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 (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 (line 25) and explained in 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. Direct manipulation is not supported.

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