# Is Needle 2 Open Source? Yes, and Here's Where to Find the Source Code

> Discover if Needle 2 is open source. Access the complete source code, Python package, and tools on GitHub at cactus-compute/needle. Explore the inference engine and fine-tuning capabilities today.

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

---

**Yes, Needle 2 is fully open-source and available on GitHub at [cactus-compute/needle](https://github.com/cactus-compute/needle), including the complete Python package, model architecture, inference engine, and fine-tuning tools.**

The Needle 2 project is developed by Cactus Compute and distributed as a public repository containing everything required to run, fine-tune, and export the 45 million parameter language model. According to the source code, the README explicitly confirms the open-source status and provides direct access to the full implementation, from the quantized 14 MB binary format to the LoRA-based training pipeline.

## Where to Find the Needle 2 Source Code

The official source code for Needle 2 is hosted on GitHub under the organization `cactus-compute`. You can clone the repository directly:

```bash
git clone https://github.com/cactus-compute/needle.git

```

The repository contains the complete Python package, including model definitions, the inference engine, and command-line tooling. As documented in [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md) at line 15, the project explicitly states its open-source status and links to this repository as the canonical source for the model weights and implementation.

## Key Components of the Open-Source Repository

The Needle 2 codebase is organized into several critical modules that implement the **Simple Attention Network** architecture, **CQ2 quantization**, and tool-calling capabilities.

### Core Public API ([`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py))

The main entry point for developers is [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), which exposes the primary interfaces: `needle.Needle` for agent instantiation, `needle.tool` for function decoration, `needle.extract` for structured data extraction, and `needle.run` for execution. This file serves as the public API surface for integrating Needle 2 into Python applications.

### Command-Line Interface ([`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py))

For terminal-based workflows, [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py) implements the complete CLI, supporting commands for downloading weights, generating training data, fine-tuning models, and building tuned `.cact` binaries. This module provides the `needle` command used for model management and deployment.

### Model Architecture ([`needle/model/architecture.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py))

The core neural network is defined in [`needle/model/architecture.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py), which implements the 45M-parameter Simple Attention Network. This file contains the Hadamard-MLP layers, Grouped Query Attention (GQA), engram KV memory mechanisms, and Sinkhorn routing logic that power the model's inference capabilities.

### Quantization Engine ([`needle/model/quantize.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/quantize.py))

To achieve the compact 14 MB binary size, [`needle/model/quantize.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/quantize.py) handles conversion to the 2-bit CQ2 format. This quantization module compresses the model weights while preserving inference quality, producing the `.cact` files used for distribution.

### Fine-Tuning Pipeline ([`needle/model/finetune.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/finetune.py))

Custom model training is implemented in [`needle/model/finetune.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/finetune.py), which provides LoRA (Low-Rank Adaptation) fine-tuning logic and adapter merging capabilities. This allows users to specialize the base model on domain-specific datasets and export tuned weights.

### Interactive Playground (`needle/playground/`)

For experimentation, the `needle/playground/` directory contains a lightweight web UI that enables interactive inference through a browser interface, demonstrating the model's tool-calling and chat capabilities without requiring custom code.

## Practical Code Examples from the Source

The open-source repository includes working examples demonstrating the three primary usage patterns: tool-calling agents, structured extraction, and custom fine-tuning.

### Implementing Tool-Calling

Decorate Python functions and create an agent to execute tools automatically:

```python
import needle

@needle.tool
def get_weather(city: str):
    "Get the current weather for a city."
    return {"city": city, "temp_c": 27, "sky": "clear"}

agent = needle.Needle(tools=[get_weather])
result = agent.run("What's the weather like in Lagos right now?")["results"]
print(result)   # [{'city': 'Lagos', 'temp_c': 27, 'sky': 'clear'}]

```

### Structured Data Extraction

Use Pydantic models to extract typed data from unstructured text:

```python
from pydantic import BaseModel
import needle

class Invoice(BaseModel):
    vendor: str
    total: float
    due_date: str

text = "Invoice from Acme Corp, $1,200.00, due 2026-09-01"
invoice = needle.extract(text, Invoice)
print(invoice.vendor, invoice.total)   # Acme Corp 1200.0

```

### Fine-Tuning and Exporting Custom Models

Train on a JSONL dataset and package the results into a portable binary:

```bash
needle finetune data.jsonl --epochs 10
needle build checkpoints/needle2.pkl --lora checkpoints/needle_lora.pkl --out my_needle.cact

```

### Loading Custom Weights

Deploy the tuned model using the standard API:

```python
import needle
agent = needle.Needle(weights="my_needle.cact", tools=[get_weather])
print(agent.run("What can I do with the weather tool?"))

```

## Summary

- **Needle 2 is open-source** and publicly available at `github.com/cactus-compute/needle` under an open-source license.
- The repository includes the complete **45M-parameter Simple Attention Network** architecture, **CQ2 quantization** system, and **LoRA fine-tuning** pipeline.
- Key source files include [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) for the public API, [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py) for command-line operations, and [`needle/model/architecture.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py) for the core model implementation.
- Users can run, fine-tune, and export custom models to the **14 MB `.cact` binary format** using the provided tooling.
- The codebase supports **tool-calling**, **structured extraction**, and **interactive inference** through both Python APIs and a web-based playground.

## Frequently Asked Questions

### Is Needle 2 open source?

Yes, Needle 2 is released as an open-source project. The repository is publicly accessible on GitHub under the `cactus-compute` organization, and the README explicitly confirms the open-source status, providing full access to the model weights, architecture, and training code.

### What license is Needle 2 released under?

The source code confirms that Needle 2 is released under an open-source license. The specific license type (e.g., Apache 2.0, MIT) is detailed in the `LICENSE` file at the root of the `cactus-compute/needle` repository.

### Can I fine-tune Needle 2 on my own data?

Yes, the repository includes a complete fine-tuning implementation in [`needle/model/finetune.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/finetune.py). You can use the `needle finetune` CLI command to train LoRA adapters on your JSONL datasets, then build and export a custom `.cact` binary containing your specialized weights.

### Where is the model architecture defined in the source code?

The core Simple Attention Network architecture is defined in [`needle/model/architecture.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/architecture.py), which implements the Hadamard-MLP, GQA attention mechanism, engram KV memory, and Sinkhorn routing. The 2-bit CQ2 quantization logic resides in [`needle/model/quantize.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/quantize.py).