Create hv_intent.py

hv_intent.py

@@ -0,0 +1,125 @@
+"""
+hv_intent.py
+
+Hypervector intent router for 5-class classification.
+
+A 512-byte hypervector memory plus a 15 KB evolved character codebook.
+Inference is one Hamming comparison per intent.
+
+Usage:
+    from hv_intent import HVIntentRouter
+
+    router = HVIntentRouter.from_pretrained(".")
+    router.predict("what is the weather today")
+    # -> "weather"
+
+Author: <your name>
+License: apache-2.0
+"""
+
+import json
+import numpy as np
+from pathlib import Path
+
+
+VOCAB = "abcdefghijklmnopqrstuvwxyz"
+D_DEFAULT = 4096
+
+
+class HVIntentRouter:
+    def __init__(self, vocab_codebook, intent_codebook, memory, labels):
+        self.vocab_codebook = vocab_codebook          # (V, D) int8 ±1
+        self.intent_codebook = intent_codebook        # (C, D) int8 ±1
+        self.memory = memory                          # (D,) int8 ±1
+        self.labels = list(labels)
+        self.vocab = VOCAB
+        self.char_to_idx = {c: i for i, c in enumerate(VOCAB)}
+        self.D = vocab_codebook.shape[1]
+
+    # -----------------------------------------------------------------------
+    #  Encoding
+    # -----------------------------------------------------------------------
+
+    def encode(self, phrase):
+        """Sum-bundle character hypervectors, majority-vote on ties."""
+        indices = [self.char_to_idx[c] for c in phrase.lower() if c in self.char_to_idx]
+        if not indices:
+            return np.zeros(self.D, dtype=np.int8)
+        stacked = self.vocab_codebook[indices].astype(np.int32)
+        s = stacked.sum(axis=0)
+        return np.where(s >= 0, np.int8(1), np.int8(-1))
+
+    # -----------------------------------------------------------------------
+    #  Inference
+    # -----------------------------------------------------------------------
+
+    def predict_proba(self, phrase):
+        """Return a softmax over intent similarities."""
+        phrase_hv = self.encode(phrase).astype(np.int32)
+        retrieved = self.memory.astype(np.int32) * phrase_hv
+        sims = (retrieved.astype(np.float32) @
+                self.intent_codebook.astype(np.float32).T) / 32.0
+        sims -= sims.max()
+        probs = np.exp(sims)
+        probs /= probs.sum()
+        return probs
+
+    def predict(self, phrase):
+        """Return the top intent label."""
+        probs = self.predict_proba(phrase)
+        return self.labels[int(np.argmax(probs))]
+
+    def predict_batch(self, phrases):
+        """Return a list of labels."""
+        return [self.predict(p) for p in phrases]
+
+    def similarity_scores(self, phrase):
+        """Return raw Hamming similarity to each intent (no softmax)."""
+        phrase_hv = self.encode(phrase).astype(np.int32)
+        retrieved = self.memory.astype(np.int32) * phrase_hv
+        return (retrieved.astype(np.float32) @
+                self.intent_codebook.astype(np.float32).T) / self.D
+
+    # -----------------------------------------------------------------------
+    #  Persistence
+    # -----------------------------------------------------------------------
+
+    @classmethod
+    def from_pretrained(cls, path):
+        """Load from a directory containing config.json and codebooks.npz."""
+        path = Path(path)
+        with open(path / "config.json") as f:
+            config = json.load(f)
+        data = np.load(path / config["weights_file"])
+        return cls(
+            vocab_codebook=data["vocab_codebook"],
+            intent_codebook=data["intent_codebook"],
+            memory=data["memory"],
+            labels=config["intent_labels"],
+        )
+
+    def save_pretrained(self, path):
+        """Save codebooks and config to a directory."""
+        path = Path(path)
+        path.mkdir(parents=True, exist_ok=True)
+        np.savez_compressed(
+            path / "codebooks.npz",
+            vocab_codebook=self.vocab_codebook,
+            intent_codebook=self.intent_codebook,
+            memory=self.memory,
+        )
+        config = {
+            "model_type": "hv-intent-router",
+            "architecture": "evolved-hypervector",
+            "dimension": int(self.D),
+            "vocabulary_size": len(self.vocab),
+            "num_intents": len(self.labels),
+            "intent_labels": self.labels,
+            "vocabulary": self.vocab,
+            "encoding": "sum-bundle",
+            "bundling": "majority-vote",
+            "similarity": "hamming",
+            "weights_file": "codebooks.npz",
+        }
+        with open(path / "config.json", "w") as f:
+            json.dump(config, f, indent=2)