Add enterprise-grade documentation, packaging, CI, and runnable examples

.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements_lgt.txt
+          pip install pytest pytest-cov
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short --cov=. --cov-report=term-missing
+
+  examples:
+    name: Smoke-test examples
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements_lgt.txt
+
+      - name: Run basic_inference example
+        run: python examples/basic_inference.py
+
+      - name: Run victorcos_integration example
+        run: python examples/victorcos_integration.py
+
+      - name: Run language_model example
+        run: python examples/language_model.py
+
+      - name: Run edge_export example
+        run: python examples/edge_export.py
+
+      - name: Run tri_model_fusion example
+        run: python examples/tri_model_fusion.py

CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] – 2024-01-01
+
+### Added
+- `GravitationalAttentionHead` – single-head gravitational attention using Newton's law
+- `MultiHeadGravitationalAttention` – multi-head extension with independent per-head `G` parameters and `get_attention_diagnostics()`
+- `FractalPositionEmbedding` – multi-scale position encoding with power-law (fractal) frequency spectrum and learnable residuals
+- `CurvedPositionEmbedding` – learnable positional vectors on a curved manifold
+- `LightweightGravitationalBlock` – single transformer block: gravitational attention + lightweight FFN (2× expansion) + layer norms
+- `LightweightGravitationalTransformer` – full transformer stack with optional vocabulary embedding, tied weights, Mirror Layer callbacks, and attention snapshots
+- `Ledger` – append-only JSONL event log with in-memory buffering and file-persistence
+- `MirrorLayer` – real-time introspection hook with rolling stability scoring and correction callbacks
+- `@victoros_module` – class decorator for packaging LGT agents as VictorOS cognitive modules
+- `VictorOSBaseModule` – base class providing `Ledger`, `MirrorLayer`, `save_checkpoint`, and `load_checkpoint`
+- `LGTVictorOSModule` – concrete VictorOS module wrapping any `LightweightGravitationalTransformer`
+- `ContainmentProtocol` – per-step safety guard (gradient clipping, force dampening, Bekenstein entropy penalty, divergence detection, architecture proposals)
+- `MetaCurvatureScheduler` – meta-gradient curvature adaptation driven by validation loss
+- `TrainingLoop` – full training orchestrator integrating all physics-aware constraints
+- `CrossGravitationalFusion` – gravitational cross-attention for tri-model stream fusion
+- `TriModelTransformer` – world / self / environment three-stream cognitive architecture
+- `export_edge_model.py` – TorchScript export and dynamic INT8 / FP16 quantisation with four size presets (`edge_150k`, `meta_probe`, `fractal_res`, `victorcos`)
+- `benchmarks/benchmark_lgt.py` – comprehensive performance benchmarking suite
+- `tests/test_lgt.py` – 60+ pytest test cases covering all components
+- `pyproject.toml` – package metadata and build configuration
+- `LICENSE` – MIT licence
+- `CONTRIBUTING.md` – contributor guidelines
+- `CHANGELOG.md` – this file
+- `docs/` – enterprise documentation (installation guide, user guide, API reference, architecture deep-dive)
+- `examples/` – five runnable example scripts
+
+[Unreleased]: https://github.com/MASSIVEMAGNETICS/Lightweight-Gravitational-Transformer/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/MASSIVEMAGNETICS/Lightweight-Gravitational-Transformer/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to Lightweight Gravitational Transformer
+
+Thank you for considering contributing to LGT! This document outlines the development setup, coding standards, and pull-request process.
+
+---
+
+## Table of Contents
+
+- [Development Setup](#development-setup)
+- [Running Tests](#running-tests)
+- [Coding Standards](#coding-standards)
+- [Pull-Request Process](#pull-request-process)
+- [Reporting Bugs](#reporting-bugs)
+- [Feature Requests](#feature-requests)
+
+---
+
+## Development Setup
+
+```bash
+# Fork and clone your fork
+git clone https://github.com/<your-username>/Lightweight-Gravitational-Transformer.git
+cd Lightweight-Gravitational-Transformer
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate    # Linux / macOS
+# .venv\Scripts\activate     # Windows
+
+# Install in editable mode with dev extras
+pip install -e ".[dev]"
+```
+
+---
+
+## Running Tests
+
+```bash
+# Run the full test suite
+pytest tests/ -v
+
+# Run with coverage report
+pytest tests/ --cov=. --cov-report=term-missing
+
+# Run a single test class
+pytest tests/test_lgt.py::TestGravitationalAttentionHead -v
+
+# Run a single test method
+pytest tests/test_lgt.py::TestGravitationalAttentionHead::test_output_shape -v
+```
+
+All tests must pass before submitting a pull request. New features must include corresponding tests in `tests/test_lgt.py`.
+
+---
+
+## Coding Standards
+
+- **Python version**: Target Python 3.9+.
+- **Type hints**: All public functions and class `__init__` signatures must include type hints.
+- **Docstrings**: Use NumPy-style docstrings for all public classes and functions.
+- **Line length**: 100 characters maximum.
+- **Formatting**: Code should be consistently formatted; match the style of existing modules.
+- **Imports**: Standard library first, then third-party (`torch`, `numpy`), then local imports. One blank line between groups.
+- **Physics parameters**: Any new physics-inspired parameter (G, curvature, masses, etc.) must be documented with the physical intuition in its docstring.
+- **No silent failures**: Raise informative `ValueError` or `RuntimeError` with a descriptive message rather than silently returning incorrect results.
+
+---
+
+## Pull-Request Process
+
+1. **Create a branch** from `main`:
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+2. **Make your changes** with clear, focused commits.
+3. **Add or update tests** in `tests/test_lgt.py`.
+4. **Ensure all tests pass**: `pytest tests/ -v`
+5. **Update documentation**:
+   - Add your change to `CHANGELOG.md` under `[Unreleased]`.
+   - Update the relevant section(s) in `docs/` and/or `README.md`.
+6. **Open a pull request** against `main` with a clear title and description.
+
+### PR Title Format
+
+```
+<type>: <short description>
+
+Types: feat | fix | docs | refactor | test | chore
+```
+
+Examples:
+- `feat: add learnable event horizon per attention head`
+- `fix: prevent NaN in GravitationalAttentionHead when positions are zero`
+- `docs: add fractal position embedding tutorial to user guide`
+
+---
+
+## Reporting Bugs
+
+Please open a [GitHub Issue](https://github.com/MASSIVEMAGNETICS/Lightweight-Gravitational-Transformer/issues) and include:
+
+1. **Python and PyTorch versions** (`python --version`, `python -c "import torch; print(torch.__version__)"`)
+2. **Minimal reproducible example** — the smallest code snippet that triggers the bug.
+3. **Expected behaviour** vs **actual behaviour**.
+4. **Full traceback** (if applicable).
+
+---
+
+## Feature Requests
+
+Open a [GitHub Issue](https://github.com/MASSIVEMAGNETICS/Lightweight-Gravitational-Transformer/issues) labelled `enhancement` describing:
+
+1. **Motivation** — what problem does the feature solve?
+2. **Proposed API** — what would the interface look like?
+3. **Alternatives considered** — what other approaches did you evaluate?

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MASSIVEMAGNETICS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.