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

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 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#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.

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#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), and controls execution with parameters like max_steps.

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#L149), extract eliminates boilerplate when your goal is converting free-form text into structured data without managing the full agent loop yourself.

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#L111).
• run — Full agent loop with automatic tool calling and iterative reasoning; defined at line 127.
• extract — Structured extraction helper that converts schemas to tools; implemented at line 149.

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

---

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). 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/*, which contains C-extension bindings. The Needle class in [needle/__init__.py](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) provides the Python interface to these underlying operations.

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