Add multi-command collect with FSM-first if-intf aux and batch cache.

ARP binds show running-config if-intf to enrich vrf; identical aux commands reuse session cache.

Co-authored-by: Cursor <cursoragent@cursor.com>

netx_api/biz_state/parsers/__init__.py

@@ -20,17 +20,18 @@ Adding a status metric
 2. ``parsers/<vendor>/<metric>.py``: ``RULE_KEYS = ("<stem>",)`` +
    ``normalize(..., fsm_tables=...)`` (use ``common.pipeline.prefer_fsm``)
 3. Register in the vendor ``PARSERS`` dict
-4. ``profiles.py``: add ``ParseProfile`` (command match + ``FieldDef`` schema)
+4. ``profiles.py``: add ``ParseProfile`` (command match + ``FieldDef`` schema);
+   optional ``aux_commands`` for multi-command collect items
 
 Collect runs TextFSM rules first → ``fsm_tables``, then calls ``normalize`` with
-both ``raw_text`` and ``fsm_tables``. The parser decides: return mapped FSM rows,
-post-process them, or ignore FSM and hand-parse ``raw_text``.
+``raw_text`` / ``raws`` / ``fsm_tables`` / ``aux_records``. Prefer FSM; hand-parse
+only when FSM has no rows.
 """
 
 from __future__ import annotations
 
 import inspect
-from typing import Any, Callable, Sequence
+from typing import Any, Callable, Mapping, Sequence
 
 from ...lldp_shared import resolve_vendor_key
 from ...ntc_parse import apply_rules, resolve_cli_platform, rules_for_command
@@ -47,8 +48,6 @@ from .zte import PARSERS as _ZTE_PARSERS
 
 NormalizeFn = Callable[..., list[dict[str, Any]]]
 
-# Later vendor packages may override earlier ones for the same parser_id.
-# Prefer moving shared logic to common/ when two vendors implement the same metric.
 _VENDOR_PARSERS: list[dict[str, NormalizeFn]] = [
     _CISCO_PARSERS,
     _HUAWEI_PARSERS,
@@ -56,7 +55,7 @@ _VENDOR_PARSERS: list[dict[str, NormalizeFn]] = [
     _JUNIPER_PARSERS,
     _NOKIA_PARSERS,
     _ERICSSON_PARSERS,
-    _ZTE_PARSERS,  # last so current ZTE status parsers win on overlaps
+    _ZTE_PARSERS,
 ]
 
 _REGISTRY: dict[str, NormalizeFn] = {
@@ -77,7 +76,6 @@ def registered_parser_ids() -> list[str]:
 
 
 def _rule_keys_for_fn(fn: NormalizeFn) -> tuple[tuple[str, ...], bool]:
-    """Return ``(keys, declared)``. ``declared`` is True when RULE_KEYS is set on fn/module."""
     keys_raw = None
     declared = False
     if hasattr(fn, "RULE_KEYS"):
@@ -101,7 +99,6 @@ def _rule_keys_for_fn(fn: NormalizeFn) -> tuple[tuple[str, ...], bool]:
 
 
 def get_parser_meta(parser_id: str) -> dict[str, Any] | None:
-    """Return ``{fn, rule_keys, rule_keys_declared}`` for a registered parser, or None."""
     fn = get_parser(parser_id)
     if not fn:
         return None
@@ -116,7 +113,6 @@ def resolve_rule_keys(
     command: str = "",
     textfsm_command: str = "",
 ) -> list[str]:
-    """RULE_KEYS from parser when declared; else index stems for textfsm_command/command."""
     meta = get_parser_meta(parser_id)
     if not meta:
         return []
@@ -138,8 +134,12 @@ def run_parser(
     command: str = "",
     params: dict[str, str] | None = None,
     textfsm_command: str = "",
+    raws: Mapping[str, str] | None = None,
+    command_rules: Mapping[str, Sequence[str]] | None = None,
+    aux_records: Mapping[str, list[dict[str, Any]]] | None = None,
+    fsm_tables_extra: Mapping[str, list[dict[str, Any]]] | None = None,
 ) -> tuple[list[dict[str, Any]], dict[str, list[dict[str, Any]]], list[str]]:
-    """Apply TextFSM rules then normalize.
+    """Apply TextFSM per-command then normalize.
 
     Returns ``(records, fsm_tables, rule_keys_used)``.
     """
