Skip to content

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 ladder_order to TransformerConfig and implement related functions

HenryNdubuakud06bafb90b88
diff --git a/doc/apis.md b/doc/apis.md
index 8159a3f..cf49129 100644
--- a/doc/apis.md
+++ b/doc/apis.md
@@ -120,6 +120,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.
+- `extract()` caps the engine at one call per turn, so a record schema never yields a second record; `escalate` is also raised when the request negates the tool's verb, quotes a command reported by someone else, or a required enumerated value has no support in the request.
- Arguments arrive after the engine's deterministic repair step, which grounds them in the request text (first/last name split, phone completion, verbatim quoted titles, place queries with their street address, weekday and explicit dates resolved against the `date:` fact, empty optionals and duplicate calls dropped). Enumerated parameters are never altered.
- `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.
diff --git a/llms.txt b/llms.txt
index cdcb381..ff38dbd 100644
--- a/llms.txt
+++ b/llms.txt
@@ -104,6 +104,7 @@ Every turn returns one dict:
- `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`.
+- `extract()` caps the engine at one call per turn (`needle_set_max_calls`), so a record schema never yields a second record.
- Arguments arrive after the engine's deterministic repair step, which grounds them in the request text: a full name in one of a first/last pair is split, a truncated phone number is completed, quoted titles are restored verbatim, place queries recover dropped words and a following street address, weekday and `March 4th` style dates resolve against the `date:` fact, empty optional strings and duplicate calls are dropped. Enumerated parameters are never altered.
## Behaviour contract (important for correct code)
diff --git a/needle/model/architecture.py b/needle/model/architecture.py
index 21c289d..d7024f1 100644
--- a/needle/model/architecture.py
+++ b/needle/model/architecture.py
@@ -68,6 +68,7 @@ class TransformerConfig:
ladder_depths: tuple = ()
ladder_sample: bool = False
ladder_widths: tuple = ()
+ ladder_order: tuple = ()
mhc_lanes: int = 4
qkv_conv_taps: int = 3
out_vocab: int = 0
@@ -105,6 +106,7 @@ class TransformerConfig:
self.global_layers = tuple(self.global_layers)
self.ladder_depths = tuple(self.ladder_depths)
self.ladder_widths = tuple(self.ladder_widths)
+ self.ladder_order = tuple(self.ladder_order)
@classmethod
def from_saved(cls, saved):
@@ -115,7 +117,8 @@ class TransformerConfig:
for key, off in (("qk_head_dim", 0), ("v_head_dim", 0),
("sliding_window", 0), ("global_layers", ()),
("ladder_depths", ()), ("ladder_sample", False),
- ("ladder_widths", ()), ("engram_seed_heads", 0),
+ ("ladder_widths", ()), ("ladder_order", ()),
+ ("engram_seed_heads", 0),
("qkv_conv_taps", 0), ("out_vocab", 0),
("image_code_offset", 0), ("image_sem_codes", 0),
("image_sem_dim", 0), ("image_tex_books", 0),
@@ -157,23 +160,39 @@ def _ladder_layer_order(num_layers):
return tuple(order)
-def ladder_layer_indices(num_layers, depth):
+def ladder_order(spec):
+ """Block selection order for a model: the bisection order of its depth, or
+ the parent's order carried by a sliced rung so nested slices stay trained."""
+ if isinstance(spec, int):
+ return _ladder_layer_order(spec)
+ saved = tuple(getattr(spec, "ladder_order", ()) or ())
+ if saved:
+ if sorted(saved) != list(range(spec.num_layers)):
+ raise ValueError(f"ladder_order {saved} is not a permutation of "
+ f"{spec.num_layers} blocks")
+ return saved
+ return _ladder_layer_order(spec.num_layers)
+
+
+def ladder_layer_indices(spec, depth):
"""Return the stable, nested original-layer indices for a depth rung.
Every deployable rung keeps both endpoint blocks. Interior blocks are
added one at a time by bisecting the largest remaining gap, producing
deterministic nested subnetworks with spatially balanced coverage.
+ `spec` is a layer count or a config (whose ladder_order wins).
"""
+ num_layers = spec if isinstance(spec, int) else spec.num_layers
if not 2 <= depth <= num_layers:
raise ValueError(
f"ladder depth must be in [2, {num_layers}], got {depth}")
- return tuple(sorted(_ladder_layer_order(num_layers)[:depth]))
+ return tuple(sorted(ladder_order(spec)[:depth]))
-def ladder_layer_ranks(num_layers):
+def ladder_layer_ranks(spec):
"""Map each original block to its selection rank in the nested ladder."""
- order = _ladder_layer_order(num_layers)
- ranks = [0] * num_layers
+ order = ladder_order(spec)
+ ranks = [0] * len(order)
for rank, layer in enumerate(order):
ranks[layer] = rank
return tuple(ranks)
@@ -182,10 +201,11 @@ def ladder_layer_ranks(num_layers):
def ladder_config(config, depth):
assert depth < config.num_layers
assert tuple(config.engram_layers) == tuple(sorted(config.engram_layers))
- selected = ladder_layer_indices(config.num_layers, depth)
+ selected = ladder_layer_indices(config, depth)
remap = {layer: i for i, layer in enumerate(selected)}
fields = dict(config.__dict__)
fields["num_layers"] = depth
+ fields["ladder_order"] = tuple(remap[l] for l in ladder_order(config) if l in remap)
fields["global_layers"] = tuple(
remap[l] for l in config.global_layers if l in remap)
fields["engram_layers"] = tuple(
@@ -198,13 +218,13 @@ def ladder_config(config, depth):
def ladder_row_keep(config, exit_depth=None):
if exit_depth is None:
return None
- ranks = jnp.asarray(ladder_layer_ranks(config.num_layers), jnp.int32)
+ ranks = jnp.asarray(ladder_layer_ranks(config), jnp.int32)
return jnp.concatenate([jnp.ones((1,), jnp.float32),
(ranks < exit_depth).astype(jnp.float32)])
def ladder_slice(params, config, depth):
- selected = ladder_layer_indices(config.num_layers, depth)
+ selected = ladder_layer_indices(config, depth)
selected_set = set(selected)
selected_array = jnp.asarray(selected, dtype=jnp.int32)
rows = jnp.asarray((0, *(layer + 1 for layer in selected)), jnp.int32)
@@ -828,7 +848,7 @@ class Stack(nn.Module):
else:
carry = x
- layer_ranks = jnp.asarray(ladder_layer_ranks(L), dtype=jnp.int32)
+ layer_ranks = jnp.asarray(ladder_layer_ranks(cfg), dtype=jnp.int32)
if exit_depth is not None:
active = layer_ranks < exit_depth
sub_positions = jnp.cumsum(active.astype(jnp.int32)) - 1
diff --git a/tests/test_build.py b/tests/test_build.py
index 11f134a..ba18288 100644
--- a/tests/test_build.py
+++ b/tests/test_build.py
@@ -38,6 +38,21 @@ def test_build_layers_exports_the_rung(tiny_checkpoint, tmp_path):
assert header["num_layers"] == 3
+def test_rung_of_a_rung_is_the_trained_rung(tiny_checkpoint):
+ import jax
+ import numpy as np
+ from needle.model.finetune import rung
+ from needle.model.run import load_checkpoint
+
+ params, config = load_checkpoint(tiny_checkpoint)
+ p3, c3 = rung(params, config, 3)
+ via_3, c_via = rung(p3, c3, 2)
+ direct, c_direct = rung(params, config, 2)
+ assert c3.ladder_order and vars(c_via) == vars(c_direct)
+ for a, b in zip(jax.tree_util.tree_leaves(via_3), jax.tree_util.tree_leaves(direct)):
+ assert np.array_equal(np.asarray(a), np.asarray(b))
+
+
def test_load_checkpoint_drops_the_mtp_block(tiny_checkpoint, tmp_path):
import pickle
import numpy as np