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.mdindex 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.txtindex 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.pyindex 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 = Falseladder_widths: tuple = ()+ ladder_order: tuple = ()mhc_lanes: int = 4qkv_conv_taps: int = 3out_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)@classmethoddef 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 areadded one at a time by bisecting the largest remaining gap, producingdeterministic 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_layersif 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] = rankreturn tuple(ranks)@@ -182,10 +201,11 @@ def ladder_layer_ranks(num_layers):def ladder_config(config, depth):assert depth < config.num_layersassert 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_depthsub_positions = jnp.cumsum(active.astype(jnp.int32)) - 1diff --git a/tests/test_build.py b/tests/test_build.pyindex 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 pickleimport numpy as np