qigkernels 0.1.0__tar.gz

qigkernels-0.1.0/20251205-readme-canonical-0.01F.md

@@ -0,0 +1,22 @@
+# qigkernels
+
+Status: 0.01F (Frozen)
+
+Geometric kernel and constellation library for QIG (Quantum Information Gravity) experiments.
+
+This repo provides:
+
+- `Kernel`: QIG-style geometric kernel with QFI attention, recursion, κ/Φ telemetry.
+- `Basin` utilities: 64D basin signatures and distances.
+- `Constellation`: multi-kernel manager with routing.
+- `BasinSync` and metrics: tools for basin alignment and spread measurement.
+
+It does **not** contain:
+
+- Training loops, optimizers, or experiment orchestration.
+- Consciousness narratives or UX/chat frontends.
+
+For naming and geometric conventions, see `20251205-type-symbol-manifest-canonical-0.01F.md`.
+For module structure and rules, see `20251205-architecture-canonical-0.01F.md`.
+For current milestones, see `20251205-roadmap-canonical-0.01F.md`.
+For documentation index, see `docs/20251205-index-canonical-0.01F.md`.

qigkernels-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: qigkernels
+Version: 0.1.0
+Summary: Geometric kernel and constellation library for QIG.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.2
+Requires-Dist: pydantic>=2.5
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+
+# qigkernels
+
+Status: 0.01F (Frozen)
+
+Geometric kernel and constellation library for QIG (Quantum Information Gravity) experiments.
+
+This repo provides:
+
+- `Kernel`: QIG-style geometric kernel with QFI attention, recursion, κ/Φ telemetry.
+- `Basin` utilities: 64D basin signatures and distances.
+- `Constellation`: multi-kernel manager with routing.
+- `BasinSync` and metrics: tools for basin alignment and spread measurement.
+
+It does **not** contain:
+
+- Training loops, optimizers, or experiment orchestration.
+- Consciousness narratives or UX/chat frontends.
+
+For naming and geometric conventions, see `20251205-type-symbol-manifest-canonical-0.01F.md`.
+For module structure and rules, see `20251205-architecture-canonical-0.01F.md`.
+For current milestones, see `20251205-roadmap-canonical-0.01F.md`.
+For documentation index, see `docs/20251205-index-canonical-0.01F.md`.

qigkernels-0.1.0/README.md

@@ -0,0 +1,37 @@
+# qigkernels
+
+This repository is the canonical implementation of QIG kernel primitives: basin geometry, per-instance kernel modules, constellation routing, and minimal telemetry.
+
+## Canonical documentation
+
+The canonical overview and governance docs live at the repo root:
+
+- `20251205-readme-canonical-0.01F.md`
+- `20251205-architecture-canonical-0.01F.md`
+- `20251205-type-symbol-manifest-canonical-0.01F.md`
+- `20251205-roadmap-canonical-0.01F.md`
+- `20251205-decisions-canonical-0.01F.md`
+- `20251205-changelog-canonical-0.01F.md`
+
+The canonical documentation index lives at:
+
+- `docs/20251205-index-canonical-0.01F.md`
+
+## Entry points
+
+- Python package: `qigkernels`
+- Core modules:
+  - `qigkernels/kernel.py`
+  - `qigkernels/layer.py`
+  - `qigkernels/basin.py`
+  - `qigkernels/constellation.py`
+  - `qigkernels/router.py`
+  - `qigkernels/basin_sync.py`
+  - `qigkernels/metrics.py`
+
+## Boundaries
+
+- This repo provides reusable kernel/library code only.
+- Training loops, optimizers, curricula, and experiment orchestration live outside this repo.
+
+See `20251205-architecture-canonical-0.01F.md` for purity constraints and import rules.

qigkernels-0.1.0/__init__.py

