Automation foundation model for tiny devices: 2-bit, 8-29 MB, tool calls, ASR, structured extraction and embeddings on phones, wearables, smart homes, robots, cars and microcontrollers.
Update run method to include executed tool results in response
HenryNdubuakub2ac7a283777
diff --git a/README.md b/README.mdindex e209a58..dee52a5 100644--- a/README.md+++ b/README.md@@ -32,7 +32,7 @@ pip install cactus-needleNeedle reads your tool descriptions to decide what to call and how to fill arguments, so describing them well is the whole game. You can do it three ways, from least to most control.-**Simple**: decorate a function. The signature gives the argument types, the docstring is the tool description, and `run()` completes the loop: model picks the call, Needle executes your function, feeds the result back, and returns the model's final answer.+**Simple**: decorate a function. The signature gives the argument types, the docstring is the tool description, and `run()` completes the loop: model picks the call, Needle executes your function, feeds the result back, and returns the final response with the executed tool results attached as `results`.```pythonimport needle@@ -43,7 +43,8 @@ def get_weather(city: str):return {"city": city, "temp_c": 27, "sky": "clear"}agent = needle.Needle(tools=[get_weather])-print(agent.run("what's it like in Lagos right now?"))+print(agent.run("what's it like in Lagos right now?")["results"])+# [{'city': 'Lagos', 'temp_c': 27, 'sky': 'clear'}]```**Medium**: describe each argument and offer choices. Needle reads a Google-style `Args:` block for per-parameter descriptions; a default makes an argument optional; a `Literal` becomes a fixed set the model must choose from (it cannot emit anything else).@@ -159,7 +160,7 @@ Needle solves every problem as a function call. The context declares what may be- A request no declared tool can serve is refused with the empty call `[]`. That is the whole contract for off-topic input; there is no free-text fallback.- Arguments contain only values evidenced by the input. An optional field with no evidence is omitted, not guessed; omission is the field-level `[]`.- `reasoning` is the model's short derivation of each argument from its source span (`'ten minutes' -> minutes 10`). It is generated unconstrained; only the call itself is grammar-constrained, so the JSON cannot be malformed while the derivation stays legible.-- After you execute a call, pass the result back as the next `complete()`. The model continues from it, and later arguments may depend on earlier results: `search_for_contact` first, then `send_instant_message` with the returned `contact_id`. A final step may answer in plain text from the results: `"type": "respond"` with empty `function_calls`.+- After you execute a call, pass the result back as the next `complete()`. The model continues from it, and later arguments may depend on earlier results: `search_for_contact` first, then `send_instant_message` with the returned `contact_id`. A final `"type": "respond"` with empty `function_calls` signals the loop is done; the answer is the tool results themselves, which `run()` collects on the final response as `results`. No free text is generated.- A session shares one toolset. Later turns are bare queries against the same tools; `reset()` rewinds the conversation and keeps the tools loaded.## Extractiondiff --git a/llms.txt b/llms.txtindex 77a68fd..7419fcd 100644--- a/llms.txt+++ b/llms.txt@@ -19,7 +19,7 @@ pip install cactus-needle- `system`: optional environment-facts string (see System facts).- `weights`: path to a tuned `.cact` to load instead of the baked base model.- `tool_index_path`: path to persist tool embeddings when you declare many tools.-- `agent.run(query, max_steps=8, max_new_tokens=256) -> dict` - full agentic loop: model picks calls, Needle executes your Python functions, feeds results back, returns the final response.+- `agent.run(query, max_steps=8, max_new_tokens=256) -> dict` - full agentic loop: model picks calls, Needle executes your Python functions, feeds results back, returns the final response with the executed tool results attached as `results`.- `agent.complete(text, max_new_tokens=256) -> dict` - one turn; you execute the call and feed the result back yourself via the next `complete(...)`.- `agent.reset()` - rewind the conversation, keep the tools loaded.- `needle.tool` - decorator that turns a function into a tool schema (attached as `fn._needle_tool`).@@ -98,7 +98,7 @@ Every turn returns one dict:}```-- `type` is `"call"` when there are tool calls, `"respond"` for a final plain-text answer from results, `"refuse"`/empty `function_calls` for off-topic input.+- `type` is `"call"` when the model wants tool calls (empty `function_calls` is the refusal for off-topic input), `"respond"` when the loop is finished; the answer is the tool results, no free text is generated.- `function_calls` is a list of `{"name", "arguments"}`. Read `arguments` directly; it is grammar-guaranteed to match your schema.- `reasoning` is a short unconstrained derivation of each argument from its source span.- `confidence` is a calibrated score in [0,1] (see Confidence gating).diff --git a/needle/__init__.py b/needle/__init__.pyindex 22dffed..8cf2a08 100644--- a/needle/__init__.py+++ b/needle/__init__.py@@ -79,10 +79,11 @@ class Needle:def run(self, query, max_steps=8, max_new_tokens=256):response = self.complete(query, max_new_tokens)+ executed = []for _ in range(max_steps):calls = response.get("function_calls") or []if response.get("type") != "call" or not calls:- return response+ breakresults = []for call in calls:fn = self._functions.get(call.get("name"))@@ -93,7 +94,9 @@ class Needle:results.append(fn(**(call.get("arguments") or {})))except Exception as exc:results.append({"error": str(exc)})+ executed.extend(results)response = self.complete(json.dumps(results, default=_jsonable), max_new_tokens)+ response["results"] = executedreturn responsedef extract(self, text, schema, max_new_tokens=256):