# What Programming Languages Does Needle Support? A Complete Guide

> Discover which programming languages Needle supports. This guide clarifies that Needle officially offers Python support for its complete API including model loading, tool-calling, and fine-tuning.

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

---

**Needle officially supports only Python.** The entire public API—model loading, tool-calling, fine-tuning, and inference—is exposed exclusively through Python functions and decorators in the `cactus-needle` package.

Needle is a lightweight AI inference framework developed by Cactus Compute. While its core engine is a compiled binary, the library provides no bindings or wrappers for any language other than Python. This article explains Needle's language support based on the actual source code, including how the Python package interfaces with the underlying engine and what options exist for developers working in other ecosystems.

## Needle Is Distributed as a Python Package

The only officially supported way to install and use Needle is through **PyPI**. According to the repository's [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md)【​README.md†L5-L9】, you install it with:

```bash
pip install cactus-needle

```

All functionality flows through the Python package. There are no npm packages, Ruby gems, Rust crates, or Go modules published by the maintainers.

### Key Entry Points in the Python API

The public API is exposed in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py). The main classes and decorators you interact with include:

- **`needle.Needle`** — The core agent class for running inference with tools
- **`@needle.tool`** — Decorator for registering Python functions as callable tools
- **`needle.extract`** — Function for structured data extraction using Pydantic models

These are implemented in pure Python and serve as the only documented interfaces.

## The Compiled Engine vs. the Python Wrapper

Under the hood, Needle loads a **compiled binary** (`.cact` file) to execute inference. The [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py) file contains the logic that manages this:

```python
from needle.model.run import load_engine, run_inference

# The engine is loaded as a binary, but only through Python

engine = load_engine("model.cact")

```

While the engine itself is language-agnostic at the binary level, the library does not expose C headers, FFI bindings, or foreign function interfaces for direct use from C, C++, Rust, or other languages. You would need to reverse-engineer the binary format and maintain your own bindings—an unsupported and fragile approach.

## Practical Example: Building a Tool-Calling Agent in Python

Here's the canonical Needle workflow, which is **Python-only**:

```python
import needle

# 1. Declare a tool with a Python function

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

# 2. Create an agent with your tools

agent = needle.Needle(tools=[get_weather])

# 3. Run a query

response = agent.run("What's the weather like in Lagos right now?")
print(response["results"])

# → [{'city': 'Lagos', 'temp_c': 27, 'sky': 'clear'}]

```

The `@needle.tool` decorator (defined in the package's Python layer) handles serialization, schema generation, and callback orchestration. None of this machinery is available outside Python.

## Structured Extraction: Also Python-Only

Needle's extraction capabilities rely heavily on **Pydantic**, a Python-specific data validation library:

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

```

Because Pydantic has no official ports to other languages, this feature is fundamentally tied to Python's runtime and type system.

## What About the Needle CLI?

The command-line interface in [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py) is itself a Python module. When you run:

```bash
needle --help

```

You're invoking a Python entry point defined in the package configuration. The CLI simply wraps the same Python API—there is no standalone binary executable. This confirms that **Python is a runtime dependency even for CLI usage**.

## Could You Use Needle from Other Languages?

Technically, you could attempt to:

- **Call the Python runtime** from another language using embedded Python (e.g., PyO3 for Rust, Python.NET for C#)
- **Shell out** to the `needle` CLI and parse JSON output
- **Reverse-engineer** the `.cact` binary format and reimplement the engine

However, none of these approaches are supported, documented, or guaranteed to remain compatible across releases. The maintainers provide no stability guarantees for the binary format or internal APIs.

## Summary

- **Python is the only officially supported language** for using Needle
- The `cactus-needle` package on PyPI provides the complete public API
- Core classes (`Needle`, `tool`, `extract`) and the CLI are all Python-based
- The compiled `.cact` inference engine is language-agnostic but not exposed directly
- No bindings exist for JavaScript, Rust, Go, C++, or any other language

If your project requires a non-Python environment, you would need to either integrate Python into your stack or select a different inference framework with broader language support.

## Frequently Asked Questions

### Does Needle have a JavaScript or TypeScript SDK?

No. As implemented in `cactus-compute/needle`, there is no JavaScript package, WebAssembly build, or Node.js bindings. The only distribution channel is PyPI. JavaScript developers would need to run Needle in a Python service and communicate via HTTP or another IPC mechanism.

### Can I use Needle from Rust or C++?

Not directly. While the compiled `.cact` engine could theoretically be loaded from any language capable of binary execution, the library provides no C headers, FFI layer, or foreign language bindings. The [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py) source shows the engine is loaded through Python-specific machinery with no external interface exposed.

### Is there a Docker image or standalone binary I can use without Python?

No official Docker image or standalone binary exists. The CLI in [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py) requires a Python interpreter. The `.cact` files are model artifacts, not executables—they require the Python wrapper to handle context, tool dispatch, and response parsing.

### Will Needle add support for more languages in the future?

The source code provides no indication of multi-language support on the roadmap. The architecture—Python package with opaque binary engine—suggests the maintainers are optimizing for Python developer experience rather than language-agnostic distribution.