seraphim-logic-core 0.1.0__tar.gz

seraphim_logic_core-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: seraphim-logic-core
+Version: 0.1.0
+Summary: Quantum-classical hybrid symbolic agent framework — Seraphim |LZ⟩
+Author-email: "Perfect Squared Inc. | P2 Labs" <contact@perfectsquaredinc.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/10XAnalytics/seraphim-logic-core
+Project-URL: Repository, https://github.com/10XAnalytics/seraphim-logic-core
+Project-URL: Bug Tracker, https://github.com/10XAnalytics/seraphim-logic-core/issues
+Keywords: quantum,symbolic-ai,agents,pennylane,entropy,swarm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+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
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: pennylane>=0.36
+Provides-Extra: qiskit
+Requires-Dist: qiskit>=1.0; extra == "qiskit"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# seraphim-logic-core
+
+**Quantum-Classical Hybrid Symbolic Agent Framework**  
+Perfect Squared Inc. | P2 Labs | Seraphim |LZ⟩
+
+> *Agents of the Highest Order*
+
+---
+
+## Overview
+
+`seraphim-logic-core` is the symbolic intelligence engine behind the Seraphim |LZ⟩ research initiative. It implements a quantum-native agent framework where agents exist in superposition across all symbolic states and collapse to a single truth via a PennyLane quantum circuit.
+
+```
+|S⟩ = Σ αᵢ |sᵢ⟩  →  |s*⟩
+
+P(kᵢ) ∝ exp(-Entropy(kᵢ))
+D = argmax_i(I(sᵢ) - β·E(sᵢ))
+```
+
+## Architecture
+
+```
+seraphim_logic_core/
+├── constants.py     — System constants (entropy thresholds, lifecycle states)
+├── entropy.py       — XOR-Lattice Entropy Engine (Shannon entropy, XOR diff, anomaly detection)
+├── grammar.py       — Symbolic Grammar Engine (symbols, rules, pre-built grammars)
+├── collapse.py      — Quantum Collapse Engine (PennyLane StatePrep + probs)
+├── agent.py         — SymbolicAgent (full ENCODED→DELIVERED lifecycle)
+└── swarm.py         — AgentSwarm (parallel agent coordination + entropy-aware voting)
+```
+
+## Agent Lifecycle
+
+```
+ENCODED → EVOLVED → INITIALIZED → COLLAPSED → ACTIVATED → DELIVERED
+```
+
+Each agent:
+1. **Encodes** a symbolic grammar into its logic space
+2. **Evolves** via grammar transition rules driven by entropy signals
+3. **Initializes** as |LZ⟩ — superposition across all states
+4. **Collapses** via PennyLane quantum circuit to |s*⟩
+5. **Activates** — emits a structured decision dict
+6. **Delivers** to the target system (QUANTA handler)
+
+## Quick Start
+
+```python
+from seraphim_logic_core import SymbolicAgent, AgentSwarm
+from seraphim_logic_core import threat_detection_grammar, integrity_grammar
+
+# Single agent — threat detection
+agent = SymbolicAgent(grammar=threat_detection_grammar())
+result = agent.run(entropy_signal=0.85)
+print(result["symbol"])  # e.g. "ANOMALOUS"
+
+# Swarm — integrity monitoring
+swarm = AgentSwarm(grammar=integrity_grammar())
+verdict = swarm.respond_to_xor_event(window_1, window_2)
+print(verdict["symbol"])  # e.g. "DEGRADED"
+```
+
+## Pre-Built Grammars
+
+| Grammar | Product | States |
+|---------|---------|--------|
+| `threat_detection_grammar()` | QUANTA-PULSE / QUANTA-RAD | NOMINAL → ANOMALOUS → SPOOFED → CONFIRMED → RESOLVED |
+| `integrity_grammar()` | QUANTA-VIGIL | SECURE → DEGRADED → BREACHED → RESTORING |
+
+## Installation
+
+```bash
+pip install seraphim-logic-core
+```
+
+**Development:**
+```bash
+git clone https://github.com/10XAnalytics/seraphim-logic-core
+cd seraphim-logic-core
+pip install -e ".[dev]"
+pytest
+```
+
+## Quantum Backend
+
+Uses [PennyLane](https://pennylane.ai/) `default.qubit` simulator (1024 shots).  
+Production deployments can target real quantum hardware via PennyLane device plugins.
+
+Classical fallback available for testing:
+```python
+agent = SymbolicAgent(grammar=threat_detection_grammar(), use_quantum=False)
+```
+
+## License
+
+Apache 2.0 — See [LICENSE](LICENSE)
+
+---
+
+*Perfect Squared Inc. | P2 Labs — "Simulate the Future. Secure the Present."*

seraphim_logic_core-0.1.0/README.md

@@ -0,0 +1,101 @@
+# seraphim-logic-core
+
+**Quantum-Classical Hybrid Symbolic Agent Framework**  
+Perfect Squared Inc. | P2 Labs | Seraphim |LZ⟩
+
+> *Agents of the Highest Order*
+
+---
+
+## Overview
+
+`seraphim-logic-core` is the symbolic intelligence engine behind the Seraphim |LZ⟩ research initiative. It implements a quantum-native agent framework where agents exist in superposition across all symbolic states and collapse to a single truth via a PennyLane quantum circuit.
+
+```
+|S⟩ = Σ αᵢ |sᵢ⟩  →  |s*⟩
+
+P(kᵢ) ∝ exp(-Entropy(kᵢ))
+D = argmax_i(I(sᵢ) - β·E(sᵢ))
+```
+
+## Architecture
+
+```
+seraphim_logic_core/
+├── constants.py     — System constants (entropy thresholds, lifecycle states)
+├── entropy.py       — XOR-Lattice Entropy Engine (Shannon entropy, XOR diff, anomaly detection)
+├── grammar.py       — Symbolic Grammar Engine (symbols, rules, pre-built grammars)
+├── collapse.py      — Quantum Collapse Engine (PennyLane StatePrep + probs)
+├── agent.py         — SymbolicAgent (full ENCODED→DELIVERED lifecycle)
+└── swarm.py         — AgentSwarm (parallel agent coordination + entropy-aware voting)
+```
+
+## Agent Lifecycle
+
+```
+ENCODED → EVOLVED → INITIALIZED → COLLAPSED → ACTIVATED → DELIVERED
+```
+
+Each agent:
+1. **Encodes** a symbolic grammar into its logic space
+2. **Evolves** via grammar transition rules driven by entropy signals
+3. **Initializes** as |LZ⟩ — superposition across all states
+4. **Collapses** via PennyLane quantum circuit to |s*⟩
+5. **Activates** — emits a structured decision dict
+6. **Delivers** to the target system (QUANTA handler)
+
+## Quick Start
+
+```python
+from seraphim_logic_core import SymbolicAgent, AgentSwarm
+from seraphim_logic_core import threat_detection_grammar, integrity_grammar
+
+# Single agent — threat detection
+agent = SymbolicAgent(grammar=threat_detection_grammar())
+result = agent.run(entropy_signal=0.85)
+print(result["symbol"])  # e.g. "ANOMALOUS"
+
+# Swarm — integrity monitoring
+swarm = AgentSwarm(grammar=integrity_grammar())
+verdict = swarm.respond_to_xor_event(window_1, window_2)
+print(verdict["symbol"])  # e.g. "DEGRADED"
+```
+
+## Pre-Built Grammars
+
+| Grammar | Product | States |
+|---------|---------|--------|
+| `threat_detection_grammar()` | QUANTA-PULSE / QUANTA-RAD | NOMINAL → ANOMALOUS → SPOOFED → CONFIRMED → RESOLVED |
+| `integrity_grammar()` | QUANTA-VIGIL | SECURE → DEGRADED → BREACHED → RESTORING |
+
+## Installation
+
+```bash
+pip install seraphim-logic-core
+```
+
+**Development:**
+```bash
+git clone https://github.com/10XAnalytics/seraphim-logic-core
+cd seraphim-logic-core
+pip install -e ".[dev]"
+pytest
+```
+
+## Quantum Backend
+
+Uses [PennyLane](https://pennylane.ai/) `default.qubit` simulator (1024 shots).  
+Production deployments can target real quantum hardware via PennyLane device plugins.
+
+Classical fallback available for testing:
+```python
+agent = SymbolicAgent(grammar=threat_detection_grammar(), use_quantum=False)
+```
+
+## License
+
+Apache 2.0 — See [LICENSE](LICENSE)
+
+---
+
+*Perfect Squared Inc. | P2 Labs — "Simulate the Future. Secure the Present."*

seraphim_logic_core-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seraphim-logic-core"
+version = "0.1.0"
+description = "Quantum-classical hybrid symbolic agent framework — Seraphim |LZ⟩"
+authors = [
+    { name = "Perfect Squared Inc. | P2 Labs", email = "contact@perfectsquaredinc.com" }
+]
+license = { text = "Apache-2.0" }
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["quantum", "symbolic-ai", "agents", "pennylane", "entropy", "swarm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.24",
+    "pennylane>=0.36",
+]
+
+[project.optional-dependencies]
+qiskit = ["qiskit>=1.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+]
+
+[project.urls]
+Homepage = "https://github.com/10XAnalytics/seraphim-logic-core"
+Repository = "https://github.com/10XAnalytics/seraphim-logic-core"
+"Bug Tracker" = "https://github.com/10XAnalytics/seraphim-logic-core/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["seraphim_logic_core*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"

seraphim_logic_core-0.1.0/seraphim_logic_core/__init__.py

@@ -0,0 +1,71 @@
+"""
+seraphim-logic-core
+Perfect Squared Inc. | P2 Labs | Seraphim |LZ⟩
+
+Quantum-classical hybrid symbolic agent framework.
+Agents exist in superposition — the quantum circuit collapses them to truth.
+
+    |S⟩ = Σ αᵢ |sᵢ⟩  →  |s*⟩
+"""
+
+__version__ = "0.1.0"
+__author__ = "Perfect Squared Inc. | P2 Labs"
+__license__ = "Apache-2.0"
+
+from .constants import (
+    ENTROPY_THRESHOLD,
+    BETA,
+    WINDOW_SIZE,
+    STRIDE,
+    QUANTUM_SHOTS,
+    STATE_ENCODED,
+    STATE_EVOLVED,
+    STATE_INITIALIZED,
+    STATE_COLLAPSED,
+    STATE_ACTIVATED,
+    STATE_DELIVERED,
+    LIFECYCLE,
+)
+
+from .entropy import (
+    shannon_entropy,
+    xor_lattice_diff,
+    entropy_over_stream,
+    entropy_decision,
+    anomaly_detected,
+    agent_spawn_count,
+)
+
+from .grammar import (
+    Symbol,
+    GrammarRule,
+    SymbolicGrammar,
+    threat_detection_grammar,
+    integrity_grammar,
+)
+
+from .collapse import (
+    entropy_weighted_amplitudes,
+    collapse,
+    collapse_classical,
+)
+
+from .agent import SymbolicAgent
+from .swarm import AgentSwarm
+
+__all__ = [
+    # Constants
+    "ENTROPY_THRESHOLD", "BETA", "WINDOW_SIZE", "STRIDE", "QUANTUM_SHOTS",
+    "STATE_ENCODED", "STATE_EVOLVED", "STATE_INITIALIZED",
+    "STATE_COLLAPSED", "STATE_ACTIVATED", "STATE_DELIVERED", "LIFECYCLE",
+    # Entropy
+    "shannon_entropy", "xor_lattice_diff", "entropy_over_stream",
+    "entropy_decision", "anomaly_detected", "agent_spawn_count",
+    # Grammar
+    "Symbol", "GrammarRule", "SymbolicGrammar",
+    "threat_detection_grammar", "integrity_grammar",
+    # Collapse
+    "entropy_weighted_amplitudes", "collapse", "collapse_classical",
+    # Agent + Swarm
+    "SymbolicAgent", "AgentSwarm",
+]

seraphim_logic_core-0.1.0/seraphim_logic_core/agent.py

@@ -0,0 +1,204 @@
+"""
+seraphim-logic-core — Symbolic Agent
+Perfect Squared Inc. | P2 Labs | Seraphim |LZ⟩
+
+A SymbolicAgent exists in superposition across all symbolic states defined
+by its grammar. Each agent traverses the Seraphim Field lifecycle:
+
+    ENCODED → EVOLVED → INITIALIZED → COLLAPSED → ACTIVATED → DELIVERED
+
+The agent uses the quantum collapse engine to resolve superposition and
+the entropy decision function to select optimal state transitions.
+"""
+
+import uuid
+import numpy as np
+from typing import Optional, List, Callable
+from .constants import (
+    STATE_ENCODED, STATE_EVOLVED, STATE_INITIALIZED,
+    STATE_COLLAPSED, STATE_ACTIVATED, STATE_DELIVERED, LIFECYCLE
+)
+from .entropy import entropy_decision, shannon_entropy
+from .grammar import SymbolicGrammar
+from .collapse import collapse, collapse_classical
+
+
+class SymbolicAgent:
+    """
+    A quantum-symbolic agent in the Seraphim Field.
+
+    Each agent:
+        - Carries a SymbolicGrammar defining its logic space
+        - Traverses the lifecycle: ENCODED → ... → DELIVERED
+        - Collapses superposition via PennyLane quantum circuit
+        - Emits decisions as collapsed symbolic states
+    """
+
+    def __init__(
+        self,
+        grammar: SymbolicGrammar,
+        agent_id: Optional[str] = None,
+        use_quantum: bool = True,
+        initial_symbol: Optional[str] = None,
+    ):
+        self.id = agent_id or str(uuid.uuid4())[:8]
+        self.grammar = grammar
+        self.use_quantum = use_quantum
+
+        # Lifecycle state
+        self.lifecycle_state: str = STATE_ENCODED
+
+        # Current symbolic state (name of active symbol)
+        symbol_names = list(grammar.symbols.keys())
+        if initial_symbol and initial_symbol in grammar.symbols:
+            self.current_symbol: str = initial_symbol
+        elif symbol_names:
+            self.current_symbol = symbol_names[0]
+        else:
+            self.current_symbol = ""
+
+        # History of collapsed states
+        self.history: List[dict] = []
+
+        # Entropy signal (updated externally or via observe())
+        self.entropy_signal: float = 0.0
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    def _advance_lifecycle(self) -> str:
+        """Move to the next lifecycle stage."""
+        current_idx = LIFECYCLE.index(self.lifecycle_state) if self.lifecycle_state in LIFECYCLE else -1
+        if current_idx < len(LIFECYCLE) - 1:
+            self.lifecycle_state = LIFECYCLE[current_idx + 1]
+        return self.lifecycle_state
+
+    def encode(self) -> "SymbolicAgent":
+        """Stage 0: Symbol encoded below Planck threshold."""
+        self.lifecycle_state = STATE_ENCODED
+        return self
+
+    def evolve(self, entropy_signal: float) -> "SymbolicAgent":
+        """
+        Stage 1: Evolve in the Seraphim Field.
+        Applies grammar transition rules based on entropy signal.
+        """
+        self.entropy_signal = entropy_signal
+        next_symbol = self.grammar.transition(self.current_symbol, entropy_signal)
+        if next_symbol:
+            self.current_symbol = next_symbol
+        self.lifecycle_state = STATE_EVOLVED
+        return self
+
+    def initialize(self) -> "SymbolicAgent":
+        """Stage 2: Initialize as |LZ⟩ — prepare superposition."""
+        self.lifecycle_state = STATE_INITIALIZED
+        return self
+
+    def collapse_state(self) -> Optional[dict]:
+        """
+        Stage 3: |S⟩ = Σαᵢ|sᵢ⟩ → |s*⟩
+
+        Collapse superposition to a single symbolic state.
+        Uses quantum circuit (PennyLane) or classical fallback.
+        Returns the collapsed state dict.
+        """
+        states = self.grammar.all_states()
+        if not states:
+            return None
+
+        if self.use_quantum:
+            result = collapse(states)
+        else:
+            result = collapse_classical(states)
+
+        if result:
+            self.current_symbol = result.get("name", self.current_symbol)
+            self.history.append(result)
+
+        self.lifecycle_state = STATE_COLLAPSED
+        return result
+
+    def activate(self, payload: Optional[dict] = None) -> dict:
+        """
+        Stage 4: Activate within QUANTA — emit decision.
+        Packages the collapsed state with entropy metadata.
+        """
+        symbol = self.grammar.get_symbol(self.current_symbol)
+        decision = {
+            "agent_id": self.id,
+            "grammar": self.grammar.name,
+            "symbol": self.current_symbol,
+            "value": symbol.value if symbol else 0.0,
+            "entropy_cost": symbol.entropy_cost if symbol else 0.0,
+            "information_gain": symbol.information_gain if symbol else 0.0,
+            "entropy_signal": self.entropy_signal,
+            "lifecycle": self.lifecycle_state,
+        }
+        if payload:
+            decision["payload"] = payload
+        self.lifecycle_state = STATE_ACTIVATED
+        decision["lifecycle"] = STATE_ACTIVATED
+        return decision
+
+    def deliver(self, decision: dict, handler: Optional[Callable[[dict], None]] = None) -> dict:
+        """
+        Stage 5: Deliver to target system.
+        Optionally calls a handler function with the decision.
+        """
+        decision["lifecycle"] = STATE_DELIVERED
+        self.lifecycle_state = STATE_DELIVERED
+        if handler:
+            handler(decision)
+        return decision
+
+    # ── Full lifecycle run ────────────────────────────────────────────────────
+
+    def run(
+        self,
+        entropy_signal: float,
+        payload: Optional[dict] = None,
+        handler: Optional[Callable[[dict], None]] = None,
+    ) -> dict:
+        """
+        Execute the full agent lifecycle in one call.
+
+        ENCODED → EVOLVED → INITIALIZED → COLLAPSED → ACTIVATED → DELIVERED
+
+        Returns the final delivered decision dict.
+        """
+        self.encode()
+        self.evolve(entropy_signal)
+        self.initialize()
+        self.collapse_state()
+        decision = self.activate(payload)
+        return self.deliver(decision, handler)
+
+    # ── Observation ───────────────────────────────────────────────────────────
+
+    def observe(self, stream: np.ndarray) -> float:
+        """
+        Compute entropy signal from a raw data stream.
+        Updates self.entropy_signal and returns it.
+        """
+        h = shannon_entropy(stream)
+        self.entropy_signal = h
+        return h
+
+    def optimal_state(self) -> Optional[dict]:
+        """
+        D = argmax_i(I(sᵢ) - β·E(sᵢ))
+        Returns the optimal state by entropy decision function.
+        """
+        states = self.grammar.all_states()
+        if not states:
+            return None
+        idx = entropy_decision(states)
+        return states[idx]
+
+    # ── Representation ────────────────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        return (
+            f"SymbolicAgent(id={self.id}, grammar={self.grammar.name}, "
+            f"symbol={self.current_symbol}, lifecycle={self.lifecycle_state})"
+        )

seraphim_logic_core-0.1.0/seraphim_logic_core/collapse.py

@@ -0,0 +1,118 @@
+"""
+seraphim-logic-core — Quantum Collapse Engine (PennyLane)
+Perfect Squared Inc. | P2 Labs | Seraphim |LZ⟩
+
+Implements Schrödinger-style superposition collapse using real quantum circuits:
+
+    |S⟩ = Σ αᵢ |sᵢ⟩  →  |s*⟩
+
+    P(kᵢ) ∝ exp(-Entropy(kᵢ))
+
+Agents exist in superposition across all possible symbolic states.
+The quantum circuit collapses this superposition to a final logic state |s*⟩
+based on entropy-weighted amplitudes.
+"""
+
+import math
+import numpy as np
+import pennylane as qml
+from typing import List, Optional
+from .constants import QUANTUM_SHOTS
+
+
+def _build_collapse_circuit(amplitudes: np.ndarray, n_qubits: int):
+    """Build a PennyLane quantum circuit that initializes and collapses superposition."""
+    dev = qml.device("default.qubit", wires=n_qubits, shots=QUANTUM_SHOTS)
+
+    @qml.qnode(dev)
+    def circuit():
+        # Initialize quantum state with entropy-weighted amplitudes
+        qml.StatePrep(amplitudes, wires=range(n_qubits))
+        # Measure all qubits — collapses superposition to |s*⟩
+        return qml.probs(wires=range(n_qubits))
+
+    return circuit
+
+
+def entropy_weighted_amplitudes(states: List[dict]) -> np.ndarray:
+    """
+    P(kᵢ) ∝ exp(-Entropy(kᵢ))
+
+    Converts symbolic states to quantum amplitudes weighted by entropy.
+    Lower entropy cost = higher amplitude = more likely to be selected.
+    """
+    n = len(states)
+    if n == 0:
+        raise ValueError("No states to collapse")
+
+    # Compute weights: exp(-entropy_cost)
+    weights = np.array([
+        math.exp(-s.get("entropy_cost", 0.5))
+        for s in states
+    ], dtype=complex)
+
+    # Pad to next power of 2 (required for quantum state vector)
+    n_qubits = math.ceil(math.log2(max(n, 2)))
+    padded_size = 2 ** n_qubits
+
+    padded = np.zeros(padded_size, dtype=complex)
+    padded[:n] = weights[:n]
+
+    # Normalize to unit vector (quantum requirement)
+    norm = np.linalg.norm(padded)
+    if norm == 0:
+        padded[:n] = 1.0 / math.sqrt(n)
+    else:
+        padded = padded / norm
+
+    return padded, n_qubits
+
+
+def collapse(states: List[dict]) -> Optional[dict]:
+    """
+    |S⟩ = Σ αᵢ |sᵢ⟩ → |s*⟩
+
+    Main collapse function. Takes a list of symbolic states in superposition
+    and uses a quantum circuit to collapse to a single final state.
+
+    Returns the collapsed state dict, or None if no states provided.
+    """
+    if not states:
+        return None
+
+    if len(states) == 1:
+        return states[0]
+
+    # Build quantum amplitudes from entropy weights
+    amplitudes, n_qubits = entropy_weighted_amplitudes(states)
+
+    # Run quantum circuit — collapse superposition
+    circuit = _build_collapse_circuit(amplitudes, n_qubits)
+    probs = circuit()
+
+    # Select the most probable basis state
+    collapsed_idx = int(np.argmax(probs))
+
+    # Map back to symbolic state (clamp to valid range)
+    state_idx = min(collapsed_idx, len(states) - 1)
+    return states[state_idx]
+
+
+def collapse_classical(states: List[dict]) -> Optional[dict]:
+    """
+    Classical fallback collapse — uses entropy weights without quantum circuit.
+    Used for testing or when quantum backend is unavailable.
+
+    P(kᵢ) ∝ exp(-Entropy(kᵢ)) — same math, sampled classically.
+    """
+    if not states:
+        return None
+
+    weights = np.array([
+        math.exp(-s.get("entropy_cost", 0.5))
+        for s in states
+    ])
+    weights = weights / weights.sum()
+
+    idx = np.random.choice(len(states), p=weights)
+    return states[int(idx)]