Needle 2 Model Configuration Presets: The Complete Guide to "needle" and "base" Variants

The Needle 2 architecture provides two built-in configuration presets defined in needle/model/architecture.py: the high-capacity "needle" preset (768-dimensional embeddings, 12 attention heads, 27 layers) and the resource-efficient "base" preset (512-dimensional embeddings, 8 attention heads, 27 layers).

The cactus-compute/needle repository implements a preset-based configuration system for its transformer architecture. These predefined parameter sets allow researchers to instantiate Needle 2 models without manually specifying every hyperparameter, ensuring reproducibility across experiments while offering flexibility for different computational budgets.

Available Needle 2 Model Configuration Presets

The PRESETS dictionary in needle/model/architecture.py declares exactly two Needle 2 model configuration presets as of the current release.

The "needle" Preset (Default High-Capacity)

This preset provides the default, higher-capacity setting optimized for maximum model capacity:

• d_model=768
• num_heads=12
• num_kv_heads=6
• num_layers=27
• engram_layers=(2, 15)

The "base" Preset (Resource-Efficient)

This preset offers a smaller configuration suitable for lower-resource environments or faster experimentation:

• d_model=512
• num_heads=8
• num_kv_heads=4
• num_layers=27
• engram_layers=(2, 15)

Notice that both presets maintain identical layer depth (num_layers=27) and engram layer targeting (engram_layers=(2, 15)), differing only in embedding dimensions and attention head counts.

Instantiating Models with Configuration Presets

To use these presets, import the PRESETS dictionary and TransformerConfig dataclass from the architecture module, then unpack the desired configuration into your model constructor.

Using the default "needle" preset:

from needle.model.architecture import TransformerConfig, PRESETS

# Instantiate using the high-capacity preset

cfg_needle = TransformerConfig(**PRESETS["needle"])
model_needle = SimpleAttentionNetwork(config=cfg_needle)

Using the lightweight "base" preset:

from needle.model.architecture import TransformerConfig, PRESETS

# Instantiate using the efficient preset

cfg_base = TransformerConfig(**PRESETS["base"])
model_base = SimpleAttentionNetwork(config=cfg_base)

Where Presets Are Defined in the Source Code

The preset system implementation spans several critical files in the cactus-compute/needle repository:

• needle/model/architecture.py: Contains the ground-truth PRESETS dictionary and the TransformerConfig dataclass that validates and stores preset values.
• needle/__init__.py: Exposes the public API, ensuring preset values flow correctly through the package entry point.
• needle/cli.py: Implements command-line argument parsing that accepts preset names to configure model runs at startup.
• doc/apis.md: Documents the public API surface, including how preset names propagate through the constructor chain.
• tests/test_build.py: Validates that models build correctly using both preset configurations, serving as the acceptance criteria for preset definitions.

Summary

• Two presets exist: "needle" (768 d_model, 12 heads) and "base" (512 d_model, 8 heads), both at 27 layers.
• Source location: Defined in the PRESETS dictionary inside needle/model/architecture.py.
• Usage pattern: Unpack preset dictionaries into TransformerConfig when initializing SimpleAttentionNetwork.
• CLI integration: The needle/cli.py module accepts preset names for command-line model configuration.
• Shared architecture: Both presets use identical engram_layers=(2, 15) targeting and layer counts, differing only in capacity dimensions.

Frequently Asked Questions

How do I switch between Needle 2 model configuration presets in my code?

Import PRESETS from needle.model.architecture and pass the desired key to TransformerConfig using dictionary unpacking. For example, TransformerConfig(**PRESETS["base"]) loads the lightweight configuration, while PRESETS["needle"] loads the default high-capacity setting.

What is the difference between d_model and num_heads in these presets?

The d_model parameter controls the embedding dimension (768 vs. 512), determining the width of the model's representation space. The num_heads parameter controls the parallel attention mechanisms (12 vs. 8), affecting how the model attends to different representation subspaces simultaneously. The "needle" preset increases both values proportionally to maintain head dimension consistency.

Can I override specific parameters after selecting a preset?

Yes. Since PRESETS returns a standard Python dictionary, you can merge or override values before instantiation. For example: TransformerConfig(**{**PRESETS["base"], "num_layers": 12}) creates a custom configuration using the base embedding dimensions but with only 12 transformer layers instead of 27.

Where are the preset values validated in the codebase?

The TransformerConfig dataclass in needle/model/architecture.py performs validation through its type system and constructors. Additionally, the test suite in tests/test_build.py verifies that both presets produce valid, buildable model instances, ensuring the parameter combinations are architecturally sound.

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