v3.0.0: 1.1M-param numpy home-command parser with conditional rules, examples, Apache-2.0

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+# --trusted-host: TLS-inspecting proxies/AV (e.g. Norton Web Shield) re-sign pypi.org
+# with a CA the container does not have; harmless on clean networks.
+RUN pip install --no-cache-dir \
+    --trusted-host pypi.org --trusted-host files.pythonhosted.org \
+    numpy flask
+
+COPY engine.py server.py ./
+COPY static/ static/
+COPY model/ model/
+
+ENV PYTHONUNBUFFERED=1
+EXPOSE 8080
+CMD ["python", "server.py"]

LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,287 @@
+---
+license: apache-2.0
+language:
+- en
+- hi
+pipeline_tag: text2text-generation
+tags:
+- text-to-json
+- home-automation
+- robotics
+- hinglish
+- tiny-model
+- from-scratch
+- edge-ai
+- numpy
+- raspberry-pi
+- conditional-rules
+- experimental
+datasets:
+- sraivante/home-commands-json-v3
+metrics:
+- exact_match
+model-index:
+- name: superfast-tiny-home-robotics-json-1m-v3
+  results:
+  - task:
+      type: text2text-generation
+      name: instruction to JSON device command
+    dataset:
+      type: sraivante/home-commands-json-v3
+      name: home-commands-json-v3 (1,500 held-out rows, greedy decode)
+    metrics:
+    - type: exact_match
+      value: 96.73
+      name: exact match (all)
+      verified: false
+    - type: exact_match
+      value: 96.89
+      name: exact match (plain commands, n=900)
+      verified: false
+    - type: exact_match
+      value: 96.50
+      name: exact match (conditional rules, n=600)
+      verified: false
+---
+
+# Superfast Tiny Home Robotics JSON 1M v3
+
+A **1,143,328-parameter character-level transformer, trained from scratch**, that
+turns an English or Hinglish sentence into one JSON device command, including
+**conditional rules** ("if temperature goes above 42...", "roz shaam 7 baje...").
+Weights are **2.1 MB (fp16)**. Inference is **numpy only**: no PyTorch, no
+tokenizer library, no internet, no GPU.
+
+```text
+"bhai bedroom ka pankha high pe chala do"
+  -> {"activity":"air","subject":"bedroom_ceiling_fan","action":"HIGH"}
+
+"agar room ka temperature 42 se upar jaye to bedroom ka heater band kar do"
+  -> {"activity":"heating","subject":"bedroom_room_heater","action":"OFF",
+      "when":{"metric":"temperature","op":">","value":42}}
+
+"roz shaam 7 baje garden ki batti chala do"
+  -> {"activity":"light","subject":"garden_light","action":"ON",
+      "when":{"metric":"time","op":"==","value":"19:00"}}
+
+"when soil moisture drops below 20 start the garden sprinkler"
+  -> {"activity":"garden","subject":"garden_sprinkler","action":"ON",
+      "when":{"metric":"soil_moisture","op":"<","value":20}}
+```
+
+This is the v3 of the series. Compared with
+[v1](https://huggingface.co/sraivante/superfast-tiny-home-robotics-json-1m-v1)
+(30 commands, 10 device types, transformers runtime) it covers **1,004 devices,
+12 actions, 7 sensor metrics for rules**, and ships with a numpy engine plus a
+web UI and Docker image.
+
+| Release | Value |
+| --- | --- |
+| Publisher | sraivante |
+| Release date | 2026-09-26 |
+| Version | v3.0.0 |
+| Training data | [home-commands-json-v3](https://huggingface.co/datasets/sraivante/home-commands-json-v3) (synthetic, templated) |
+| Architecture | GPT-style causal decoder, char-level vocab (78 symbols), d=160, 4 layers, 4 heads, FFN 512, context 360 |
+| Parameters | 1,143,328 |
+| Weights | `model/model_v3_fp16.npz`, 2,146,783 bytes |
+| Runtime deps | `numpy` (plus `flask` for the optional server) |
+| License | Apache-2.0 |
+
+## Why a tiny model and not an LLM
+
+A home robot or a Raspberry Pi behind a microphone does not need to know the
+capital of France. It needs to turn "pankha tez kar do" into a command in a few
+milliseconds, offline, on a CPU that is also doing wake-word detection. This
+model is that one component: the **parser** between speech-to-text and the
+actuator. Everything else (safety, permissions, device state) stays in
+deterministic code you control.
+
+Measured on this release, single request, Python 3.13, numpy 2.3, Intel
+Core i7-1360P, default threads:
+
+| Input | Latency |
+| --- | ---: |
+| plain command (about 30 chars) | 70 to 90 ms |
+| conditional rule (about 70 chars) | 130 to 150 ms |
+| process RSS, engine loaded + warm (Python + numpy included) | 73 MB |
+
+Latency is dominated by Python overhead per generated character, not by
+FLOPs. Raspberry Pi 5 and Jetson Orin Nano numbers are not yet measured;
+treat the table as desktop numbers.
+
+## Quick start
+
+```bash
+pip install numpy
+git clone https://huggingface.co/sraivante/superfast-tiny-home-robotics-json-1m-v3
+cd superfast-tiny-home-robotics-json-1m-v3
+python engine.py "kitchen ki light band kar do"
+# {"activity":"light","subject":"kitchen_light","action":"OFF"}
+```
+
+In Python:
+
+```python
+import engine
+engine.init("model")                        # loads the npz once
+raw, confidence = engine.parse_scored("turn off the porch light")
+# raw        -> '{"activity":"light","subject":"porch_light","action":"OFF"}'
+# confidence -> avg log-prob per generated char; near 0.0 = in-domain
+```
+
+Web UI + REST API (Docker, no GPU):
+
+```bash
+docker compose up --build         # open http://localhost:8080
+curl -s localhost:8080/api/parse -H 'Content-Type: application/json' \
+     -d '{"text":"if aqi goes above 250 set the bedroom air purifier on high"}'
+```
+
+The API returns the command, `valid_json`, catalog `issues`, `confidence`,
+`latency_ms` and a single `ok` flag. **Act only on `ok: true`.**
+
+## How it is meant to be used (examples/)
+
+The model is a parser. `model/devices-catalog.json` is the law. Every example
+below runs the output through catalog validation before anything moves.
+
+| Example | What it shows |
+| --- | --- |
+| `examples/quickstart.py` | text in, validated command out, off-domain input rejected |
+| `examples/rule_engine.py` | what to do with the `when` clause: store it, watch sensors, fire once per crossing |
+| `examples/mqtt_bridge.py` | publish to `home/<subject>/set` for ESP32 / Tasmota / Zigbee2MQTT devices |
+| `examples/home_assistant.py` | map subjects to Home Assistant entities and call services locally |
+
+Run any of them from the repo root, all have a `--dry-run` or simulated mode:
+
+```bash
+python examples/quickstart.py
+python examples/rule_engine.py
+python examples/mqtt_bridge.py --dry-run "bedroom ka pankha high pe chala do"
+python examples/home_assistant.py --dry-run "garden ki light band kar do"
+```
+
+### The pipeline this slots into
+
+```text
+mic -> wake word -> Whisper/Vosk (Hindi+English) -> THIS MODEL -> catalog check -> actuator
+                                                      ~100 ms        ~0 ms       GPIO / MQTT / ROS
+```
+
+Plain commands (no `when`) go straight to the actuator. Conditional commands are
+stored as rules and evaluated on every sensor tick. `rule_engine.py` output on a
+simulated day:
+
+```text
+"agar temperature 35 se upar jaye to bedroom ka ac high kar do"
+  RULE stored: bedroom_ac -> HIGH when temperature > 35
+"roz subah 6 baje garden sprinkler chalu kar do"
+  RULE stored: garden_sprinkler -> ON when time == 06:00
+
+[sensor] temperature = 36
+  ACTUATE bedroom_ac                   HIGH    (temperature=36 > 35)
+[sensor] time = 06:00
+  ACTUATE garden_sprinkler             ON      (time=06:00 == 06:00)
+```
+
+### Robotics use
+
+For a mobile robot or a robotic arm the same pattern applies: swap the device
+catalog for your robot's capabilities (`arm_gripper: OPEN/CLOSE`,
+`base_motor: START/STOP/LOW/MEDIUM/HIGH`, `head_camera: ON/OFF/STATUS`),
+regenerate the data with the scripts in the dataset repo, retrain for about an
+hour on two CPU cores, and you have a command parser that fits in the L2 cache.
+The `when` clause maps directly to sensor-gated behaviours
+("agar battery 15 se neeche jaye to charging dock pe jao").
+
+## Output schema
+
+```json
+{"activity": "...", "subject": "...", "action": "...",
+ "when": {"metric": "...", "op": ">|<|==", "value": 42}}
+```
+
+- **1,004 subjects** in `model/devices-catalog.json`, each with its `activity`
+  (18 of them: light, power, air, access, security, air_quality, cooling,
+  heating, entertainment, music, garden, kitchen, office, network, water,
+  laundry, cleaning, aquarium) and its allowed actions.
+- **12 actions**: ON, OFF, START, STOP, LOW, MEDIUM, HIGH, OPEN, CLOSE, LOCK,
+  UNLOCK, STATUS.
+- **7 metrics** for `when`: temperature, humidity, aqi, battery, water_level,
+  soil_moisture, time (value `"HH:MM"`, op `==`).
+- `when` is optional. Rules in the training data are sensible by construction:
+  high temperature turns cooling ON or heating OFF, never the reverse.
+
+## Confidence guard
+
+`parse_scored` returns the mean log-probability of the generated characters.
+In-domain commands decode at about 0.0; gibberish or off-domain sentences
+score clearly lower and the server flags them (default threshold -0.006, env
+`HCAI_CONF_THRESHOLD`). Example: "what is the capital of france" scores -0.022
+and is rejected. This is a useful guard, not a guarantee: command-shaped
+off-domain input can still slip through.
+
+## Evaluation
+
+1,500 held-out rows from the same generator (900 plain, 600 conditional),
+greedy decode, exact string match on the JSON:
+
+| Metric | Value |
+| --- | ---: |
+| exact match, all | 96.73 % |
+| exact match, plain | 96.89 % |
+| exact match, conditional | 96.50 % |
+| valid JSON | 100 % |
+
+Full numbers and 12 sample failures are in `model/metrics_v3.json`. The
+held-out rows themselves were not preserved in this release; the dataset repo
+ships the generators and the deterministic `prep_mix.py` (seed 108) that
+produced the train/eval split.
+
+## Honest limitations
+
+- **Synthetic, templated training data.** The accuracy above measures
+  interpolation inside the template space, not the wild. Novel or indirect
+  phrasing ("andhera kar do", "thoda tez") fails.
+- **Observed misses that pass validation.** "kitchen ki chimney high pe karo"
+  returned `STATUS` in our tests, and that is an allowed action for the
+  chimney, so the catalog check passed it. Treat STATUS on an imperative
+  sentence with suspicion in your own guard.
+- **Char-level spelling errors** in subjects happen (see sample failures);
+  the catalog check exists exactly for that. Reject anything with issues.
+- **No negation, no reject class.** "fan mat chalao" can become `ON`.
+- **One instruction, one command.** No multi-intent, no context or pronouns.
+- Time rules are one-shot `==` triggers; recurrence ("roz") is not encoded
+  separately, your scheduler decides that.
+- Romanised Hindi only. Devanagari input is not in the vocabulary and is
+  silently dropped by the tokenizer.
+
+## Adapting to your devices
+
+1. Edit the device tables in `generators/generate_dataset_v2.py` and the rule
+   tables in `generators/generate_dataset_v3_conditional.py` (dataset repo).
+2. Regenerate and mix: `python generate_dataset_v2.py && python generate_dataset_v3_conditional.py && python prep_mix.py`
+3. Retrain (needs torch; about 80 minutes on two CPU cores, minutes on a GPU):
+   `python training/train_v3.py train --seconds 4200 && python training/train_v3.py export`
+4. Drop `model_v3_fp16.npz`, `model_v3_config.json` and the new
+   `devices-catalog.json` into `model/`.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `model/model_v3_fp16.npz` | weights, fp16, 2.1 MB |
+| `model/model_v3_config.json` | vocab (`itos`) + architecture config |
+| `model/devices-catalog.json` | the 1,004 subjects with allowed actions |
+| `model/metrics_v3.json` | eval numbers and sample failures |
+| `engine.py` | numpy inference, kv-cached greedy decode |
+| `server.py`, `static/index.html` | Flask API + offline web UI |
+| `examples/` | quickstart, rule engine, MQTT bridge, Home Assistant bridge |
+| `training/train_v3.py` | full PyTorch training and export source |
+| `Dockerfile`, `docker-compose.yml` | 150 MB image, healthcheck included |
+
+## License
+
+Apache-2.0 for the weights, code and catalog. The training data is fully
+synthetic and released under the same license in the dataset repo. No
+warranty: this model suggests commands, your code decides whether to obey.

docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  home-command-ai:
+    build: .
+    container_name: home-command-ai
+    ports:
+      - "8080:8080"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request;urllib.request.urlopen('http://localhost:8080/api/health')"]
+      interval: 30s
+      timeout: 5s
+      retries: 3

engine.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""
+Numpy-only inference engine for the home-command LM (v3: plain + conditional).
+No torch at runtime. Loads model/ (npz weights + config) once, then parse().
+"""
+
+import json
+import os
+
+import numpy as np
+
+_W = None
+_CFG = None
+_ITOS = None
+_STOI = None
+
+
+def init(model_dir=None):
+    global _W, _CFG, _ITOS, _STOI
+    model_dir = model_dir or os.path.join(os.path.dirname(os.path.abspath(__file__)), "model")
+    _W = {k: v.astype(np.float32)
+          for k, v in np.load(os.path.join(model_dir, "model_v3_fp16.npz")).items()}
+    _CFG = json.load(open(os.path.join(model_dir, "model_v3_config.json")))
+    _ITOS = _CFG["itos"]
+    _STOI = {c: i for i, c in enumerate(_ITOS)}
+
+
+def _ln(x, w, b, eps=1e-5):
+    m = x.mean(-1, keepdims=True)
+    v = ((x - m) ** 2).mean(-1, keepdims=True)
+    return (x - m) / np.sqrt(v + eps) * w + b
+
+
+def _gelu(x):
+    return 0.5 * x * (1.0 + np.tanh(0.7978845608028654 * (x + 0.044715 * x ** 3)))
+
+
+def _block(i, x, cache, cfg):
+    p = f"blocks.{i}."
+    T = x.shape[0]
+    H, D = cfg["HEADS"], cfg["D"]
+    HD = D // H
+    h = _ln(x, _W[p + "ln1.weight"], _W[p + "ln1.bias"])
+    qkv = h @ _W[p + "qkv.weight"].T + _W[p + "qkv.bias"]
+    q, k, v = np.split(qkv, 3, axis=-1)
+    q = q.reshape(T, H, HD).transpose(1, 0, 2)
+    k = k.reshape(T, H, HD).transpose(1, 0, 2)
+    v = v.reshape(T, H, HD).transpose(1, 0, 2)
+    if cache.get(i) is not None:
+        pk, pv = cache[i]
+        k = np.concatenate([pk, k], axis=1)
+        v = np.concatenate([pv, v], axis=1)
+    cache[i] = (k, v)
+    Tk = k.shape[1]
+    att = q @ k.transpose(0, 2, 1) / np.sqrt(HD)
+    if T > 1:
+        mask = np.triu(np.full((T, Tk), -1e9, dtype=np.float32), k=Tk - T + 1)
+        att = att + mask[None]
+    att = att - att.max(-1, keepdims=True)
+    att = np.exp(att)
+    att = att / att.sum(-1, keepdims=True)
+    out = (att @ v).transpose(1, 0, 2).reshape(T, D)
+    x = x + out @ _W[p + "proj.weight"].T + _W[p + "proj.bias"]
+    h2 = _ln(x, _W[p + "ln2.weight"], _W[p + "ln2.bias"])
+    return x + _gelu(h2 @ _W[p + "fc1.weight"].T + _W[p + "fc1.bias"]) @ _W[p + "fc2.weight"].T + _W[p + "fc2.bias"]
+
+
+def _forward(tokens, cache, past_len):
+    cfg = _CFG["config"]
+    T = len(tokens)
+    x = _W["tok.weight"][tokens] + _W["pos.weight"][past_len:past_len + T]
+    for i in range(cfg["LAYERS"]):
+        x = _block(i, x, cache, cfg)
+    x = _ln(x, _W["lnf.weight"], _W["lnf.bias"])
+    return x[-1] @ _W["tok.weight"].T
+
+
+def _logprob_of(logits, t):
+    m = logits.max()
+    return float(logits[t] - m - np.log(np.exp(logits - m).sum()))
+
+
+def parse_scored(instruction, max_new=170):
+    """instruction -> (raw output string, avg logprob per generated char).
+
+    The avg logprob is a confidence signal: in-distribution instructions
+    decode near 0.0; gibberish or unknown phrasing scores clearly lower.
+    """
+    if _W is None:
+        init()
+    toks = [_STOI[c] for c in instruction if c in _STOI] + [_STOI["\t"]]
+    max_ctx = _W["pos.weight"].shape[0]
+    toks = toks[-(max_ctx - max_new - 1):]
+    cache = {}
+    logits = _forward(toks, cache, 0)
+    out, lps = [], []
+    past = len(toks)
+    nl = _STOI["\n"]
+    for _ in range(max_new):
+        t = int(logits.argmax())
+        lps.append(_logprob_of(logits, t))
+        if t == nl:
+            break
+        out.append(t)
+        logits = _forward([t], cache, past)
+        past += 1
+    conf = float(np.mean(lps)) if lps else -99.0
+    return "".join(_ITOS[t] for t in out), conf
+
+
+def parse(instruction, max_new=170):
+    """instruction text -> raw model output string (should be JSON)."""
+    return parse_scored(instruction, max_new)[0]
+
+
+if __name__ == "__main__":
+    import sys
+    init()
+    print(parse(" ".join(sys.argv[1:]) or "turn off the kitchen light"))

examples/hcai_client.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""
+Shared helper for the examples: model + catalog validation in one object.
+
+    from hcai_client import Parser
+    p = Parser()                       # loads ../model by default
+    r = p.parse("bedroom ka pankha high pe chala do")
+    if r["ok"]:
+        act(r["command"])
+
+The model is a *parser*. The catalog is the law: never actuate anything
+unless r["ok"] is True.
+"""
+
+import json
+import os
+import sys
+import time
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+sys.path.insert(0, ROOT)
+
+import engine  # noqa: E402  (numpy-only inference, lives in the repo root)
+
+METRICS = {"temperature", "humidity", "aqi", "battery", "water_level",
+           "soil_moisture", "time"}
+OPS = {">", "<", "=="}
+
+
+class Parser:
+    def __init__(self, model_dir=None, conf_threshold=-0.006):
+        model_dir = model_dir or os.path.join(ROOT, "model")
+        engine.init(model_dir)
+        cat = json.load(open(os.path.join(model_dir, "devices-catalog.json"), encoding="utf-8"))
+        self.devices = {d["subject"]: d for d in cat["catalog"]}
+        self.conf_threshold = conf_threshold
+        engine.parse("turn on the light")  # warm-up
+
+    def validate(self, obj):
+        issues = []
+        if not isinstance(obj, dict):
+            return ["output is not a JSON object"]
+        if not {"activity", "subject", "action"}.issubset(obj):
+            issues.append("missing keys")
+        extra = set(obj) - {"activity", "subject", "action", "when"}
+        if extra:
+            issues.append(f"unexpected keys: {sorted(extra)}")
+        dev = self.devices.get(obj.get("subject"))
+        if dev is None:
+            issues.append(f"unknown subject '{obj.get('subject')}'")
+        else:
+            if obj.get("action") not in dev["actions"]:
+                issues.append(f"action '{obj.get('action')}' not allowed for "
+                              f"{obj['subject']} (allowed: {dev['actions']})")
+            if obj.get("activity") != dev["activity"]:
+                issues.append(f"activity mismatch (catalog says '{dev['activity']}')")
+        w = obj.get("when")
+        if w is not None:
+            if not isinstance(w, dict) or set(w) != {"metric", "op", "value"}:
+                issues.append("bad 'when' clause shape")
+            else:
+                if w["metric"] not in METRICS:
+                    issues.append(f"unknown metric '{w['metric']}'")
+                if w["op"] not in OPS:
+                    issues.append(f"unknown op '{w['op']}'")
+        return issues
+
+    def parse(self, text):
+        t0 = time.time()
+        raw, conf = engine.parse_scored(text.strip())
+        ms = round((time.time() - t0) * 1000, 1)
+        try:
+            obj = json.loads(raw)
+        except Exception:
+            return {"ok": False, "raw": raw, "command": None, "confidence": conf,
+                    "latency_ms": ms, "issues": ["model output is not valid JSON"]}
+        issues = self.validate(obj)
+        if conf < self.conf_threshold:
+            issues.append(f"low confidence ({conf:.4f}): probably not a device command")
+        return {"ok": not issues, "raw": raw, "command": obj, "confidence": round(conf, 5),
+                "latency_ms": ms, "issues": issues}

examples/home_assistant.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Text -> Home Assistant service call, fully local (no cloud LLM in the loop).
+
+Map catalog subjects to your HA entity ids in ENTITY_MAP, then:
+
+    export HA_URL=http://homeassistant.local:8123 HA_TOKEN=<long-lived token>
+    python examples/home_assistant.py "drawing room ka pankha medium pe karo"
+    python examples/home_assistant.py --dry-run "garden ki light band kar do"
+
+Only plain commands are sent; conditional ones are printed as a suggested
+HA automation trigger (wire them into automations.yaml or a rule runner).
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.request
+
+from hcai_client import Parser
+
+# subject (from model/devices-catalog.json)  ->  Home Assistant entity_id
+ENTITY_MAP = {
+    "living_room_light": "light.living_room",
+    "drawing_room_ceiling_fan": "fan.drawing_room",
+    "bedroom_ac": "climate.bedroom",
+    "main_door_lock": "lock.main_door",
+    "garden_light": "switch.garden_light",
+}
+
+# (domain, action) -> (service, extra data)
+SERVICE = {
+    ("light", "ON"): ("turn_on", {}), ("light", "OFF"): ("turn_off", {}),
+    ("switch", "ON"): ("turn_on", {}), ("switch", "OFF"): ("turn_off", {}),
+    ("fan", "ON"): ("turn_on", {}), ("fan", "OFF"): ("turn_off", {}),
+    ("fan", "LOW"): ("set_percentage", {"percentage": 33}),
+    ("fan", "MEDIUM"): ("set_percentage", {"percentage": 66}),
+    ("fan", "HIGH"): ("set_percentage", {"percentage": 100}),
+    ("climate", "ON"): ("turn_on", {}), ("climate", "OFF"): ("turn_off", {}),
+    ("climate", "HIGH"): ("set_fan_mode", {"fan_mode": "high"}),
+    ("lock", "LOCK"): ("lock", {}), ("lock", "UNLOCK"): ("unlock", {}),
+}
+
+
+def call_ha(domain, service, data, dry_run):
+    base = os.environ.get("HA_URL", "http://homeassistant.local:8123")
+    url = f"{base}/api/services/{domain}/{service}"
+    print(f"POST {url}  {json.dumps(data)}")
+    if dry_run:
+        return
+    req = urllib.request.Request(
+        url, data=json.dumps(data).encode(), method="POST",
+        headers={"Authorization": f"Bearer {os.environ['HA_TOKEN']}",
+                 "Content-Type": "application/json"})
+    with urllib.request.urlopen(req, timeout=5) as resp:
+        print(resp.status, resp.read()[:200])
+
+
+def suggest_trigger(w):
+    if w["metric"] == "time":
+        return {"platform": "time", "at": w["value"]}
+    key = "above" if w["op"] == ">" else "below"
+    return {"platform": "numeric_state", "entity_id": f"sensor.{w['metric']}", key: w["value"]}
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("text", nargs="+")
+    ap.add_argument("--dry-run", action="store_true")
+    a = ap.parse_args()
+
+    r = Parser().parse(" ".join(a.text))
+    if not r["ok"]:
+        print("REJECTED:", r["issues"])
+        sys.exit(1)
+    cmd = r["command"]
+    print("parsed:", json.dumps(cmd), f"({r['latency_ms']} ms)")
+
+    if "when" in cmd:
+        print("conditional -> suggested automation trigger:", json.dumps(suggest_trigger(cmd["when"])))
+        return
+
+    entity = ENTITY_MAP.get(cmd["subject"])
+    if not entity:
+        print(f"no entity mapped for '{cmd['subject']}' - add it to ENTITY_MAP")
+        sys.exit(2)
+    domain = entity.split(".")[0]
+    svc = SERVICE.get((domain, cmd["action"]))
+    if not svc:
+        print(f"no service for {domain}/{cmd['action']}")
+        sys.exit(2)
+    call_ha(domain, svc[0], {"entity_id": entity, **svc[1]}, a.dry_run)
+
+
+if __name__ == "__main__":
+    main()

examples/mqtt_bridge.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""
+Text -> MQTT. Publishes validated commands to `home/<subject>/set` so any
+ESP32 / Tasmota / Zigbee2MQTT device can subscribe and act.
+
+    pip install paho-mqtt
+    python examples/mqtt_bridge.py --dry-run "kitchen ki chimney high pe karo"
+    python examples/mqtt_bridge.py --broker 192.168.1.10 "turn off the porch light"
+
+Conditional commands are published to `home/rules/add` for a rule runner
+(see rule_engine.py) instead of being executed directly.
+"""
+
+import argparse
+import json
+import sys
+
+from hcai_client import Parser
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("text", nargs="+")
+    ap.add_argument("--broker", default="localhost")
+    ap.add_argument("--port", type=int, default=1883)
+    ap.add_argument("--dry-run", action="store_true", help="print, do not publish")
+    a = ap.parse_args()
+
+    r = Parser().parse(" ".join(a.text))
+    if not r["ok"]:
+        print("REJECTED:", r["issues"], "| raw:", r["raw"])
+        sys.exit(1)
+
+    cmd = r["command"]
+    if "when" in cmd:
+        topic, payload = "home/rules/add", json.dumps(cmd)
+    else:
+        topic, payload = f"home/{cmd['subject']}/set", cmd["action"]
+
+    print(f"PUBLISH {topic}  <-  {payload}   ({r['latency_ms']} ms)")
+    if a.dry_run:
+        return
+    import paho.mqtt.publish as publish
+    publish.single(topic, payload, hostname=a.broker, port=a.port, qos=1, retain=False)
+
+
+if __name__ == "__main__":
+    main()

examples/quickstart.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""
+Smallest possible use: text in, validated JSON command out.
+
+    python examples/quickstart.py
+    python examples/quickstart.py "agar aqi 200 se upar jaye to purifier high kar do"
+"""
+
+import json
+import sys
+
+from hcai_client import Parser
+
+DEMO = [
+    "bhai bedroom ka pankha high pe chala do",
+    "turn off the kitchen light",
+    "agar room ka temperature 42 se upar jaye to bedroom ka heater band kar do",
+    "roz shaam 7 baje garden ki batti chala do",
+    "when soil moisture drops below 20 start the garden sprinkler",
+    "what is the capital of france",          # off-domain: must be rejected
+]
+
+p = Parser()
+for text in (sys.argv[1:] or DEMO):
+    r = p.parse(text)
+    flag = "OK " if r["ok"] else "REJ"
+    print(f"{flag} {r['latency_ms']:6.1f}ms  {text}")
+    print(f"      -> {json.dumps(r['command'], ensure_ascii=False)}")
+    if r["issues"]:
+        print(f"      issues: {r['issues']}")

examples/rule_engine.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""
+What to do with the "when" clause: a tiny rule engine.
+
+Plain commands fire immediately. Conditional commands are stored as rules and
+evaluated every time a sensor reading (or the clock) changes. This is the
+whole point of the v3 model: the user speaks once, the device obeys forever.
+
+    python examples/rule_engine.py            # runs a simulated day
+
+Replace `actuate()` with your GPIO / MQTT / ROS call and `SENSOR_FEED` with
+your real sensors.
+"""
+
+import time
+
+from hcai_client import Parser
+
+OPS = {">": lambda a, b: a > b, "<": lambda a, b: a < b, "==": lambda a, b: a == b}
+
+
+def actuate(cmd, why):
+    # >>> your hardware goes here <<<
+    print(f"  ACTUATE {cmd['subject']:<28} {cmd['action']:<7} ({why})")
+
+
+class Home:
+    def __init__(self):
+        self.rules = []          # stored conditional commands
+        self.state = {}          # latest sensor readings, e.g. {"temperature": 31}
+
+    def say(self, text, parser):
+        r = parser.parse(text)
+        print(f'\n"{text}"')
+        if not r["ok"]:
+            print(f"  REJECTED: {r['issues']}")
+            return
+        cmd = r["command"]
+        if "when" not in cmd:
+            actuate(cmd, "direct command")
+        else:
+            w = cmd["when"]
+            self.rules.append({"cmd": cmd, "armed": True})
+            print(f"  RULE stored: {cmd['subject']} -> {cmd['action']} "
+                  f"when {w['metric']} {w['op']} {w['value']}")
+
+    def sensor(self, metric, value):
+        """Feed one reading; fire any rule whose condition just became true."""
+        self.state[metric] = value
+        for rule in self.rules:
+            w = rule["cmd"]["when"]
+            if w["metric"] != metric:
+                continue
+            hit = OPS[w["op"]](value, w["value"])
+            if hit and rule["armed"]:
+                actuate(rule["cmd"], f"{metric}={value} {w['op']} {w['value']}")
+                rule["armed"] = False          # edge-triggered: fire once per crossing
+            elif not hit:
+                rule["armed"] = True           # re-arm when condition clears
+
+
+if __name__ == "__main__":
+    p = Parser()
+    home = Home()
+
+    home.say("living room ki light on kar do", p)
+    home.say("agar temperature 35 se upar jaye to bedroom ka ac high kar do", p)
+    home.say("when aqi goes above 200 turn on the hall air purifier", p)
+    home.say("roz subah 6 baje garden sprinkler chalu kar do", p)
+
+    print("\n--- simulated sensor feed ---")
+    SENSOR_FEED = [("temperature", 31), ("aqi", 120), ("temperature", 36),
+                   ("time", "05:59"), ("time", "06:00"), ("aqi", 240),
+                   ("temperature", 33), ("temperature", 37)]
+    for metric, value in SENSOR_FEED:
+        print(f"[sensor] {metric} = {value}")
+        home.sensor(metric, value)
+        time.sleep(0.05)

model/metrics_v3.json

@@ -0,0 +1,63 @@
+{
+ "metrics": {
+  "eval_n": 1500,
+  "exact_match": 0.9673,
+  "valid_json": 1.0,
+  "plain_exact": 0.9689,
+  "conditional_exact": 0.965,
+  "plain_n": 900,
+  "conditional_n": 600,
+  "decode_seconds": 35.0,
+  "step": 6717
+ },
+ "sample_failures": [
+  {
+   "pred": "{\"activity\":\"cooling\",\"subject\":\"study_room_cooler\",\"action\":\"LOW\"}",
+   "gold": "{\"activity\":\"cooling\",\"subject\":\"study_room_cooler\",\"action\":\"HIGH\"}"
+  },
+  {
+   "pred": "{\"activity\":\"entertainment\",\"subject\":\"veranda_radio\",\"action\":\"STATUS\"}",
+   "gold": "{\"activity\":\"entertainment\",\"subject\":\"drawing_room_tv\",\"action\":\"STATUS\"}"
+  },
+  {
+   "pred": "{\"activity\":\"air_quality\",\"subject\":\"air_light\",\"action\":\"OFF\"}",
+   "gold": "{\"activity\":\"aquarium\",\"subject\":\"aquarium_light\",\"action\":\"OFF\"}"
+  },
+  {
+   "pred": "{\"activity\":\"power\",\"subject\":\"smart_plug_5\",\"action\":\"ON\"}",
+   "gold": "{\"activity\":\"power\",\"subject\":\"smart_plug_8\",\"action\":\"ON\"}"
+  },
+  {
+   "pred": "{\"activity\":\"air\",\"subject\":\"lobby_ceiling_fan\",\"action\":\"LOW\"}",
+   "gold": "{\"activity\":\"air\",\"subject\":\"lobby_ceiling_fan\",\"action\":\"ON\"}"
+  },
+  {
+   "pred": "{\"activity\":\"music\",\"subject\":\"master_bedroom_speaker\",\"action\":\"LOW\"}",
+   "gold": "{\"activity\":\"music\",\"subject\":\"master_bedroom_speaker\",\"action\":\"MEDIUM\"}"
+  },
+  {
+   "pred": "{\"activity\":\"water\",\"subject\":\"water_purifier\",\"action\":\"ON\"}",
+   "gold": "{\"activity\":\"power\",\"subject\":\"ups\",\"action\":\"ON\"}"
+  },
+  {
+   "pred": "{\"activity\":\"security\",\"subject\":\"camera_6\",\"action\":\"ON\",\"when\":{\"metric\":\"time\",\"op\":\"==\",\"value\":\"06:00\"}}",
+   "gold": "{\"activity\":\"security\",\"subject\":\"camera_1\",\"action\":\"ON\"}"
+  },
+  {
+   "pred": "{\"activity\":\"security\",\"subject\":\"camera_6\",\"action\":\"STATUS\"}",
+   "gold": "{\"activity\":\"security\",\"subject\":\"camera_1\",\"action\":\"STATUS\"}"
+  },
+  {
+   "pred": "{\"activity\":\"kitchen\",\"subject\":\"air_fryer\",\"action\":\"STOP\"}",
+   "gold": "{\"activity\":\"laundry\",\"subject\":\"dryer\",\"action\":\"STOP\"}"
+  },
+  {
+   "pred": "{\"activity\":\"security\",\"subject\":\"camera_6\",\"action\":\"STATUS\"}",
+   "gold": "{\"activity\":\"security\",\"subject\":\"camera_7\",\"action\":\"STATUS\"}"
+  },
+  {
+   "pred": "{\"activity\":\"access\",\"subject\":\"washroom_immersion_rodor_k\",\"action\":\"ON\"}",
+   "gold": "{\"activity\":\"heating\",\"subject\":\"washroom_immersion_rod\",\"action\":\"ON\"}"
+  }
+ ]
+}

model/model_v3_config.json

@@ -0,0 +1 @@
+{"itos": ["<pad>", "\t", "\n", " ", "!", "\"", "'", ",", ".", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", ":", "<", "=", ">", "?", "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "_", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "{", "}"], "config": {"D": 160, "LAYERS": 4, "HEADS": 4, "FFN": 512, "MAX_LEN": 360}, "params": 1143328, "step": 6717}

model/model_v3_fp16.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fc749ecd89c1ae30a159d6d701036298b5583645b7fbf114311e006929c8778b
+size 2146783

requirements.txt

@@ -0,0 +1,2 @@
+numpy>=1.24
+flask>=3.0

server.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""
+home-command-ai server: web UI + JSON API around the tiny numpy LM.
+
+  GET  /              the UI
+  POST /api/parse     {"text": "..."} -> parsed command + validation
+  GET  /api/devices   the device catalog (subjects, activities, allowed actions)
+  GET  /api/health
+"""
+
+import json
+import os
+import time
+
+from flask import Flask, jsonify, request, send_from_directory
+
+import engine
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+app = Flask(__name__, static_folder=None)
+
+engine.init()
+
+CATALOG = json.load(open(os.path.join(HERE, "model", "devices-catalog.json")))
+DEVICES = {d["subject"]: d for d in CATALOG["catalog"]}
+METRICS = {"temperature", "humidity", "aqi", "battery", "water_level",
+           "soil_moisture", "time"}
+OPS = {">", "<", "=="}
+# avg logprob below this flags the parse as out-of-domain (see README)
+CONF_THRESHOLD = float(os.environ.get("HCAI_CONF_THRESHOLD", "-0.006"))
+
+# warm up (first call pays small numpy init costs)
+engine.parse("turn on the light")
+
+
+def validate(obj):
+    """schema + catalog checks -> list of issue strings (empty = fully valid)"""
+    issues = []
+    if not isinstance(obj, dict):
+        return ["output is not a JSON object"]
+    base_keys = {"activity", "subject", "action"}
+    if not base_keys.issubset(obj.keys()):
+        issues.append("missing keys")
+    extra = set(obj.keys()) - base_keys - {"when"}
+    if extra:
+        issues.append(f"unexpected keys: {sorted(extra)}")
+    subj = obj.get("subject")
+    dev = DEVICES.get(subj)
+    if dev is None:
+        issues.append(f"unknown subject '{subj}' (not in catalog)")
+    else:
+        if obj.get("action") not in dev["actions"]:
+            issues.append(f"action '{obj.get('action')}' not allowed for {subj} "
+                          f"(allowed: {dev['actions']})")
+        if obj.get("activity") != dev["activity"]:
+            issues.append(f"activity mismatch (catalog says '{dev['activity']}')")
+    w = obj.get("when")
+    if w is not None:
+        if not isinstance(w, dict) or set(w.keys()) != {"metric", "op", "value"}:
+            issues.append("bad 'when' clause shape")
+        else:
+            if w["metric"] not in METRICS:
+                issues.append(f"unknown metric '{w['metric']}'")
+            if w["op"] not in OPS:
+                issues.append(f"unknown op '{w['op']}'")
+    return issues
+
+
+@app.get("/")
+def index():
+    return send_from_directory(os.path.join(HERE, "static"), "index.html")
+
+
+@app.get("/api/health")
+def health():
+    return jsonify({"ok": True, "devices": len(DEVICES)})
+
+
+@app.get("/api/devices")
+def devices():
+    return jsonify(CATALOG)
+
+
+@app.post("/api/parse")
+def api_parse():
+    body = request.get_json(force=True, silent=True) or {}
+    text = (body.get("text") or "").strip()
+    if not text:
+        return jsonify({"ok": False, "error": "empty text"}), 400
+    t0 = time.time()
+    raw, conf = engine.parse_scored(text)
+    latency_ms = round((time.time() - t0) * 1000, 1)
+    try:
+        obj = json.loads(raw)
+        valid_json = True
+    except Exception:
+        obj, valid_json = None, False
+    issues = validate(obj) if valid_json else ["model output is not valid JSON"]
+    if conf < CONF_THRESHOLD:
+        issues.append(f"low model confidence ({conf:.4f}) — input may be "
+                      "out-of-domain; not a home-device command?")
+    return jsonify({
+        "ok": valid_json and not issues,
+        "raw": raw,
+        "command": obj,
+        "valid_json": valid_json,
+        "issues": issues,
+        "confidence": round(conf, 5),
+        "latency_ms": latency_ms,
+    })
+
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", "8080"))
+    print(f"home-command-ai listening on http://0.0.0.0:{port}")
+    app.run(host="0.0.0.0", port=port)

static/index.html

@@ -0,0 +1,224 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>home-command-ai</title>
+<style>
+  :root {
+    --bg: #0d1117; --panel: #161b22; --panel2: #1c2129; --border: #2d333b;
+    --text: #e6edf3; --dim: #8b949e; --accent: #58a6ff; --ok: #3fb950;
+    --warn: #d29922; --bad: #f85149; --key: #79c0ff; --str: #a5d6ff;
+    --num: #ffa657; --chip: #21262d;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    background: var(--bg); color: var(--text);
+    font: 15px/1.55 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    min-height: 100vh;
+  }
+  .wrap { max-width: 1060px; margin: 0 auto; padding: 24px 18px 60px; }
+  header { display: flex; align-items: baseline; gap: 14px; flex-wrap: wrap; margin-bottom: 6px; }
+  h1 { font-size: 22px; font-weight: 700; }
+  h1 .dot { color: var(--accent); }
+  .sub { color: var(--dim); font-size: 13px; }
+  .badges { margin-left: auto; display: flex; gap: 8px; }
+  .pill {
+    font-size: 11.5px; padding: 3px 10px; border-radius: 999px;
+    border: 1px solid var(--border); color: var(--dim); background: var(--panel);
+  }
+  .grid { display: grid; grid-template-columns: 1fr 340px; gap: 18px; margin-top: 18px; }
+  @media (max-width: 900px) { .grid { grid-template-columns: 1fr; } }
+  .card { background: var(--panel); border: 1px solid var(--border); border-radius: 12px; padding: 16px; }
+  .inputrow { display: flex; gap: 10px; }
+  #cmd {
+    flex: 1; background: var(--panel2); border: 1px solid var(--border);
+    border-radius: 10px; color: var(--text); padding: 12px 14px; font-size: 15px;
+    outline: none;
+  }
+  #cmd:focus { border-color: var(--accent); }
+  button {
+    background: var(--accent); color: #0d1117; font-weight: 700; border: 0;
+    border-radius: 10px; padding: 0 22px; font-size: 15px; cursor: pointer;
+  }
+  button:hover { filter: brightness(1.1); }
+  button:disabled { opacity: .5; cursor: wait; }
+  .chips { display: flex; flex-wrap: wrap; gap: 7px; margin-top: 12px; }
+  .chip {
+    background: var(--chip); border: 1px solid var(--border); color: var(--dim);
+    font-size: 12.5px; padding: 5px 11px; border-radius: 999px; cursor: pointer;
+  }
+  .chip:hover { color: var(--text); border-color: var(--accent); }
+  .result { margin-top: 16px; display: none; }
+  .status { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 10px; align-items: center; }
+  .tag { font-size: 12px; font-weight: 600; padding: 3px 10px; border-radius: 999px; }
+  .tag.ok { background: rgba(63,185,80,.15); color: var(--ok); border: 1px solid rgba(63,185,80,.4); }
+  .tag.bad { background: rgba(248,81,73,.15); color: var(--bad); border: 1px solid rgba(248,81,73,.4); }
+  .tag.warn { background: rgba(210,153,34,.15); color: var(--warn); border: 1px solid rgba(210,153,34,.4); }
+  .tag.dim { background: var(--chip); color: var(--dim); border: 1px solid var(--border); font-weight: 400; }
+  pre {
+    background: var(--panel2); border: 1px solid var(--border); border-radius: 10px;
+    padding: 14px; overflow-x: auto; font: 13.5px/1.6 ui-monospace, "Cascadia Code", Menlo, monospace;
+  }
+  .k { color: var(--key); } .s { color: var(--str); } .n { color: var(--num); }
+  .issues { margin-top: 10px; font-size: 13px; color: var(--warn); }
+  .issues li { margin-left: 18px; }
+  h2 { font-size: 14px; text-transform: uppercase; letter-spacing: .06em; color: var(--dim); margin-bottom: 10px; }
+  .hist-item {
+    padding: 8px 10px; border-radius: 8px; cursor: pointer; font-size: 13px;
+    color: var(--dim); border: 1px solid transparent; display: flex; gap: 8px; align-items: center;
+  }
+  .hist-item:hover { background: var(--panel2); border-color: var(--border); color: var(--text); }
+  .hist-item .st { width: 7px; height: 7px; border-radius: 50%; flex: none; }
+  #devsearch {
+    width: 100%; background: var(--panel2); border: 1px solid var(--border);
+    border-radius: 8px; color: var(--text); padding: 8px 12px; font-size: 13.5px;
+    outline: none; margin-bottom: 10px;
+  }
+  .dev { padding: 7px 4px; border-bottom: 1px solid var(--border); font-size: 12.5px; }
+  .dev b { color: var(--text); font-weight: 600; display: block; font-family: ui-monospace, monospace; }
+  .dev span { color: var(--dim); }
+  #devlist { max-height: 420px; overflow-y: auto; }
+  .count { color: var(--dim); font-size: 12px; margin-bottom: 6px; }
+  footer { margin-top: 26px; color: var(--dim); font-size: 12.5px; text-align: center; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header>
+    <h1>home-command<span class="dot">-ai</span></h1>
+    <div class="sub">Hinglish + English &rarr; JSON device commands &amp; rules</div>
+    <div class="badges">
+      <span class="pill">1.1M params</span>
+      <span class="pill">char-level LM</span>
+      <span class="pill">100% offline</span>
+    </div>
+  </header>
+
+  <div class="grid">
+    <div>
+      <div class="card">
+        <div class="inputrow">
+          <input id="cmd" placeholder='try: "bhai bedroom ka pankha high pe chala do"' autocomplete="off">
+          <button id="go">Parse</button>
+        </div>
+        <div class="chips" id="examples"></div>
+        <div class="result" id="result">
+          <div class="status" id="status"></div>
+          <pre id="json"></pre>
+          <ul class="issues" id="issues"></ul>
+        </div>
+      </div>
+      <div class="card" style="margin-top:18px">
+        <h2>History</h2>
+        <div id="history"><div class="sub">Parsed commands will appear here.</div></div>
+      </div>
+    </div>
+    <div class="card">
+      <h2>Device catalog</h2>
+      <input id="devsearch" placeholder="search 1004 devices&hellip;">
+      <div class="count" id="devcount"></div>
+      <div id="devlist"></div>
+    </div>
+  </div>
+
+  <footer>
+    tiny char-level transformer &middot; trained on synthetic EN/Hinglish home-command data
+    &middot; validate every command against the catalog before acting on it
+  </footer>
+</div>
+
+<script>
+const EXAMPLES = [
+  "turn off the kitchen light",
+  "bhai bedroom ka pankha high pe chala do",
+  "washing machine start karo",
+  "agar room ka temperature 42 se upar jaye to bedroom ka heater band kar do",
+  "if aqi goes above 250 set the living room air purifier on high",
+  "roz shaam 7 baje garden ki batti chala do",
+  "balcony wala parde khol do",
+  "tanki ka level 90 paar kare to motor band kar do",
+  "at 6:30 am open the master bedroom curtains",
+  "main gate khula hai kya",
+  "second floor bathroom ka geyser on kar do",
+  "jab mitti ki nami 20 se kam ho to garden ka sprinkler chalao"
+];
+let history = [];
+let devices = [];
+
+const $ = id => document.getElementById(id);
+
+function colorJSON(obj) {
+  const j = JSON.stringify(obj, null, 2);
+  return j.replace(/"([^"]+)":/g, '"<span class="k">$1</span>":')
+          .replace(/: "([^"]*)"/g, ': "<span class="s">$1</span>"')
+          .replace(/: (\d+)/g, ': <span class="n">$1</span>');
+}
+
+function render(res, text) {
+  $("result").style.display = "block";
+  const st = $("status");
+  st.innerHTML = "";
+  const tags = [];
+  tags.push(res.valid_json ? '<span class="tag ok">&#10003; valid JSON</span>'
+                           : '<span class="tag bad">&#10007; invalid JSON</span>');
+  if (res.valid_json) {
+    tags.push(res.issues.length === 0 ? '<span class="tag ok">&#10003; catalog OK</span>'
+                                      : '<span class="tag warn">&#9888; check issues</span>');
+    if (res.command && res.command.when)
+      tags.push('<span class="tag dim">rule (conditional)</span>');
+  }
+  tags.push(`<span class="tag dim">${res.latency_ms} ms</span>`);
+  st.innerHTML = tags.join("");
+  $("json").innerHTML = res.valid_json ? colorJSON(res.command)
+                                       : (res.raw || "(empty)");
+  $("issues").innerHTML = (res.issues || [])
+    .map(i => `<li>${i}</li>`).join("");
+  history.unshift({ text, ok: res.ok });
+  history = history.slice(0, 8);
+  $("history").innerHTML = history.map((h, i) =>
+    `<div class="hist-item" onclick="reuse(${i})">
+       <span class="st" style="background:${h.ok ? 'var(--ok)' : 'var(--warn)'}"></span>
+       <span>${h.text.replace(/</g, "&lt;")}</span></div>`).join("");
+}
+
+function reuse(i) { $("cmd").value = history[i].text; parse(); }
+
+async function parse() {
+  const text = $("cmd").value.trim();
+  if (!text) return;
+  $("go").disabled = true;
+  try {
+    const r = await fetch("/api/parse", {
+      method: "POST", headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ text })
+    });
+    render(await r.json(), text);
+  } catch (e) {
+    render({ valid_json: false, raw: "server error: " + e, issues: [], latency_ms: "-" }, text);
+  }
+  $("go").disabled = false;
+}
+
+function renderDevices(q) {
+  q = (q || "").toLowerCase();
+  const hits = devices.filter(d => d.subject.includes(q)).slice(0, 60);
+  $("devcount").textContent =
+    q ? `${devices.filter(d => d.subject.includes(q)).length} match` : `${devices.length} devices`;
+  $("devlist").innerHTML = hits.map(d =>
+    `<div class="dev"><b>${d.subject}</b>
+     <span>${d.activity} &middot; ${d.actions.join(" / ")}</span></div>`).join("");
+}
+
+$("go").onclick = parse;
+$("cmd").addEventListener("keydown", e => { if (e.key === "Enter") parse(); });
+$("devsearch").addEventListener("input", e => renderDevices(e.target.value));
+$("examples").innerHTML = EXAMPLES.map(e =>
+  `<span class="chip" onclick="$('cmd').value=this.textContent;parse()">${e}</span>`).join("");
+
+fetch("/api/devices").then(r => r.json()).then(c => {
+  devices = c.catalog; renderDevices("");
+});
+</script>
+</body>
+</html>

