Feature/pdnam (#365)

* migrate to pathlib

* type hints; vendor C-extern

* choose model implementation based on number of weights; fail early

* use upstream MicroNAM directly

* missing pdnam~ impl

* start on ADR

* add pdnam~ to supported objects

* use custom exception

Author: dromer

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "tests/src/tinywav"]
 	path = tests/src/tinywav
 	url = https://github.com/mhroth/tinywav.git
+[submodule "hvcc/generators/ir2c/static/MicroNam"]
+	path = hvcc/generators/ir2c/static/MicroNam
+	url = https://github.com/jaffco/MicroNAM.git

CHANGELOG.md

@@ -10,6 +10,7 @@ Features:
 * Add `flash_time` to pd2gui Bang parser
 * Only parse GUI with `--gui` flag
 * Port objects from cyclone
+* Port `pdnam~` external using `MicroNAM`
 
 Bugfixes:
 

docs/adr/ADR-005-PDNAM-External.md

@@ -0,0 +1,50 @@
+# ADR-005: PDNAM External
+
+Date: 2026-04-20
+
+PR: https://github.com/Wasted-Audio/hvcc/pull/365
+
+## Context
+
+Recently someone posted a very small NAM implementation, called [MicroNAM](https://github.com/jaffco/MicroNAM), that can be embedded and run on STM32 via ie. the Daisy platform. Immediately the thought came up that this would be very nice to integrate into Heavy.
+
+Because until now there was no basic NAM loader for PD first an external, based on NeuralAudio library, called [PDNAM](https://github.com/wasted-Audio/pdnam) was created. It takes only a single argument to a NAM model json file. Due to its simplicity a port to Heavy should be relatively easy.
+
+### Capabilities
+
+MicroNAM supports loading 4 WaveNet model types:
+
+- Nano
+- Feather
+- Lite
+- Standard
+
+We should be able to load all of these in our implementation as well.
+
+Included in MicroNAM is a python script that converts a WaveNet model file to a C header. We should be able to call this code, or a derivative, from HVCC.
+
+Since MicroNAM is written in C++ we will need to have a C extern wrapper so it can be loaded by Heavy C code.
+
+## Decision
+
+A new internal object `__nam~f` will be defined that defers the implementation of `[pdnam~]` using an abstraction. During the IR stage we will then parse the first argument - path to the NAM file - to detect which model type is being used. At this stage we will then overload the specific object type, depending on the model. All types are defined in the core `heavy.ir.json`.
+
+Subsequently the `ir2c` stage will then handle these new object types returning the specific `c_struct`, initialization, free, and process methods to use. The implementations for these are defined in `HvSignalNam.h` and `HvSignalNam.c`. During initialization the size of the model weights is returned to include in the Heavy memory accounting logic.
+
+Because MicroNAM is written in C++ we need to create `MicroNAM_C.h/cpp` C externs that handle all the initialization, processing and freeing in our Heavy implementation. MicroNAM is added as a submodule as part of the `static/` files. The C externs and MicroNAM code will be included in the output when the `SignalNam` objects are used.
+
+In order to include the model weights as a header we will extend `HeavyObject` with a new method `get_C_gen_header_code` that is currently only used by our `SignalNam` class. Here we can then convert the NAM file to a newly generated header. The `ir2c` stage will then collect any such generated headers and write them to the output directory.
+
+For inferring the model type and creating the model weights name and header file we will modify and include the original MicroNAM python script and use it as a local `SignalNamHeader` module, for use in the various mentioned processing stages.
+
+## MVP Definition
+
+The user should be able to create a patch using `[pdnam~ <path_to_nam_file>]` and have it converted to C and run during processing. The resulting output should be very comparable to the `pdnam~` runtime.
+
+## Future Improvements
+
+We can possibly load NAM models more dynamically by parsing the JSON and updating the model weights. This would be limited to a specific model type and adds other complexity, so is currently unwanted.
+
+We will stick to a pure static implementation for the time being.
+
+Right now SIMD implementations are missing, these could possibly be added in the future.

docs/reference/objects/supported.md

@@ -229,6 +229,14 @@ Objects ported from [cyclone](https://github.com/porres/pd-cyclone) library.
 | tanh~ | |
 | tanx~ | |
 
+## Other externals
+
+Objects ported from other PD externals
+
+| object | limitations |
+| --- | --- |
+| pdnam~ | only supports WaveNet models Nano, Feather, Lite, and Standard |
+
 ## Supported Abstractions
 
 These are commonly used - or built in - abstractions that consist of compatible vanilla objects.

hvcc/core/hv2ir/BufferPool.py

@@ -75,7 +75,7 @@ def retain_buffer(self, b: List, count: int = 1) -> int:
                     return k + count  # return the new retain count
             raise HeavyException(f"{b} not found in BufferPool!")
 
-    def release_buffer(self, b: List, count: int = 1) -> int:
+    def release_buffer(self, b: tuple[str, int], count: int = 1) -> int:
         """ Reduces the retain count of the buffer. Returns the new count.
         """
         # adc~, ZERO_BUFFER, send~ buffers are special. They can not be released.

hvcc/core/hv2ir/HIrNam.py

@@ -0,0 +1,52 @@
+# Copyright (C) 2026 Wasted Audio
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from typing import Dict, Optional
+from pathlib import Path
+
+from .HeavyIrObject import HeavyIrObject
+from .HeavyGraph import HeavyGraph
+
+from hvcc.generators.ir2c.SignalNamHeader import ModelNet, load_nam_file
+
+
+class HIrNam(HeavyIrObject):
+    """ __nam~f
+    """
+
+    def __init__(
+        self,
+        obj_type: str,
+        args: Optional[Dict] = None,
+        graph: Optional[HeavyGraph] = None,
+        annotations: Optional[Dict] = None
+    ) -> None:
+        assert obj_type == "__nam~f"
+
+        # load the nam file to retrieve the model type
+        assert args is not None
+        model_net, _, _ = load_nam_file(Path(args["nam"]))
+
+        # overload the object type based on the model
+        if model_net == ModelNet.Nano:
+            obj_type = "__nam_nano~f"
+        elif model_net == ModelNet.Feather:
+            obj_type = "__nam_feather~f"
+        elif model_net == ModelNet.Lite:
+            obj_type = "__nam_lite~f"
+        elif model_net == ModelNet.Standard:
+            obj_type = "__nam_standard~f"
+
+        super().__init__(obj_type, args=args, graph=graph, annotations=annotations)

hvcc/core/hv2ir/HeavyIrObject.py

@@ -68,8 +68,8 @@ def __init__(
 
         # the list of signal buffers at the inlets and outlets
         # these are filled in by HeavyGraph.assign_signal_buffers()
-        self.inlet_buffers = [("zero", 0)] * self.num_inlets
-        self.outlet_buffers = [("zero", 0)] * self.num_outlets
+        self.inlet_buffers: list[tuple[str, int]] = [("zero", 0)] * self.num_inlets
+        self.outlet_buffers: list[tuple[str, int]] = [("zero", 0)] * self.num_outlets
 
         # True if this object has already been ordered in the signal chain
         self.__is_ordered = False
@@ -152,7 +152,7 @@ def assign_signal_buffers(self, buffer_pool: Optional[BufferPool]) -> None:
                 if len(cc) == 0:
                     continue
                 if len(cc) == 1:
-                    c = cc[0]  # get the connection
+                    c: Connection = cc[0]  # get the connection
 
                     # get the buffer at the outlet of the connected object
                     buf = c.from_object.outlet_buffers[c.outlet_index]

hvcc/core/hv2ir/HeavyParser.py

@@ -24,6 +24,7 @@
 from .HIrExpr import HIrExpr
 from .HIrInlet import HIrInlet
 from .HIrLorenz import HIrLorenz
+from .HIrNam import HIrNam
 from .HIrOutlet import HIrOutlet
 from .HIrPack import HIrPack
 from .HIrSwitchcase import HIrSwitchcase
@@ -293,6 +294,7 @@ def reduce(self) -> Tuple[Set, List]:
     "system": HLangSystem,
     "phasor": HLangPhasor,
     "line": HLangLine,
+    "__nam~f": HIrNam,
     "random": HLangRandom,
     "delay": HLangDelay,
     "table": HLangTable,

hvcc/core/json/heavy.ir.json

@@ -1982,6 +1982,111 @@
       "required": false
     }]
   },
+  "__nam~f": {
+    "inlets": [
+      "~f>"
+    ],
+    "ir": {
+      "control": false,
+      "signal": true,
+      "init": true
+    },
+    "outlets": [
+      "~f>"
+    ],
+    "args": [{
+      "name": "nam",
+      "value_type": "string",
+      "description": "path to NAM file",
+      "default": "",
+      "required": true
+    }],
+    "perf": {}
+  },
+  "__nam_nano~f": {
+    "inlets": [
+      "~f>"
+    ],
+    "ir": {
+      "control": false,
+      "signal": true,
+      "init": true
+    },
+    "outlets": [
+      "~f>"
+    ],
+    "args": [{
+      "name": "nam",
+      "value_type": "string",
+      "description": "path to NAM file",
+      "default": "",
+      "required": true
+    }],
+    "perf": {}
+  },
+  "__nam_feather~f": {
+    "inlets": [
+      "~f>"
+    ],
+    "ir": {
+      "control": false,
+      "signal": true,
+      "init": true
+    },
+    "outlets": [
+      "~f>"
+    ],
+    "args": [{
+      "name": "nam",
+      "value_type": "string",
+      "description": "path to NAM file",
+      "default": "",
+      "required": true
+    }],
+    "perf": {}
+  },
+  "__nam_lite~f": {
+    "inlets": [
+      "~f>"
+    ],
+    "ir": {
+      "control": false,
+      "signal": true,
+      "init": true
+    },
+    "outlets": [
+      "~f>"
+    ],
+    "args": [{
+      "name": "nam",
+      "value_type": "string",
+      "description": "path to NAM file",
+      "default": "",
+      "required": true
+    }],
+    "perf": {}
+  },
+  "__nam_standard~f": {
+    "inlets": [
+      "~f>"
+    ],
+    "ir": {
+      "control": false,
+      "signal": true,
+      "init": true
+    },
+    "outlets": [
+      "~f>"
+    ],
+    "args": [{
+      "name": "nam",
+      "value_type": "string",
+      "description": "path to NAM file",
+      "default": "",
+      "required": true
+    }],
+    "perf": {}
+  },
   "__neq": {
     "inlets": [
       "-->",

hvcc/generators/ir2c/HeavyObject.py

@@ -15,7 +15,7 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 from struct import unpack, pack
-from typing import Callable, Dict, List, Union
+from typing import Callable, Dict, List, Union, Optional
 
 from hvcc.types.IR import IROnMessage, IRSignalList, IRBuffer, IRObjectdict
 
@@ -123,6 +123,10 @@ def get_C_class_header_code(cls, obj_type: str, args: Dict) -> List[str]:
     def get_C_class_impl_code(cls, obj_type: str, args: Dict) -> List[str]:
         return []
 
+    @classmethod
+    def get_C_gen_header_code(cls, obj_type: str, obj_id: str, args: Dict) -> Optional[tuple[str, str]]:
+        return None
+
     @classmethod
     def get_C_process(cls, process_dict: IRSignalList, obj_type: str, obj_id: str, args: Dict) -> List[str]:
         raise NotImplementedError("method get_C_process not implemented")