sperner 0.1.0__py3-none-any.whl

sperner/__init__.py

@@ -0,0 +1,78 @@
+"""
+Equilib — Gradient-free multi-objective alignment via Sperner's Lemma.
+
+Provides N-dimensional topological solvers, surrogate active-learning solvers,
+PEFT/LoRA integration, MoE routing, and human-in-the-loop alignment tools.
+"""
+
+__version__ = "0.1.0"
+
+from typing import Callable, Optional, Union
+
+import numpy as np
+import torch
+
+from .ndim_solver import NDimEquilibSolver, SpernerConvergenceError
+from .sperner_trainer import SpernerTrainer
+from .surrogate_solver import NDimSurrogateEquilibSolver, SurrogateEquilibSolver
+from .solver import EquilibSolver
+from .adaptive_solver import AdaptiveEquilibSolver
+from .analytics import calculate_frustration_score
+from .agentic_judge import AgenticEquilibriumJudge, auto_align_batch
+from .industrial import AutoModelMerger
+from .moe_router import TopologicalMoERouter
+
+
+def solve_equilibrium(
+    n_objs: int,
+    subdivision: int = 100,
+    oracle: Optional[Callable[[np.ndarray], int]] = None,
+) -> Union[np.ndarray, NDimEquilibSolver]:
+    """High-level utility to solve an equilibrium problem.
+
+    Args:
+        n_objs: Number of objectives to balance (>= 2).
+        subdivision: Resolution of the search grid (>= 2).
+        oracle: A callable taking a weight vector (numpy array of shape ``(n_objs,)``)
+                and returning the index of the most dissatisfied objective.
+
+    Returns:
+        If *oracle* is provided, a numpy array of optimal weights.
+        Otherwise, an :class:`NDimEquilibSolver` instance for manual use.
+
+    Example::
+
+        >>> from sperner import solve_equilibrium
+        >>> weights = solve_equilibrium(3, subdivision=20,
+        ...     oracle=lambda w: int(np.argmax([0.4, 0.4, 0.2] - w)))
+    """
+    solver = NDimEquilibSolver(n_objs=n_objs, subdivision=subdivision)
+    if oracle is not None:
+
+        def wrapped_oracle(weights_batch: torch.Tensor) -> torch.Tensor:
+            batch_size = weights_batch.shape[0]
+            labels = torch.zeros(batch_size, dtype=torch.long)
+            for i in range(batch_size):
+                labels[i] = oracle(weights_batch[i].cpu().numpy())
+            return labels
+
+        result = solver.solve(oracle_fn=wrapped_oracle, batch_size=1)
+        return result[0].cpu().numpy()
+    return solver
+
+
+__all__ = [
+    "NDimEquilibSolver",
+    "NDimSurrogateEquilibSolver",
+    "SpernerTrainer",
+    "EquilibSolver",
+    "SurrogateEquilibSolver",
+    "AdaptiveEquilibSolver",
+    "AutoModelMerger",
+    "TopologicalMoERouter",
+    "AgenticEquilibriumJudge",
+    "auto_align_batch",
+    "calculate_frustration_score",
+    "SpernerConvergenceError",
+    "solve_equilibrium",
+]

sperner/adaptive_solver.py

