lambda-gate public API v0.2.0

build/torch-universal/szl_lambda_gate/__init__.py

@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: Apache-2.0
+# © 2026 SZL Holdings · Stephen P. Lutar · ORCID 0009-0001-0110-4173
+"""szl_lambda_gate — the Lambda-Spine aggregator (Λ) as a universal kernel.
+
+A pure-PyTorch (universal) kernel from SZL Holdings for the Hugging Face
+Kernel Hub. It ports the canonical Λ aggregator into a differentiable,
+torch.compile-friendly torch op:
+
+    Λ(x) = ∏ xᵢ^{wᵢ},  Σwᵢ = 1,  wᵢ > 0,  xᵢ ∈ [0,1]   (weighted geometric mean)
+
+plus an ADVISORY governance gate (Λ vs threshold), the four carried axioms as
+real runtime self-checks, and pure nn.Module layers.
+
+Load from the Hub:
+
+    import torch
+    from kernels import get_kernel
+
+    lg = get_kernel("SZLHOLDINGS/szl-lambda-gate")
+    axes = torch.tensor([0.9, 0.8, 0.95])        # axis scores in [0,1]
+    score = lg.lambda_aggregate(axes)            # Λ(x) ∈ [0,1]
+    res = lg.lambda_gate(axes, threshold=0.5)    # ADVISORY pass/fail
+    print(res.score, res.passed, res.advisory)
+
+WHAT Λ IS / IS NOT (HONESTY — SZL Holdings doctrine v11):
+  Λ is the weighted-geometric-mean aggregator — a non-compensatory, ADVISORY
+  way to roll axis scores in [0,1] into one number (any zeroed axis zeroes the
+  aggregate). It is NOT "proven trust" and NOT a closed theorem: Λ-uniqueness
+  remains Conjecture 1 (OPEN — an unresolved CAUCHY_ND step plus a missing
+  symmetry axiom). Label it honestly everywhere; a gate "pass" is advisory.
+
+PROVENANCE: backed by the Lean 4 formalization szl-holdings/lutar-lean
+  (749 declarations / 14 axioms / 163 tracked sorries),
+  DOI 10.5281/zenodo.20434308 (lutar-lean). Λ uniqueness = Conjecture 1 (open).
+"""
+from typing import Optional
+
+import torch
+
+from . import layers  # noqa: F401  (must be importable for Hub layer mapping)
+from ._lambda import YUYAY_AXES, YUYAY_FLOORS, LambdaGateResult
+from ._lambda import find_axiom_violation as _find_axiom_violation
+from ._lambda import is_bounded_by_max as _is_bounded_by_max
+from ._lambda import is_egyptian_exact as _is_egyptian_exact
+from ._lambda import is_homogeneous as _is_homogeneous
+from ._lambda import is_monotone as _is_monotone
+from ._lambda import lambda_aggregate as _lambda_aggregate
+from ._lambda import lambda_gate as _lambda_gate
+from ._lambda import lambda_gate_batch as _lambda_gate_batch
+from ._lambda import selfcheck as _selfcheck
+from ._lambda import yuyay_weights as _yuyay_weights
+
+__all__ = [
+    "lambda_aggregate",
+    "lambda_gate",
+    "lambda_gate_batch",
+    "LambdaGateResult",
+    "is_monotone",
+    "is_egyptian_exact",
+    "is_bounded_by_max",
+    "is_homogeneous",
+    "find_axiom_violation",
+    "selfcheck",
+    "yuyay_weights",
+    "YUYAY_AXES",
+    "YUYAY_FLOORS",
+    "layers",
+    "DOCTRINE_FOOTER",
+    "PROVENANCE",
+    "__version__",
+]
+
+__version__ = "0.2.0"
+DOCTRINE_FOOTER = (
+    "SZL Holdings · Λ = Conjecture 1 (ADVISORY, weighted geometric mean) · "
+    "uniqueness OPEN · NOT proven trust · honesty over checklist"
+)
+PROVENANCE = {
+    "lean_repo": "szl-holdings/lutar-lean",
+    "lean_declarations": 749,
+    "lean_axioms": 14,
+    "lean_tracked_sorries": 163,
+    "doi_lutar_lean": "10.5281/zenodo.20434308",
+    "lambda_status": "Conjecture 1 (open) — uniqueness unproven; advisory only",
+}
+
+
+def lambda_aggregate(
+    axes: torch.Tensor,
+    weights: Optional[torch.Tensor] = None,
+) -> torch.Tensor:
+    """Λ(x) = ∏ xᵢ^{wᵢ}, the weighted geometric mean over the last dim of axes.
+
+    See ``szl_lambda_gate._lambda.lambda_aggregate``. Axis scores in [0,1],
+    uniform weights when ``weights`` is None. Differentiable, batched, and
+    torch.compile-friendly. ADVISORY — NOT proven trust.
+    """
+    return _lambda_aggregate(axes, weights=weights)
+
+
+def lambda_gate(
+    axes: torch.Tensor,
+    weights: Optional[torch.Tensor] = None,
+    threshold: float = 0.5,
+) -> LambdaGateResult:
+    """ADVISORY Λ governance gate: returns LambdaGateResult(score, passed,
+    threshold, advisory). ``passed`` = Λ(axes) >= threshold. A pass is an
+    advisory, non-compensatory signal — NOT proven trust (Λ = Conjecture 1).
+    """
+    return _lambda_gate(axes, weights=weights, threshold=threshold)
+
+
+def lambda_gate_batch(
+    candidates: torch.Tensor,
+    weights: Optional[torch.Tensor] = None,
+    threshold: float = 0.5,
+) -> LambdaGateResult:
+    """ADVISORY batch gate over many candidate action-vectors (shape (..., N, k)).
+
+    The realistic per-inference-step call: score all N candidates at once and
+    return the advisory pass mask. Returns LambdaGateResult(score, passed,
+    threshold, advisory) with score/passed of shape (..., N). NOT proven trust.
+    """
+    return _lambda_gate_batch(candidates, weights=weights, threshold=threshold)
+
+
+def yuyay_weights(dtype: torch.dtype = torch.float64, device=None) -> torch.Tensor:
+    """Canonical 13-axis Yuyay Λ weight vector (uniform 1/13), ADVISORY only.
+
+    Use as ``weights`` over the 13 ``YUYAY_AXES``. The yuyay_v3 gate is a
+    conjunctive AND with per-axis floors (``YUYAY_FLOORS``); this Λ roll-up is
+    the weighted geometric mean and is ADVISORY — NOT proven trust.
+    """
+    return _yuyay_weights(dtype=dtype, device=device)
+
+
+def find_axiom_violation(k=5, trials=200, weights=None, seed=0, tol=1e-6):
+    """Random-search for any A1–A4 violation; returns (axiom, axes, weights) or
+    None. An honest falsification attempt — finding nothing is evidence, not a
+    proof (Λ-uniqueness is Conjecture 1, open).
+    """
+    return _find_axiom_violation(k=k, trials=trials, weights=weights, seed=seed, tol=tol)
+
+
+def selfcheck(k=5, trials=64, seed=0) -> dict:
+    """Expose the A1–A4 empirical self-checks + version as a single verdict dict.
+
+    Callable as get_kernel(...).selfcheck(). EMPIRICAL checks on sampled inputs,
+    NOT a proof of Λ-uniqueness (Conjecture 1, open). Advisory only.
+    """
+    return _selfcheck(k=k, trials=trials, seed=seed)
+
+
+# ---- axiom runtime self-checks (real, verifiable; NOT a uniqueness proof) -- #
+def is_monotone(axes, weights=None, delta=0.05, tol=1e-7) -> bool:
+    """A1 IsMonotone self-check: Λ is non-decreasing in each axis (on this data)."""
+    return _is_monotone(axes, weights=weights, delta=delta, tol=tol)
+
+
+def is_egyptian_exact(c, k=3, weights=None, tol=1e-5) -> bool:
+    """A3 IsEgyptianExact self-check: Λ(c, …, c) = c."""
+    return _is_egyptian_exact(c, k=k, weights=weights, tol=tol)
+
+
+def is_bounded_by_max(axes, weights=None, tol=1e-6) -> bool:
+    """A4 IsBounded self-check: Λ(x) ≤ maxᵢ xᵢ."""
+    return _is_bounded_by_max(axes, weights=weights, tol=tol)
+
+
+def is_homogeneous(axes, t, weights=None, tol=1e-5) -> bool:
+    """A2 IsHomogeneous(degree 1) self-check: Λ(t·x) = t·Λ(x)."""
+    return _is_homogeneous(axes, t, weights=weights, tol=tol)