panasonic-ac-models 1.0.0b7__tar.gz

panasonic_ac_models-1.0.0b7/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: panasonic_ac_models
+Version: 1.0.0b7
+Summary: Hardware database and feature gating lookup engine for Panasonic Smart ACs (Indian Market / MirAIe IoT)
+Author-email: selvakk2k <selvakk2k@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/selvakk2k/panasonic-ac-models
+Project-URL: Documentation, https://github.com/selvakk2k/panasonic-ac-models#readme
+Project-URL: Repository, https://github.com/selvakk2k/panasonic-ac-models.git
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# panasonic-ac-models
+
+A model capability database and lookup engine for Panasonic Smart Air Conditioners (Indian Market / MirAIe platform). Designed for Home Assistant custom integrations, companion libraries, and custom dashboard cards to dynamically determine supported AC features (HVAC modes, Nanoe ionizer, Converti presets).
+
+---
+
+## Installation & Usage
+
+### Python Library (Backend / Home Assistant Integrations)
+
+Install via `pip`:
+
+```bash
+pip install git+https://github.com/selvakk2k/panasonic-ac-models.git
+```
+
+Query AC capabilities using the normalized lookup engine:
+
+```python
+from panasonic_ac_models import ACModelLookup
+
+lookup = ACModelLookup()
+
+# Query any indoor unit SKU (handles 'CS/CU-', casing, and spaces automatically)
+caps = lookup.get_capabilities("CS/CU-EZ18BKYD")
+
+print(caps["series"])          # "EZ"
+print(caps["has_heat_mode"])   # 1 (Dual Heat Pump)
+print(caps["converti_type"])   # "7-in-1"
+
+# Dynamic feature gating
+hvac_modes = ["cool", "heat", "off"] if caps["has_heat_mode"] == 1 else ["cool", "off"]
+show_nanoe = (caps["has_nanoe"] == 1)
+```
+
+---
+
+### Direct CDN (JavaScript / Frontend Cards)
+
+Fetch `models.json` directly via jsDelivr CDN:
+
+```
+https://cdn.jsdelivr.net/gh/selvakk2k/panasonic-ac-models@main/models.json
+```
+
+```javascript
+fetch("https://cdn.jsdelivr.net/gh/selvakk2k/panasonic-ac-models@main/models.json")
+  .then(res => res.json())
+  .then(data => {
+    const rawModel = "CS/CU-NU18AKY4WXD";
+    const cleanModel = rawModel.replace(/^(CS\/CU|CU)[-_\s]?/i, 'CS-').trim().toUpperCase();
+    
+    const family = data.families.find(f => f.indoor_units.includes(cleanModel));
+    console.log("Heat Mode:", family?.has_heat_mode);
+    console.log("Converti Mode:", family?.converti_type);
+  });
+```
+
+---
+
+## Feature Gating Rules
+
+| Feature | Condition | Series / Generations |
+|---|---|---|
+| Wi-Fi / MirAIe | All Inverter Splits | NU, SU, EU, AU, HU, XU, EZ, KZ, WU, QU, YU, RU, TU, VU, ZU, LU, S-##PUY |
+| Non-Smart | Fixed Speed / Window | KN, KU, CW-, PUB, PD |
+| Heat Mode | Dual Heat Pump | EZ, KZ only |
+| Nanoe Ionizer | Purification Models | HU, XU only |
+| Converti 8-in-1 | 2026+ Models | NU/SU (Gen ≥ B) & EZ/HU/EU (Gen ≥ C) |
+| Converti 7-in-1 | 2023–2025 Models | All other 2023–2025 inverter splits |
+| Auto-Convertible (none) | Pre-2023 Models | 2020–2022 models (Gen W, X - sensor auto-scaling, no manual percentage buttons) |
+
+---
+
+## Database Summary
+
+- **Models Tracked**: 403 verified Wi-Fi models across 116 hardware families.
+- **Data Sources**: Bureau of Energy Efficiency (BEE) certified labels, Panasonic India catalogs, empirical MirAIe telemetry.
+
+---
+
+## Contributing
+
+Pull requests are welcome! To add or correct a model:
+
+1. Edit `models.json`.
+2. Add the indoor SKU to the appropriate `indoor_units` array under `families`.
+3. Submit a PR. Continuous Integration (`check-jsonschema`) will validate changes against `schema.json`.
+
+---
+
+## Authors & Credits
+
+- **Lead Maintainer**: [@selvakk2k](https://github.com/selvakk2k)
+- **AI Pair Programming & Architecture**: Antigravity (Google DeepMind Team)

panasonic_ac_models-1.0.0b7/README.md

@@ -0,0 +1,95 @@
+# panasonic-ac-models
+
+A model capability database and lookup engine for Panasonic Smart Air Conditioners (Indian Market / MirAIe platform). Designed for Home Assistant custom integrations, companion libraries, and custom dashboard cards to dynamically determine supported AC features (HVAC modes, Nanoe ionizer, Converti presets).
+
+---
+
+## Installation & Usage
+
+### Python Library (Backend / Home Assistant Integrations)
+
+Install via `pip`:
+
+```bash
+pip install git+https://github.com/selvakk2k/panasonic-ac-models.git
+```
+
+Query AC capabilities using the normalized lookup engine:
+
+```python
+from panasonic_ac_models import ACModelLookup
+
+lookup = ACModelLookup()
+
+# Query any indoor unit SKU (handles 'CS/CU-', casing, and spaces automatically)
+caps = lookup.get_capabilities("CS/CU-EZ18BKYD")
+
+print(caps["series"])          # "EZ"
+print(caps["has_heat_mode"])   # 1 (Dual Heat Pump)
+print(caps["converti_type"])   # "7-in-1"
+
+# Dynamic feature gating
+hvac_modes = ["cool", "heat", "off"] if caps["has_heat_mode"] == 1 else ["cool", "off"]
+show_nanoe = (caps["has_nanoe"] == 1)
+```
+
+---
+
+### Direct CDN (JavaScript / Frontend Cards)
+
+Fetch `models.json` directly via jsDelivr CDN:
+
+```
+https://cdn.jsdelivr.net/gh/selvakk2k/panasonic-ac-models@main/models.json
+```
+
+```javascript
+fetch("https://cdn.jsdelivr.net/gh/selvakk2k/panasonic-ac-models@main/models.json")
+  .then(res => res.json())
+  .then(data => {
+    const rawModel = "CS/CU-NU18AKY4WXD";
+    const cleanModel = rawModel.replace(/^(CS\/CU|CU)[-_\s]?/i, 'CS-').trim().toUpperCase();
+    
+    const family = data.families.find(f => f.indoor_units.includes(cleanModel));
+    console.log("Heat Mode:", family?.has_heat_mode);
+    console.log("Converti Mode:", family?.converti_type);
+  });
+```
+
+---
+
+## Feature Gating Rules
+
+| Feature | Condition | Series / Generations |
+|---|---|---|
+| Wi-Fi / MirAIe | All Inverter Splits | NU, SU, EU, AU, HU, XU, EZ, KZ, WU, QU, YU, RU, TU, VU, ZU, LU, S-##PUY |
+| Non-Smart | Fixed Speed / Window | KN, KU, CW-, PUB, PD |
+| Heat Mode | Dual Heat Pump | EZ, KZ only |
+| Nanoe Ionizer | Purification Models | HU, XU only |
+| Converti 8-in-1 | 2026+ Models | NU/SU (Gen ≥ B) & EZ/HU/EU (Gen ≥ C) |
+| Converti 7-in-1 | 2023–2025 Models | All other 2023–2025 inverter splits |
+| Auto-Convertible (none) | Pre-2023 Models | 2020–2022 models (Gen W, X - sensor auto-scaling, no manual percentage buttons) |
+
+---
+
+## Database Summary
+
+- **Models Tracked**: 403 verified Wi-Fi models across 116 hardware families.
+- **Data Sources**: Bureau of Energy Efficiency (BEE) certified labels, Panasonic India catalogs, empirical MirAIe telemetry.
+
+---
+
+## Contributing
+
+Pull requests are welcome! To add or correct a model:
+
+1. Edit `models.json`.
+2. Add the indoor SKU to the appropriate `indoor_units` array under `families`.
+3. Submit a PR. Continuous Integration (`check-jsonschema`) will validate changes against `schema.json`.
+
+---
+
+## Authors & Credits
+
+- **Lead Maintainer**: [@selvakk2k](https://github.com/selvakk2k)
+- **AI Pair Programming & Architecture**: Antigravity (Google DeepMind Team)

panasonic_ac_models-1.0.0b7/panasonic_ac_models/__init__.py

@@ -0,0 +1,3 @@
+from .lookup import ACModelLookup
+
+__all__ = ["ACModelLookup"]

panasonic_ac_models-1.0.0b7/panasonic_ac_models/decoder.py

@@ -0,0 +1,59 @@
+import re
+from typing import Dict, Any, Optional
+
+PANASONIC_MODEL_REGEX = re.compile(
+    r"^(?:CS/CU|CS|CU|S)?[-_\s]?"
+    r"(?P<series>[A-Z]{2})"
+    r"(?P<capacity>\d{2})"
+    r"(?P<gen>[A-Z])"
+    r"(?:KY)?"
+    r"(?P<rating>\d)?"
+    r"(?P<suffix>[A-Z0-9-]*)$",
+    re.IGNORECASE
+)
+
+CAPACITY_MAP = {
+    "09": "0.75T",
+    "11": "0.9T",
+    "12": "1T",
+    "17": "1.4T",
+    "18": "1.5T",
+    "24": "2T",
+    "26": "2.2T",
+    "30": "2.5T",
+}
+
+HEAT_MODE_SERIES = {"EZ", "KZ"}
+NANOE_SERIES = {"HU", "XU"}
+
+
+def decode_model_string(model_code: str) -> Optional[Dict[str, Any]]:
+    """Parses capability flags from a Panasonic AC model code string via deterministic rules."""
+    match = PANASONIC_MODEL_REGEX.match(model_code.strip().upper())
+    if not match:
+        return None
+
+    data = match.groupdict()
+    series = data["series"]
+    gen = data["gen"]
+
+    # Converti Generation Logic: Gen >= B/C receives 8-in-1; Gen Y/Z/A receives 7-in-1; older -> none
+    if gen in {"B", "C"}:
+        converti = "8-in-1"
+    elif gen in {"Y", "Z", "A"}:
+        converti = "7-in-1"
+    else:
+        converti = "none"
+
+    return {
+        "family_key": f"{series}-{data['capacity']}-{gen}",
+        "series": series,
+        "generation": gen,
+        "capacity_class": CAPACITY_MAP.get(data["capacity"], f"{data['capacity']} Ton"),
+        "speed_type": "variable",
+        "has_wifi": 1,
+        "has_heat_mode": 1 if series in HEAT_MODE_SERIES else 0,
+        "has_nanoe": 1 if series in NANOE_SERIES else 0,
+        "converti_type": converti,
+        "resolved_via": "regex_decoder"
+    }

panasonic_ac_models-1.0.0b7/panasonic_ac_models/lookup.py

@@ -0,0 +1,62 @@
+import json
+import os
+import re
+from typing import Dict, Any, Optional
+from .decoder import decode_model_string
+
+PKG_DIR = os.path.dirname(__file__)
+PARENT_DIR = os.path.dirname(PKG_DIR)
+
+DEFAULT_JSON_PATH = os.path.join(PKG_DIR, "models.json")
+if not os.path.exists(DEFAULT_JSON_PATH):
+    DEFAULT_JSON_PATH = os.path.join(PARENT_DIR, "models.json")
+
+
+def normalize_code(raw_code: str) -> str:
+    """Normalizes input model strings (e.g. 'cs/cu-su18aky3w' -> 'CS-SU18AKY3W')."""
+    cleaned = raw_code.strip().upper()
+    cleaned = re.sub(r'^(CS/CU|CU)[-_\s]?', 'CS-', cleaned)
+    if not cleaned.startswith('CS-') and not cleaned.startswith('S-'):
+        cleaned = f"CS-{cleaned}"
+    return cleaned
+
+
+class ACModelLookup:
+    """O(1) normalized lookup engine for Panasonic AC models."""
+
+    def __init__(self, json_path: Optional[str] = None):
+        path = json_path or DEFAULT_JSON_PATH
+        with open(path, "r", encoding="utf-8") as f:
+            self.db = json.load(f)
+
+        # O(1) Normalized Lookup Index
+        self._index: Dict[str, Dict[str, Any]] = {}
+        for family in self.db.get("families", []):
+            for unit in family.get("indoor_units", []):
+                norm = normalize_code(unit)
+                self._index[norm] = family
+
+    def get_capabilities(self, model_code: str) -> Dict[str, Any]:
+        """Resolves capability flags using exact index matching or regex decoding."""
+        norm = normalize_code(model_code)
+
+        # 1. Exact Match from Index
+        if norm in self._index:
+            result = dict(self._index[norm])
+            result["resolved_via"] = "database"
+            return result
+
+        # 2. Dynamic Fallback
+        dynamic = decode_model_string(model_code)
+        if dynamic:
+            return dynamic
+
+        # 3. Default Safe Fallback
+        return {
+            "family_key": "UNKNOWN",
+            "has_wifi": 1,
+            "has_heat_mode": 0,
+            "has_nanoe": 0,
+            "converti_type": "7-in-1",
+            "resolved_via": "safe_default"
+        }