klix-engine 0.1.0__tar.gz

klix_engine-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Umgebungen
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/

klix_engine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max-Christoph Hänel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

klix_engine-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: klix-engine
+Version: 0.1.0
+Summary: Entkoppelte Entscheidungs-Köpfe (Choice, Score, Flag) auf einem geteilten semantischen Backbone - lokal, deterministisch, ohne Modelltraining.
+Author: Max-Christoph Hänel
+License: MIT
+License-File: LICENSE
+Keywords: classification,decision-engine,embeddings,nlp,routing,semantic-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: German
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: fastembed<1,>=0.3
+Requires-Dist: numpy>=1.24
+Requires-Dist: scikit-learn>=1.3
+Description-Content-Type: text/markdown
+
+# Klix
+
+Entkoppelte Entscheidungs-Köpfe auf einem geteilten semantischen Backbone.
+Ein Text geht **genau einmal** durch das Embedding-Modell (Dense + Sparse), beliebig viele
+Köpfe (`Choice`, `Score`, `Flag`) arbeiten anschließend auf den vorberechneten Vektoren –
+jeder in seinem eigenen mathematischen Raum. Kein Modelltraining, keine Slot-Limits,
+vollständig offline und CPU-only.
+
+## Architektur
+
+```text
+Text ──► HybridBackbone (FastEmbed-Dense + TF-IDF-Sparse, einmalig ~10 ms)
+              │
+              ├──► Choice   (Routing/Klassifikation: Max-Similarity + Keyword-Boost)
+              ├──► Score    (kontinuierliche Achse: Low/High-Anker + Sigmoid)
+              ├──► Flag     (Boolesch: 2/3-Klassen-Softmax mit Temperatur)
+              └──► eigene Köpfe (von BaseHead erben)
+```
+
+- **Shared Backbone:** Der Text wird einmal embedding + einmal TF-IDF transformiert.
+  3 Köpfe oder 50 Köpfe – die Extraktionskosten bleiben gleich.
+- **Entkoppelte Köpfe:** Neue Optionen in einem `Choice` beeinflussen weder `Score`- noch
+  `Flag`-Ergebnisse. Jeder Kopf kapselt seine eigene Logik.
+- **Deklarativ:** Nur Schemata mit Beispielsätzen definieren, `compile()`, fertig.
+
+## Installation
+
+```bash
+uv add klix-engine
+# oder
+pip install klix-engine
+```
+
+Beim ersten Aufruf lädt FastEmbed das Modell `paraphrase-multilingual-MiniLM-L12-v2`
+(~120 MB, einmalig, danach lokal gecacht). Danach läuft alles offline.
+
+## Schnellstart
+
+```python
+from klix import DecisionEngine, Choice, Score, Flag
+
+engine = DecisionEngine()
+
+engine.add_head(
+    Choice(
+        name="target",
+        options={
+            "it_ops": ["VPN abgerissen", "Server down", "Rechner bootet nicht"],
+            "ot_plant": ["Roboterzelle steht", "SPS Fehler", "Taktzeit deviation"],
+            "finance": ["KST 4210 über Budget", "Rechnung freigeben"],
+            "facility": ["Öllache Halle 2", "Heizung defekt"],
+        },
+    )
+)
+
+engine.add_head(
+    Score(
+        name="urgency",
+        low_anchors=["Routine-Wartung", "Informelle Frage"],
+        high_anchors=["Notfall sofort", "Produktionsstillstand", "Akute Gefahr"],
+        min_val=0.0,
+        max_val=3.0,
+    )
+)
+
+engine.add_head(
+    Flag(
+        name="is_security",
+        true_anchors=["Hackerangriff", "Ransomware Befall", "Datenabfluss"],
+        false_anchors=["Hardware kaputt", "Netzwerkstörung", "Alltägliche Anfrage"],
+        threshold=0.5,
+    )
+)
+
+engine.compile()
+
+res = engine.decide("plc-34 meldet fehler, förderband steht sofort!")
+
+print(res)                                   # <DecisionResult (11 ms): target=ot_plant, urgency=2.9, is_security=False>
+print(res.target)                            # 'ot_plant'
+print(res.urgency)                           # 2.87
+print(res.is_security)                       # False
+print(res.details("is_security"))            # {'value': False, 'probability': 0.03}
+```
+
+## Eigene Köpfe
+
+Von `BaseHead` erben und `evaluate(encoded)` implementieren:
+
+```python
+import re
+from klix import BaseHead
+
+class RegExExtractionHead(BaseHead):
+    def __init__(self, name: str, pattern: str):
+        super().__init__(name)
+        self.re = re.compile(pattern)
+
+    def get_reference_texts(self) -> list[str]:
+        return []  # keine Referenztexte nötig
+
+    def fit(self, backbone) -> None:
+        pass
+
+    def evaluate(self, encoded) -> dict:
+        match = self.re.search(encoded.text)
+        return {"value": match.group(0) if match else None}
+```
+
+## Entwicklung
+
+```bash
+uv sync          # Abhängigkeiten installieren
+uv run pytest    # Tests
+uv run python examples/demo.py
+uv build         # PyPI-Artefakte (wheel + sdist) nach dist/
+uv publish       # Hochladen (erfordert Token/Account)
+```
+
+## Lizenz
+
+MIT

