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

Yes, Needle 2 is fully open-source and available on GitHub at 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:

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 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)

The main entry point for developers is 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)

For terminal-based workflows, 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)

The core neural network is defined in 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)

To achieve the compact 14 MB binary size, 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)

Custom model training is implemented in 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:

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:

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:

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:

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 for the public API, needle/cli.py for command-line operations, and 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. 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, 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.

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