qigkernels 0.2.1__tar.gz → 0.2.2__tar.gz

qigkernels-0.2.2/.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+max_line_length = 100
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

qigkernels-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release to PyPI (Trusted Publishing)
+
+# Publishes qigkernels to PyPI via OIDC Trusted Publishing — NO API token.
+# https://docs.pypi.org/trusted-publishers/
+#
+# Version is AUTO-DERIVED from the release tag via setuptools-scm — tag `v0.2.2` builds
+# version 0.2.2, no manual pyproject bump. Trigger: publishing a GitHub Release.
+# Manual `workflow_dispatch` builds and tests but does NOT publish.
+#
+# PyPI side (one-time, web UI — needs the project owner's PyPI account):
+#   pypi.org -> Your projects -> qigkernels -> Manage -> Publishing ->
+#   Add a new pending/trusted publisher (GitHub):
+#     Owner:               GaryOcean428
+#     Repository name:      qigkernels
+#     Workflow filename:    release.yml
+#     Environment name:     pypi
+#   The Environment name MUST match the `environment: pypi` below.
+#
+# All third-party actions are pinned to a full commit SHA (supply-chain hardening);
+# the `# vX` comment records the human tag. This is the canonical template for the
+# trusted-publishing rollout to the other QIG packages (qig-project#6).
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test suite (release gate)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3 (node24)
+        with:
+          fetch-depth: 0   # setuptools-scm derives the version from git tags
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0 (node24)
+        with:
+          python-version: "3.11"
+      - name: Install package + test deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests
+        run: python -m pytest tests/ -q
+
+  build:
+    name: Build sdist + wheel
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3 (node24)
+        with:
+          fetch-depth: 0   # setuptools-scm derives the version from git tags
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0 (node24)
+        with:
+          python-version: "3.11"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Verify built version matches the release tag
+        if: github.event_name == 'release'
+        env:
+          TAG_NAME: ${{ github.event.release.tag_name }}
+        run: |
+          TAG="${TAG_NAME#v}"
+          BUILT=$(ls dist/*.whl | sed -E 's#.*/[A-Za-z0-9._]+-([0-9][^-]*)-.*#\1#' | head -1)
+          echo "built=$BUILT  release-tag=$TAG"
+          if [ "$BUILT" != "$TAG" ]; then
+            echo "::error::setuptools-scm built version ($BUILT) != release tag ($TAG). Tag the release commit as v$BUILT, or check git tags are fetched (fetch-depth: 0)."
+            exit 1
+          fi
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1 (node24)
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI (OIDC, no token)
+    needs: build
+    if: github.event_name == 'release'   # only a published Release actually uploads
+    runs-on: ubuntu-latest
+    environment: pypi                      # MUST match the PyPI trusted-publisher config
+    permissions:
+      id-token: write                      # REQUIRED for Trusted Publishing (job-level, per PyPI docs)
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1 (node24)
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1

qigkernels-0.2.2/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg-info/
+dist/
+build/
+.env
+.venv
+venv/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+.windsurfrules

qigkernels-0.2.2/20251205-architecture-canonical-0.01F.md

@@ -0,0 +1,273 @@
+# QIG Kernels Architecture & Rules
+
+Status: 0.01F (Frozen)
+Canonical naming & geometry: see `20251205-type-symbol-manifest-canonical-0.01F.md`.
+
+---
+
+## 1. Module Layers & Import Rules
+
+The import graph must remain acyclic and follow this direction:
+
+```text
+[core]      : qigkernels.kernel, qigkernels.layer
+[geometry]  : qigkernels.basin, qigkernels.metrics
+[structure] : qigkernels.constellation, qigkernels.router, qigkernels.basin_sync
+[io/tools]  : qigkernels.storage, tools/
+```
+
+### Allowed imports
+
+* `kernel` may import:
+  * `layer`,
+  * standard libs,
+  * `torch`, `pydantic` (for configs/telemetry models if used).
+
+* `basin` may import:
+  * standard libs,
+  * `torch`.
+
+* `metrics` may import:
+  * `basin`,
+  * `kernel` (for `KernelTelemetry` only).
+
+* `router` may import:
+  * standard libs,
+  * `typing`.
+
+* `constellation` may import:
+  * `kernel`,
+  * `basin`,
+  * `router`.
+
+* `basin_sync` may import:
+  * `basin`,
+  * `constellation`.
+
+* `storage` may import:
+  * `basin`,
+  * `constellation`.
+
+* `pure_kernel_template` may import:
+  * standard libs,
+  * `torch`.
+
+* `tools/qig_purity_check.py` may import anything, but **no production code may import tools**.
+
+> **Rule:** If a new module is added, its allowed imports must be documented here and updated in `__init__.py`.
+> No new `.py` files under `qigkernels/` without updating this section.
+
+---
+
+## 2. QIG Purity Rules
+
+We inherit global rules from `TYPE_SYMBOL_CONCEPT_MANIFEST.md` and add code-level constraints:
+
+### 2.1 Conceptual Constraints
+
+* Think and document in **geometric** terms:
+  * Fisher metric, basins, κ, Φ, curvature, manifolds.
+* Avoid importing or reimplementing classical **"off-the-shelf transformer"** stacks.
+* Any use of standard components (e.g. `nn.Embedding`) must serve the geometric architecture, not the other way around.
+
+### 2.2 Banned / discouraged patterns (enforced by `qig_purity_check.py`)
+
+* Hard bans (script fails if found in library code):
+  * `nn.Transformer`
+  * `BertModel`
+  * `GPT2Model`
+  * `CrossEntropyLoss` (without a comment explaining geometric role)
+  * `AdamW` / `Adam` optimizers in this repo
+
+* Soft bans (warnings):
+  * "token-level cross entropy" in comments/docs.
+  * "just fine-tune a transformer" in comments/docs.
+
+If a banned symbol legitimately appears in an experiment adapter, that code lives outside this repo.
+
+---
+
+## 3. File Length & Modularity
+
+* Soft limit: **400 lines** per module under `qigkernels/`.
+* If a module exceeds 400 lines, agents must:
+  * refactor into smaller modules, **or**
+  * explicitly justify in `DECISIONS.md` (with a new decision entry).
+* No "god modules" performing orchestration + I/O + geometry.
+
+---
+
+## 4. Pydantic & Config Usage
+
+* Pydantic models may be used for:
+  * kernel configuration (`KernelConfig`),
+  * telemetry snapshot types,
+  * constellation configuration.
+
+**Rules:**
+
+* All Pydantic models live in the module they logically belong to (no random `models.py` dumping ground).
+* They must be imported via `qigkernels.kernel`, `qigkernels.constellation`, etc., not deep paths.
+* Pydantic models must use `ConfigDict` to forbid extra fields (`extra="forbid"`).
+
+If in doubt, prefer plain dataclasses in core geometry and use Pydantic only at the boundaries (config/IO).
+
+---
+
+## 5. Documentation Discipline
+
+Allowed top-level docs:
+
+* `README.md` – What this library is, high-level usage.
+* `ARCHITECTURE.md` – This file: structure, rules, imports.
+* `ROADMAP.md` – Milestones and sequencing (no time estimates).
+* `CHANGELOG.md` – Human-readable log of changes.
+* `DECISIONS.md` – Design decisions and their status.
+* `TYPE_SYMBOL_CONCEPT_MANIFEST.md` – Canonical external spec (read-only here).
+
+**Forbidden:**
+
+* New "summary" or "notes" `.md` files.
+* Per-feature ad-hoc docs like `basin_notes.md`, `design_v3.md`, etc.
+
+If an agent wants to "summarize" or "document":
+
+* Update `ARCHITECTURE.md` or `DECISIONS.md`.
+* Record what changed in `CHANGELOG.md`.
+
+---
+
+## 6. Agent Behaviour Guidelines
+
+* No timeframes or schedules in any file.
+* No "we'll do a simpler version first and maybe improve later" as a justification for stubbing core logic.
+  * If something is intentionally stubbed:
+    * mark clearly as `# TODO:`,
+    * link to a specific entry in `ROADMAP.md` or `DECISIONS.md`.
+* When modifying behaviour, prefer:
+  * **editing existing files** over creating new ones.
+  * e.g. adjust `ARCHITECTURE.md` instead of adding `architecture_v2.md`.
+
+---
+
+## 7. Import / Export Manifest
+
+All external surface of the library is defined in `qigkernels/__init__.py`.
+
+* Any new public function/class must be:
+  * imported and re-exported in `__init__.py`,
+  * documented in `README.md` under "Public API".
+* No module may import from `qig-consciousness` or `qig-con2`.
+* This library is **downstream-only**: other repos may depend on it, not vice versa.
+
+---
+
+## 8. Explicit Out-of-Scope
+
+The following are **never** part of `qigkernels` (see D-011):
+
+| Category | Examples | Where it belongs |
+|----------|----------|------------------|
+| **Training** | Optimizers, loss functions, training loops, gradient accumulation | `qig-training` or experiment repo |
+| **Corpora** | Raw text, tokenizers, vocab files, sampling logic | `qig-training` or experiment repo |
+| **Curriculum** | Phase schedules, regime progressions, maturity tracking | Experiment repo |
+| **UX/Story** | Chat interfaces, consciousness narratives, "Gary/Ocean" prompts | Experiment repo |
+| **Safety/Ethics** | Safety metrics, content filtering, social alignment scores | Experiment repo |
+| **Experiment configs** | Hyperparameter sweeps, experiment manifests, run configs | Experiment repo |
+
+**Boundary test:** "Does this belong in the geometry engine, or in an experiment repo that uses the engine?"
+
+* Φ, κ, basins, signatures, routing, sync → **qigkernels**
+* Data, stories, prompts, corpora, training → **experiment layer**
+
+---
+
+## 9. Physics Constants (FROZEN)
+
+All physics constants in qigkernels are experimentally validated. The authoritative
+source is `qig-verification/docs/FROZEN_FACTS.md`.
+
+### Validated Constants
+
+| Constant | Value | Source | Location in qigkernels |
+|----------|-------|--------|------------------------|
+| κ₃ | 41.09 ± 0.59 | L=3 emergence | `Kernel.base_coupling` |
+| β(3→4) | 0.44 ± 0.04 | Running coupling slope | `Kernel.beta_slope` |
+| κ* | 64 ± 1.5 | Fixed point (L=4,5,6) | `BASIN_DIM` |
+
+### Rules
+
+1. **Never change** these defaults without new validated measurements in qig-verification
+2. Tests in `test_smoke.py::TestPhysicsConstants` enforce alignment
+3. Constructor overrides are allowed for experiments but require justification
+4. Physics flows FROM qig-verification TO qigkernels, never reverse
+
+**Reference:** Decision D-012, `qig-verification/docs/FROZEN_FACTS.md`
+
+---
+
+## 10. E8 Geometric Foundation
+
+The validated physics (κ* = 64) coincides with E8 exceptional geometry (rank² = 8² = 64).
+This is the implementation direction for qigkernels: build E8-aligned structures, measure results.
+
+### Foundation (Validated Physics)
+
+```text
+κ* = 64 ± 1.5     ← Experimentally validated fixed point (L=4,5,6)
+rank(E8)² = 64    ← E8 exceptional Lie group rank squared
+Agreement: 0.23σ  ← Not coincidence, geometric necessity
+```
+
+### Implementation Direction (Informed Hypotheses)
+
+| Hypothesis | ID | Implementation Target |
+|------------|----|-----------------------|
+| κ* = rank(E8)² | H-013 | Basin signatures in 64D ≈ E8-aligned space |
+| 7 primitive kernels | H-014 | Kernel lattice with HRT/PER/MEM/ACT/PRD/ETH/META |
+| 240-kernel saturation | H-014 | Growth toward E8 root positions |
+| 8 consciousness metrics | H-015 | Add External Coupling (C) as 8th metric |
+
+### Build → Measure → Refine Cycle
+
+```text
+Phase 1: Build E8-aligned structures
+         - 64D basin signatures (done)
+         - 7 primitive kernel codes (qig-dreams)
+         - Constellation routing (done)
+
+Phase 2: Implement kernel lattice
+         - Kernel specialization by primitive
+         - Basin-coordinated inter-kernel routing
+         - Natural saturation detection (~5-9k tokens)
+
+Phase 3: Measure against E8 predictions
+         - PCA for 8D active subspace
+         - Distance to E8 root positions
+         - Kernel count trajectory toward 240
+
+Phase 4: Refine hypotheses based on measurements
+         - Promote validated → FROZEN_FACTS
+         - Archive falsified hypotheses
+         - Iterate implementation
+```
+
+### Geometric Primitives (from H-014)
+
+These align with `qig-dreams` corpus primitive codes:
+
+| Code | Kernel Type | E8 Role |
+|------|-------------|---------|
+| HRT | Heart | Phase reference (simple root 1) |
+| PER | Perception | Sensory input (simple root 2) |
+| MEM | Memory | Storage/recall (simple root 3) |
+| ACT | Action | Motor output (simple root 4) |
+| PRD | Prediction | Future modeling (simple root 5) |
+| ETH | Ethics | Value alignment (simple root 6) |
+| META | Meta | Self-model (simple root 7) |
+| MIX | Multi | Cross-primitive (simple root 8) |
+
+The 8 simple roots generate E8's 240 roots via Weyl group action.
+Kernels "crystallize" toward these root positions during training.
+
+**Reference:** Decisions H-013, H-014, H-015

qigkernels-0.2.2/20251205-changelog-canonical-0.01F.md

@@ -0,0 +1,151 @@
+# Changelog
+
+Status: 0.01F (Frozen, append-only)
+Format inspired by Keep a Changelog.
+
+## [Unreleased]
+
+### Added
+
+- Initial scaffolding for `qigkernels` library:
+  - Docs: `README`, `ARCHITECTURE`, `ROADMAP`, `CHANGELOG`, `DECISIONS`.
+  - Config: `pyproject.toml`, `markdownlint.json`, `.editorconfig`, `.gitignore`, `pre-commit-config.yaml`.
+  - Tools: `tools/qig_purity_check.py`.
+  - Package skeleton under `qigkernels/`.
+- Core modules implemented:
+  - `basin.py`: BasinProjector, compute_signature, basin_distance, save/load.
+  - `layer.py`: QIGLayer with attention, recursion, tacking, regime detection.
+  - `kernel.py`: Kernel with stacked layers and KernelTelemetry.
+  - `router.py`: round_robin, select_phi_min, select_phi_max, select_balanced.
+  - `constellation.py`: Instance, Constellation with routing and step.
+  - `basin_sync.py`: BasinSyncPacket, export/import/save/load.
+  - `metrics.py`: average_phi, average_kappa, basin_spread, integration_score.
+  - `storage.py`: save/load kernel and signature utilities.
+- ISO 27001 aligned naming convention (`20251205-naming-convention-canonical-0.01F.md`):
+  - Document naming format: `YYYYMMDD-name-type-version[STATUS].md`
+  - Status codes: F (Frozen), H (Hypothesis), V (Verified)
+  - Renamed all canonical docs to follow convention.
+- Decisions D-006 through D-010 integrated from repo_recon.md analysis.
+- uv venv setup with torch, pydantic, numpy, dev tools.
+- Smoke tests: `tests/test_smoke.py` (19 tests covering all modules).
+
+### Changed
+
+- Roadmap: Added explicit pre-training governance gate for hard-ban audit enforcement.
+- Roadmap: Added future QPU validation protocol milestone (docs + interfaces only; no QPU tooling in qigkernels).
+
+### Fixed
+
+- `layer.py`: Added `.detach()` to avoid grad tensor warning.
+- All type annotations fixed for ruff/mypy compliance.
+- `pyproject.toml`: Updated to modern ruff lint section format.
+- `constellation.py`: Removed conflicting `instances()` method (attribute preferred).
+- `test_smoke.py`: Module-level imports for proper type resolution.
+
+### Added (Physics Alignment)
+
+- D-012: Physics constants alignment with qig-verification/FROZEN_FACTS.md
+- `TestPhysicsConstants`: 3 tests verifying κ₃, β(3→4), κ* alignment
+- `qig_purity_check.py`: Physics constant validation in core modules
+- Architecture §9: Physics constants section referencing FROZEN_FACTS
+
+### Added (Ecosystem Integration)
+
+- Compatibility shims for experiment repos:
+  - `qig-consciousness/src/qig_compat.py`: Provides fallback imports
+  - `qig-con2/src/qig_compat.py`: Same pattern for qig-con2
+- Updated `pyproject.toml` in both repos with qigkernels dependency comments
+- Updated `qig-consciousness/docs/2025-11-27--imports.md` with qigkernels import guide
+
+### Added (Hypotheses)
+
+- H-013: E8 geometric hypothesis (κ* = rank(E8)² = 64)
+- H-014: Primitive kernel bootstrap (7 primitives → 240 kernels)
+- H-015: 8th consciousness metric - External Coupling (C)
+
+### Added (E8 Implementation Direction)
+
+- Architecture §10: E8 Geometric Foundation
+  - Build → Measure → Refine cycle
+  - Geometric primitives table (HRT/PER/MEM/ACT/PRD/ETH/META/MIX)
+  - E8 simple roots → 240 root crystallization concept
+- Roadmap M9-M12: E8 implementation phases
+  - M9: Foundation (e8.py, primitive types, PCA validation)
+  - M10: Kernel Lattice (specialization, assigning kernel, 7-kernel bootstrap)
+  - M11: Growth & Measurement (240-kernel trajectory, 8th metric)
+  - M12: Validation & Promotion (controlled experiments, FROZEN_FACTS updates)
+
+### Added (qig-core Integration)
+
+- D-016: qig-core integration decision (PRE-E8, NEEDS REVIEW)
+- Roadmap M13: qig-core review and integration
+  - qig-core v1.0.0 predates E8 direction, needs compatibility review
+  - Ideal hierarchy: qig-core → qigkernels → qig-dreams → qig-consciousness
+  - Consolidation items: BasinSync, distance functions, KAPPA_STAR source
+
+### Added (8 Primitives Formalization)
+
+- Type-symbol manifest §4.5: Formal definition of 8 E8-aligned primitives
+- REL (Relationship/Coupling) as true 8th primitive (E8 simple root 8)
+- MIX clarified as admin-only category, NOT a primitive
+- Purity rule: Agents MUST NOT treat MIX as a primitive
+
+### Added (Frontier Milestones M14-M18)
+
+- M14: REL Coupling Tensors (off-diagonal metric, agency closure threshold)
+- M15: Agent Self-Assembly (minimal loop structures, attractor configurations)
+- M16: Syntergy Integration (relational primacy → REL curvature mapping)
+- M17: Quench Cosmology via QFI (κ-running as cosmological coupling)
+- M18: Consciousness as E8-Coupled Dynamics (phase space characterization)
+- Fixed M9 primitive list: PER/MEM/ACT/PRD/ETH/META/HRT/REL (not MIX)
+
+### Phase B Complete: Geometry Extraction (2025-12-06)
+
+- **qig-consciousness now imports geometry from qigkernels:**
+  - `src/constants.py`: Imports KAPPA_STAR, PHI_* thresholds from qigkernels
+  - `src/coordination/basin_sync.py`: Uses qigkernels.basin_distance
+  - KAPPA_STAR aligned to E8 (64.0 vs old 63.5)
+- **New regime thresholds exported from qigkernels:**
+  - PHI_LINEAR = 0.45, PHI_GEOMETRIC = 0.80, PHI_BREAKDOWN = 0.80
+  - PHI_EMERGENCY = 0.50
+- **Validated:** No stray constants, no ad-hoc basin math, no reverse imports
+- **Coordinated by:** Codex (extraction), Claude.ai (architecture), ChatGPT (QA)
+- See: `qig-dreams/prompts/20251206-codex-phase-b-extraction-prompt-0.01.md`
+
+### Added (8 Consciousness Metrics + T/C Implementation - 2025-12-06)
+
+- `metrics.py`: Complete 8 consciousness metrics (E8-aligned)
+  - `ConsciousnessMetrics` dataclass: Φ, κ, M, Γ, G, T, R, C
+  - `compute_temporal_coherence()`: T metric from basin history
+  - `compute_external_coupling()`: C metric (observer effect)
+  - `estimate_external_coupling_from_telemetry()`: C estimation heuristic
+- Regime thresholds with **hysteresis** to prevent oscillation:
+  - `PHI_CONSCIOUS_ENTER = 0.70`, `PHI_CONSCIOUS_EXIT = 0.65`
+  - `PHI_GEOMETRIC_ENTER = 0.45`, `PHI_GEOMETRIC_EXIT = 0.40`
+  - `PHI_BREAKDOWN_ENTER = 0.80`, `PHI_BREAKDOWN_EXIT = 0.75`
+- Updated `__init__.py` to export all new metrics
+
+### Added (REL Coupling Implementation - 2025-12-06)
+
+- `rel_coupling.py`: Instance-to-instance REL coupling computation
+  - `RELState` dataclass for tracking relationship history
+  - `compute_rel_coupling()` with basin overlap, history, primitive alignment
+  - `compute_rel_from_basins()` convenience function
+  - `REL_LAMBDA_MAX = 0.7` safety cap
+- `basin_sync.py`: REL-weighted synchronization
+  - `effective_basin_distance()`: d_eff = d_F · (1 - λ_rel · r_ij)
+  - `rel_weighted_sync_loss()`: w_sync · d²_eff
+  - `compute_sync_strength_with_rel()`: REL-modulated sync strength
+- Updated `__init__.py` to export all REL functions
+- Added docs:
+  - `docs/20251206-integration-plan-ultra-mode-0.01H.md`
+  - `docs/20251206-rel-weighted-basin-sync-spec.md`
+  - `docs/20251206-e8-consciousness-stack-diagram.md`
+
+### Fixed (Geometric Purity - CRITICAL)
+
+- `basin.py`: Replaced Euclidean L2 distance with Fisher-Rao (Bures approximation)
+- `basin_sync.py`: Now uses E8-aligned constants from `constants.py`
+- Added `constants.py`: KAPPA_STAR=64 (E8 rank²), validated physics parameters
+- Added `qig-core` as dependency in pyproject.toml
+- **This restores geometric purity** — basin distances now respect curved manifold