klix_engine-0.1.0/README.md

@@ -0,0 +1,122 @@
+# Klix
+
+Entkoppelte Entscheidungs-Köpfe auf einem geteilten semantischen Backbone.
+Ein Text geht **genau einmal** durch das Embedding-Modell (Dense + Sparse), beliebig viele
+Köpfe (`Choice`, `Score`, `Flag`) arbeiten anschließend auf den vorberechneten Vektoren –
+jeder in seinem eigenen mathematischen Raum. Kein Modelltraining, keine Slot-Limits,
+vollständig offline und CPU-only.
+
+## Architektur
+
+```text
+Text ──► HybridBackbone (FastEmbed-Dense + TF-IDF-Sparse, einmalig ~10 ms)
+              │
+              ├──► Choice   (Routing/Klassifikation: Max-Similarity + Keyword-Boost)
+              ├──► Score    (kontinuierliche Achse: Low/High-Anker + Sigmoid)
+              ├──► Flag     (Boolesch: 2/3-Klassen-Softmax mit Temperatur)
+              └──► eigene Köpfe (von BaseHead erben)
+```
+
+- **Shared Backbone:** Der Text wird einmal embedding + einmal TF-IDF transformiert.
+  3 Köpfe oder 50 Köpfe – die Extraktionskosten bleiben gleich.
+- **Entkoppelte Köpfe:** Neue Optionen in einem `Choice` beeinflussen weder `Score`- noch
+  `Flag`-Ergebnisse. Jeder Kopf kapselt seine eigene Logik.
+- **Deklarativ:** Nur Schemata mit Beispielsätzen definieren, `compile()`, fertig.
+
+## Installation
+
+```bash
+uv add klix-engine
+# oder
+pip install klix-engine
+```
+
+Beim ersten Aufruf lädt FastEmbed das Modell `paraphrase-multilingual-MiniLM-L12-v2`
+(~120 MB, einmalig, danach lokal gecacht). Danach läuft alles offline.
+
+## Schnellstart
+
+```python
+from klix import DecisionEngine, Choice, Score, Flag
+
+engine = DecisionEngine()
+
+engine.add_head(
+    Choice(
+        name="target",
+        options={
+            "it_ops": ["VPN abgerissen", "Server down", "Rechner bootet nicht"],
+            "ot_plant": ["Roboterzelle steht", "SPS Fehler", "Taktzeit deviation"],
+            "finance": ["KST 4210 über Budget", "Rechnung freigeben"],
+            "facility": ["Öllache Halle 2", "Heizung defekt"],
+        },
+    )
+)
+
+engine.add_head(
+    Score(
+        name="urgency",
+        low_anchors=["Routine-Wartung", "Informelle Frage"],
+        high_anchors=["Notfall sofort", "Produktionsstillstand", "Akute Gefahr"],
+        min_val=0.0,
+        max_val=3.0,
+    )
+)
+
+engine.add_head(
+    Flag(
+        name="is_security",
+        true_anchors=["Hackerangriff", "Ransomware Befall", "Datenabfluss"],
+        false_anchors=["Hardware kaputt", "Netzwerkstörung", "Alltägliche Anfrage"],
+        threshold=0.5,
+    )
+)
+
+engine.compile()
+
+res = engine.decide("plc-34 meldet fehler, förderband steht sofort!")
+
+print(res)                                   # <DecisionResult (11 ms): target=ot_plant, urgency=2.9, is_security=False>
+print(res.target)                            # 'ot_plant'
+print(res.urgency)                           # 2.87
+print(res.is_security)                       # False
+print(res.details("is_security"))            # {'value': False, 'probability': 0.03}
+```
+
+## Eigene Köpfe
+
+Von `BaseHead` erben und `evaluate(encoded)` implementieren:
+
+```python
+import re
+from klix import BaseHead
+
+class RegExExtractionHead(BaseHead):
+    def __init__(self, name: str, pattern: str):
+        super().__init__(name)
+        self.re = re.compile(pattern)
+
+    def get_reference_texts(self) -> list[str]:
+        return []  # keine Referenztexte nötig
+
+    def fit(self, backbone) -> None:
+        pass
+
+    def evaluate(self, encoded) -> dict:
+        match = self.re.search(encoded.text)
+        return {"value": match.group(0) if match else None}
+```
+
+## Entwicklung
+
+```bash
+uv sync          # Abhängigkeiten installieren
+uv run pytest    # Tests
+uv run python examples/demo.py
+uv build         # PyPI-Artefakte (wheel + sdist) nach dist/
+uv publish       # Hochladen (erfordert Token/Account)
+```
+
+## Lizenz
+
+MIT