@@ -153,28 +153,83 @@ def run_parser(
         vendor_key=resolve_vendor_key(vendor, device_type),
     )
     cmd_hint = str(textfsm_command or command or "").strip()
-    rule_keys = resolve_rule_keys(
-        parser_id=parser_id,
-        platform=platform,
-        command=command,
-        textfsm_command=textfsm_command,
-    )
-    fsm_tables: dict[str, list[dict[str, Any]]] = {}
-    if rule_keys and str(raw_text or "").strip():
-        fsm_tables = apply_rules(
+    raw_map: dict[str, str] = {"primary": str(raw_text or "")}
+    if raws:
+        for k, v in raws.items():
+            key = str(k or "").strip() or "primary"
+            raw_map[key] = str(v or "")
+
+    rules_map: dict[str, list[str]] = {}
+    if command_rules:
+        for k, seq in command_rules.items():
+            rules_map[str(k)] = [str(x).strip() for x in (seq or ()) if str(x).strip()]
+    if "primary" not in rules_map:
+        rules_map["primary"] = resolve_rule_keys(
+            parser_id=parser_id,
             platform=platform,
-            text=raw_text,
-            rule_keys=rule_keys,
-            command=cmd_hint,
+            command=command,
+            textfsm_command=textfsm_command,
         )
-    records = fn(
-        raw_text=raw_text,
-        fsm_tables=fsm_tables,
-        vendor=vendor,
-        device_type=device_type,
-        command=cmd_hint or command,
-        params=params or {},
-    )
+
+    fsm_tables: dict[str, list[dict[str, Any]]] = {}
+    used_keys: list[str] = []
+    for key, rules in rules_map.items():
+        if not rules:
+            continue
+        text = raw_map.get(key) or (raw_map.get("primary") if key == "primary" else "")
+        if not str(text or "").strip():
+            for rk in rules:
+                fsm_tables.setdefault(rk, [])
+                if rk not in used_keys:
+                    used_keys.append(rk)
+            continue
+        wrap_cmd = cmd_hint if key == "primary" else key.replace("_", " ")
+        part = apply_rules(
+            platform=platform,
+            text=text,
+            rule_keys=rules,
+            command=wrap_cmd,
+        )
+        fsm_tables.update(part)
+        for rk in rules:
+            if rk not in used_keys:
+                used_keys.append(rk)
+
+    if fsm_tables_extra:
+        for k, rows in fsm_tables_extra.items():
+            stem = str(k or "").strip()
+            if not stem:
+                continue
+            fsm_tables[stem] = list(rows or [])
+            if stem not in used_keys:
+                used_keys.append(stem)
+
+    call_kw: dict[str, Any] = {
+        "raw_text": raw_map.get("primary") or "",
+        "fsm_tables": fsm_tables,
+        "raws": raw_map,
+        "aux_records": dict(aux_records or {}),
+        "vendor": vendor,
+        "device_type": device_type,
+        "command": cmd_hint or command,
+        "params": params or {},
+    }
+    try:
+        sig = inspect.signature(fn)
+        if any(p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()):
+            filtered = call_kw
+        else:
+            filtered = {k: v for k, v in call_kw.items() if k in sig.parameters}
+    except (TypeError, ValueError):
+        filtered = {
+            "raw_text": call_kw["raw_text"],
+            "fsm_tables": fsm_tables,
+            "vendor": vendor,
+            "device_type": device_type,
+            "command": cmd_hint or command,
+            "params": params or {},
+        }
+    records = fn(**filtered)
     if not isinstance(records, list):
         records = []
-    return records, fsm_tables, rule_keys
+    return records, fsm_tables, used_keys

netx_api/biz_state/parsers/zte/__init__.py

@@ -10,6 +10,7 @@ from typing import Any, Callable
 
 from .arp import is_valid_arp_age, normalize_arp
 from .bgp_peer import normalize_bgp_peer
+from .if_intf import normalize_if_intf, parse_if_intf_vrf_map
 from .interface_brief import normalize_interface_brief
 from .isis_adjacency import normalize_isis_adjacency
 from .nd6_cache import normalize_nd6_cache
@@ -20,6 +21,7 @@ PARSERS: dict[str, NormalizeFn] = {
     "isis_adjacency": normalize_isis_adjacency,
     "interface_brief": normalize_interface_brief,
     "arp": normalize_arp,
+    "if_intf": normalize_if_intf,
     "nd6_cache": normalize_nd6_cache,
     "bgp_peer": normalize_bgp_peer,
 }
@@ -29,7 +31,9 @@ __all__ = [
     "is_valid_arp_age",
     "normalize_arp",
     "normalize_bgp_peer",
+    "normalize_if_intf",
     "normalize_interface_brief",
     "normalize_isis_adjacency",
     "normalize_nd6_cache",
+    "parse_if_intf_vrf_map",
 ]

netx_api/biz_state/parsers/zte/arp.py

@@ -1,6 +1,7 @@
 """ZTE: show arp [| one-line].
 
 Pipeline: TextFSM rule ``zte_zxros_show_arp`` → map rows → hand fallback.
+VRF filled from aux ``if_intf`` (show running-config if-intf), FSM-first.
 """
 
 from __future__ import annotations
@@ -11,6 +12,7 @@ from typing import Any, Mapping
 from ....lldp_shared import resolve_vendor_key
 from ....ntc_parse import apply_rules, resolve_cli_platform, row_get
 from ..common.pipeline import prefer_fsm
+from .if_intf import parse_if_intf_vrf_map
 
 RULE_KEYS = ("zte_zxros_show_arp",)
 
@@ -32,6 +34,7 @@ def _row_from_fields(
     exter: str = "",
     inter: str = "",
     sub: str = "",
+    vrf: str = "",
 ) -> dict[str, Any] | None:
     ip = str(ip or "").strip()
     iface = str(iface or "").strip()
@@ -48,6 +51,7 @@ def _row_from_fields(
         "inter_vlan": str(inter or "").strip()[:32],
         "sub_interface": str(sub or "").strip()[:128],
         "entry_type": "dynamic" if dynamic else "static",
+        "vrf": str(vrf or "").strip()[:128],
     }
 
 
@@ -110,6 +114,40 @@ def _hand_parse(*, raw_text: str, **_kw: Any) -> list[dict[str, Any]]:
     return out
 
 
+def _vrf_map_from_aux(
+    *,
+    raws: Mapping[str, str] | None,
+    aux_records: Mapping[str, list[dict[str, Any]]] | None,
+    fsm_tables: Mapping[str, list[dict[str, Any]]] | None,
+) -> dict[str, str]:
+    recs = list((aux_records or {}).get("if_intf") or [])
+    if recs:
+        return parse_if_intf_vrf_map(rows=recs)
+    fsm_rows = (fsm_tables or {}).get("zte_zxros_show_running_config_if_intf") or []
+    if fsm_rows:
+        mapped = [
+            {
+                "interface": row_get(r, "INTERFACE", "interface"),
+                "vrf": row_get(r, "VRF", "vrf"),
+            }
+            for r in fsm_rows
+        ]
+        return parse_if_intf_vrf_map(rows=mapped)
+    raw = str((raws or {}).get("if_intf") or "")
+    if raw.strip():
+        return parse_if_intf_vrf_map(raw_text=raw)
+    return {}
+
+
+def _enrich_vrf(rows: list[dict[str, Any]], vrf_map: dict[str, str]) -> list[dict[str, Any]]:
+    if not rows:
+        return rows
+    for r in rows:
+        iface = str(r.get("interface") or "").strip()
+        r["vrf"] = (vrf_map.get(iface) or "")[:128]
+    return rows
+
+
 def normalize_arp(
     *,
     raw_text: str,
@@ -118,6 +156,8 @@ def normalize_arp(
     device_type: str = "",
     command: str = "",
     params: dict[str, str] | None = None,
+    raws: Mapping[str, str] | None = None,
+    aux_records: Mapping[str, list[dict[str, Any]]] | None = None,
 ) -> list[dict[str, Any]]:
     _ = params
     tables = dict(fsm_tables or {})
@@ -132,7 +172,7 @@ def normalize_arp(
             tables = apply_rules(
                 platform=platform, text=raw_text, rule_keys=RULE_KEYS, command=cmd
             )
-    return prefer_fsm(
+    rows = prefer_fsm(
         tables,
         RULE_KEYS,
         _map_fsm_rows,
@@ -142,6 +182,8 @@ def normalize_arp(
         device_type=device_type,
         command=command,
     )
+    vrf_map = _vrf_map_from_aux(raws=raws, aux_records=aux_records, fsm_tables=tables)
+    return _enrich_vrf(rows, vrf_map)
 
 
 normalize_arp.RULE_KEYS = RULE_KEYS

netx_api/biz_state/parsers/zte/if_intf.py

@@ -0,0 +1,113 @@
+"""ZTE: show running-config if-intf → interface / VRF map.
+
+Pipeline: TextFSM ``zte_zxros_show_running_config_if_intf`` first; hand fallback.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping
+
+from ....lldp_shared import resolve_vendor_key
+from ....ntc_parse import apply_rules, resolve_cli_platform, row_get
+from ..common.pipeline import prefer_fsm
+
+RULE_KEYS = ("zte_zxros_show_running_config_if_intf",)
+
+_IFACE_RE = re.compile(r"^\s*interface\s+(\S+)\s*$", re.I)
+_VRF_RE = re.compile(r"^\s*ip\s+vrf\s+forwarding\s+(\S+)\s*$", re.I)
+
+
+def _map_fsm_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for r in rows:
+        iface = row_get(r, "INTERFACE", "interface")
+        vrf = row_get(r, "VRF", "vrf")
+        if not iface or not vrf or iface in seen:
+            continue
+        seen.add(iface)
+        out.append({"interface": iface[:128], "vrf": vrf[:128]})
+    return out
+
+
+def _hand_parse(*, raw_text: str, **_kw: Any) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    cur = ""
+    cur_vrf = ""
+    for raw in str(raw_text or "").splitlines():
+        line = raw.rstrip()
+        m_if = _IFACE_RE.match(line)
+        if m_if:
+            if cur and cur_vrf and cur not in seen:
+                seen.add(cur)
+                out.append({"interface": cur[:128], "vrf": cur_vrf[:128]})
+            cur = m_if.group(1).strip()
+            cur_vrf = ""
+            continue
+        if line.strip() == "$":
+            if cur and cur_vrf and cur not in seen:
+                seen.add(cur)
+                out.append({"interface": cur[:128], "vrf": cur_vrf[:128]})
+            cur = ""
+            cur_vrf = ""
+            continue
+        m_vrf = _VRF_RE.match(line)
+        if m_vrf and cur:
+            cur_vrf = m_vrf.group(1).strip()
+    if cur and cur_vrf and cur not in seen:
+        out.append({"interface": cur[:128], "vrf": cur_vrf[:128]})
+    return out
+
+
+def parse_if_intf_vrf_map(raw_text: str = "", *, rows: list[dict[str, Any]] | None = None) -> dict[str, str]:
+    """Build interface → vrf from metric rows or raw if-intf text."""
+    if rows is None:
+        rows = _hand_parse(raw_text=raw_text)
+    out: dict[str, str] = {}
+    for r in rows or []:
+        iface = str((r or {}).get("interface") or "").strip()
+        vrf = str((r or {}).get("vrf") or "").strip()
+        if iface and vrf:
+            out[iface] = vrf
+    return out
+
+
+def normalize_if_intf(
+    *,
+    raw_text: str,
+    fsm_tables: Mapping[str, list[dict[str, Any]]] | None = None,
+    vendor: str = "",
+    device_type: str = "",
+    command: str = "",
+    params: dict[str, str] | None = None,
+    raws: Mapping[str, str] | None = None,
+    aux_records: Mapping[str, list[dict[str, Any]]] | None = None,
+) -> list[dict[str, Any]]:
+    _ = (params, raws, aux_records)
+    tables = dict(fsm_tables or {})
+    if not any(tables.get(k) for k in RULE_KEYS):
+        platform = resolve_cli_platform(
+            vendor=vendor,
+            device_type=device_type,
+            vendor_key=resolve_vendor_key(vendor, device_type),
+        )
+        cmd = str(command or "show running-config if-intf").strip()
+        if platform:
+            tables = apply_rules(
+                platform=platform, text=raw_text, rule_keys=RULE_KEYS, command=cmd
+            )
+    return prefer_fsm(
+        tables,
+        RULE_KEYS,
+        _map_fsm_rows,
+        _hand_parse,
+        raw_text=raw_text,
+        vendor=vendor,
+        device_type=device_type,
+        command=command,
+    )
+
+
+normalize_if_intf.RULE_KEYS = RULE_KEYS