Upload README.md with huggingface_hub

README.md

@@ -11,22 +11,30 @@ tags:
   - webassembly
 ---
 
-![Needle 2](banner.png)
+![Needle 2](assets/banner.png)
 
 # Needle 2
 
-Needle 2 is a 45M-parameter foundation tool call/use model for tiny devices; run it or embed it in phones, wearables, watches, TVs, smart home, small robots. 
-Compressed to CQ2-bit with Cactus Quants, the whole model ships as a single 14MB binary that runs a full session in 28MB of RAM. 
-A Raspberry Pi 5 prefills at 1.3k tok/s and decodes at 500+; an iPhone 17 Pro prefills at 3k+ and decodes at 1k+.
+Needle 2 is an open 45M-parameter model for tool calling, device use and structured extraction. The whole model is a single 14MB binary that runs a full session in 28MB of RAM. It is built on our Simple Attention Network findings, compressed to CQ2-bit with Cactus Quants, and baked into its own engine. On the benchmarks below, Needle 2 trades wins with other small models like FunctionGemma 270M, LFM2.5 230M and Apple FM, at 5x to 70x smaller, and 2 bits against their f16. Needle hits 500 tokens/sec decode speed on a Raspberry Pi 5, between 400-1,500 tokens/sec on VR devices like Meta Quest 3S and Apple Vision Pro, and ranges 300-700 on sub-$200 phones such as the Samsung A-Series. With a peak session RAM around 28MB, Needle reaches microcontrollers like the ESP32-P4; others have reported running it on an ESP32-S3 in about 11MB.
 
 - **Self-contained**: model baked into the binary, no runtime, no downloads, no network.
-- **Runs everywhere**: ARM64, x86-64, ARMv7, RISC-V, Cortex-M, and WebAssembly, on Apple, Windows, Linux, Android, Raspberry Pi.
+- **Runs everywhere**: ARM64, x86-64, ARMv7, RISC-V, and WebAssembly, on Apple, Windows, Linux, Android, Raspberry Pi.
 - **Simple contract**: tool calls come back as structured data, text in, JSON out; a byte-level grammar compiled from your schemas constrains every token.
 - **Confidence-gated**: every response carries a calibrated confidence score from a learned head; set a threshold, act above it, escalate below it.
-- **Tool retrieval**: declare a large catalogue and a built-in retrieval head renders only the top ten tools per turn, with the grammar constrained to that subset.
-- **Bounded memory**: a 256-token sliding window with the tools pinned as KV sinks; session memory caps near 14MB no matter how long the conversation runs.
+- **Tool retrieval**: declare a large catalogue and a built-in retrieval head renders only the top five tools per turn, with the grammar constrained to that subset.
+- **Bounded memory**: a 256-token sliding window with the tools pinned as KV sinks, so total memory stays near 28MB no matter how long the conversation runs.
 