@@ -0,0 +1,129 @@
+import logging
+from typing import List, Optional
+
+import numpy as np
+
+from .solver import EquilibSolver
+
+logger = logging.getLogger(__name__)
+
+
+class AdaptiveEquilibSolver(EquilibSolver):
+    """Iterative-refinement ("zoom") solver for high-precision 3-objective alignment.
+
+    Repeatedly solves on coarser grids and re-bases the search simplex onto the
+    panchromatic triangle found in the previous iteration, achieving exponential
+    precision improvement with linear cost.
+
+    Args:
+        subdivision: Base grid resolution per zoom level.
+        max_depth: Maximum number of zoom iterations.
+        precision: Target diameter for the final triangle (in weight space).
+    """
+
+    def __init__(
+        self,
+        subdivision: int = 10,
+        max_depth: int = 5,
+        precision: float = 1e-6,
+    ) -> None:
+        super().__init__(subdivision)
+        self.max_depth = max_depth
+        self.precision = precision
+        self.basis = np.eye(3)
+
+    def weights_from_coords(self, x, y):
+        """
+        Maps local grid coordinates (x, y) to Global Weights via the current Basis.
+        """
+        # 1. Local Barycentric Coordinates (u, v, w)
+        u = x / self.n
+        v = y / self.n
+        w = (self.n - x - y) / self.n
+
+        local_weights = np.array([u, v, w])
+
+        # 2. Map to Global Simplex via Matrix Multiplication
+        return local_weights @ self.basis
+
+    def solve_adaptive(self):
+        """
+        Runs the iterative 'Zoom' process.
+        """
+        logger.info(
+            f"Starting Adaptive Sperner (Depth {self.max_depth}, Grid {self.n})..."
+        )
+
+        final_tri = None
+        global_tri_weights = []
+
+        for depth in range(1, self.max_depth + 1):
+            logger.info(f"DEPTH {depth}: Zooming into sub-simplex...")
+            # Run the standard walk on the current basis
+            result_tri_coords, path = self.walk()
+
+            if not result_tri_coords:
+                logger.error("FAIL: Walk failed at this depth.")
+                break
+
+            # Extract the vertices of the result triangle in GLOBAL weights
+            # The result_tri_coords are integer tuples [(x1,y1), (x2,y2), (x3,y3)]
+            global_tri_weights = []
+            vertex_labels = []
+
+            for pt in result_tri_coords:
+                g_w = self.weights_from_coords(*pt)
+                label = self.oracle_label(*pt)
+                global_tri_weights.append(g_w)
+                vertex_labels.append(label)
+
+            # Visualization of current precision
+            d01 = np.linalg.norm(global_tri_weights[0] - global_tri_weights[1])
+            d12 = np.linalg.norm(global_tri_weights[1] - global_tri_weights[2])
+            d20 = np.linalg.norm(global_tri_weights[2] - global_tri_weights[0])
+            max_diam = max(d01, d12, d20)
+
+            # Calculate centroid
+            centroid = sum(global_tri_weights) / 3
+            logger.info(
+                f"RESULT Depth {depth}: Centroid {np.round(centroid, 5)} | Precision (Diam): {max_diam:.6f}"
+            )
+
+            if max_diam < self.precision:
+                logger.info(
+                    f"DONE: Precision target {self.precision} reached.")
+                break
+
+            # PREPARE NEXT DEPTH: "Zoom" into this triangle
+
+            # Check if we have a panchromatic triangle (labels {0, 1, 2})
+            if set(vertex_labels) != {0, 1, 2}:
+                logger.warning(
+                    f"WARN: Triangle at depth {depth} is not panchromatic: {vertex_labels}. Zooming might fail."
+                )
+                break
+
+            new_basis = np.zeros((3, 3))
+
+            for w, l in zip(global_tri_weights, vertex_labels):
+                new_basis[l] = w
+
+            self.basis = new_basis
+            self.vertices = {}
+
+            final_tri = global_tri_weights
+
+        if final_tri:
+            logger.info(
+                f"COMPLETE: Final High-Precision Equilibrium: {np.round(sum(final_tri)/3, 7)}"
+            )
+        return final_tri
+
+
+if __name__ == "__main__":
+    # Run Adaptive Solver
+    # Start with a coarse grid (n=10) but zoom in 10 times.
+    solver = AdaptiveEquilibSolver(subdivision=10,
+                                   max_depth=10,
+                                   precision=1e-7)
+    solver.solve_adaptive()

sperner/agentic_judge.py