klix_engine-0.1.0/examples/demo.py

@@ -0,0 +1,89 @@
+"""Demo: Klix-Engine mit drei Köpfen (Choice, Score, Flag) auf IT/OT-Tickets."""
+
+import time
+
+from klix import DecisionEngine, Flag, Score, Choice
+
+
+def main() -> None:
+    engine = DecisionEngine()
+
+    engine.add_head(
+        Choice(
+            name="target",
+            options={
+                "it_ops": ["VPN abgerissen", "Server down", "Rechner bootet nicht", "web-02 timeout"],
+                "ot_plant": ["Roboterzelle steht", "SPS Fehler", "plc-34 fehler", "Taktzeit deviation"],
+                "finance": ["KST 4210 über Budget", "Rechnung freigeben", "Skonto abziehen"],
+                "facility": ["Schmiermittel-Pfütze Rutschgefahr", "Öllache Halle 2", "Heizung defekt"],
+            },
+        )
+    )
+
+    engine.add_head(
+        Score(
+            name="urgency",
+            low_anchors=["Routine-Wartung", "Informelle Frage", "Hat Zeit nächste Woche"],
+            high_anchors=["Notfall sofort", "Produktionsstillstand", "Akute Gefahr", "Kritischer Ausfall"],
+            min_val=0.0,
+            max_val=3.0,
+        )
+    )
+
+    engine.add_head(
+        Flag(
+            name="is_security",
+            true_anchors=["Hackerangriff", "Ransomware Befall", "Root login kompromittiert", "Datenabfluss"],
+            false_anchors=["Hardware kaputt", "Standard IT Problem", "Netzwerkstörung", "Alltägliche Anfrage"],
+            neutral_anchors=["Routineanfrage", "Allgemeine Frage", "Sonstiges Thema"],
+            threshold=0.5,
+        )
+    )
+
+    engine.compile()
+
+    tickets = [
+        "plc-34 meldet fehler, förderband steht sofort!",
+        "Kaffee ist alle, wer füllt die Maschine nach?",
+        "Halle 2 neben der Presse steht Öl auf dem Boden, jemand ist fast ausgerutscht",
+        "Verdächtiger Login auf dem Domain-Controller, Root-Zugriff um 3 Uhr nachts",
+        "VPN bricht bei Homeoffice ständig ab, Kundentermin in 10 Minuten",
+        "Rechnung 2024-118 bitte freigeben, Skonto läuft morgen ab",
+        "Roboterzelle 3 bleibt im Zyklus stehen, Taktzeit verdoppelt",
+        "Routine-Wartung der Lüftung ist nächste Woche geplant",
+    ]
+
+    print("=" * 72)
+    print("Klix-Engine Demo - 3 Köpfe, geteilter Backbone")
+    print("=" * 72)
+
+    for ticket in tickets:
+        result = engine.decide(ticket)
+        security = result.details("is_security")
+        print(f"\nTicket : {ticket}")
+        print(f"Result : {result}")
+        print(
+            f"  target={result.target} (Konfidenz {result.details('target')['confidence']:.0%}) | "
+            f"urgency={result.urgency}/3.0 | "
+            f"is_security={result.is_security} (p={security['probability']:.1%})"
+        )
+
+    # Latenz-Test: 10 Durchläufe, zeigt Shared-Backbone-Kosten vs. Kopf-Kosten.
+    print("\n" + "=" * 72)
+    print("Latenzprofil (10 Durchläufe je Ticket)")
+    print("=" * 72)
+    total = 0.0
+    for ticket in tickets[:3]:
+        times = []
+        for _ in range(10):
+            result = engine.decide(ticket)
+            times.append(result.latency_ms)
+        avg = sum(times) / len(times)
+        total += avg
+        print(f"  {avg:6.1f} ms Ø  |  {ticket[:50]}")
+    print(f"\nGeteilter Backbone: 8 Tickets × 3 Köpfe = 24 Kopf-Entscheidungen bei "
+          f"nur {total / 3:.0f} ms Ø Embedding-Kosten pro Durchlauf.")
+
+
+if __name__ == "__main__":
+    main()

