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

> Explore the two Needle 2 model configuration presets: the powerful 'needle' and efficient 'base' variants. Understand their architecture and choose the best fit for your project.

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

---

**The Needle 2 architecture provides two built-in configuration presets defined in [`needle/model/architecture.py`](https://github.com/cactus-compute/needle/blob/main/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`](https://github.com/cactus-compute/needle/blob/main/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:

```python
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:

```python
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`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py)**: Contains the ground-truth `PRESETS` dictionary and the `TransformerConfig` dataclass that validates and stores preset values.
- **[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)**: Exposes the public API, ensuring preset values flow correctly through the package entry point.
- **[`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py)**: Implements command-line argument parsing that accepts preset names to configure model runs at startup.
- **[`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md)**: Documents the public API surface, including how preset names propagate through the constructor chain.
- **[`tests/test_build.py`](https://github.com/cactus-compute/needle/blob/main/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`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py).
- **Usage pattern**: Unpack preset dictionaries into `TransformerConfig` when initializing `SimpleAttentionNetwork`.
- **CLI integration**: The [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/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`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py) performs validation through its type system and constructors. Additionally, the test suite in [`tests/test_build.py`](https://github.com/cactus-compute/needle/blob/main/tests/test_build.py) verifies that both presets produce valid, buildable model instances, ensuring the parameter combinations are architecturally sound.