-![Size-quality frontier: mobile-class and below](frontier.svg)
+Source, engine, and training code: [github.com/cactus-compute/needle](https://github.com/cactus-compute/needle).
+
+![Size-quality frontier: mobile-class and below](assets/frontier.png)
+
+## Simple Attention Network
+
+Needle 2 is a Simple Attention Network, our dense small-model recipe: a Hadamard MLP in place of the FFN, GQA attention, engram key-value memory, and multi-lane hyper-connections. See the paper for the design and ablations: [arXiv:2607.18363](https://arxiv.org/abs/2607.18363).
+
+![Simple Attention Network architecture](assets/architecture.png)
+
+Each block carries its update rule. Here x̂ is the RMS-normalised flattening of the four residual streams, H the orthonormal Walsh-Hadamard transform (a fixed matrix, applied in n log n time with no weights to read), (kₜ, vₜ) rows gathered from hashed n-gram tables, and P the doubly-stochastic normalisation of the routing logits A, computed by Sinkhorn iteration; a, b, g and all σ-gates are learned and input-dependent. Both attention and MLP residuals are sandwich-normed and gated, the engram sites fire at two layers, and decoding is constrained by a byte-level grammar compiled from the declared schemas.
 
 ## Quickstart with Python
 
@@ -34,33 +42,102 @@ A Raspberry Pi 5 prefills at 1.3k tok/s and decodes at 500+; an iPhone 17 Pro pr
 pip install cactus-needle
 ```
 
-The PyPI package is a small pure-Python shim; the first `import needle` downloads the engine for your platform (~13 MB, cached in `~/.cache/cactus-needle`), so the first run needs network. Every run after is offline.
+Needle 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.
 
 ```python
 import needle
 
-tools = [
-    {"name": "set_timer",
-     "parameters": {"type": "object", "properties": {"minutes": {"type": "integer"}, "label": {"type": "string"}}}},
-    {"name": "play_music",
-     "parameters": {"type": "object", "properties": {"query": {"type": "string"}}}},
-]
+@needle.tool
+def get_weather(city: str):
+    "Get the current weather for a city."
+    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?")["reasoning"])
+```
+
+**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).
+
+```python
+from typing import Literal
+
+@needle.tool
+def set_thermostat(temperature: int, mode: Literal["heat", "cool", "auto"] = "auto"):
+    """Set the thermostat.
+
+    Args:
+        temperature: target temperature in Celsius
+        mode: heating strategy to use
+    """
+    return {"temperature": temperature, "mode": mode}
+
+agent = needle.Needle(tools=[set_thermostat])
+agent.run("make it 21 and cool the room")
+```
+
+**Advanced**: constrain the values with `needle.Field`, attached inline via `Annotated`. Ranges, patterns, lengths, and item counts are compiled into the decode grammar, so the model can only ever emit values that satisfy them.
+
+```python
+from typing import Annotated
+
+@needle.tool
+def send_money(
+    amount: Annotated[float, needle.Field(gt=0, le=10000, description="USD, up to 10,000")],
+    to:     Annotated[str,   needle.Field(pattern=r"^@[a-z0-9_]+$", description="recipient handle")],
+    memo:   Annotated[str,   needle.Field(max_length=80)] = "",
+):
+    "Send money to a handle."
+    return {"sent": amount, "to": to}
+```
+
+`Field` supports `description`, `enum`, `const`, `ge`/`le`/`gt`/`lt`, `multiple_of`, `min_length`/`max_length`, `pattern`, `format`, `min_items`/`max_items`, and `unique_items`.
 
+**Extraction**: to pull structured data out of text, declare the shape and call `extract()`. Pass a Pydantic model and you get a typed object back.
+
+```python
+from pydantic import BaseModel
+
+class Invoice(BaseModel):
+    vendor: str
+    total: float
+    due_date: str
+
+invoice = needle.extract("Invoice from Acme Corp, $1,200.00, due 2026-09-01", Invoice)
+print(invoice.vendor, invoice.total)   # -> Acme Corp 1200.0
+```
+
+**By hand** - the decorator just builds a JSON schema; you can pass that schema directly, which is exactly what Needle consumes. This is how you set descriptions and constraints without the decorator (and `tools.json` for the CLI is the same shape):
+
+```python
+tools = [{
+    "name": "set_lights",
+    "description": "Turn a room's lights on or off and set brightness",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "room": {"type": "string", "description": "which room to control"},
+            "on": {"type": "boolean"},
+            "brightness": {"type": "integer", "minimum": 0, "maximum": 100},
+        },
+        "required": ["room", "on"],
+    },
+}]
 agent = needle.Needle(tools=tools)
-# with many tools, persist their embeddings across runs:
-# agent = needle.Needle(tools=tools, tool_index_path="tools.idx")
+```
 
-response = agent.complete("set a 10 minute timer for the pasta") 
+Prefer to drive the loop yourself instead of `run()`? `complete()` returns the raw call and you execute it:
 
+```python
+import json
+response = agent.complete("dim the living room to 30")
 if response["type"] == "call":