@@ -0,0 +1,53 @@
+import torch
+from typing import List
+
+
+class AgenticEquilibriumJudge:
+    """Automated alignment judge that provides oracle labels without a human.
+
+    Uses a simulated capability surface to identify the weakest objective
+    for any given weight mix.  In production, replace the scoring logic with
+    a distilled reward model.
+
+    Args:
+        metrics: Human-readable names for each objective dimension.
+        device: Torch device for tensor operations.
+    """
+
+    def __init__(self, metrics: List[str], device: str = "cpu") -> None:
+        self.metrics = metrics
+        self.device = device
+
+    def get_labels(self, weights: torch.Tensor) -> torch.Tensor:
+        """Return the index of the weakest objective for each row.
+
+        Args:
+            weights: Tensor of shape ``(batch, n_objs)`` with non-negative weights.
+
+        Returns:
+            Long tensor of shape ``(batch,)`` with label indices.
+        """
+        batch_size = weights.shape[0]
+        n_objs = weights.shape[1]
+
+        # Simulated Capability Surface (Realistic Non-Linear Trade-offs)
+        # In a real system, this triggers actual inference.
+        with torch.no_grad():
+            # Objectives are satisfied based on weights but penalize each other (Alignment Tax)
+            scores = weights * 0.9 - 0.1 * torch.sum(
+                weights**2, dim=1, keepdim=True)
+
+            # The label is the index of the score that is furthest from perfection (1.0)
+            gaps = 1.0 - scores
+            return torch.argmax(gaps, dim=1)
+
+
+def auto_align_batch(n_objs: int, batch_size: int = 128, device: str = "cpu"):
+    """Plug-and-play batch alignment."""
+    from .ndim_solver import NDimEquilibSolver
+
+    judge = AgenticEquilibriumJudge(
+        metrics=[f"cap_{i}" for i in range(n_objs)], device=device)
+    solver = NDimEquilibSolver(n_objs=n_objs, device=device)
+
+    return solver.solve(oracle_fn=judge.get_labels, batch_size=batch_size)

sperner/analytics.py

@@ -0,0 +1,47 @@
+"""Alignment diagnostics and walk analytics."""
+
+from typing import List, Sequence, Union
+
+import numpy as np
+
+
+def calculate_frustration_score(
+    path_vertices: Sequence[Union[List[float], np.ndarray]], ) -> float:
+    """Measure topological frustration of a Sperner walk path.
+
+    The frustration score is the ratio of total path length to net displacement.
+
+    * ~1.0 — direct convergence, minimal conflict.
+    * 1.5–3.0 — moderate trade-off complexity.
+    * >3.0 — high frustration; objectives are strongly conflicting.
+    * 999.0 — loop detected (zero net displacement).
+
+    Args:
+        path_vertices: Sequence of coordinate arrays visited by the solver.
+
+    Returns:
+        Frustration score (float).  Returns 1.0 for paths shorter than 2 steps.
+    """
+    if not path_vertices or len(path_vertices) < 2:
+        return 1.0
+
+    path = np.array(path_vertices)
+
+    # 1. Calculate total distance walked (sum of Euclidean steps)
+    diffs = path[1:] - path[:-1]
+    distances = np.linalg.norm(diffs, axis=1)
+    total_dist = np.sum(distances)
+
+    # 2. Calculate displacement (Start to Finish)
+    start = path[0]
+    end = path[-1]
+    displacement = np.linalg.norm(end - start)
+
+    # Avoid division by zero
+    if displacement < 1e-9:
+        return 999.0  # Loop detected or returned to start
+
+    # Ratio: How much did we wander?
+    frustration_index = total_dist / displacement
+
+    return float(frustration_index)

sperner/human_ui.py