klix_engine-0.1.0/examples/minimal.py

@@ -0,0 +1,7 @@
+# Minimalbeispiel
+from klix import DecisionEngine, Choice
+
+engine = DecisionEngine()
+engine.add_head(Choice(name="route", options={"ja": ["klar", "auf jeden"], "nein": ["lieber nicht"]}))
+engine.compile()
+print(engine.decide("klarer Fall"))

klix_engine-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "klix-engine"
+version = "0.1.0"
+description = "Entkoppelte Entscheidungs-Köpfe (Choice, Score, Flag) auf einem geteilten semantischen Backbone - lokal, deterministisch, ohne Modelltraining."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Max-Christoph Hänel" }]
+keywords = ["nlp", "decision-engine", "embeddings", "classification", "routing", "semantic-search"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Natural Language :: German",
+]
+dependencies = [
+    "fastembed>=0.3,<1",
+    "numpy>=1.24",
+    "scikit-learn>=1.3",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/klix"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

klix_engine-0.1.0/src/klix/__init__.py

@@ -0,0 +1,15 @@
+"""Klix: Entkoppelte Entscheidungs-Köpfe (Choice, Score, Flag) auf einem geteilten semantischen Backbone."""
+
+from klix.engine import DecisionEngine, DecisionResult
+from klix.heads import BaseHead, Choice, Flag, Score
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DecisionEngine",
+    "DecisionResult",
+    "BaseHead",
+    "Choice",
+    "Score",
+    "Flag",
+]

klix_engine-0.1.0/src/klix/backbone.py