training/train_v3.py

@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+"""
+v3 training: plain + conditional commands, one model.
+Same architecture family as train.py but 4 layers / FFN 512 (~1.1M params)
+and longer context for the "when" clause. Reads train_mix.jsonl / eval_mix.jsonl
+(built by prep_mix.py).
+
+  python3 train_v3.py train --seconds 3300
+  python3 train_v3.py eval
+  python3 train_v3.py export
+"""
+
+import argparse
+import json
+import math
+import os
+import time
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+torch.set_num_threads(2)
+torch.manual_seed(108)
+
+TRAIN_F, EVAL_F = "train_mix.jsonl", "eval_mix.jsonl"
+CKPT, LOG = "ckpt3.pt", "train3_log.txt"
+D, LAYERS, HEADS, FFN = 160, 4, 4, 512
+MAX_LEN = 360
+MAX_STEPS_HORIZON = 5_000
+LR, WARMUP = 1e-3, 200
+
+
+def read_rows(path):
+    rows = []
+    for line in open(path, encoding="utf-8"):
+        o = json.loads(line)
+        tgt = json.dumps(o["output"], separators=(",", ":"), ensure_ascii=False)
+        rows.append((o["instruction"], tgt))
+    return rows
+
+
+def build_vocab(rows_list):
+    chars = set("\t\n")
+    for rows in rows_list:
+        for a, b in rows:
+            chars.update(a)
+            chars.update(b)
+    itos = ["<pad>"] + sorted(chars)
+    return itos, {c: i for i, c in enumerate(itos)}
+
+
+def encode_rows(rows, stoi):
+    out = []
+    for src, tgt in rows:
+        ids = [stoi[c] for c in src] + [stoi["\t"]] + [stoi[c] for c in tgt] + [stoi["\n"]]
+        if len(ids) <= MAX_LEN:
+            out.append((ids, len(src) + 1))
+    return out
+
+
+def make_batches(encoded, budget_chars=12_000, max_b=256, seed=0):
+    order = sorted(range(len(encoded)), key=lambda i: len(encoded[i][0]))
+    batches, cur = [], []
+    for i in order:
+        cur.append(i)
+        if len(encoded[i][0]) * len(cur) >= budget_chars or len(cur) >= max_b:
+            batches.append(cur)
+            cur = []
+    if cur:
+        batches.append(cur)
+    __import__("random").Random(seed).shuffle(batches)
+    return batches
+
+
+def batch_tensors(encoded, idxs):
+    Lmax = max(len(encoded[i][0]) for i in idxs)
+    B = len(idxs)
+    x = torch.zeros((B, Lmax), dtype=torch.long)
+    labels = torch.full((B, Lmax - 1), -100, dtype=torch.long)
+    for r, i in enumerate(idxs):
+        ids, out_start = encoded[i]
+        x[r, :len(ids)] = torch.tensor(ids, dtype=torch.long)
+        for j in range(max(out_start - 1, 0), len(ids) - 1):
+            labels[r, j] = ids[j + 1]
+    return x, labels
+
+
+class Block(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.ln1 = nn.LayerNorm(D)
+        self.qkv = nn.Linear(D, 3 * D)
+        self.proj = nn.Linear(D, D)
+        self.ln2 = nn.LayerNorm(D)
+        self.fc1 = nn.Linear(D, FFN)
+        self.fc2 = nn.Linear(FFN, D)
+
+    def forward(self, x, past=None):
+        B, T, _ = x.shape
+        h = self.ln1(x)
+        q, k, v = self.qkv(h).split(D, dim=2)
+        hd = D // HEADS
+        q = q.view(B, T, HEADS, hd).transpose(1, 2)
+        k = k.view(B, T, HEADS, hd).transpose(1, 2)
+        v = v.view(B, T, HEADS, hd).transpose(1, 2)
+        if past is not None:
+            pk, pv = past
+            k = torch.cat([pk, k], dim=2)
+            v = torch.cat([pv, v], dim=2)
+        att = F.scaled_dot_product_attention(q, k, v, is_causal=(past is None))
+        att = att.transpose(1, 2).contiguous().view(B, T, D)
+        x = x + self.proj(att)
+        return x + self.fc2(F.gelu(self.fc1(self.ln2(x)))), (k, v)
+
+
+class TinyLM(nn.Module):
+    def __init__(self, vocab, max_len=MAX_LEN):
+        super().__init__()
+        self.tok = nn.Embedding(vocab, D)
+        self.pos = nn.Embedding(max_len, D)
+        self.blocks = nn.ModuleList([Block() for _ in range(LAYERS)])
+        self.lnf = nn.LayerNorm(D)
+        self.head = nn.Linear(D, vocab, bias=False)
+        self.head.weight = self.tok.weight
+        self.apply(self._init)
+
+    @staticmethod
+    def _init(m):
+        if isinstance(m, (nn.Linear, nn.Embedding)):
+            nn.init.normal_(m.weight, mean=0.0, std=0.02)
+            if isinstance(m, nn.Linear) and m.bias is not None:
+                nn.init.zeros_(m.bias)
+
+    def forward(self, x, pasts=None, past_len=0):
+        B, T = x.shape
+        pos = torch.arange(past_len, past_len + T)
+        h = self.tok(x) + self.pos(pos)[None, :, :]
+        new_pasts = []
+        for i, blk in enumerate(self.blocks):
+            h, kv = blk(h, None if pasts is None else pasts[i])
+            new_pasts.append(kv)
+        return self.head(self.lnf(h)), new_pasts
+
+    @torch.no_grad()
+    def generate(self, prompts, stoi, itos, max_new=170):
+        self.eval()
+        nl = stoi["\n"]
+        outs = [[] for _ in prompts]
+        by_len = {}
+        for i, p in enumerate(prompts):
+            by_len.setdefault(len(p), []).append(i)
+        for L, idxs in by_len.items():
+            for c0 in range(0, len(idxs), 64):
+                chunk = idxs[c0:c0 + 64]
+                x = torch.tensor([prompts[i] for i in chunk], dtype=torch.long)
+                logits, pasts = self.forward(x)
+                nxt = logits[:, -1].argmax(-1)
+                done = torch.zeros(len(chunk), dtype=torch.bool)
+                past_len = L
+                for _ in range(max_new):
+                    for r in range(len(chunk)):
+                        if not done[r]:
+                            t = nxt[r].item()
+                            if t == nl:
+                                done[r] = True
+                            else:
+                                outs[chunk[r]].append(t)
+                    if done.all():
+                        break
+                    logits, pasts = self.forward(nxt[:, None], pasts, past_len)
+                    past_len += 1
+                    nxt = logits[:, -1].argmax(-1)
+        return ["".join(itos[t] for t in o) for o in outs]
+
+
+def lr_at(step):
+    if step < WARMUP:
+        return LR * (step + 1) / WARMUP
+    p = min(1.0, (step - WARMUP) / (MAX_STEPS_HORIZON - WARMUP))
+    return LR * (0.15 + 0.85 * 0.5 * (1 + math.cos(math.pi * p)))
+
+
+def save_ckpt(model, opt, step, chars, epoch, itos):
+    torch.save({"model": model.state_dict(), "opt": opt.state_dict(),
+                "step": step, "chars": chars, "epoch": epoch, "itos": itos,
+                "config": {"D": D, "LAYERS": LAYERS, "HEADS": HEADS, "FFN": FFN,
+                           "MAX_LEN": MAX_LEN}}, CKPT + ".tmp")
+    os.replace(CKPT + ".tmp", CKPT)
+
+
+def cmd_train(args):
+    tr = read_rows(TRAIN_F)
+    ev = read_rows(EVAL_F)
+    itos, stoi = build_vocab([tr, ev])
+    enc = encode_rows(tr, stoi)
+    print(f"train rows: {len(enc)}  vocab: {len(itos)}", flush=True)
+    model = TinyLM(len(itos))
+    print(f"params: {sum(p.numel() for p in model.parameters())/1e6:.2f}M", flush=True)
+    opt = torch.optim.AdamW(model.parameters(), lr=LR, betas=(0.9, 0.95),
+                            weight_decay=0.01)
+    step = chars = epoch = 0
+    if os.path.exists(CKPT):
+        st = torch.load(CKPT, map_location="cpu", weights_only=False)
+        model.load_state_dict(st["model"])
+        opt.load_state_dict(st["opt"])
+        step, chars, epoch = st["step"], st["chars"], st["epoch"]
+        print(f"resumed at step {step}", flush=True)
+    logf = open(LOG, "a")
+    start = time.time()
+    deadline = start + args.seconds
+    ema = None
+    while time.time() < deadline:
+        for idxs in make_batches(enc, seed=epoch):
+            if time.time() > deadline:
+                break
+            x, labels = batch_tensors(enc, idxs)
+            for g in opt.param_groups:
+                g["lr"] = lr_at(step)
+            logits, _ = model(x)
+            loss = F.cross_entropy(logits[:, :-1].reshape(-1, logits.size(-1)),
+                                   labels.reshape(-1), ignore_index=-100)
+            opt.zero_grad(set_to_none=True)
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0)
+            opt.step()
+            step += 1
+            chars += int(x.numel())
+            ema = loss.item() if ema is None else 0.97 * ema + 0.03 * loss.item()
+            if step % 20 == 0:
+                el = time.time() - start
+                msg = (f"step {step} loss {loss.item():.4f} ema {ema:.4f} "
+                       f"lr {lr_at(step):.2e} chars {chars} elapsed {el:.0f}s "
+                       f"sps {step/max(el, 1e-9):.2f}")
+                print(msg, flush=True)
+                logf.write(msg + "\n")
+                logf.flush()
+            if step % 300 == 0:
+                save_ckpt(model, opt, step, chars, epoch, itos)
+        epoch += 1
+    save_ckpt(model, opt, step, chars, epoch, itos)
+    print(f"DONE step {step} ema {ema} epochs {epoch}", flush=True)
+
+
+def cmd_eval(args):
+    st = torch.load(CKPT, map_location="cpu", weights_only=False)
+    itos = st["itos"]
+    stoi = {c: i for i, c in enumerate(itos)}
+    model = TinyLM(len(itos))
+    model.load_state_dict(st["model"])
+    ev = read_rows(EVAL_F)
+    prompts, golds = [], []
+    for src, tgt in ev:
+        if any(c not in stoi for c in src) or len(src) + 1 > MAX_LEN - 170:
+            continue
+        prompts.append([stoi[c] for c in src] + [stoi["\t"]])
+        golds.append(tgt)
+    t0 = time.time()
+    preds = model.generate(prompts, stoi, itos)
+    dt = time.time() - t0
+    stats = {"plain": [0, 0], "conditional": [0, 0]}
+    valid = 0
+    fails = []
+    for p, g in zip(preds, golds):
+        kind = "conditional" if '"when"' in g else "plain"
+        stats[kind][1] += 1
+        try:
+            po = json.loads(p)
+            valid += 1
+        except Exception:
+            po = None
+        if p == g:
+            stats[kind][0] += 1
+        elif len(fails) < 12:
+            fails.append({"pred": p, "gold": g})
+    n = len(golds)
+    exact = stats["plain"][0] + stats["conditional"][0]
+    metrics = {
+        "eval_n": n, "exact_match": round(exact / n, 4),
+        "valid_json": round(valid / n, 4),
+        "plain_exact": round(stats["plain"][0] / max(stats["plain"][1], 1), 4),
+        "conditional_exact": round(stats["conditional"][0] / max(stats["conditional"][1], 1), 4),
+        "plain_n": stats["plain"][1], "conditional_n": stats["conditional"][1],
+        "decode_seconds": round(dt, 1), "step": st["step"],
+    }
+    print(json.dumps(metrics, indent=1))
+    json.dump({"metrics": metrics, "sample_failures": fails},
+              open("metrics_v3.json", "w"), indent=1)
+
+
+def cmd_export(args):
+    import numpy as np
+    st = torch.load(CKPT, map_location="cpu", weights_only=False)
+    itos = st["itos"]
+    model = TinyLM(len(itos))
+    model.load_state_dict(st["model"])
+    n_params = sum(p.numel() for p in model.parameters())
+    torch.save({"state_dict": {k: v.half() for k, v in model.state_dict().items()},
+                "itos": itos, "config": st["config"], "step": st["step"]},
+               "model_v3_fp16.pt")
+    np.savez_compressed("model_v3_fp16.npz",
+                        **{k: v.half().numpy() for k, v in model.state_dict().items()})
+    json.dump({"itos": itos, "config": st["config"], "params": n_params,
+               "step": st["step"]}, open("model_v3_config.json", "w"))
+    print(f"exported: {n_params} params ({n_params/1e6:.2f}M)")
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser()
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    t = sub.add_parser("train")
+    t.add_argument("--seconds", type=int, default=3300)
+    sub.add_parser("eval")
+    sub.add_parser("export")
+    a = ap.parse_args()
+    {"train": cmd_train, "eval": cmd_eval, "export": cmd_export}[a.cmd](a)