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.
feat: add publish-component workflow for WebAssembly component and enhance validation for ungrounded fields
HenryNdubuaku21291c78dac7
diff --git a/.github/workflows/publish-component.yaml b/.github/workflows/publish-component.yamlnew file mode 100644index 0000000..8f5ddec--- /dev/null+++ b/.github/workflows/publish-component.yaml@@ -0,0 +1,63 @@+name: publish-component++# Publishes the WebAssembly component of a Needle engine generation to GHCR as+# an OCI artifact and signs it with Sigstore keyless signing, so consumers can+# pull it with oras or wkg and verify the signature with cosign.+on:+ workflow_dispatch:+ inputs:+ generation:+ description: Needle engine generation+ default: "2"+ type: choice+ options: ["2", "3"]+ push:+ tags: ["v*"]++permissions:+ contents: read++jobs:+ publish:+ runs-on: ubuntu-latest+ permissions:+ contents: read+ packages: write+ id-token: write+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-python@v5+ with:+ python-version: "3.12"+ - run: pip install -e .+ - id: component+ run: |+ generation="${{ github.event.inputs.generation || '2' }}"+ needle download wasm-component --generation "$generation" --out .+ version=$(python3 -c "from needle.agent import fetch; print(fetch.engine_version($generation))")+ echo "generation=$generation" >> "$GITHUB_OUTPUT"+ echo "version=$version" >> "$GITHUB_OUTPUT"+ echo "image=ghcr.io/${{ github.repository_owner }}/needle${generation}-component" >> "$GITHUB_OUTPUT"+ - uses: oras-project/setup-oras@v1+ - uses: sigstore/cosign-installer@v3+ - run: echo "${{ secrets.GITHUB_TOKEN }}" | oras login ghcr.io --username "${{ github.actor }}" --password-stdin+ - id: push+ working-directory: wasm-component+ run: |+ image="${{ steps.component.outputs.image }}"+ version="${{ steps.component.outputs.version }}"+ digest=$(oras push "$image:$version,latest" \+ --artifact-type application/vnd.wasm.component.v1+wasm \+ --annotation "org.opencontainers.image.source=https://github.com/${{ github.repository }}" \+ --annotation "org.opencontainers.image.version=$version" \+ --annotation "org.opencontainers.image.title=needle.component.wasm" \+ --format go-template='{{.digest}}' \+ needle.component.wasm:application/vnd.wasm.component.v1+wasm \+ needle.wit:text/plain)+ echo "digest=$digest" >> "$GITHUB_OUTPUT"+ echo "published $image:$version@$digest"+ - run: cosign sign --yes "${{ steps.component.outputs.image }}@${{ steps.push.outputs.digest }}"+ - run: |+ cosign verify "${{ steps.component.outputs.image }}@${{ steps.push.outputs.digest }}" \+ --certificate-identity-regexp '^https://github.com/${{ github.repository }}/' \+ --certificate-oidc-issuer https://token.actions.githubusercontent.comdiff --git a/.github/workflows/release.yaml b/.github/workflows/release.yamlindex 22285b9..156724e 100644--- a/.github/workflows/release.yaml+++ b/.github/workflows/release.yaml@@ -74,10 +74,11 @@ jobs:echo "skip=true" >> "$GITHUB_OUTPUT"exit 0fi- if [ -z "$last" ]; then- last="v$(curl -s https://pypi.org/pypi/cactus-needle/json | python3 -c 'import json,sys; print(json.load(sys.stdin)["info"]["version"])')"- fi- echo "next=$(echo "${last#v}" | awk -F. '{printf "%d.%d.%d", $1, $2, $3 + 1}')" >> "$GITHUB_OUTPUT"+ # A manual bump on main or a publish whose tag step failed leaves+ # PyPI ahead of the tags; the next version follows whichever is newer.+ published=$(curl -sf https://pypi.org/pypi/cactus-needle/json | python3 -c 'import json,sys; print(json.loads(sys.stdin.read(), strict=False)["info"]["version"])' || true)+ current=$(printf '%s\n%s\n' "${last#v}" "$published" | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)+ echo "next=$(echo "$current" | awk -F. '{printf "%d.%d.%d", $1, $2, $3 + 1}')" >> "$GITHUB_OUTPUT"- if: steps.version.outputs.skip != 'true'run: |next="${{ steps.version.outputs.next }}"@@ -98,6 +99,6 @@ jobs:git config user.name "github-actions[bot]"git config user.email "41898282+github-actions[bot]@users.noreply.github.com"git add pyproject.toml needle/__init__.py- git commit -m "chore: release ${{ steps.version.outputs.next }}"+ git diff --cached --quiet || git commit -m "chore: release ${{ steps.version.outputs.next }}"git tag "v${{ steps.version.outputs.next }}"git push origin "v${{ steps.version.outputs.next }}"diff --git a/doc/apis.md b/doc/apis.mdindex e365ce1..9b8999a 100644--- a/doc/apis.md+++ b/doc/apis.md@@ -5,7 +5,7 @@| `needle.Needle(tools=None, system=None, weights=None, tool_index_path=None, buffer_size=65536)` | Create an agent bound to one toolset. `tools` takes decorated functions, Pydantic models, raw JSON schema dicts, or a JSON string. `system` carries environment facts. `weights` loads a tuned `.cact`. `tool_index_path` persists tool embeddings for large catalogues. || `agent.complete(text="", max_new_tokens=256, audio=None, audio_format="wav", sample_rate=0, channels=1)` | Complete a text, speech, or mixed turn. `audio` accepts WAV bytes or a path; PCM16 and float32 buffers use the accompanying format, rate, and channel fields. || `agent.embed(text="", audio=None, audio_format="wav", sample_rate=0, channels=1)` | Embed text, serialized tool schemas, audio, or a mixed input with the Needle 3 retrieval head. |-| `agent.run(query="", max_steps=8, max_new_tokens=256, audio=None, audio_format="wav", sample_rate=0, channels=1)` | Full agentic loop: the model picks calls, Needle executes your Python functions and feeds results back, and the final response carries the executed tool results as `results`. |+| `agent.run(query="", max_steps=8, max_new_tokens=256, audio=None, audio_format="wav", sample_rate=0, channels=1, strict=True)` | Full agentic loop: the model picks calls, Needle executes your Python functions and feeds results back, and the final response carries the executed tool results as `results`. || `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`). || `needle.Field(...)` | Per argument constraints, attached inline with `typing.Annotated` or passed as a default. |@@ -119,6 +119,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 `[]`.+- A date argument whose year matches none of the years written in the conversation so far or in the `system` facts is reported in `validation.ungrounded` as `tool.field`, alongside anything the engine itself flags as ungrounded. `run()` does not execute such a call; its result is `{"error": "ungrounded field"}` and the model continues from it. Pass `strict=False` to execute anyway.- `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 `"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.- An agent shares one toolset. Later turns are bare queries against the same tools; `reset()` rewinds the conversation and keeps the tools loaded.@@ -180,3 +181,17 @@ Each generation's engine is fetched once and cached under `~/.cache/cactus-needl3. Set `NEEDLE2_LIB_PATH=/path/to/libneedle.so` or `NEEDLE3_LIB_PATH=/path/to/libneedle.so` to override one generation. The legacy `NEEDLE_LIB_PATH` remains a Needle 2 alias; it is deliberately ignored for Needle 3 so a v3 archive cannot be sent to a v2 engine.The Python package itself installs offline the standard way: `pip download cactus-needle` on a connected machine, then `pip install --no-index --find-links <dir> cactus-needle` on the device. On a device that must never attempt the network, also set `HF_HUB_OFFLINE=1` so a missing engine fails fast with a clear error instead of trying to download.++## WebAssembly component++`needle download wasm-component --generation 2 --out .` pulls `needle.component.wasm` and its `needle.wit` world from the Hub. The same files are published to GHCR as a signed OCI artifact, one image per engine generation, tagged with the engine version:++```sh+oras pull ghcr.io/cactus-compute/needle2-component:2.0.4++cosign verify ghcr.io/cactus-compute/needle2-component:2.0.4 \+ --certificate-identity-regexp '^https://github.com/cactus-compute/needle/' \+ --certificate-oidc-issuer https://token.actions.githubusercontent.com+```++The artifact type is `application/vnd.wasm.component.v1+wasm`, so `wkg oci pull` works as well. Signatures are Sigstore keyless from the `publish-component` workflow in this repository; the certificate identity above is the only trust anchor.diff --git a/llms.txt b/llms.txtindex d7cc5c3..a9e2ca6 100644--- a/llms.txt+++ b/llms.txt@@ -103,6 +103,7 @@ Every turn returns one dict:- `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).+- `validation.ungrounded`, when present, lists `tool.field` names whose value is not grounded in the input, including date arguments whose year matches nothing in the conversation or the `system` facts. `run()` refuses those calls with `{"error": "ungrounded field"}` unless `strict=False`.## Behaviour contract (important for correct code)diff --git a/needle/__init__.py b/needle/__init__.pyindex ee0cfc3..a008020 100644--- a/needle/__init__.py+++ b/needle/__init__.py@@ -161,13 +161,18 @@ class Needle:warnings.warn("finetuning does not update the confidence head, so scores are ""uncalibrated for tuned weights; this agent reports confidence as None",stacklevel=2)- self._system = (system or "").encode("utf-8")+ self._system_text = system or ""+ self._system = self._system_text.encode("utf-8")tools_json = tools if isinstance(tools, str) else json.dumps(self._resolve(tools))self._tools_json = tools_json.encode("utf-8")try:- self._n_tools = len(json.loads(tools_json))+ parsed_tools = json.loads(tools_json)+ self._n_tools = len(parsed_tools)except (json.JSONDecodeError, TypeError):- self._n_tools = None+ parsed_tools, self._n_tools = [], None+ self._tool_schemas = [entry for entry in (parsed_tools or [])+ if isinstance(entry, dict)]+ self._seen_years = set()self._tool_index_path = tool_index_path.encode("utf-8") if tool_index_path else Noneself._buffer = ctypes.create_string_buffer(buffer_size)if self._weights:@@ -192,6 +197,7 @@ class Needle:_active.pop(generation, None)raise RuntimeError("needle_init failed")_active[generation] = self+ self._seen_years = set()def _resolve(self, tools):schemas = []@@ -220,10 +226,11 @@ class Needle:return self._complete(text, max_new_tokens, payload)def _complete(self, text: str, max_new_tokens: int = 256,- audio=None) -> dict:+ audio=None, ground: bool = True) -> dict:if audio is not None and self._generation < 3:raise ValueError("audio requires a Needle 3 model")self._bind()+ self._seen_years |= _source_years(text or "")if self._worker is not None:raw = self._worker.complete(text, max_new_tokens, audio)else:@@ -249,6 +256,9 @@ class Needle:f"engine bug - please report it with the prompt and schema") from errif self._weights:response["confidence"] = None+ if ground:+ _annotate_ungrounded(response, self._tool_schemas, self._seen_years,+ self._system_text)return responsedef embed(self, text: str = "", audio=None, audio_format="wav",@@ -272,7 +282,7 @@ class Needle:def run(self, query: str = "", max_steps: int = 8,max_new_tokens: int = 256, audio=None, audio_format="wav",- sample_rate=0, channels=1) -> dict:+ sample_rate=0, channels=1, strict: bool = True) -> dict:_track("run", self._track_props())payload = _prepare_audio(audio, audio_format, sample_rate, channels)response = self._complete(query, max_new_tokens, payload)@@ -281,18 +291,25 @@ class Needle:calls = response.get("function_calls") or []if response.get("type") != "call" or not calls:break+ ungrounded = _ungrounded_paths(response)results = []for call in calls:+ name = str(call.get("name"))+ fabricated = sorted(ungrounded.get(name, ()))+ if strict and fabricated:+ results.append({"error": "ungrounded " + ", ".join(fabricated)})+ continuefn = self._functions.get(call.get("name"))if fn is None:- results.append({"error": "unknown tool: " + str(call.get("name"))})+ results.append({"error": "unknown tool: " + name})continuetry: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 = self._complete(json.dumps(results, default=_jsonable),+ max_new_tokens, ground=False)response["results"] = executedreturn response@@ -307,6 +324,7 @@ class Needle:self._worker.reset()else:_lib(self._generation).needle_reset()+ self._seen_years = set()def close(self):if self._worker is not None:@@ -373,9 +391,15 @@ def _source_years(text):for match in re.finditer(pattern, lowered)}-def _temporal_grounding(text, schema, arguments):+def _licensed_years(seen_years, system=None):+ years = set(seen_years)+ if years and system:+ years |= _source_years(system)+ return years+++def _walk_grounding(schema, arguments, years):root = _schema_parameters(schema)- years = _source_years(text)checked, failures = set(), set()def walk(value, node, path):@@ -405,8 +429,44 @@ def _temporal_grounding(text, schema, arguments):return checked, failures-def _validate_extraction(text, schema, arguments, response):- checked, failures = _temporal_grounding(text, schema, arguments)+def _temporal_grounding(text, schema, arguments, system=None):+ years = _licensed_years(_source_years(text), system)+ return _walk_grounding(schema, arguments, years)+++def _ungrounded_paths(response):+ validation = response.get("validation") or {}+ grouped = {}+ for name in validation.get("ungrounded") or []:+ tool, _, path = str(name).partition(".")+ grouped.setdefault(tool, set()).add(path or tool)+ return grouped+++def _annotate_ungrounded(response, tool_schemas, seen_years, system=None):+ calls = response.get("function_calls") or []+ years = _licensed_years(seen_years, system)+ if not calls or not years:+ return+ schemas = {entry.get("name"): entry for entry in tool_schemas}+ found = []+ for call in calls:+ schema = schemas.get(call.get("name"))+ if schema is None:+ continue+ _, failures = _walk_grounding(schema, call.get("arguments") or {}, years)+ found.extend(f"{call['name']}.{path}" for path in sorted(failures))+ if not found:+ return+ validation = response.setdefault("validation", {}) or {}+ response["validation"] = validation+ existing = list(validation.get("ungrounded") or [])+ validation["ungrounded"] = existing + [+ name for name in found if name not in existing]+++def _validate_extraction(text, schema, arguments, response, system=None):+ checked, failures = _temporal_grounding(text, schema, arguments, system)validation = response.get("validation") or {}for name in validation.get("ungrounded") or []:path = name.split(".", 1)[-1]@@ -443,5 +503,5 @@ def extract(text: str, schema: type | dict, system: str | None = None,return Nonearguments = calls[0].get("arguments") or {}if strict:- _validate_extraction(text, schema, arguments, response)+ _validate_extraction(text, schema, arguments, response, system)return schema(**arguments) if _is_pydantic_model(schema) else argumentsdiff --git a/tests/test_grounding.py b/tests/test_grounding.pynew file mode 100644index 0000000..9d0abca--- /dev/null+++ b/tests/test_grounding.py@@ -0,0 +1,130 @@+import datetime+import json++import pydantic+import pytest+++class _Stub:+ def __init__(self):+ self.envelopes = []+ self.calls = []++ def needle_init(self, system, tools, index):+ self.calls.append("init")+ return 0++ def needle_load(self, blob, size):+ return 0++ def needle_complete(self, text, *args):+ self.calls.append(("complete", text.decode("utf-8")))+ buffer = args[-2]+ envelope = self.envelopes.pop(0) if len(self.envelopes) > 1 else self.envelopes[0]+ buffer.value = json.dumps(envelope).encode("utf-8")+ return 0++ def needle_reset(self):+ self.calls.append("reset")+++def stub(monkeypatch):+ import needle++ engine = _Stub()+ monkeypatch.setattr(needle, "_lib", lambda generation=2: engine)+ monkeypatch.setattr(needle, "_library_path", lambda generation=2: "/tmp/libneedle2")+ monkeypatch.setattr(needle, "_active", {})+ return engine+++class Invoice(pydantic.BaseModel):+ vendor: str+ due_date: datetime.date+++def _call(due_date, name="Invoice"):+ return {"type": "call", "confidence": 0.9,+ "function_calls": [{"name": name,+ "arguments": {"vendor": "Acme", "due_date": due_date}}]}+++def test_complete_flags_call_dates_that_contradict_the_input(stub):+ import needle++ stub.envelopes = [_call("2026-09-05")]+ agent = needle.Needle(tools=[Invoice])+ response = agent.complete("Send an invoice to Acme due on 5th September 2031")++ assert response["validation"]["ungrounded"] == ["Invoice.due_date"]+++def test_complete_leaves_grounded_dates_alone(stub):+ import needle++ stub.envelopes = [_call("2031-09-05")]+ agent = needle.Needle(tools=[Invoice])+ response = agent.complete("Send an invoice to Acme due on 5th September 2031")++ assert "validation" not in response+++def test_input_without_a_year_is_not_checked(stub):+ import needle++ stub.envelopes = [_call("2026-09-05")]+ agent = needle.Needle(tools=[Invoice])+ response = agent.complete("Send Acme an invoice due next Friday")++ assert "validation" not in response+++def test_run_refuses_ungrounded_calls_unless_strict_is_off(stub):+ import needle++ stub.envelopes = [_call("2026-09-05"), {"type": "respond", "function_calls": []}]+ agent = needle.Needle(tools=[Invoice])+ response = agent.run("Send an invoice to Acme due on 5th September 2031")+ assert response["results"] == [{"error": "ungrounded due_date"}]++ stub.envelopes = [_call("2026-09-05"), {"type": "respond", "function_calls": []}]+ agent.reset()+ response = agent.run("Send an invoice to Acme due on 5th September 2031", strict=False)+ assert response["results"][0].due_date == datetime.date(2026, 9, 5)+++def test_system_facts_license_relative_dates(stub):+ import needle++ stub.envelopes = [_call("2026-07-22")]+ agent = needle.Needle(tools=[Invoice], system="date: 2026-07-21 Tue 14:30")+ response = agent.complete("invoice Acme tomorrow for the 2019 reunion")++ assert "validation" not in response+++def test_years_carry_across_turns_until_reset(stub):+ import needle++ stub.envelopes = [_call("2031-09-05")]+ agent = needle.Needle(tools=[Invoice])+ assert "validation" not in agent.complete("bill Acme on 5th September 2031")+ assert "validation" not in agent.complete(json.dumps({"id": 42, "since": "2019-03-01"}))++ agent.reset()+ response = agent.complete("customer since March 2019, bill them")+ assert response["validation"]["ungrounded"] == ["Invoice.due_date"]+++def test_engine_reported_fabrications_are_kept_and_block_execution(stub):+ import needle++ envelope = _call("2031-09-05")+ envelope["validation"] = {"ungrounded": ["Invoice.vendor"]}+ stub.envelopes = [envelope, {"type": "respond", "function_calls": []}]+ agent = needle.Needle(tools=[Invoice])+ response = agent.run("bill someone on 5th September 2031")++ assert response["results"] == [{"error": "ungrounded vendor"}]+ assert stub.calls[-1] == ("complete", json.dumps([{"error": "ungrounded vendor"}]))diff --git a/tests/test_release.py b/tests/test_release.pyindex 0e759d0..2eff506 100644--- a/tests/test_release.py+++ b/tests/test_release.py@@ -32,16 +32,30 @@ def repo(tmp_path):return tmp_path-def version_output(repo):+def version_output(repo, published="0.0.0"):+ import osworkflow = WORKFLOW.read_text()block = workflow.split(" - id: version\n run: |\n", 1)[1]block = block.split(" - if:", 1)[0]output = repo / "output"output.write_text("")- run_block(repo, block, GITHUB_OUTPUT=str(output))+ fake_bin = repo / "fake-bin"+ fake_bin.mkdir(exist_ok=True)+ curl = fake_bin / "curl"+ curl.write_text("#!/bin/sh\nprintf '%s' '{\"info\": {\"version\": \"" + published + "\"}}'\n")+ curl.chmod(0o755)+ run_block(repo, block, GITHUB_OUTPUT=str(output),+ PATH=f"{fake_bin}{os.pathsep}{os.environ['PATH']}")return output.read_text().strip()+def tag_block(next_version):+ workflow = WORKFLOW.read_text()+ block = workflow.rsplit(" run: |\n", 1)[1]+ block = block.split(" git push", 1)[0]+ return block.replace("${{ steps.version.outputs.next }}", next_version)++def test_existing_release_tag_skips_unchanged_source(repo):git(repo, "tag", "v2.0.11")assert version_output(repo) == "skip=true"@@ -51,12 +65,8 @@ def test_release_tag_contains_versioned_source_and_skips_unchanged_main(repo):original = git(repo, "rev-parse", "HEAD")(repo / "pyproject.toml").write_text('version = "2.0.12"\n')(repo / "needle/__init__.py").write_text('__version__ = "2.0.12"\n')- workflow = WORKFLOW.read_text()- block = workflow.rsplit(" run: |\n", 1)[1]# The test uses a local tag and never pushes to a remote.- block = block.split(" git push", 1)[0]- block = block.replace("${{ steps.version.outputs.next }}", "2.0.12")- run_block(repo, block)+ run_block(repo, tag_block("2.0.12"))assert git(repo, "show", "v2.0.12:pyproject.toml") == 'version = "2.0.12"'assert git(repo, "show", "v2.0.12:needle/__init__.py") == '__version__ = "2.0.12"'assert git(repo, "rev-parse", "v2.0.12^") == original@@ -68,3 +78,31 @@ def test_release_tag_contains_versioned_source_and_skips_unchanged_main(repo):git(repo, "add", "feature.py")git(repo, "commit", "-m", "Add feature")assert version_output(repo) == "next=2.0.13"+++def test_manual_bump_on_main_follows_the_published_version(repo):+ git(repo, "tag", "v2.0.11")+ (repo / "pyproject.toml").write_text('version = "2.0.12"\n')+ (repo / "needle/__init__.py").write_text('__version__ = "2.0.12"\n')+ git(repo, "commit", "-am", "Bump version on main")+ bumped = git(repo, "rev-parse", "HEAD")++ assert version_output(repo, published="2.0.12") == "next=2.0.13"++ (repo / "pyproject.toml").write_text('version = "2.0.13"\n')+ (repo / "needle/__init__.py").write_text('__version__ = "2.0.13"\n')+ run_block(repo, tag_block("2.0.13"))+ assert git(repo, "show", "v2.0.13:pyproject.toml") == 'version = "2.0.13"'+ assert git(repo, "rev-parse", "v2.0.13^") == bumped+ assert version_output(repo, published="2.0.13") == "skip=true"+++def test_tag_step_tolerates_already_versioned_files(repo):+ (repo / "pyproject.toml").write_text('version = "2.0.13"\n')+ (repo / "needle/__init__.py").write_text('__version__ = "2.0.13"\n')+ git(repo, "commit", "-am", "Bump version on main")+ head = git(repo, "rev-parse", "HEAD")++ run_block(repo, tag_block("2.0.13"))+ assert git(repo, "rev-parse", "v2.0.13^{commit}") == head+ assert version_output(repo, published="2.0.13") == "skip=true"