@@ -0,0 +1,224 @@
+import streamlit as st
+import numpy as np
+import requests
+import json
+import logging
+import torch
+from sperner.sperner_trainer import SpernerTrainer
+from sperner.analytics import calculate_frustration_score
+
+DEFAULT_OBJECTIVES = ["Safety", "Helpfulness", "Creativity"]
+
+
+def main():
+    # Set up page
+    st.set_page_config(page_title="Sperner: Live Manifold Alignment",
+                       layout="wide",
+                       page_icon="🧬")
+
+    # Configuration Sidebar
+    with st.sidebar:
+        st.header("⚙️ Local LLM Config")
+        st.info("Compatible with OpenAI-style APIs (LM Studio, Ollama, vLLM)")
+        llm_url = st.text_input(
+            "Server URL", value="http://127.0.0.1:1234/v1/chat/completions")
+        model_name = st.text_input("Model Name", value="local-model")
+
+        default_prompt = (
+            "Write a short, highly creative story about a robot discovering a garden. "
+            "The story must be engaging but strictly avoid any mention of technology or electricity."
+        )
+        test_prompt = st.text_area("Test Prompt", value=default_prompt)
+
+        st.divider()
+        st.header("🎯 Objectives")
+        n_objs = st.number_input(
+            "Number of objectives",
+            min_value=2,
+            max_value=10,
+            value=len(DEFAULT_OBJECTIVES),
+            step=1,
+        )
+        obj_names = []
+        for i in range(int(n_objs)):
+            default = DEFAULT_OBJECTIVES[i] if i < len(
+                DEFAULT_OBJECTIVES) else f"Objective {i+1}"
+            obj_names.append(
+                st.text_input(f"Objective {i+1}",
+                              value=default,
+                              key=f"obj_{i}"))
+        st.info(
+            f"The solver will find the Nash Equilibrium between {len(obj_names)} goals."
+        )
+
+    # Session State Initialization
+    if "solver_gen" not in st.session_state:
+        st.session_state.solver_gen = None
+        st.session_state.step = 0
+        st.session_state.history = []
+        st.session_state.current_weights = None
+        st.session_state.last_response = ""
+        st.session_state.finished = False
+
+    def call_local_llm(weights):
+        """
+        Translates topological weights into a dynamic system prompt 
+        and queries the local server with robust response parsing.
+        """
+        w = weights.flatten()
+        priorities = ", ".join(f"{obj_names[i]} Weight: {w[i]:.2f}"
+                               for i in range(len(obj_names)))
+        system_prompt = (
+            f"You are an AI with following priorities: {priorities}. "
+            f"Strictly follow these weights. Adjust your tone and content accordingly."
+        )
+
+        payload = {
+            "model": model_name,
+            "system_prompt": system_prompt,
+            "input": test_prompt
+        }
+
+        try:
+            response = requests.post(llm_url, json=payload, timeout=15)
+            if response.status_code == 200:
+                data = response.json()
+
+                # --- ROBUST PARSING STRATEGY ---
+                # 1. Standard OpenAI/LM-Studio Format
+                content = data.get("choices", [{}])[0].get("message",
+                                                           {}).get("content")
+                if content: return content
+
+                # 2. Simple 'choices' with 'text' (Legacy Completions)
+                content = data.get("choices", [{}])[0].get("text")
+                if content: return content
+
+                # 3. Direct 'content' or 'response' keys (Ollama/Simple Wrappers)
+                content = data.get("content") or data.get(
+                    "response") or data.get("output")
+                if content: return content
+
+                # 4. Fallback: Display the raw JSON so the user can debug
+                return f"⚠️ Unrecognized JSON structure. Raw response:\n{json.dumps(data, indent=2)}"
+
+            else:
+                return f"❌ Server Error {response.status_code}: {response.text}"
+        except Exception as e:
+            return f"❌ Connection Error: {str(e)}"
+
+    def start_alignment():
+        # We use the mock trainer just to get the generator logic
+        trainer = SpernerTrainer("mock", obj_names, [], mock=True)
+        st.session_state.solver_gen = trainer.train_generator(grid_size=10)
+        st.session_state.step = 1
+        st.session_state.history = []
+        st.session_state.finished = False
+
+        # Get first proposal
+        weights, _ = next(st.session_state.solver_gen)
+        st.session_state.current_weights = weights
+        st.session_state.last_response = call_local_llm(weights)
+
+    def submit_verdict(label_idx):
+        try:
+            # Feed the human label back to the solver
+            weights, _ = st.session_state.solver_gen.send(label_idx)
+            st.session_state.current_weights = weights
+            st.session_state.history.append(weights)
+            st.session_state.step += 1
+            # Get the new model response for the new weights
+            with st.spinner("Generating new response from local manifold..."):
+                st.session_state.last_response = call_local_llm(weights)
+        except StopIteration as e:
+            st.session_state.finished = True
+            st.session_state.final_result = e.value
+
+    # --- UI LAYOUT ---
+    st.title("🧬 Sperner: Live Manifold Alignment")
+    st.markdown("""
+    ### Find the "Goldilocks Zone" of your Local LLM.
+    This tool uses a **Sperner Walk** to navigate the latent space of your model. 
+    Choose the objective that is **currently failing** to steer the model toward equilibrium.
+    """)
+
+    if not st.session_state.solver_gen:
+        if st.button("🚀 Start Live Alignment Session",
+                     use_container_width=True):
+            start_alignment()
+            st.rerun()
+    else:
+        if st.session_state.finished:
+            st.balloons()
+            st.success("✅ Nash Equilibrium Reached!")
+            if hasattr(st.session_state, 'final_result'
+                       ) and st.session_state.final_result is not None:
+                # result might be a torch.Tensor, numpy array or None
+                res = st.session_state.final_result
+                if isinstance(res, torch.Tensor):
+                    res = res.cpu().numpy().flatten()
+                elif isinstance(res, (list, np.ndarray)):
+                    res = np.array(res).flatten()
+
+                st.json(dict(zip(obj_names, res.tolist())))
+
+            if st.button("Restart"):
+                st.session_state.solver_gen = None
+                st.rerun()
+        else:
+            col1, col2 = st.columns([1, 2])
+
+            with col1:
+                st.subheader("📊 Current Manifold Weights")
+                if st.session_state.current_weights is not None:
+                    for i, name in enumerate(obj_names):
+                        if i < len(st.session_state.current_weights):
+                            val = float(st.session_state.current_weights[i])
+                            st.progress(val, text=f"{name}: {val*100:.1f}%")
+
+                st.divider()
+                st.metric("Walk Step", st.session_state.step)
+                if st.session_state.history:
+                    f_score = calculate_frustration_score(
+                        st.session_state.history)
+                    st.write(f"Topology Frustration: `{f_score:.2f}`")
+
+            with col2:
+                st.subheader("🤖 Local LLM Response")
+                if st.session_state.current_weights is not None:
+                    st.info(
+                        f"Generated at weights: {np.round(st.session_state.current_weights, 2)}"
+                    )
+                st.chat_message("assistant").write(
+                    st.session_state.last_response)
+
+                st.divider()
+                st.subheader("👨‍⚖️ Your Verdict")
+                st.write(
+                    "Which capability is **least satisfied** in this response?"
+                )
+
+                n_cols = min(len(obj_names), 4)
+                for row_start in range(0, len(obj_names), n_cols):
+                    v_cols = st.columns(min(n_cols,
+                                            len(obj_names) - row_start))
+                    for j, name in enumerate(obj_names[row_start:row_start +
+                                                       len(v_cols)]):
+                        idx = row_start + j
+                        if v_cols[j].button(
+                                f"Needs more {name}",
+                                key=f"btn_{idx}",
+                                use_container_width=True,
+                                type="primary" if idx == 0 else "secondary"):
+                            submit_verdict(idx)
+                            st.rerun()
+
+        if st.session_state.history:
+            st.divider()
+            st.subheader("📈 Alignment Path")
+            chart_data = np.array(st.session_state.history)
+            st.line_chart(chart_data)
+
+
+if __name__ == "__main__":
+    main()

