Merge

Author: mgarcia01752

CODING_AGENTS.md

@@ -69,6 +69,8 @@ Before introducing new types, validators, formats, or storage conventions:
   - Strict typing everywhere; avoid `Dict`/`List`/`Tuple`/`Union` and avoid `Any`.
   - Prefer built-in generics (`dict[str, int]`, `list[str]`) and `A | B` rather than `Union`.
   - Prefer Pydantic `BaseModel` over dict returns for public interfaces.
+  - Device-scoped API responses (top-level responses that include `mac_address`) must include a top-level `system_description` field using the parsed sysDescr model.
+  - Do not omit `system_description` on device-scoped responses; when unavailable, return an empty sysDescr model rather than `null`.
   - `BaseModel` fields must be one-line `Field(...)` declarations with descriptions.
   - Avoid generic returns; every method must have an explicit return type annotation.
   - Every method argument must have an explicit type annotation.

demo/README.md

@@ -128,6 +128,10 @@ This will:
     - `mac_address` → `aa:bb:cc:dd:ee:ff`
     - `filename` → updated filename
     - `device_details.system_description` → generic demo values:
+    - If canonical API response JSON is present, sanitize:
+      - `device.mac_address` → `aa:bb:cc:dd:ee:ff`
+      - `device.system_description` → generic demo values
+    - Legacy top-level `system_description` is also sanitized when present
 
       ```json
       {

docs/api/fast-api/common/response.md

@@ -8,22 +8,35 @@ Status Lookup: [Status Codes](../status/fast-api-status-codes.md)
 
 ```json
 {
-  "mac_address": "aa:bb:cc:dd:ee:ff",
   "status": 0,
   "message": null,
+  "device": {
+    "mac_address": "aa:bb:cc:dd:ee:ff",
+    "system_description": {
+      "HW_REV": "",
+      "VENDOR": "",
+      "BOOTR": "",
+      "SW_REV": "",
+      "MODEL": "",
+      "is_empty": true
+    }
+  },
   "data": []
 }
 ```
 
 > Some endpoints use `"results"` (object or array) instead of `"data"`. The chosen key is documented per-endpoint Guide.
+> `device` is the top-level device identity block.
 
 ## Fields
 
 | Field              | Type            | Description                                                             |
 | ------------------ | --------------- | ----------------------------------------------------------------------- |
-| `mac_address`      | string          | Target CM MAC (any supported format; normalized internally).            |
 | `status`           | integer         | Numeric result from `ServiceStatusCode` (see Status Codes link above).  |
 | `message`          | string or null  | Optional human-readable message (`null` if not set).                    |
+| `device`           | object          | Canonical device identity block containing `mac_address` and `system_description`. |
+| `device.mac_address` | string        | Target CM MAC (normalized internally).                                  |
+| `device.system_description` | object | Parsed sysDescr model; empty model when sysDescr is unavailable.        |
 | `data` / `results` | object or array | Endpoint-specific payload (may be an object or an array; may be empty). |
 
 ## PNM Header

docs/api/fast-api/single/ds/ofdm/channel-stats.md

@@ -13,7 +13,9 @@ TFTP parameters are not required.
 
 ## Response
 
-This endpoint returns the standard envelope described in [Common → Response](../../../common/response.md) (`mac_address`, `status`, `message`, `data`).
+This endpoint returns the standard envelope described in [Common → Response](../../../common/response.md) (`status`, `message`, `device`, `data`).
+
+`device` is the top-level device identity block and contains `device.mac_address` and `device.system_description` (empty model when unavailable).
 
 `data` is an **array** of downstream OFDM channels. Each item contains the SNMP table `index`, the `channel_id`, and an `entry` with DS-OFDM configuration and statistics.
 

docs/api/fast-api/single/ds/ofdm/profile-stats.md

@@ -25,7 +25,9 @@ TFTP parameters are not required.
 
 ## Response
 
-This endpoint returns the standard envelope described in [Common → Response](../../../common/response.md) (`mac_address`, `status`, `message`, `data`).  
+This endpoint returns the standard envelope described in [Common → Response](../../../common/response.md) (`status`, `message`, `device`, `data`).
+
+`device` is the top-level device identity block and contains `device.mac_address` and `device.system_description` (empty model when unavailable).  
 On success, `data` is an array of OFDM channels with per-profile counters.
 
 ### Abbreviated example

docs/api/fast-api/single/ds/scqam/channel-stats.md

@@ -13,7 +13,9 @@ TFTP parameters are not required.
 
 ## Response
 
-This endpoint returns the standard envelope described in [Common → Response](../../../common/response.md) (`mac_address`, `status`, `message`, `data`).
+This endpoint returns the standard envelope described in [Common → Response](../../../common/response.md) (`status`, `message`, `device`, `data`).
+
+`device` is the top-level device identity block and contains `device.mac_address` and `device.system_description` (empty model when unavailable).
 
 ### Abbreviated Example
 

docs/api/fast-api/single/ds/scqam/cw-error-rate.md

@@ -36,7 +36,9 @@ TFTP parameters are not required for this measurement.
 
 ## Response
 
-This endpoint returns the standard envelope described in [Common → Response](../../../common/response.md) (`mac_address`, `status`, `message`, `data`).
+This endpoint returns the standard envelope described in [Common → Response](../../../common/response.md) (`status`, `message`, `device`, `data`).
+
+`device` is the top-level device identity block and contains `device.mac_address` and `device.system_description` (empty model when unavailable).
 
 The `data` field is an array of per-channel codeword error summaries for each detected downstream SC-QAM channel.
 

docs/api/fast-api/single/fdd/fdd-diplexer-band-edge-cap.md

@@ -13,7 +13,9 @@ TFTP parameters are not required.
 
 ## Response
 
-This endpoint returns the standard envelope described in [Common → Response](../../common/response.md) (`mac_address`, `status`, `message`, `data`).
+This endpoint returns the standard envelope described in [Common → Response](../../common/response.md) (`status`, `message`, `device`, `data`).
+
+`device` is the top-level device identity block and contains `device.mac_address` and `device.system_description` (empty model when unavailable).
 
 `data` is an **array** of capability sets. Each item contains a capability `index` and an `entry` with the upstream upper, downstream lower, and downstream upper diplexer band-edge frequencies (in MHz).
 

docs/api/fast-api/single/fdd/fdd-system-diplexer-configuration.md

@@ -13,7 +13,9 @@ TFTP parameters are not required.
 
 ## Response
 
-This endpoint returns the standard envelope described in [Common → Response](../../common/response.md) (`mac_address`, `status`, `message`, `data`).
+This endpoint returns the standard envelope described in [Common → Response](../../common/response.md) (`status`, `message`, `device`, `data`).
+
+`device` is the top-level device identity block and contains `device.mac_address` and `device.system_description` (empty model when unavailable).
 
 `data` is an **object** with the SNMP `index` and an `entry` containing the configured band-edge frequencies (MHz).
 

docs/api/fast-api/single/general/diplexer-configuration.md

@@ -13,7 +13,9 @@ TFTP parameters are not required.
 
 ## Response
 
-This endpoint returns the standard envelope described in [Common → Response](../../common/response.md) (`mac_address`, `status`, `message`, `data`).
+This endpoint returns the standard envelope described in [Common → Response](../../common/response.md) (`status`, `message`, `device`, `data`).
+
+`device` is the top-level device identity block and contains `device.mac_address` and `device.system_description` (empty model when unavailable).
 
 ### Abbreviated Example