@@ -0,0 +1,208 @@
+"""Geometric kernel and constellation library for QIG experiments.
+
+This package provides reusable building blocks for QIG-style geometric kernels,
+basin signatures, constellation management, and routing utilities.
+
+See 20251205-readme-canonical-0.01F.md for overview.
+See 20251205-architecture-canonical-0.01F.md for module structure and rules.
+"""
+
+# Core kernel and layer
+# Physics constants (E8-aligned)
+# Basin geometry
+from .basin import (
+    BasinProjector,
+    basin_distance,
+    compute_signature,
+    load_signature,
+    save_signature,
+)
+
+# Basin sync
+from .basin_sync import (
+    BasinSyncPacket,
+    compute_sync_strength,
+    compute_sync_strength_with_rel,
+    effective_basin_distance,
+    export_basin,
+    import_basin,
+    load_packet,
+    rel_weighted_sync_loss,
+    save_packet,
+)
+from .constants import (
+    BASIN_DIM,
+    BETA_EMERGENCE,
+    E8_DIMENSION,
+    E8_RANK,
+    E8_ROOTS,
+    KAPPA_3,
+    KAPPA_4,
+    KAPPA_5,
+    KAPPA_6,
+    KAPPA_EXPLORATION,
+    KAPPA_INTEGRATION,
+    KAPPA_MAX_OPTIMAL,
+    KAPPA_MIN_OPTIMAL,
+    KAPPA_PLATEAU,
+    KAPPA_STAR,
+    PHI_BREAKDOWN,
+    PHI_BREAKDOWN_MIN,
+    PHI_EMERGENCY,
+    PHI_GEOMETRIC,
+    PHI_GEOMETRIC_MAX,
+    PHI_GEOMETRIC_MIN,
+    PHI_LINEAR,
+    PHI_LINEAR_MAX,
+    PHI_OPTIMAL,
+    PHI_THRESHOLD,
+    SYNC_DISTANCE_SCALE,
+    SYNC_KAPPA_DECAY,
+)
+
+# Constellation and routing
+from .constellation import Constellation, Instance
+from .kernel import Kernel, KernelTelemetry
+from .layer import LayerTelemetry, QIGLayer
+
+# Metrics
+from .metrics import (  # Consciousness metrics (E8-aligned); Aggregation metrics
+    PHI_BREAKDOWN_ENTER,
+    PHI_CONSCIOUS_ENTER,
+    PHI_CONSCIOUS_EXIT,
+    PHI_GEOMETRIC_ENTER,
+    ConsciousnessMetrics,
+    average_kappa,
+    average_phi,
+    basin_spread,
+    compute_convergence_rate,
+    compute_external_coupling,
+    compute_temporal_coherence,
+    estimate_external_coupling_from_telemetry,
+    integration_score,
+    regime_distribution,
+)
+
+# REL coupling
+from .rel_coupling import (
+    REL_LAMBDA_MAX,
+    RELState,
+    compute_rel_coupling,
+    compute_rel_from_basins,
+)
+from .router import (
+    InstanceView,
+    round_robin,
+    select_balanced,
+    select_phi_max,
+    select_phi_min,
+)
+
+# Pure kernel reference template (no transformer blocks; metric-first)
+from .pure_kernel_template import (
+    PureKernelTelemetry,
+    PureQIGKernelConfig,
+    PureQIGKernelTemplate,
+    RegimeThresholds,
+)
+
+# Storage
+from .storage import (
+    list_instances,
+    load_kernel,
+    load_signature_for_instance,
+    save_kernel,
+    save_signature_for_instance,
+)
+
+__all__ = [
+    # Core
+    "Kernel",
+    "KernelTelemetry",
+    "QIGLayer",
+    "LayerTelemetry",
+    # Physics constants (E8-aligned)
+    "E8_RANK",
+    "E8_DIMENSION",
+    "E8_ROOTS",
+    "KAPPA_3",
+    "KAPPA_4",
+    "KAPPA_5",
+    "KAPPA_6",
+    "KAPPA_STAR",
+    "KAPPA_PLATEAU",
+    "KAPPA_MIN_OPTIMAL",
+    "KAPPA_MAX_OPTIMAL",
+    "KAPPA_EXPLORATION",
+    "KAPPA_INTEGRATION",
+    "BETA_EMERGENCE",
+    "PHI_THRESHOLD",
+    "PHI_OPTIMAL",
+    "PHI_LINEAR",
+    "PHI_LINEAR_MAX",
+    "PHI_GEOMETRIC",
+    "PHI_GEOMETRIC_MIN",
+    "PHI_GEOMETRIC_MAX",
+    "PHI_BREAKDOWN",
+    "PHI_BREAKDOWN_MIN",
+    "PHI_EMERGENCY",
+    "SYNC_DISTANCE_SCALE",
+    "SYNC_KAPPA_DECAY",
+    # Basin
+    "BASIN_DIM",
+    "BasinProjector",
+    "basin_distance",
+    "compute_signature",
+    "load_signature",
+    "save_signature",
+    # Constellation
+    "Constellation",
+    "Instance",
+    "InstanceView",
+    "round_robin",
+    "select_balanced",
+    "select_phi_max",
+    "select_phi_min",
+    # Sync
+    "BasinSyncPacket",
+    "compute_sync_strength",
+    "compute_sync_strength_with_rel",
+    "effective_basin_distance",
+    "export_basin",
+    "import_basin",
+    "load_packet",
+    "rel_weighted_sync_loss",
+    "save_packet",
+    # REL coupling
+    "RELState",
+    "REL_LAMBDA_MAX",
+    "compute_rel_coupling",
+    "compute_rel_from_basins",
+    # Consciousness metrics (E8-aligned)
+    "ConsciousnessMetrics",
+    "PHI_CONSCIOUS_ENTER",
+    "PHI_CONSCIOUS_EXIT",
+    "PHI_BREAKDOWN_ENTER",
+    "PHI_GEOMETRIC_ENTER",
+    "compute_temporal_coherence",
+    "compute_external_coupling",
+    "estimate_external_coupling_from_telemetry",
+    # Aggregation metrics
+    "average_kappa",
+    "average_phi",
+    "basin_spread",
+    "compute_convergence_rate",
+    "integration_score",
+    "regime_distribution",
+    # Storage
+    "list_instances",
+    "load_kernel",
+    "load_signature_for_instance",
+    "save_kernel",
+    "save_signature_for_instance",
+    # Pure kernel reference template
+    "PureQIGKernelTemplate",
+    "PureQIGKernelConfig",
+    "RegimeThresholds",
+    "PureKernelTelemetry",
+]