@@ -0,0 +1,64 @@
+"""Geteilte Feature-Extraktion: ein Text geht genau einmal dense + sparse transformiert rein."""
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+from fastembed import TextEmbedding
+from sklearn.feature_extraction.text import TfidfVectorizer
+
+# Kompakte deutsche Stoppwortliste (bewusst klein, damit Fachbegriffe ihre
+# Information behalten; erweiterbar via build_vocabulary(..., stop_words=...)).
+_DEFAULT_GERMAN_STOPWORDS = [
+    "die", "der", "das", "ein", "eine", "einer", "eines", "einem", "einen",
+    "im", "in", "ist", "und", "für", "von", "mit", "an", "auf", "nach", "zu",
+    "nicht", "mehr", "wird", "wie", "was", "hier", "dort",
+]
+
+
+@dataclass
+class EncodedInput:
+    """Ergebnis der einmaligen Feature-Extraktion für einen Eingabetext."""
+
+    text: str
+    dense_vec: np.ndarray  # normalisierter Dense-Vektor (MiniLM, 384 dim)
+    sparse_vec: Any  # TF-IDF Sparse-Matrix (1 x V) oder None vor compile()
+
+
+class HybridBackbone:
+    """Kapselt Dense- (FastEmbed) und Sparse- (TF-IDF) Repräsentation eines Texts.
+
+    Wird von der Engine genau einmal instanziiert. Der Text wird pro `decide()`-Aufruf
+    genau einmal encoded; alle Köpfe arbeiten anschließend auf `EncodedInput`.
+    """
+
+    def __init__(self, model_name: str = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"):
+        self.embed_model = TextEmbedding(model_name=model_name)
+        self.tfidf_vec: TfidfVectorizer | None = None
+        self.is_indexed = False
+
+    def build_vocabulary(
+        self,
+        all_texts: list[str],
+        stop_words: list[str] | None = None,
+    ) -> None:
+        """Baut den Sparse-Index über alle in den Köpfen hinterlegten Referenztexte auf."""
+        if stop_words is None:
+            stop_words = _DEFAULT_GERMAN_STOPWORDS
+        self.tfidf_vec = TfidfVectorizer(
+            analyzer="word",
+            token_pattern=r"(?u)\b[\w-]+\b",
+            lowercase=True,
+            stop_words=stop_words,
+        )
+        self.tfidf_vec.fit(all_texts)
+        self.is_indexed = True
+
+    def encode(self, text: str) -> EncodedInput:
+        """Erzeugt beide Vektoren in einem Rutsch."""
+        vec = np.array(list(self.embed_model.embed([text]))[0])
+        norm = float(np.linalg.norm(vec))
+        dense_norm = vec / (norm if norm > 0 else 1.0)
+
+        sparse = self.tfidf_vec.transform([text]) if self.is_indexed else None
+        return EncodedInput(text=text, dense_vec=dense_norm, sparse_vec=sparse)

klix_engine-0.1.0/src/klix/engine.py

@@ -0,0 +1,83 @@
+"""Die Orchestrierungs-Engine: bindet Backbone und Köpfe zusammen."""
+
+import time
+
+from klix.backbone import HybridBackbone
+from klix.heads import BaseHead
+
+
+class DecisionResult:
+    """Ergebnis eines `decide()`-Aufrufs; Kopf-Werte als Attribute abrufbar."""
+
+    def __init__(self, text: str, latency_ms: float, head_data: dict):
+        self.text = text
+        self.latency_ms = latency_ms
+        self.data = head_data
+
+    def __getattr__(self, name: str):
+        if name in self.data:
+            return self.data[name]["value"]
+        raise AttributeError(f"Kopf '{name}' existiert nicht im Ergebnis.")
+
+    def details(self, name: str) -> dict:
+        """Vollständiges Ergebnis-Dict eines einzelnen Kopfs."""
+        return self.data.get(name, {})
+
+    def __repr__(self):
+        items = [f"{key}={value['value']}" for key, value in self.data.items()]
+        return f"<DecisionResult ({self.latency_ms:.1f}ms): {', '.join(items)}>"
+
+
+class DecisionEngine:
+    """Shared-Backbone-Engine mit beliebig vielen entkoppelten Köpfen.
+
+    Der Text wird pro `decide()` genau einmal encoded; alle Köpfe evaluieren
+    danach parallel auf denselben Vektoren.
+    """
+
+    def __init__(self, model_name: str = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"):
+        self.backbone = HybridBackbone(model_name=model_name)
+        self.heads: list[BaseHead] = []
+        self._compiled = False
+
+    def add_head(self, head: BaseHead) -> "DecisionEngine":
+        """Registriert einen Kopf (fluent, verkettbar)."""
+        self.heads.append(head)
+        self._compiled = False
+        return self
+
+    def compile(self) -> None:
+        """Sammelt alle Texte aller Köpfe ein und initialisiert die Indizes."""
+        all_texts = []
+        for head in self.heads:
+            all_texts.extend(head.get_reference_texts())
+
+        if not all_texts:
+            raise ValueError("Keine Referenztexte vorhanden: erst Köpfe via add_head() registrieren.")
+
+        self.backbone.build_vocabulary(all_texts)
+
+        for head in self.heads:
+            head.fit(self.backbone)
+
+        self._compiled = True
+
+    def decide(self, text: str) -> DecisionResult:
+        """Encoded den Text einmal und evaluiert alle Köpfe auf den Vektoren."""
+        if not self.heads:
+            raise ValueError("Keine Köpfe registriert: erst add_head() aufrufen.")
+        if not self._compiled:
+            self.compile()
+
+        start = time.perf_counter()
+
+        # 1. Einmalige Vektorisierung (~10-12 ms).
+        encoded = self.backbone.encode(text)
+
+        # 2. Evaluation aller Köpfe (< 0.2 ms insgesamt).
+        results: dict[str, dict] = {}
+        for head in self.heads:
+            results[head.name] = head.evaluate(encoded)
+
+        elapsed_ms = (time.perf_counter() - start) * 1000
+        return DecisionResult(text=text, latency_ms=elapsed_ms, head_data=results)