# Needle Class API Methods: The Three Core Methods for Building LLM Applications

> Discover the three core Needle class API methods: complete for single responses, run for agent loops with tool execution, and extract for structured data. Build better LLM apps.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: api-reference
- Published: 2026-08-26

---

**The Needle class exposes three main API methods: `complete` for single-step responses, `run` for multi-step agent loops with tool execution, and `extract` for structured data extraction.**

The `Needle` class in the Cactus Needle repository serves as the primary high-level interface for interacting with the LLM engine. Whether you're building simple completions, complex agent workflows, or structured extraction pipelines, these three methods provide the complete surface area you need. This article breaks down each method with source code references and runnable examples from the [`cactus-compute/needle`](https://github.com/cactus-compute/needle) repository.

---

## complete: Single-Step LLM Completion

The **`complete`** method sends a prompt to the engine and returns a single-step response wrapped in a JSON envelope. It is the most straightforward entry point when you don't need tool execution or multi-turn reasoning.

In [[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py#L111), the `complete` method handles the direct model interaction without entering the agent loop. It accepts standard generation parameters such as `max_new_tokens` and returns a dictionary containing the generated content.

```python
from needle import Needle

# Initialise a Needle agent (no tools needed for plain completion)

agent = Needle()

# Ask the model for a completion

response = agent.complete("Write a short poem about sunrise.", max_new_tokens=64)

print(response["content"])

# → e.g. "Golden light unfurls…"

```

Use `complete` when you need a direct answer without external tool calls or structured output requirements.

---

## run: Multi-Step Agent Loop with Tool Execution

The **`run`** method implements the full agent loop: it calls `complete`, automatically invokes any returned function calls (tools), feeds the results back into the model, and repeats until a stop condition is met. This is the method you need for complex workflows requiring tool usage.

As implemented in [[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py#L127), `run` manages the conversation state, handles tool registration via the `@tool` decorator from [[`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py)](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py), and controls execution with parameters like `max_steps`.

```python
from needle import Needle, tool, Field

# Define a simple tool

@tool
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

# Initialise the agent with the tool

agent = Needle(tools=[add])

# Run a query that will trigger the tool

result = agent.run(
    "What is 7 plus 5? Then multiply the sum by 2.",
    max_steps=4,
    max_new_tokens=64,
)

print(result["content"])

# → Model may call `add` first, then we handle the result, etc.

print(result["results"])

# → List of tool call results, e.g. [{"add": 12}, {"error": "..."}]

```

The `run` method returns a dictionary containing both the final content and a history of tool execution results in the `results` key.

---

## extract: One-Shot Structured Data Extraction

The **`extract`** method provides a convenience wrapper for structured extraction scenarios. It treats a single Pydantic schema as the only tool, performs a one-shot extraction, and returns a typed object—either a Pydantic model or plain dictionary.

Located in [[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py#L149), `extract` eliminates boilerplate when your goal is converting free-form text into structured data without managing the full agent loop yourself.

```python
from needle import extract
from pydantic import BaseModel, Field

class Person(BaseModel):
    name: str = Field(..., description="Person's full name")
    age: int = Field(..., description="Person's age in years")

text = "Alice is 30 years old."

person = extract(text, Person)

print(person.name)  # → Alice

print(person.age)   # → 30

```

Unlike `run`, `extract` does not require explicit tool registration or step management—it handles schema-to-tool conversion internally.

---

## Method Comparison

| Method | Use Case | Tool Support | Returns |
|--------|----------|------------|---------|
| `complete` | Direct LLM queries | No | JSON envelope with content |
| `run` | Complex multi-step workflows | Yes (registered tools) | Content + tool result history |
| `extract` | Structured data extraction | Implicit (schema as tool) | Typed Pydantic model or dict |

---

## Summary

- **`complete`** — Single-step completions without tool execution; simplest entry point in [[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py#L111).
- **`run`** — Full agent loop with automatic tool calling and iterative reasoning; defined at [line 127](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py#L127).
- **`extract`** — Structured extraction helper that converts schemas to tools; implemented at [line 149](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py#L149).

These three methods constitute the complete public API surface of the Needle class as documented in [[`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md)](https://github.com/cactus-compute/needle/blob/main/doc/apis.md).

---

## Frequently Asked Questions

### What is the difference between `complete` and `run` in the Needle class?

`complete` performs a single model call and returns the response directly, while `run` implements a multi-step loop that can invoke tools, feed results back to the model, and continue until completion. Use `complete` for simple queries and `run` when your application requires tool execution or multi-turn reasoning.

### Can I use `extract` with custom Pydantic models?

Yes. The `extract` method accepts any Pydantic `BaseModel` subclass and uses its schema for one-shot structured extraction. The model fields and `Field` descriptions guide the extraction behavior.

### How do I register tools for use with the `run` method?

Tools are registered using the `@tool` decorator from [[`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py)](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py). Pass the decorated functions to the `Needle` constructor via the `tools` parameter, then `run` will automatically invoke them when the model requests function calls.

### Where is the actual inference implemented in the Needle repository?

The low-level inference engine is implemented in [`needle/model/*`](https://github.com/cactus-compute/needle/tree/main/needle/model), which contains C-extension bindings. The `Needle` class in [[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) provides the Python interface to these underlying operations.