-    tool_result = run_tool(response["function_calls"][0])
-    response = agent.complete(tool_result) 
-    response = agent.complete("and put on some jazz")   
-
-agent.reset() 
+    result = set_lights(**response["function_calls"][0]["arguments"])
+    response = agent.complete(json.dumps(result))   # feed the result back
 ```
 
-Every turn returns one JSON object:
+With a large catalogue, persist tool embeddings across runs with `needle.Needle(tools=..., tool_index_path="tools.idx")`. Every turn returns one JSON object:
 
 ```json
 {
@@ -113,7 +190,6 @@ Download the folder for your platform from the release:
 | Windows ARM | `windows-arm64` | `needle.exe` | `libneedle.a` |
 | Android | `android-arm64` / `android-armv7` / `android-riscv64` | `needle` | `libneedle.a` |
 | iOS / watchOS / tvOS | `ios-arm64` / `watchos-arm64` / `tvos-arm64` | - | `libneedle.a` |
-| Cortex-M (bare-metal/RTOS) | `cortex-m4` / `cortex-m7` / `cortex-m55` | - | `libneedle.a` |
 | Browser / Node (WebAssembly) | `wasm` | - | `needle.js` + `needle.wasm` |
 
 To run it, use the command-line binary. On macOS, Linux, or Android:
@@ -172,21 +248,15 @@ To run it, use the command-line binary. On macOS, Linux, or Android:
 
 ## Tool retrieval
 
-Ten or fewer declared tools render directly. Above that, retrieval engages: at init every tool schema is embedded once by a built-in contrastive head, 
-each turn embeds the query, and only the ten highest-scoring tools enter the context, with the grammar rebuilt over just that subset. an unselected 
-tool is unreachable, not merely unlikely. `--tool-index <path>` (CLI) or `tool_index_path` (Python) persists the embeddings on disk, keyed by a fingerprint 
-over the schemas and the model; a matching fingerprint loads instantly, a changed schema re-embeds only what changed.
+Five or fewer declared tools render directly. Above that, retrieval engages: at init every tool schema is embedded once by a built-in contrastive head, each turn embeds the query, and only the five highest-scoring tools enter the context, with the grammar rebuilt over just that subset. An unselected tool is unreachable, not merely unlikely. `--tool-index <path>` (CLI) or `tool_index_path` (Python) persists the embeddings on disk, keyed by a fingerprint over the schemas and the model; a matching fingerprint loads instantly, a changed schema re-embeds only what changed.
 
 ## Confidence
 
-The `confidence` field is the minimum of two signals: a calibrated post-hoc head that scores the full prompt plus the call the model just produced, and 
-the decoding probability of the call tokens. A call is accepted only when both agree, so the failure mode is escalation, not wrong execution. The contract: 
-pick a threshold for your product, act at or above it, re-ask or route to a bigger model below it. Off-topic requests return the empty call `[]`.
+The `confidence` field is the minimum of two signals: a calibrated post-hoc head that scores the full prompt plus the call the model just produced, and the decoding probability of the call tokens. A call is accepted only when both agree, so the failure mode is escalation, not wrong execution. The contract: pick a threshold for your product, act at or above it, re-ask or route to a bigger model below it. Off-topic requests return the empty call `[]`.
 
-## Custom weights
+## Fine-tuning
 
-- `needle_load(cact, n)` borrows the caller's buffer: no copy is made, the pointer must stay valid and unmodified until the next `needle_load` call or process exit. This is the load path when weights are not embedded (WebAssembly, or bytes fetched over a network); to load a `.cact` from disk, read the file and pass the bytes.
-- Embedded builds keep the weights in the binary's read-only section; all weight bytes stay file-backed and evictable, nothing is copied to the heap.
+Needle is open and trainable end to end. Fine-tune it on your own tools and domains, then export to a `.cact` and ship it like the base model. See the [needle repo](https://github.com/cactus-compute/needle) for training and export.
 
 ## Extraction
 
@@ -219,4 +289,21 @@ Extraction is the same exchange as tool calling: declare the record schema as th
 
 ```json
 { "type": "call", "function_calls": [ { "name": "receipt", "arguments": { "merchant": "GreenMart", "total": 7.75 } } ] }
-```
+```
+
+## Citation
+
+Needle 2 is built by the Cactus Compute team. If you use it in your work, please cite:
+
+```bibtex
+@misc{needle2_2026,
+  title        = {Needle 2: A 45M-Parameter Foundation Tool-Calling Model for Tiny Devices},
+  author       = {Ndubuaku, Henry and Mosoyan, Karen and Mroz, Jakub and Cylich, Noah and
+                  Kumar, Satyajit and Sandhu, Parkirat and Shemet, Roman and Lee, Justin H.},
+  year         = {2026},
+  organization = {Cactus Compute, Inc.},
+  howpublished = {\url{https://github.com/cactus-compute/needle}}
+}
+```
+
+Reach out on founders@cactuscompute.com for partnerships, collaborations, synergies and deploying Needle2 in your product.