sperner/industrial.py

@@ -0,0 +1,112 @@
+import logging
+from typing import Callable, Dict, List
+
+import numpy as np
+import torch
+
+from .ndim_solver import NDimEquilibSolver
+
+logger = logging.getLogger(__name__)
+
+
+class AutoModelMerger:
+    """Production-grade model merger using topological alignment.
+
+    Finds the Nash equilibrium of conflicting model capabilities by mapping
+    each capability to a simplex dimension and running a Sperner walk.
+
+    Args:
+        base_model_id: Identifier for the base model (e.g. HuggingFace repo id).
+        adapter_ids: List of adapter/capability identifiers to merge.
+        device: Torch device for the underlying solver.
+    """
+
+    def __init__(
+        self,
+        base_model_id: str,
+        adapter_ids: List[str],
+        device: str = "cpu",
+    ) -> None:
+        self.base_model_id = base_model_id
+        self.adapter_ids = adapter_ids
+        self.capability_names = [aid.split('/')[-1] for aid in adapter_ids]
+        self.device = device
+
+    def find_optimal_mix(self,
+                         evaluators: List[Callable],
+                         precision: int = 50) -> Dict[str, float]:
+        """
+        The 'Set and Forget' method for model alignment.
+        """
+        logger.info(
+            f"Starting Industrial Alignment for: {self.capability_names}")
+
+        solver = NDimEquilibSolver(n_objs=len(self.adapter_ids),
+                                   subdivision=precision,
+                                   device=self.device)
+
+        def industrial_oracle(weights_batch: torch.Tensor) -> torch.Tensor:
+            """
+            Vectorized oracle for the industrial merger.
+            """
+            batch_size = weights_batch.shape[0]
+            labels = torch.zeros(batch_size,
+                                 dtype=torch.long,
+                                 device=self.device)
+
+            for i in range(batch_size):
+                weights = weights_batch[i].cpu().numpy()
+                scores = []
+                for ev in evaluators:
+                    scores.append(ev(weights))
+
+                # We want to find the objective with the largest gap to the max score
+                # (The most dissatisfied capability)
+                scores_np = np.array(scores)
+                labels[i] = int(np.argmax(np.max(scores_np) - scores_np))
+
+            return labels
+
+        # High-performance synchronous solve
+        best_weights_tensor = solver.solve(oracle_fn=industrial_oracle,
+                                           batch_size=1)
+
+        # Convert back to dictionary
+        best_weights = best_weights_tensor[0].cpu().numpy()
+        return dict(zip(self.capability_names, best_weights))
+
+
+def run_enterprise_demo():
+    print("\n" + "=" * 50)
+    print(" ENTERPRISE MODEL MERGING DEMO")
+    print("=" * 50)
+
+    merger = AutoModelMerger(
+        "meta-llama/Llama-3",
+        ["adapters/speed", "adapters/accuracy", "adapters/safety"])
+
+    # Define simple business constraints
+    def speed_eval(w):
+        return float(w[0] * 0.9)
+
+    def accuracy_eval(w):
+        return float(w[1] * 0.95 - (w[0] * 0.1))
+
+    def safety_eval(w):
+        return float(w[2] * 1.0 - (w[1] * 0.2))
+
+    evaluators = [speed_eval, accuracy_eval, safety_eval]
+
+    print("[STEP 1] Calculating Nash Equilibrium for Capabilities...")
+    result = merger.find_optimal_mix(evaluators)
+
+    print("\n[STEP 2] Optimal Industrial Deployment Weights:")
+    for cap, weight in result.items():
+        print(f"  --> {cap:10}: {weight*100:5.1f}%")
+
+    print("\n[RESULT] This mix guarantees maximum system stability.")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    run_enterprise_demo()