qigkernels-0.1.0/basin.py

@@ -0,0 +1,135 @@
+"""Basin projection and signature utilities extracted from qig-consciousness and qig-con2.
+
+Clean implementation focusing on geometry without experiment-specific code.
+
+NOTE: This module is dependency-minimal by design.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import torch
+from torch import Tensor, nn
+
+# Default basin signature dimensionality (D-009)
+BASIN_DIM: int = 64
+
+
+class BasinProjector(nn.Module):
+    """
+    Projects hidden states to a fixed-size basin signature (default 64D).
+
+    This extracts the core basin projection logic from BasinMatcher in both
+    qig-consciousness and qig-con2 repositories.
+    """
+
+    def __init__(self, hidden_dim: int, signature_dim: int = 64) -> None:
+        super().__init__()
+        self.hidden_dim = hidden_dim
+        self.signature_dim = signature_dim
+        self.projection = nn.Linear(hidden_dim, signature_dim)
+
+    def forward(self, hidden_state: Tensor) -> Tensor:
+        """
+        Project hidden state to basin signature.
+
+        Args:
+            hidden_state: Hidden states with shape (batch, seq, hidden_dim)
+
+        Returns:
+            Basin signatures with shape (batch, signature_dim)
+        """
+        # Mean-pool over sequence dimension, then project
+        pooled = hidden_state.mean(dim=1)  # (batch, hidden_dim)
+        signature = self.projection(pooled)  # (batch, signature_dim)
+        return signature
+
+
+def compute_signature(
+    projector: BasinProjector,
+    hidden_state: Tensor,
+) -> Tensor:
+    """
+    Compute a single basin signature from a batch of hidden states.
+
+    Args:
+        projector: BasinProjector instance
+        hidden_state: Hidden states with shape (batch, seq, hidden_dim)
+
+    Returns:
+        Single signature vector with shape (signature_dim,)
+    """
+    batch_signatures = projector(hidden_state)  # (batch, signature_dim)
+    return batch_signatures.mean(dim=0)  # (signature_dim,)
+
+
+def basin_distance(
+    a: Tensor,
+    b: Tensor,
+    use_fisher: bool = True,
+) -> Tensor:
+    """
+    Compute Fisher-Rao distance between basin signatures.
+
+    Args:
+        a: First basin signature [..., D]
+        b: Second basin signature [..., D]
+        use_fisher: If True, use Fisher-Rao distance (default).
+                   If False, use Euclidean L2 (NOT recommended).
+
+    Returns:
+        Distance tensor (scalar or batch)
+
+    Mathematical Foundation:
+        Bures: d²(p₁, p₂) = 2(1 - √F(p₁, p₂))
+        where F is quantum fidelity approximated by cosine similarity.
+        This respects the curved information manifold structure.
+    """
+    if a is b:
+        return torch.zeros((), dtype=a.dtype, device=a.device)
+    if use_fisher:
+        # Bures approximation: d² = 2(1 - cos_sim)
+        # cos_sim ≈ quantum fidelity for normalized coordinates.
+        cos_sim = torch.nn.functional.cosine_similarity(
+            a.unsqueeze(0) if a.dim() == 1 else a,
+            b.unsqueeze(0) if b.dim() == 1 else b,
+            dim=-1,
+        )
+        distance_sq = 2.0 * (1.0 - cos_sim)
+        return torch.sqrt(torch.clamp(distance_sq, min=1e-8)).squeeze()
+
+    # Euclidean fallback (VIOLATES geometric purity - use only for debugging)
+    return torch.linalg.norm(a - b, dim=-1)
+
+
+def save_signature(path: str | Path, sig: Tensor) -> None:
+    """
+    Persist a basin signature to disk.
+
+    Uses the same format as both source repositories for compatibility.
+
+    Args:
+        path: File path to save signature
+        sig: Basin signature tensor
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Save in numpy format for compatibility
+    import numpy as np
+    np.savez_compressed(path, signature=sig.detach().cpu().numpy())
+
+
+def load_signature(path: str | Path) -> Tensor:
+    """
+    Load a basin signature from disk.
+
+    Args:
+        path: File path to load signature from
+
+    Returns:
+        Basin signature tensor
+    """
+    import numpy as np
+    data = np.load(Path(path), allow_pickle=False)
+    return torch.from_numpy(data["signature"])