kontinuum-core 0.1.1__tar.gz

kontinuum_core-0.1.1/LICENSE

@@ -0,0 +1,10 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+This repository uses the GNU Affero General Public License v3.0.
+For the full license text, see:
+https://www.gnu.org/licenses/agpl-3.0.txt

kontinuum_core-0.1.1/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: kontinuum-core
+Version: 0.1.1
+Summary: Neuro-inspired learning engine for anomaly detection
+Author-email: Chance-Konstruktion <introareback@gmail.com>
+License: AGPL-3.0
+Project-URL: Homepage, https://github.com/Chance-Konstruktion/kontinuum-core
+Project-URL: Issues, https://github.com/Chance-Konstruktion/kontinuum-core/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# KONTINUUM Core
+
+Pure Python learning engine extracted from [KONTINUUM](https://github.com/Chance-Konstruktion/ha-kontinuum). No Home Assistant dependency — usable from any Python project.
+
+> **Part of the 3-repo family:**
+> **kontinuum-core** (this repo, HA-free Python package on PyPI) ·
+> [`ha-kontinuum`](https://github.com/Chance-Konstruktion/ha-kontinuum) (full HA Pro integration with UI) ·
+> [`ha-kontinuum-lite`](https://github.com/Chance-Konstruktion/ha-kontinuum-lite) (slim HA integration, no UI)
+
+## Installation
+
+```bash
+pip install kontinuum-core
+```
+
+## Usage
+
+```python
+from kontinuum_core import KontinuumEngine
+
+engine = KontinuumEngine()
+snapshot = engine.observe({"token": "bedroom.light.on", "room": "bedroom"})
+print(snapshot.surprise)
+```
+
+## License
+
+AGPL-3.0 – see LICENSE file.

kontinuum_core-0.1.1/README.md

@@ -0,0 +1,28 @@
+# KONTINUUM Core
+
+Pure Python learning engine extracted from [KONTINUUM](https://github.com/Chance-Konstruktion/ha-kontinuum). No Home Assistant dependency — usable from any Python project.
+
+> **Part of the 3-repo family:**
+> **kontinuum-core** (this repo, HA-free Python package on PyPI) ·
+> [`ha-kontinuum`](https://github.com/Chance-Konstruktion/ha-kontinuum) (full HA Pro integration with UI) ·
+> [`ha-kontinuum-lite`](https://github.com/Chance-Konstruktion/ha-kontinuum-lite) (slim HA integration, no UI)
+
+## Installation
+
+```bash
+pip install kontinuum-core
+```
+
+## Usage
+
+```python
+from kontinuum_core import KontinuumEngine
+
+engine = KontinuumEngine()
+snapshot = engine.observe({"token": "bedroom.light.on", "room": "bedroom"})
+print(snapshot.surprise)
+```
+
+## License
+
+AGPL-3.0 – see LICENSE file.

kontinuum_core-0.1.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kontinuum-core"
+version = "0.1.1"
+authors = [{name = "Chance-Konstruktion", email = "introareback@gmail.com"}]
+description = "Neuro-inspired learning engine for anomaly detection"
+readme = "README.md"
+license = {text = "AGPL-3.0"}
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: GNU Affero General Public License v3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/Chance-Konstruktion/kontinuum-core"
+Issues = "https://github.com/Chance-Konstruktion/kontinuum-core/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

kontinuum_core-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kontinuum_core-0.1.1/src/kontinuum_core/__init__.py

@@ -0,0 +1,13 @@
+"""KONTINUUM Core - neuro-inspired learning engine (HA-free)."""
+from .engine import KontinuumEngine
+from .scheduler import Scheduler
+from .types import MemoryState, Observation, Prediction
+
+__version__ = "0.1.1"
+__all__ = [
+    "KontinuumEngine",
+    "Scheduler",
+    "Observation",
+    "Prediction",
+    "MemoryState",
+]

kontinuum_core-0.1.1/src/kontinuum_core/amygdala.py

@@ -0,0 +1,164 @@
+"""Amygdala module for KONTINUUM Core.
+
+Biological inspiration: Risk assessment and safety gate. The amygdala
+evaluates proposed actions emotionally – above all for danger – and can
+trigger a rapid "STOP!" before the prefrontal cortex has finished
+reasoning.
+"""
+
+import logging
+import time
+
+_LOGGER = logging.getLogger(__name__)
+
+NEVER_AUTO = {"alarm", "lock"}
+
+RISK_SCORES = {
+    "light": 0.05, "media": 0.05, "automation": 0.1,
+    "switch": 0.2, "fan": 0.15, "cover": 0.3,
+    "climate": 0.35, "water_heater": 0.4, "vacuum": 0.25,
+    "lock": 0.9, "alarm": 1.0,
+}
+
+SAFE_STATES = {
+    "light": {"on", "off"},
+    "media": {"playing", "paused", "standby", "off"},
+    "switch": {"on", "off"},
+    "fan": {"on", "off"},
+    "climate": {"heating", "cooling", "idle", "off"},
+    "cover": {"open", "closed"},
+    "automation": {"on"},
+}
+
+
+class Amygdala:
+    """Assesses the risk of a proposed action."""
+
+    def __init__(self):
+        self.learned_risk = {}
+        self.veto_log = []
+        self.total_assessments = 0
+        self.total_vetoes = 0
+        self.total_cautions = 0
+
+    def assess(self, token: str, semantic: str, room: str,
+               state: str, confidence: float,
+               context: dict = None) -> dict:
+        """Assesses the risk of an action."""
+        self.total_assessments += 1
+        context = context or {}
+        reasons = []
+
+        # 1. Absolute vetoes
+        if semantic in NEVER_AUTO:
+            self.total_vetoes += 1
+            reason = f"{semantic} is safety-critical"
+            reasons.append(reason)
+            self._log_veto(token, reason)
+            return {
+                "decision": "VETO", "risk": 1.0,
+                "reasons": reasons, "required_confidence": float("inf"),
+            }
+
+        system_mode = context.get("system_mode", "home")
+        if system_mode in ("away", "vacation"):
+            if semantic not in ("automation",):
+                reasons.append(f"System in {system_mode} mode")
+
+        # 2. Base risk
+        base_risk = RISK_SCORES.get(semantic, 0.3)
+
+        # 2b. SAFE_STATES check
+        if semantic in SAFE_STATES:
+            if state not in SAFE_STATES[semantic]:
+                base_risk = min(1.0, base_risk + 0.2)
+                reasons.append(f"Unknown state '{state}' for {semantic}: +0.2")
+
+        # 3. Context modifiers
+        risk = base_risk
+
+        if system_mode in ("away", "vacation"):
+            risk = min(1.0, risk + 0.3)
+            reasons.append("Away mode: +0.3 risk")
+
+        is_night = context.get("is_night", False)
+        if is_night and semantic == "light" and state == "on":
+            risk = min(1.0, risk + 0.1)
+            reasons.append("Light on at night: +0.1")
+
+        learned_key = f"{room}.{semantic}.{state}"
+        if learned_key in self.learned_risk:
+            modifier = self.learned_risk[learned_key]
+            risk = max(0.0, min(1.0, risk + modifier))
+            reasons.append(f"Learned: {modifier:+.2f}")
+
+        # 4. Confidence thresholds
+        if risk < 0.15:
+            required_conf = 0.3
+        elif risk < 0.3:
+            required_conf = 0.5
+        elif risk < 0.5:
+            required_conf = 0.65
+        elif risk < 0.7:
+            required_conf = 0.8
+        else:
+            required_conf = 0.95
+
+        # 5. Decision
+        if risk >= 0.95:
+            decision = "VETO"
+            self.total_vetoes += 1
+            reasons.append(f"Risk {risk:.2f} >= 0.95")
+            self._log_veto(token, reasons[-1])
+        elif confidence < required_conf:
+            decision = "CAUTION"
+            self.total_cautions += 1
+            reasons.append(f"Conf {confidence:.0%} < {required_conf:.0%}")
+        else:
+            decision = "ALLOW"
+            reasons.append(f"Conf {confidence:.0%} >= {required_conf:.0%}")
+
+        return {
+            "decision": decision, "risk": round(risk, 3),
+            "reasons": reasons, "required_confidence": required_conf,
+        }
+
+    def learn_from_feedback(self, token: str, feedback: str):
+        """Adjusts risk based on user feedback."""
+        if feedback == "negative":
+            current = self.learned_risk.get(token, 0.0)
+            self.learned_risk[token] = min(0.5, current + 0.05)
+        elif feedback == "positive":
+            current = self.learned_risk.get(token, 0.0)
+            self.learned_risk[token] = max(-0.2, current - 0.02)
+
+    def _log_veto(self, token: str, reason: str):
+        self.veto_log.append({"timestamp": time.time(), "token": token, "reason": reason})
+        if len(self.veto_log) > 50:
+            self.veto_log = self.veto_log[-50:]
+        _LOGGER.info("VETO: %s – %s", token, reason)
+
+    def to_dict(self) -> dict:
+        return {
+            "learned_risk": self.learned_risk,
+            "total_assessments": self.total_assessments,
+            "total_vetoes": self.total_vetoes,
+            "total_cautions": self.total_cautions,
+        }
+
+    def from_dict(self, data: dict):
+        self.learned_risk = data.get("learned_risk", {})
+        self.total_assessments = data.get("total_assessments", 0)
+        self.total_vetoes = data.get("total_vetoes", 0)
+        self.total_cautions = data.get("total_cautions", 0)
+
+    @property
+    def stats(self) -> dict:
+        return {
+            "total_assessments": self.total_assessments,
+            "total_vetoes": self.total_vetoes,
+            "total_cautions": self.total_cautions,
+            "learned_risks": len(self.learned_risk),
+            "veto_rate": f"{self.total_vetoes / max(1, self.total_assessments):.1%}",
+            "recent_vetos": self.veto_log[-5:],
+        }

kontinuum_core-0.1.1/src/kontinuum_core/anterior_cingulate.py

@@ -0,0 +1,178 @@
+"""Anterior Cingulate Cortex (ACC) – conflict monitor and error tracker.
+
+Biological inspiration: The ACC detects conflicts between competing
+action candidates and signals when uncertainty is too high. It
+modulates the decision threshold: many conflicts → act more cautiously,
+high clarity → act faster.
+
+Responsibilities:
+- Detect conflicts between modules (e.g. Hippocampus vs Amygdala)
+- Track prediction errors (expectation vs reality)
+- Adjust confidence thresholds dynamically
+- Signal "cognitive control" when uncertainty is high
+
+Performance: pure arithmetic, no I/O, no ML. ~0 ms per event.
+"""
+
+import logging
+from collections import deque
+
+_LOGGER = logging.getLogger(__name__)
+
+# How many decisions to keep in the rolling window
+HISTORY_SIZE = 200
+# EMA factor for conflict rate
+EMA_ALPHA = 0.05
+# Thresholds for conflict level
+CONFLICT_LOW = 0.2
+CONFLICT_HIGH = 0.6
+
+
+class AnteriorCingulateCortex:
+    """Monitors conflicts between modules and adapts decision thresholds."""
+
+    def __init__(self):
+        self._conflict_history = deque(maxlen=HISTORY_SIZE)
+        self._error_history = deque(maxlen=HISTORY_SIZE)
+
+        self.conflict_level = 0.0      # 0.0 = no conflict, 1.0 = max conflict
+        self.error_rate = 0.0          # fraction of wrong predictions
+        self.cognitive_control = 0.0   # how hard to brake
+
+        self.total_conflicts = 0
+        self.total_agreements = 0
+        self.total_errors = 0
+        self.total_correct = 0
+        self.threshold_adjustments = 0
+
+        self.confidence_threshold = 0.5
+        self._last_update_ts = 0.0
+
+    def observe_decision(self, proposals: list) -> float:
+        """Measures the conflict level of a decision round.
+
+        proposals: list of module suggestions, e.g.:
+          [{"source": "hippocampus", "action": "light.on", "confidence": 0.8},
+           {"source": "amygdala", "action": "veto", "confidence": 0.6}]
+
+        Returns: conflict value in [0.0, 1.0]
+        """
+        if not proposals or len(proposals) < 2:
+            self._conflict_history.append(0.0)
+            self._update_ema()
+            self.total_agreements += 1
+            return 0.0
+
+        actions = [p.get("action", "") for p in proposals]
+        unique_actions = set(actions)
+
+        disagreement = (len(unique_actions) - 1) / max(1, len(actions) - 1)
+
+        has_veto = any(p.get("action") == "veto" or p.get("veto", False) for p in proposals)
+        if has_veto:
+            disagreement = min(1.0, disagreement + 0.3)
+
+        confidences = [p.get("confidence", 0.5) for p in proposals]
+        if len(confidences) > 1:
+            mean_conf = sum(confidences) / len(confidences)
+            variance = sum((c - mean_conf) ** 2 for c in confidences) / len(confidences)
+            disagreement = min(1.0, disagreement + variance * 0.5)
+
+        self._conflict_history.append(disagreement)
+        self._update_ema()
+
+        if disagreement > CONFLICT_LOW:
+            self.total_conflicts += 1
+        else:
+            self.total_agreements += 1
+
+        return disagreement
+
+    def observe_outcome(self, was_correct: bool):
+        """Records whether the last action was correct."""
+        self._error_history.append(0.0 if was_correct else 1.0)
+
+        if was_correct:
+            self.total_correct += 1
+        else:
+            self.total_errors += 1
+
+        self.error_rate = (
+            EMA_ALPHA * (0.0 if was_correct else 1.0)
+            + (1.0 - EMA_ALPHA) * self.error_rate
+        )
+
+        self._adjust_threshold()
+
+    def get_adjusted_threshold(self, base_confidence: float = 0.5) -> float:
+        """Returns an adjusted confidence threshold.
+
+        High conflict → threshold raised (more cautious).
+        Low conflict  → threshold lowered (act faster).
+        """
+        return max(0.2, min(0.95, base_confidence + self.cognitive_control * 0.3))
+
+    def should_defer_to_cortex(self) -> bool:
+        """Returns True when uncertainty is high enough to consult the cortex (LLM)."""
+        return self.conflict_level > CONFLICT_HIGH or self.error_rate > 0.4
+
+    def _update_ema(self):
+        if self._conflict_history:
+            latest = self._conflict_history[-1]
+            self.conflict_level = (
+                EMA_ALPHA * latest + (1.0 - EMA_ALPHA) * self.conflict_level
+            )
+        self.cognitive_control = min(1.0, self.conflict_level * 0.6 + self.error_rate * 0.4)
+
+    def _adjust_threshold(self):
+        old = self.confidence_threshold
+
+        if self.error_rate > 0.3:
+            self.confidence_threshold = min(0.9, self.confidence_threshold + 0.02)
+        elif self.error_rate < 0.1 and self.conflict_level < CONFLICT_LOW:
+            self.confidence_threshold = max(0.3, self.confidence_threshold - 0.01)
+
+        if abs(old - self.confidence_threshold) > 0.001:
+            self.threshold_adjustments += 1
+
+    @property
+    def stats(self) -> dict:
+        return {
+            "conflict_level": round(self.conflict_level, 3),
+            "error_rate": round(self.error_rate, 3),
+            "cognitive_control": round(self.cognitive_control, 3),
+            "confidence_threshold": round(self.confidence_threshold, 3),
+            "total_conflicts": self.total_conflicts,
+            "total_agreements": self.total_agreements,
+            "total_errors": self.total_errors,
+            "total_correct": self.total_correct,
+            "threshold_adjustments": self.threshold_adjustments,
+        }
+
+    def to_dict(self) -> dict:
+        return {
+            "conflict_level": self.conflict_level,
+            "error_rate": self.error_rate,
+            "cognitive_control": self.cognitive_control,
+            "confidence_threshold": self.confidence_threshold,
+            "total_conflicts": self.total_conflicts,
+            "total_agreements": self.total_agreements,
+            "total_errors": self.total_errors,
+            "total_correct": self.total_correct,
+            "threshold_adjustments": self.threshold_adjustments,
+        }
+
+    def from_dict(self, data: dict):
+        self.conflict_level = data.get("conflict_level", 0.0)
+        self.error_rate = data.get("error_rate", 0.0)
+        self.cognitive_control = data.get("cognitive_control", 0.0)
+        self.confidence_threshold = data.get("confidence_threshold", 0.5)
+        self.total_conflicts = data.get("total_conflicts", 0)
+        self.total_agreements = data.get("total_agreements", 0)
+        self.total_errors = data.get("total_errors", 0)
+        self.total_correct = data.get("total_correct", 0)
+        self.threshold_adjustments = data.get("threshold_adjustments", 0)
+
+
+# Backwards-compatible alias for engine.py imports.
+AnteriorCingulate = AnteriorCingulateCortex