trioron 0.2.0__tar.gz

trioron-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcelinus R Hatorangan
+
+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.

trioron-0.2.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: trioron
+Version: 0.2.0
+Summary: Continual-learning architecture with archive-routed multi-branch absorption
+Author-email: Marcelinus R Hatorangan <marcelinusrocky@aol.com>
+License: MIT
+Project-URL: Repository, https://github.com/marcrockhat/trioron-project
+Keywords: continual-learning,neural-networks,modular-deep-learning,edge-ai,trioron
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch<3.0,>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: torchvision>=0.15
+Provides-Extra: bridge-text
+Requires-Dist: sentence-transformers>=2.2; extra == "bridge-text"
+Provides-Extra: bridge-image
+Requires-Dist: open-clip-torch>=2.20; extra == "bridge-image"
+Requires-Dist: Pillow>=10.0; extra == "bridge-image"
+Provides-Extra: bridge-audio
+Requires-Dist: openai-whisper>=20231117; extra == "bridge-audio"
+Provides-Extra: bridge-all
+Requires-Dist: sentence-transformers>=2.2; extra == "bridge-all"
+Requires-Dist: open-clip-torch>=2.20; extra == "bridge-all"
+Requires-Dist: Pillow>=10.0; extra == "bridge-all"
+Requires-Dist: openai-whisper>=20231117; extra == "bridge-all"
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.110; extra == "serve"
+Requires-Dist: uvicorn[standard]>=0.27; extra == "serve"
+Requires-Dist: pydantic>=2.0; extra == "serve"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Trioron — an epigenetic-inspired self-expanding architecture
+
+A continual-learning architecture built around the **trioron**: a node with three coupled state variables (weight, plasticity coefficient, utility) that grows, prunes, and consolidates under a per-curriculum byte budget. Designed for resource-conscious deployment on agentic-AI / IoT / embedded hardware.
+
+The full design is in `trioron_blueprint.md`. The paper draft is in `paper/`.
+
+- **Want a 5-min reproduction of the paper headline?** → [QUICKSTART.md](QUICKSTART.md)
+- **Want to build your own trioron network and deploy it as an agent?** → [MANUAL.md](MANUAL.md)
+- **Just the cross-modal bridge / encoders?** → [BRIDGE.md](BRIDGE.md)
+- **Want a visual walk-through of the mechanisms?** → [tour/](tour/) — a static
+  Canvas petri-dish demo, thirteen chapters with one knob each. Live at
+  <https://marcrockhat.github.io/trioron-project/tour/>.
+- **Want an example of what it can do?** → Check out <https://huggingface.co/spaces/Marcrockhat/trioron-demo>.
+
+## Headline
+
+On a 30-class class-incremental curriculum (chained-15: MNIST → Fashion-MNIST → EMNIST-letters), with growth + dreaming + manifold replay enabled:
+
+- **0.601 ± 0.008 full-softmax / 0.677 ± 0.007 domain-aware / 0.961 ± 0.001 task-aware** at 30 KB of replay storage (n = 10 seeds, paired).
+- σ-confident wins over PackNet, HAT, Online EWC, and LwF + EWC on full-softmax and domain-aware (+10σ to +28σ paired). Matches a K = 50 hippocampal exemplar buffer within 0.04 absolute full-softmax at 1/25th the storage.
+- BF16 + int8 dream-archive: **157 KB total deployment** (network + manifold buffer), Δ ≤ 0.0008 lossless.
+- Ship-wake-extend loop validated end-to-end at 23 tasks / 38 classes, **168 KB total**, original tasks preserved at task-aware ≥ 0.93.
+- Multi-branch absorption: zero-shot composition of independently-trained donors via a 4-byte L0 handshake (R · S factorization), lossless on task-aware out to N = 5 donors.
+
+Method and result details: `paper/paper.pdf` (built from `paper/paper.tex`).
+
+## Quick install (use as a library)
+
+Until the PyPI release lands, install straight from GitHub:
+
+```bash
+pip install git+https://github.com/marcrockhat/trioron-project.git
+```
+
+Build your first donor:
+
+```python
+from trioron.api import TaskData, TrioronConfig, build_donor
+
+tasks = [
+    TaskData(
+        name="cats_vs_dogs",
+        X_train=Xtr, y_train=ytr,   # (N, 784) float32, (N,) int64
+        X_test=Xte,  y_test=yte,
+        classes=[0, 1],
+    ),
+    TaskData(
+        name="birds_vs_fish",
+        X_train=..., y_train=...,
+        X_test=...,  y_test=...,
+        classes=[2, 3],
+    ),
+]
+
+donor = build_donor(
+    label="my_donor",
+    tasks=tasks,
+    seed=42,                            # shared L0 seed (paper §3.10)
+    config=TrioronConfig(cap_bytes=32_000),
+    out_path="my_donor.pt",
+)
+```
+
+Compose donors with `trioron.api.absorb` and deploy with `trioron.api.deploy_agent`; see [MANUAL.md](MANUAL.md) for the full surface and the docstring in `trioron/api.py` for the three supported flows.
+
+## Setup (WSL2)
+
+The section below is for *reproducing the paper*, not library use. If you only need the API, the quick install above is enough.
+
+```bash
+# Move into WSL filesystem (NOT /mnt/c — that's slow)
+cd ~/trioron-project
+
+# Use a venv
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install
+pip install -r requirements.txt
+```
+
+Torch CPU wheel is ~750 MB. First install is the slow part.
+
+## Run the unit tests
+
+```bash
+python3 test_node.py            # TrioronLayer
+python3 test_network.py         # TrioronNetwork
+python3 test_classification.py  # multi-class head
+python3 test_dreaming.py        # dream block (replay/compress/purge/archive)
+python3 test_frustration.py     # plateau-counter multiplier
+python3 test_pruner.py
+python3 test_triggers.py        # plateau / rank-saturation / grad-stability
+python3 test_incubator.py
+python3 test_ceilings.py        # cap_bytes pre-flight
+python3 test_packnet.py
+python3 test_hat.py
+```
+
+Expected: all PASS, 0 FAIL on each file.
+
+## Reproduce the headline results
+
+The n = 10 panels driving the paper's headline table run unattended via:
+
+```bash
+bash experiments/run_n10_paper.sh
+```
+
+This sequentially runs the manifold-replay panel, the five-family competitor sweep (PackNet / HAT / Online EWC / LwF + EWC / hippocampal K = 50), and the dream-archive panel. Individual panels can also be launched directly:
+
+```bash
+# chained-15 manifold-grown panel, n = 10
+python3 experiments/bench_manifold_replay_n10.py
+
+# Competitor sweep on chained-15 (n = 10)
+python3 experiments/bench_packnet_chained_15_n10.py
+python3 experiments/bench_hat_chained_15_n10.py
+python3 experiments/bench_online_ewc_chained_15_n10.py
+python3 experiments/bench_lwf_chained_15_n10.py
+
+# Dream-archive Phase 1 + Phase 2 (storage win, n = 3 pending rerun)
+python3 experiments/bench_archive_n3.py
+
+# Ship-wake-extend loop (chained-15 → +8 EMNIST K..R)
+python3 experiments/bench_chained_extend.py
+```
+
+CSVs and `*_run*.log` files land in `outputs/`. Run logs from every reported panel are committed; CSVs are gitignored.
+
+## Layout
+
+```
+trioron-project/
+├── README.md                    # this file
+├── trioron_blueprint.md         # full design doc
+├── trioron/                     # core modules
+│   ├── api.py                   # public build_donor / train / extend API
+│   ├── cli.py                   # command-line entry point
+│   ├── node.py                  # TrioronLayer (per-node λ, u, r)
+│   ├── network.py               # TrioronNetwork (multi-layer, EWC)
+│   ├── classification.py        # CE head + grow_class
+│   ├── triggers.py              # plateau / rank / grad-stability
+│   ├── pruner.py                # cellular pruning (cosine-nearest redistribute)
+│   ├── incubator.py             # growth probe
+│   ├── ceilings.py              # cap_bytes pre-flight
+│   ├── dreaming.py              # replay / compress / purge / archive
+│   ├── frustration.py           # plateau multiplier
+│   ├── curriculum.py            # chained-15 / chained-23 builders
+│   ├── multibranch.py           # multi-branch organism (zero-shot absorption)
+│   ├── composition/             # L0 handshake translator (R · S factorization)
+│   ├── senses/                  # sensory-organism / CIFAR-side experiments
+│   ├── bridge/                  # cross-modal encoders (see BRIDGE.md)
+│   ├── packnet.py               # PackNet competitor
+│   └── hat.py                   # HAT competitor
+├── experiments/                 # bench scripts (CSV + log outputs)
+├── outputs/                     # bench CSVs (gitignored) + run logs (committed)
+├── paper/
+│   ├── paper.tex                # integrated paper source (compiles with pdflatex)
+│   ├── paper.pdf                # built artifact
+│   └── refs.bib                 # bibliography
+├── tour/                        # static Canvas demo (13 scenes); GitHub Pages source
+├── hf_space_build/              # Hugging Face Space deployment build
+└── test_*.py                    # unit tests
+```
+
+## Status
+
+- [x] Step 1: TrioronLayer + tests
+- [x] Step 2: TrioronNetwork + 2-task continual-learning verification
+- [x] Step 3: Scripted incubation environment
+- [x] Step 4: Three-condition growth trigger (plateau / rank / grad-stability)
+- [x] Step 5: Cellular division routine
+- [x] Step 6: Pruning loop
+- [x] Step 7: Hard ceilings (cap_bytes pre-flight)
+- [x] Step 8: Benchmark vs same-param fixed MLP (falsification gate cleared)
+- [x] Phase 4.5: Dreaming phase (replay / compress / purge / archive)
+- [x] Manifold replay (storage-free pseudo-rehearsal)
+- [x] Dream archive (Phase 1 row-lock + Phase 2 int8 quant)
+- [x] BF16 mixed-precision deployment substrate
+- [x] Ship-wake-extend loop (chained-15 → chained-23)
+- [x] Five-family competitor sweep (PackNet / HAT / Online EWC / LwF / hippo) at n = 10
+- [x] Multi-branch absorption + L0 handshake translator (R · S factorization)
+- [x] Tour: 13-scene Canvas demo at <https://marcrockhat.github.io/trioron-project/tour/>
+- [x] Full integrated paper draft (`paper/paper.tex`, 29 pages)
+- [ ] ArXiv submission (pending endorsement)
+- [ ] PyPI release (currently install via `pip install git+https://github.com/marcrockhat/trioron-project.git`)
+- [ ] Deployment script + ready-to-use checkpoint for Orange Pi 5B
+
+## Disclosure
+
+This work was carried out in collaboration with two personified AI assistants
+in defined supporting roles: **Gemma** (Gemini Pro 3.1, academic-advisory) and
+**Chloe** (Claude Opus 4.7 1M-context, engineering). Human-led problem framing
+and final decision-making; AI-supported implementation, analysis, and writing.
+The human author holds sole responsibility for all claims, methodological
+choices, and interpretations. Per recent editorial guidance
+([Nature 2023](https://www.nature.com/articles/d41586-023-00191-1),
+[WAME 2023](https://wame.org/page3.php?id=106)), AI systems are not listed
+as authors of record.
+
+## License
+
+[MIT](LICENSE). Copyright © 2026 Marcelinus R Hatorangan.

trioron-0.2.0/README.md

@@ -0,0 +1,204 @@
+# Trioron — an epigenetic-inspired self-expanding architecture
+
+A continual-learning architecture built around the **trioron**: a node with three coupled state variables (weight, plasticity coefficient, utility) that grows, prunes, and consolidates under a per-curriculum byte budget. Designed for resource-conscious deployment on agentic-AI / IoT / embedded hardware.
+
+The full design is in `trioron_blueprint.md`. The paper draft is in `paper/`.
+
+- **Want a 5-min reproduction of the paper headline?** → [QUICKSTART.md](QUICKSTART.md)
+- **Want to build your own trioron network and deploy it as an agent?** → [MANUAL.md](MANUAL.md)
+- **Just the cross-modal bridge / encoders?** → [BRIDGE.md](BRIDGE.md)
+- **Want a visual walk-through of the mechanisms?** → [tour/](tour/) — a static
+  Canvas petri-dish demo, thirteen chapters with one knob each. Live at
+  <https://marcrockhat.github.io/trioron-project/tour/>.
+- **Want an example of what it can do?** → Check out <https://huggingface.co/spaces/Marcrockhat/trioron-demo>.
+
+## Headline
+
+On a 30-class class-incremental curriculum (chained-15: MNIST → Fashion-MNIST → EMNIST-letters), with growth + dreaming + manifold replay enabled:
+
+- **0.601 ± 0.008 full-softmax / 0.677 ± 0.007 domain-aware / 0.961 ± 0.001 task-aware** at 30 KB of replay storage (n = 10 seeds, paired).
+- σ-confident wins over PackNet, HAT, Online EWC, and LwF + EWC on full-softmax and domain-aware (+10σ to +28σ paired). Matches a K = 50 hippocampal exemplar buffer within 0.04 absolute full-softmax at 1/25th the storage.
+- BF16 + int8 dream-archive: **157 KB total deployment** (network + manifold buffer), Δ ≤ 0.0008 lossless.
+- Ship-wake-extend loop validated end-to-end at 23 tasks / 38 classes, **168 KB total**, original tasks preserved at task-aware ≥ 0.93.
+- Multi-branch absorption: zero-shot composition of independently-trained donors via a 4-byte L0 handshake (R · S factorization), lossless on task-aware out to N = 5 donors.
+
+Method and result details: `paper/paper.pdf` (built from `paper/paper.tex`).
+
+## Quick install (use as a library)
+
+Until the PyPI release lands, install straight from GitHub:
+
+```bash
+pip install git+https://github.com/marcrockhat/trioron-project.git
+```
+
+Build your first donor:
+
+```python
+from trioron.api import TaskData, TrioronConfig, build_donor
+
+tasks = [
+    TaskData(
+        name="cats_vs_dogs",
+        X_train=Xtr, y_train=ytr,   # (N, 784) float32, (N,) int64
+        X_test=Xte,  y_test=yte,
+        classes=[0, 1],
+    ),
+    TaskData(
+        name="birds_vs_fish",
+        X_train=..., y_train=...,
+        X_test=...,  y_test=...,
+        classes=[2, 3],
+    ),
+]
+
+donor = build_donor(
+    label="my_donor",
+    tasks=tasks,
+    seed=42,                            # shared L0 seed (paper §3.10)
+    config=TrioronConfig(cap_bytes=32_000),
+    out_path="my_donor.pt",
+)
+```
+
+Compose donors with `trioron.api.absorb` and deploy with `trioron.api.deploy_agent`; see [MANUAL.md](MANUAL.md) for the full surface and the docstring in `trioron/api.py` for the three supported flows.
+
+## Setup (WSL2)
+
+The section below is for *reproducing the paper*, not library use. If you only need the API, the quick install above is enough.
+
+```bash
+# Move into WSL filesystem (NOT /mnt/c — that's slow)
+cd ~/trioron-project
+
+# Use a venv
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install
+pip install -r requirements.txt
+```
+
+Torch CPU wheel is ~750 MB. First install is the slow part.
+
+## Run the unit tests
+
+```bash
+python3 test_node.py            # TrioronLayer
+python3 test_network.py         # TrioronNetwork
+python3 test_classification.py  # multi-class head
+python3 test_dreaming.py        # dream block (replay/compress/purge/archive)
+python3 test_frustration.py     # plateau-counter multiplier
+python3 test_pruner.py
+python3 test_triggers.py        # plateau / rank-saturation / grad-stability
+python3 test_incubator.py
+python3 test_ceilings.py        # cap_bytes pre-flight
+python3 test_packnet.py
+python3 test_hat.py
+```
+
+Expected: all PASS, 0 FAIL on each file.
+
+## Reproduce the headline results
+
+The n = 10 panels driving the paper's headline table run unattended via:
+
+```bash
+bash experiments/run_n10_paper.sh
+```
+
+This sequentially runs the manifold-replay panel, the five-family competitor sweep (PackNet / HAT / Online EWC / LwF + EWC / hippocampal K = 50), and the dream-archive panel. Individual panels can also be launched directly:
+
+```bash
+# chained-15 manifold-grown panel, n = 10
+python3 experiments/bench_manifold_replay_n10.py
+
+# Competitor sweep on chained-15 (n = 10)
+python3 experiments/bench_packnet_chained_15_n10.py
+python3 experiments/bench_hat_chained_15_n10.py
+python3 experiments/bench_online_ewc_chained_15_n10.py
+python3 experiments/bench_lwf_chained_15_n10.py
+
+# Dream-archive Phase 1 + Phase 2 (storage win, n = 3 pending rerun)
+python3 experiments/bench_archive_n3.py
+
+# Ship-wake-extend loop (chained-15 → +8 EMNIST K..R)
+python3 experiments/bench_chained_extend.py
+```
+
+CSVs and `*_run*.log` files land in `outputs/`. Run logs from every reported panel are committed; CSVs are gitignored.
+
+## Layout
+
+```
+trioron-project/
+├── README.md                    # this file
+├── trioron_blueprint.md         # full design doc
+├── trioron/                     # core modules
+│   ├── api.py                   # public build_donor / train / extend API
+│   ├── cli.py                   # command-line entry point
+│   ├── node.py                  # TrioronLayer (per-node λ, u, r)
+│   ├── network.py               # TrioronNetwork (multi-layer, EWC)
+│   ├── classification.py        # CE head + grow_class
+│   ├── triggers.py              # plateau / rank / grad-stability
+│   ├── pruner.py                # cellular pruning (cosine-nearest redistribute)
+│   ├── incubator.py             # growth probe
+│   ├── ceilings.py              # cap_bytes pre-flight
+│   ├── dreaming.py              # replay / compress / purge / archive
+│   ├── frustration.py           # plateau multiplier
+│   ├── curriculum.py            # chained-15 / chained-23 builders
+│   ├── multibranch.py           # multi-branch organism (zero-shot absorption)
+│   ├── composition/             # L0 handshake translator (R · S factorization)
+│   ├── senses/                  # sensory-organism / CIFAR-side experiments
+│   ├── bridge/                  # cross-modal encoders (see BRIDGE.md)
+│   ├── packnet.py               # PackNet competitor
+│   └── hat.py                   # HAT competitor
+├── experiments/                 # bench scripts (CSV + log outputs)
+├── outputs/                     # bench CSVs (gitignored) + run logs (committed)
+├── paper/
+│   ├── paper.tex                # integrated paper source (compiles with pdflatex)
+│   ├── paper.pdf                # built artifact
+│   └── refs.bib                 # bibliography
+├── tour/                        # static Canvas demo (13 scenes); GitHub Pages source
+├── hf_space_build/              # Hugging Face Space deployment build
+└── test_*.py                    # unit tests
+```
+
+## Status
+
+- [x] Step 1: TrioronLayer + tests
+- [x] Step 2: TrioronNetwork + 2-task continual-learning verification
+- [x] Step 3: Scripted incubation environment
+- [x] Step 4: Three-condition growth trigger (plateau / rank / grad-stability)
+- [x] Step 5: Cellular division routine
+- [x] Step 6: Pruning loop
+- [x] Step 7: Hard ceilings (cap_bytes pre-flight)
+- [x] Step 8: Benchmark vs same-param fixed MLP (falsification gate cleared)
+- [x] Phase 4.5: Dreaming phase (replay / compress / purge / archive)
+- [x] Manifold replay (storage-free pseudo-rehearsal)
+- [x] Dream archive (Phase 1 row-lock + Phase 2 int8 quant)
+- [x] BF16 mixed-precision deployment substrate
+- [x] Ship-wake-extend loop (chained-15 → chained-23)
+- [x] Five-family competitor sweep (PackNet / HAT / Online EWC / LwF / hippo) at n = 10
+- [x] Multi-branch absorption + L0 handshake translator (R · S factorization)
+- [x] Tour: 13-scene Canvas demo at <https://marcrockhat.github.io/trioron-project/tour/>
+- [x] Full integrated paper draft (`paper/paper.tex`, 29 pages)
+- [ ] ArXiv submission (pending endorsement)
+- [ ] PyPI release (currently install via `pip install git+https://github.com/marcrockhat/trioron-project.git`)
+- [ ] Deployment script + ready-to-use checkpoint for Orange Pi 5B
+
+## Disclosure
+
+This work was carried out in collaboration with two personified AI assistants
+in defined supporting roles: **Gemma** (Gemini Pro 3.1, academic-advisory) and
+**Chloe** (Claude Opus 4.7 1M-context, engineering). Human-led problem framing
+and final decision-making; AI-supported implementation, analysis, and writing.
+The human author holds sole responsibility for all claims, methodological
+choices, and interpretations. Per recent editorial guidance
+([Nature 2023](https://www.nature.com/articles/d41586-023-00191-1),
+[WAME 2023](https://wame.org/page3.php?id=106)), AI systems are not listed
+as authors of record.
+
+## License
+
+[MIT](LICENSE). Copyright © 2026 Marcelinus R Hatorangan.