Understanding the Response Shape of agent.complete() in Needle

The agent.complete() method returns a Python dictionary containing mandatory keys type and content, with optional fields including function_calls, confidence, and engine-specific metadata.

The agent.complete() method serves as the high-level entry point for executing completion requests in the Needle library, a native-engine agent framework maintained by cactus-compute. When you invoke this API, you receive a structured Python dictionary that encapsulates the native engine's JSON output along with Needle's post-processing enrichments, making the agent.complete() response shape predictable yet extensible for diverse use cases.

Core Response Structure

The response dictionary always includes two mandatory fields derived directly from the parsed JSON envelope. The type key returns a string describing the reply nature—typically "completion" for plain text or "call" when the model requests function invocation. The content key provides the generated text output as a string.

Beyond these required fields, the dictionary may include several optional entries:

• function_calls: A list[dict] containing tool invocations the model requests. Each dictionary specifies the tool name and an arguments dictionary mapping parameter names to values.
• confidence: A float representing the model-reported confidence score, or None when using fine-tuned weights.
• results: A list populated only after executing the run() loop, containing accumulated outputs from executed tool calls.
• Engine-specific metadata: Any additional keys returned by the underlying engine—such as model_version or tokens_used—pass through unchanged.

Internal Response Construction Pipeline

Understanding how Needle assembles this dictionary requires examining the internal execution flow defined in needle/__init__.py.

The Wrapper and Telemetry Layer

The public Needle.complete() method acts as a telemetry-enabled wrapper around the private _complete implementation. According to lines 21-27 of needle/__init__.py, this entry point first invokes telemetry tracking (implemented in needle/_telemetry.py at line 24), prepares optional audio payloads, and forwards the request to _complete.

Native Engine Integration

The _complete method handles the heavy lifting of engine communication. Lines 52-57 validate audio support, bind the native library if necessary, and dispatch to either the fine-tuning worker defined in needle/_worker.py (lines 284-291) or the compiled library (lib.needle_complete). The raw string response undergoes parsing via json.loads to produce the initial dictionary structure.

Post-Processing and Enrichment

After parsing, Needle applies two critical modifications before returning control to the caller. Lines 58-59 inject response["confidence"] = None when the agent detects fine-tuned weights, as the confidence head remains unupdated in these configurations. Finally, unless grounding is explicitly disabled, the _annotate_ungrounded function mutates the dictionary in-place to flag any ungrounded tool calls.

Function Calls and Tool Execution

When the model determines that external tools are necessary, the function_calls field becomes populated with structured call descriptors governed by schemas defined in needle/agent/tools.py. Each entry in this list contains at minimum the tool name and an arguments dictionary.

Needle's run() method subsequently consumes these descriptors to execute the actual Python functions, accumulating results back into the response dictionary under the results key during successive completion cycles.

Practical Usage Examples

The following patterns demonstrate how to interact with different response shapes in production code.

Simple text completion:

from needle import Needle

agent = Needle()
resp = agent.complete("Explain quantum tunnelling in one sentence.")

print(resp["type"])     # → "completion"

print(resp["content"])  # → "Quantum tunnelling …"

Completion triggering tool execution:

def weather(city: str) -> str:
    return f"The weather in {city} is sunny."

agent = Needle(tools=[weather])
resp = agent.complete("What's the weather in Paris?")

# Inspect potential function calls

print(resp.get("function_calls"))

# → [{'name': 'weather', 'arguments': {'city': 'Paris'}}]

Using fine-tuned weights (confidence disabled):

agent = Needle(weights="my_finetuned.cact")
resp = agent.complete("Summarise the article.")

# Confidence is explicitly set to None with custom weights

print(resp["confidence"])  # → None

Summary

• agent.complete() returns a Python dictionary parsed from the engine's JSON envelope.
• Mandatory fields include type (reply classification) and content (generated text).
• Optional fields encompass function_calls for tool invocations, confidence scores (unless using fine-tuned weights), and engine-specific metadata.
• Post-processing occurs in needle/__init__.py, where confidence injection and ungrounded call annotation modify the response before return.
• Tool execution results populate the results key only after run() processes function calls.

Frequently Asked Questions

What are the mandatory fields in the agent.complete() response?

Every response dictionary returned by agent.complete() must contain the type and content keys. The type field indicates whether the output represents a plain text completion or a function call request, while content holds the actual generated text string.

Why is the confidence field set to None when using fine-tuned weights?

When you initialize the Needle agent with custom weights via the weights parameter, the _complete method forces response["confidence"] = None at lines 58-59 of needle/__init__.py. This occurs because the fine-tuning process does not update the model's confidence head, making score reporting unreliable for these configurations.

How does Needle handle function calls in the response?

The engine populates the optional function_calls field with a list of dictionaries describing requested tool invocations. Each dictionary specifies the target tool's name and its arguments as a parameter mapping. The run() method subsequently processes these descriptors to execute the actual Python functions and accumulate outputs.

Can the response contain additional engine-specific metadata?

Yes. Any extra fields returned by the underlying native engine—such as model_version, tokens_used, or provider-specific diagnostics—pass through the JSON parsing layer unchanged and appear in the final dictionary alongside Needle's standard fields.

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