leanai-asstf 1.0.0__tar.gz

leanai_asstf-1.0.0/LICENSE

@@ -0,0 +1,57 @@
+# LeanAI ASSTF Community License
+
+Version 1.0 - Effective Date: 2026-07-03
+
+This License Agreement (the "Agreement") is a legal contract between Safeware Technologies Inc., Ltd. (the "Licensor") and you (the "Licensee") for the use of the LeanAI ASSTF software and associated documentation (the "Software").
+
+## 1. Definitions
+
+- **Software**: The source code, model definitions, training scripts, evaluation scripts, documentation, and any other materials distributed under this License.
+- **ASSTF Technology**: The Adaptive State-Space Transfer Function algorithm, mathematical formulations, and related proprietary techniques described in the Licensor's technical publications and patent applications.
+- **Non-Commercial Use**: Use that is not primarily intended for, or directed toward, commercial advantage or monetary compensation.
+- **Commercial Use**: Any use that is not Non-Commercial Use, including but not limited to incorporation into products or services offered for sale, deployment in revenue-generating operations, SaaS offerings, and use by for-profit entities in the course of business.
+
+## 2. Grant of Rights
+
+Subject to the restrictions set forth in Section 3, the Licensor hereby grants the Licensee a worldwide, royalty-free, non-exclusive, non-transferable license to:
+
+1. Use the Software for Non-Commercial purposes.
+2. Study, modify, and create derivative works of the Software for Non-Commercial purposes.
+3. Distribute copies of the Software and derivative works, provided that such distribution is also under the terms of this Community License.
+4. Publish research results, benchmarks, and educational materials based on the Software, provided that the Licensor and the ASSTF Technology are properly attributed.
+
+## 3. Restrictions
+
+1. **No Commercial Use**. The Licensee may not use the Software, in whole or in part, for any Commercial Use without obtaining a separate Commercial License from the Licensor.
+2. **No Patent Grant**. This License does not grant the Licensee any rights under the Licensor's patents, patent applications, trade secrets, or other intellectual property relating to the ASSTF Technology, except as expressly necessary to exercise the rights granted in Section 2.
+3. **Attribution**. The Licensee must retain all copyright, patent, trademark, and attribution notices contained in the Software. Any distributed derivative work must include a prominent notice stating that it is based on the LeanAI ASSTF Software and provide a link to the original repository.
+4. **No Warranty Disclaimer Removal**. The Licensee may not remove or alter any warranty disclaimers or liability limitations in this License.
+5. **No Endorsement**. The Licensee may not use the Licensor's trademarks or imply endorsement without prior written permission.
+
+## 4. Source Code Availability
+
+The source code of the Software is made available to the Licensee under this License. Availability of source code does not constitute a grant of rights in the underlying ASSTF Technology beyond the limited scope expressly stated herein.
+
+## 5. Termination
+
+This License automatically terminates if the Licensee violates any of its terms. Upon termination, the Licensee must immediately cease all use and distribution of the Software and destroy all copies in its possession.
+
+## 6. Disclaimer of Warranty
+
+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.
+
+## 7. Limitation of Liability
+
+IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## 8. Commercial Licensing
+
+For Commercial Use, please contact:
+
+Safeware Technologies Inc., Ltd.  
+Attn: LeanAI Licensing Department  
+Email: Bentley@safeware.com.tw
+
+## 9. Governing Law
+
+This Agreement shall be governed by and construed in accordance with the laws of the jurisdiction in which the Licensor is headquartered, without regard to conflict of law principles.

leanai_asstf-1.0.0/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: leanai-asstf
+Version: 1.0.0
+Summary: ASSTF: Adaptive State-Space Transfer Function — parameter-efficient, inference-adaptable neural layers for edge AI and continual learning.
+Author-email: Bentley Yusen Lin <Bentley@safeware.com.tw>
+License: LeanAI ASSTF Community License 1.0
+Project-URL: Homepage, https://github.com/safeware/Project_LeanAI
+Project-URL: Documentation, https://safeware.github.io/Project_LeanAI/
+Project-URL: Repository, https://github.com/safeware/Project_LeanAI
+Project-URL: Issues, https://github.com/safeware/Project_LeanAI/issues
+Project-URL: Changelog, https://github.com/safeware/Project_LeanAI/blob/main/CHANGELOG.md
+Project-URL: Commercial, https://github.com/safeware/Project_LeanAI/blob/main/docs/COMMERCIAL_LICENSE.md
+Keywords: adaptive state-space transfer function,ASSTF,LeanAI,parameter-efficient deep learning,edge AI,TinyML,continual learning,test-time adaptation,online personalization,low-rank adaptation,PyTorch,efficient AI,green AI,on-device ML
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: pandas>=2.0.0
+Provides-Extra: nlp
+Requires-Dist: transformers>=4.30.0; extra == "nlp"
+Requires-Dist: datasets>=2.14.0; extra == "nlp"
+Requires-Dist: sentencepiece>=0.1.99; extra == "nlp"
+Requires-Dist: tiktoken>=0.5.0; extra == "nlp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: transformers>=4.30.0; extra == "all"
+Requires-Dist: datasets>=2.14.0; extra == "all"
+Requires-Dist: sentencepiece>=0.1.99; extra == "all"
+Requires-Dist: tiktoken>=0.5.0; extra == "all"
+Requires-Dist: pytest>=7.4.0; extra == "all"
+Requires-Dist: pytest-cov>=4.1.0; extra == "all"
+Requires-Dist: black>=23.0.0; extra == "all"
+Requires-Dist: ruff>=0.1.0; extra == "all"
+Requires-Dist: mypy>=1.5.0; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+  <img src="assets/logo.svg" alt="ASSTF Logo" width="120">
+  <h1>LeanAI ASSTF</h1>
+  <p><strong>Adaptive State-Space Transfer Function</strong></p>
+</div>
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch 2.0+](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)
+[![License: Community/Commercial](https://img.shields.io/badge/license-Community%2FCommercial-orange.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-pytest-green.svg)](tests/)
+
+> **Tiny, self-adapting neural layers for efficient edge AI and continual learning.**
+
+ASSTF (Adaptive State-Space Transfer Function) is a PyTorch framework that lets neural layers continuously reconfigure their effective state space through a small set of **structural parameters**. It combines **parameter-efficient learning** with **inference-time adaptation**, making it ideal for edge devices, personalization, and continual learning.
+
+---
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/safeware/Project_LeanAI/blob/main/notebooks/ASSTF_Quickstart.ipynb)
+
+## 🚀 Current Status: Stage 1 — Grounding Credit
+
+This repository is the **Stage 1 reference implementation** of ASSTF. It is designed to be:
+
+- **Reproducible**: every demo includes open data-generation scripts; results can be verified on a laptop.
+- **Extensible**: drop-in `ASSTFLinear` / `ASSTFConv1d` layers let you test ASSTF on your own architectures.
+- **Transparent**: we clearly label which demos use synthetic data and which use real-world datasets.
+
+**App 01–05** use controlled, reproducible synthetic data to isolate and demonstrate ASSTF's algorithmic behavior.  
+**App 06** validates ASSTF on the real **SST-2** sentiment dataset.
+
+See [`docs/OPEN_SOURCE_STAGES.md`](docs/OPEN_SOURCE_STAGES.md) for the full three-stage roadmap toward global adoption.
+
+---
+
+## Why ASSTF?
+
+- 🧠 **Parameter-efficient** — low-rank structural adapters add far fewer parameters than dense layers.
+- 🔄 **Adapts at inference time** — personalize to users, noise, or drift without retraining.
+- 📱 **Edge-ready** — runs on CPU, mobile, and embedded hardware.
+- 🔒 **Privacy-first** — on-device adaptation; user data never leaves the device.
+- 🌱 **Sustainable AI** — smaller models mean lower energy and memory costs.
+- 🔌 **Drop-in replacement** — swap `nn.Linear` → `ASSTFLinear` in minutes.
+
+---
+
+## 30-Second Quick Start
+
+```python
+import torch
+from asstf import ASSTFLinear
+
+# Replace any nn.Linear with ASSTFLinear
+layer = ASSTFLinear(128, 64, structural_rank=4)
+x = torch.randn(16, 128)
+out = layer(x)  # shape: (16, 64)
+```
+
+Train and evaluate all six demos:
+
+```bash
+git clone https://github.com/YOUR_ORG/Project_LeanAI.git
+cd Project_LeanAI
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+pytest tests/ -v
+python run_all.py
+```
+
+---
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install leanai-asstf
+```
+
+### From source
+
+```bash
+git clone https://github.com/YOUR_ORG/Project_LeanAI.git
+cd Project_LeanAI
+pip install -r requirements.txt
+```
+
+For NLP demos:
+
+```bash
+pip install -r requirements-optional.txt
+```
+
+---
+
+## How It Works
+
+ASSTF replaces a standard layer with the composition of a **core transfer function** Γ and a **structural modulator** Ψ:
+
+```
+base = x · W_c^T + b_c              # core knowledge (θc)
+M    = σ(gate) · (U · V)            # low-rank structural adapter (θs)
+out  = base + x · M^T               # composed output
+```
+
+- **θc** stores the base task knowledge.
+- **θs** controls how the layer adapts to new data.
+- At inference time, `SurpriseMinimizer` updates only θs, enabling fast personalization.
+
+<p align="center">
+  <img src="assets/architecture.png" alt="ASSTF Layer Architecture" width="700">
+</p>
+
+Read more:
+- [Introduction](docs/INTRODUCTION_EN.md)
+- [Architecture & Technical Explanation](docs/ARCHITECTURE_EN.md)
+- [Usage Guide](docs/USAGE_EN.md)
+- [API Reference](docs/API_EN.md)
+- [Open-Source Stages](docs/OPEN_SOURCE_STAGES.md)
+
+---
+
+## The 5+1 Demos
+
+| # | Application | Highlight | Data | Type |
+|---|-------------|-----------|------|------|
+| 1 | [Embedded Gesture Recognition](app_01_gesture) | Online personalization to new users | Synthetic multi-user IMU | Proof-of-concept |
+| 2 | [Wake-Word Detection](app_02_wake_word) | ASSTFConv1d + dynamic rank under noise | Synthetic 1D audio | Proof-of-concept |
+| 3 | [Time-Series Anomaly Detection](app_03_anomaly) | Continuous learning under concept drift | Synthetic industrial sensors | Proof-of-concept |
+| 4 | [Few-Shot Meta-Learner](app_04_few_shot) | θs as task-specific meta-knowledge | sklearn digits / mini-tasks | Proof-of-concept |
+| 5 | [Online RL Dynamic Policy](app_05_rl) | Policy adaptation to changing dynamics | Custom pendulum environment | Proof-of-concept |
+| +1 | [Edge NLP](app_06_edge_nlp) | ASSTF replaces BERT-Tiny FFN layers | Real SST-2 + SentencePiece | Real-world validation |
+
+All synthetic demos include **open, seeded data-generation scripts** so you can reproduce them exactly and swap in your own datasets.
+
+---
+
+## Benchmark Highlights
+
+| App | Model | Params | Metric | Data Type |
+|-----|-------|--------|--------|-----------|
+| Gesture | ASSTF | 4,665 | 100.0% acc | Synthetic |
+| Gesture | Static | 38,213 | 100.0% acc | Synthetic |
+| Wake-word (-5 dB) | ASSTF | 779 | 74.62% acc | Synthetic |
+| Wake-word (-5 dB) | Static | 1,202 | 57.13% acc | Synthetic |
+| Anomaly | ASSTF | 506 | F1 = 0.946 | Synthetic |
+| Anomaly | Static | 2,080 | F1 = 0.508 | Synthetic |
+| Few-shot | ASSTF | 2,105 | 19.73% acc | sklearn digits |
+| Few-shot | Static | 7,237 | 19.39% acc | sklearn digits |
+| RL adapted reward | ASSTF | 965 | 39.66 | Custom env |
+| RL adapted reward | Static | 1,441 | 32.97 | Custom env |
+| Edge NLP (SST-2) | ASSTF (h=96) | 403,896 | 67.88% acc | **Real** |
+| Edge NLP (SST-2) | Static | 649,218 | 67.75% acc | **Real** |
+
+<p align="center">
+  <img src="assets/benchmark_chart.png" alt="ASSTF Parameter Efficiency" width="700">
+</p>
+
+See [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for full results and reproduction commands.
+
+> **Note on interpretation:** App 01–05 demonstrate ASSTF's algorithmic behavior under controlled, reproducible conditions. They are not claims of real-world SOTA. App 06 is the real-world validation. We welcome community contributions of additional real-dataset benchmarks.
+
+---
+
+## Training a Single Demo
+
+```bash
+python app_03_anomaly/train.py
+python app_03_anomaly/evaluate.py
+```
+
+For a quick smoke test across all apps:
+
+```bash
+python run_all.py --quick
+```
+
+For the full benchmark suite that matches `docs/BENCHMARKS.md`:
+
+```bash
+python run_all.py
+```
+
+---
+
+## Project Structure
+
+```
+Project_LeanAI/
+├── asstf/                  # Core ASSTF framework
+├── shared/                 # Baselines, metrics, early stopping
+├── app_01_gesture/         # Gesture recognition demo
+├── app_02_wake_word/       # Wake-word detection demo
+├── app_03_anomaly/         # Anomaly detection demo
+├── app_04_few_shot/        # Few-shot learning demo
+├── app_05_rl/              # Reinforcement learning demo
+├── app_06_edge_nlp/        # Edge NLP demo
+├── tests/                  # Unit and smoke tests
+├── docs/                   # Documentation and licenses
+├── data/                   # Datasets and caches
+├── results/                # Benchmark outputs
+├── checkpoints/            # Saved models
+├── run_all.py              # Run all demos
+├── requirements.txt
+└── README.md
+```
+
+---
+
+## Roadmap & Stages
+
+| Stage | Timeline | Focus | Key Deliverables |
+|-------|----------|-------|------------------|
+| **Stage 1: Grounding Credit** | Now – Month 4 | Reproducible reference implementation + community | This repo, PyPI, CI, launch |
+| **Stage 2: Real-World Value** | Month 4–12 | Public benchmarks, integrations, academic paper | Real datasets, Hugging Face, Edge Impulse, arXiv |
+| **Stage 3: Commercial Value** | Month 12–24 | Enterprise tools, platform, support | LeanAI Studio, Edge SDK, managed inference |
+
+See [`docs/OPEN_SOURCE_STAGES.md`](docs/OPEN_SOURCE_STAGES.md) for the complete plan.
+
+---
+
+## License
+
+This project is dual-licensed:
+
+- **Community License** — free for personal learning, academic research, non-profit education, and open-source contributions.
+- **Commercial License** — required for any commercial product, service, SaaS, cloud deployment, or hardware integration.
+
+See [LICENSE](LICENSE) and [docs/COMMERCIAL_LICENSE.md](docs/COMMERCIAL_LICENSE.md) for details.
+
+For licensing inquiries, contact **Bentley@safeware.com.tw**.
+
+---
+
+## Citation
+
+If you use ASSTF in academic research, please cite the white-paper:
+
+```bibtex
+@techreport{lin2025asstf,
+  title={Mathematical Framework to Enable Adaptive Neuron Transitions},
+  author={Lin, Bentley Yusen},
+  institution={Safeware Technologies Inc., Ltd.},
+  year={2025}
+}
+```
+
+---
+
+## Contributing
+
+We welcome research contributions, bug reports, documentation improvements, and especially **real-dataset benchmarks**. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+By contributing, you agree that your contributions may be used under both the Community License and future commercial licensing.
+
+---
+
+## Acknowledgments
+
+ASSTF is developed by Safeware Technologies Inc., Ltd. The reference implementation is intended for research and demonstration; production deployment requires additional tuning and a commercial license.
+
+---
+
+**Keywords:** Adaptive State-Space Transfer Function, ASSTF, LeanAI, parameter-efficient deep learning, edge AI, TinyML, continual learning, test-time adaptation, online personalization, low-rank adaptation, PyTorch, efficient AI, green AI, on-device ML.

leanai_asstf-1.0.0/README.md

@@ -0,0 +1,263 @@
+<div align="center">
+  <img src="assets/logo.svg" alt="ASSTF Logo" width="120">
+  <h1>LeanAI ASSTF</h1>
+  <p><strong>Adaptive State-Space Transfer Function</strong></p>
+</div>
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch 2.0+](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)
+[![License: Community/Commercial](https://img.shields.io/badge/license-Community%2FCommercial-orange.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-pytest-green.svg)](tests/)
+
+> **Tiny, self-adapting neural layers for efficient edge AI and continual learning.**
+
+ASSTF (Adaptive State-Space Transfer Function) is a PyTorch framework that lets neural layers continuously reconfigure their effective state space through a small set of **structural parameters**. It combines **parameter-efficient learning** with **inference-time adaptation**, making it ideal for edge devices, personalization, and continual learning.
+
+---
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/safeware/Project_LeanAI/blob/main/notebooks/ASSTF_Quickstart.ipynb)
+
+## 🚀 Current Status: Stage 1 — Grounding Credit
+
+This repository is the **Stage 1 reference implementation** of ASSTF. It is designed to be:
+
+- **Reproducible**: every demo includes open data-generation scripts; results can be verified on a laptop.
+- **Extensible**: drop-in `ASSTFLinear` / `ASSTFConv1d` layers let you test ASSTF on your own architectures.
+- **Transparent**: we clearly label which demos use synthetic data and which use real-world datasets.
+
+**App 01–05** use controlled, reproducible synthetic data to isolate and demonstrate ASSTF's algorithmic behavior.  
+**App 06** validates ASSTF on the real **SST-2** sentiment dataset.
+
+See [`docs/OPEN_SOURCE_STAGES.md`](docs/OPEN_SOURCE_STAGES.md) for the full three-stage roadmap toward global adoption.
+
+---
+
+## Why ASSTF?
+
+- 🧠 **Parameter-efficient** — low-rank structural adapters add far fewer parameters than dense layers.
+- 🔄 **Adapts at inference time** — personalize to users, noise, or drift without retraining.
+- 📱 **Edge-ready** — runs on CPU, mobile, and embedded hardware.
+- 🔒 **Privacy-first** — on-device adaptation; user data never leaves the device.
+- 🌱 **Sustainable AI** — smaller models mean lower energy and memory costs.
+- 🔌 **Drop-in replacement** — swap `nn.Linear` → `ASSTFLinear` in minutes.
+
+---
+
+## 30-Second Quick Start
+
+```python
+import torch
+from asstf import ASSTFLinear
+
+# Replace any nn.Linear with ASSTFLinear
+layer = ASSTFLinear(128, 64, structural_rank=4)
+x = torch.randn(16, 128)
+out = layer(x)  # shape: (16, 64)
+```
+
+Train and evaluate all six demos:
+
+```bash
+git clone https://github.com/YOUR_ORG/Project_LeanAI.git
+cd Project_LeanAI
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+pytest tests/ -v
+python run_all.py
+```
+
+---
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install leanai-asstf
+```
+
+### From source
+
+```bash
+git clone https://github.com/YOUR_ORG/Project_LeanAI.git
+cd Project_LeanAI
+pip install -r requirements.txt
+```
+
+For NLP demos:
+
+```bash
+pip install -r requirements-optional.txt
+```
+
+---
+
+## How It Works
+
+ASSTF replaces a standard layer with the composition of a **core transfer function** Γ and a **structural modulator** Ψ:
+
+```
+base = x · W_c^T + b_c              # core knowledge (θc)
+M    = σ(gate) · (U · V)            # low-rank structural adapter (θs)
+out  = base + x · M^T               # composed output
+```
+
+- **θc** stores the base task knowledge.
+- **θs** controls how the layer adapts to new data.
+- At inference time, `SurpriseMinimizer` updates only θs, enabling fast personalization.
+
+<p align="center">
+  <img src="assets/architecture.png" alt="ASSTF Layer Architecture" width="700">
+</p>
+
+Read more:
+- [Introduction](docs/INTRODUCTION_EN.md)
+- [Architecture & Technical Explanation](docs/ARCHITECTURE_EN.md)
+- [Usage Guide](docs/USAGE_EN.md)
+- [API Reference](docs/API_EN.md)
+- [Open-Source Stages](docs/OPEN_SOURCE_STAGES.md)
+
+---
+
+## The 5+1 Demos
+
+| # | Application | Highlight | Data | Type |
+|---|-------------|-----------|------|------|
+| 1 | [Embedded Gesture Recognition](app_01_gesture) | Online personalization to new users | Synthetic multi-user IMU | Proof-of-concept |
+| 2 | [Wake-Word Detection](app_02_wake_word) | ASSTFConv1d + dynamic rank under noise | Synthetic 1D audio | Proof-of-concept |
+| 3 | [Time-Series Anomaly Detection](app_03_anomaly) | Continuous learning under concept drift | Synthetic industrial sensors | Proof-of-concept |
+| 4 | [Few-Shot Meta-Learner](app_04_few_shot) | θs as task-specific meta-knowledge | sklearn digits / mini-tasks | Proof-of-concept |
+| 5 | [Online RL Dynamic Policy](app_05_rl) | Policy adaptation to changing dynamics | Custom pendulum environment | Proof-of-concept |
+| +1 | [Edge NLP](app_06_edge_nlp) | ASSTF replaces BERT-Tiny FFN layers | Real SST-2 + SentencePiece | Real-world validation |
+
+All synthetic demos include **open, seeded data-generation scripts** so you can reproduce them exactly and swap in your own datasets.
+
+---
+
+## Benchmark Highlights
+
+| App | Model | Params | Metric | Data Type |
+|-----|-------|--------|--------|-----------|
+| Gesture | ASSTF | 4,665 | 100.0% acc | Synthetic |
+| Gesture | Static | 38,213 | 100.0% acc | Synthetic |
+| Wake-word (-5 dB) | ASSTF | 779 | 74.62% acc | Synthetic |
+| Wake-word (-5 dB) | Static | 1,202 | 57.13% acc | Synthetic |
+| Anomaly | ASSTF | 506 | F1 = 0.946 | Synthetic |
+| Anomaly | Static | 2,080 | F1 = 0.508 | Synthetic |
+| Few-shot | ASSTF | 2,105 | 19.73% acc | sklearn digits |
+| Few-shot | Static | 7,237 | 19.39% acc | sklearn digits |
+| RL adapted reward | ASSTF | 965 | 39.66 | Custom env |
+| RL adapted reward | Static | 1,441 | 32.97 | Custom env |
+| Edge NLP (SST-2) | ASSTF (h=96) | 403,896 | 67.88% acc | **Real** |
+| Edge NLP (SST-2) | Static | 649,218 | 67.75% acc | **Real** |
+
+<p align="center">
+  <img src="assets/benchmark_chart.png" alt="ASSTF Parameter Efficiency" width="700">
+</p>
+
+See [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for full results and reproduction commands.
+
+> **Note on interpretation:** App 01–05 demonstrate ASSTF's algorithmic behavior under controlled, reproducible conditions. They are not claims of real-world SOTA. App 06 is the real-world validation. We welcome community contributions of additional real-dataset benchmarks.
+
+---
+
+## Training a Single Demo
+
+```bash
+python app_03_anomaly/train.py
+python app_03_anomaly/evaluate.py
+```
+
+For a quick smoke test across all apps:
+
+```bash
+python run_all.py --quick
+```
+
+For the full benchmark suite that matches `docs/BENCHMARKS.md`:
+
+```bash
+python run_all.py
+```
+
+---
+
+## Project Structure
+
+```
+Project_LeanAI/
+├── asstf/                  # Core ASSTF framework
+├── shared/                 # Baselines, metrics, early stopping
+├── app_01_gesture/         # Gesture recognition demo
+├── app_02_wake_word/       # Wake-word detection demo
+├── app_03_anomaly/         # Anomaly detection demo
+├── app_04_few_shot/        # Few-shot learning demo
+├── app_05_rl/              # Reinforcement learning demo
+├── app_06_edge_nlp/        # Edge NLP demo
+├── tests/                  # Unit and smoke tests
+├── docs/                   # Documentation and licenses
+├── data/                   # Datasets and caches
+├── results/                # Benchmark outputs
+├── checkpoints/            # Saved models
+├── run_all.py              # Run all demos
+├── requirements.txt
+└── README.md
+```
+
+---
+
+## Roadmap & Stages
+
+| Stage | Timeline | Focus | Key Deliverables |
+|-------|----------|-------|------------------|
+| **Stage 1: Grounding Credit** | Now – Month 4 | Reproducible reference implementation + community | This repo, PyPI, CI, launch |
+| **Stage 2: Real-World Value** | Month 4–12 | Public benchmarks, integrations, academic paper | Real datasets, Hugging Face, Edge Impulse, arXiv |
+| **Stage 3: Commercial Value** | Month 12–24 | Enterprise tools, platform, support | LeanAI Studio, Edge SDK, managed inference |
+
+See [`docs/OPEN_SOURCE_STAGES.md`](docs/OPEN_SOURCE_STAGES.md) for the complete plan.
+
+---
+
+## License
+
+This project is dual-licensed:
+
+- **Community License** — free for personal learning, academic research, non-profit education, and open-source contributions.
+- **Commercial License** — required for any commercial product, service, SaaS, cloud deployment, or hardware integration.
+
+See [LICENSE](LICENSE) and [docs/COMMERCIAL_LICENSE.md](docs/COMMERCIAL_LICENSE.md) for details.
+
+For licensing inquiries, contact **Bentley@safeware.com.tw**.
+
+---
+
+## Citation
+
+If you use ASSTF in academic research, please cite the white-paper:
+
+```bibtex
+@techreport{lin2025asstf,
+  title={Mathematical Framework to Enable Adaptive Neuron Transitions},
+  author={Lin, Bentley Yusen},
+  institution={Safeware Technologies Inc., Ltd.},
+  year={2025}
+}
+```
+
+---
+
+## Contributing
+
+We welcome research contributions, bug reports, documentation improvements, and especially **real-dataset benchmarks**. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+By contributing, you agree that your contributions may be used under both the Community License and future commercial licensing.
+
+---
+
+## Acknowledgments
+
+ASSTF is developed by Safeware Technologies Inc., Ltd. The reference implementation is intended for research and demonstration; production deployment requires additional tuning and a commercial license.
+
+---
+
+**Keywords:** Adaptive State-Space Transfer Function, ASSTF, LeanAI, parameter-efficient deep learning, edge AI, TinyML, continual learning, test-time adaptation, online personalization, low-rank adaptation, PyTorch, efficient AI, green AI, on-device ML.

leanai_asstf-1.0.0/asstf/__init__.py

@@ -0,0 +1,29 @@
+"""
+ASSTF (Adaptive State-Space Transfer Function) Reference Implementation
+=======================================================================
+
+This package provides a PyTorch reference implementation of the ASSTF
+framework described in the LeanAI technical white-paper.  It is intended for
+research, education, and non-commercial evaluation under the LeanAI ASSTF
+Community License.  Commercial use requires a separate Commercial License.
+
+Core modules
+------------
+core        : ASSTF layers and building blocks.
+trainer     : Bilevel optimisation trainer (Algorithm 1 in the paper).
+adaptation  : Inference-time structural adaptation via surprise minimisation.
+"""
+
+from .core import ASSTFLinear, ASSTFBlock, ASSTFConv1d, ASSTFConvBlock, count_parameters
+from .trainer import BilevelTrainer
+from .adaptation import SurpriseMinimizer
+
+__all__ = [
+    "ASSTFLinear",
+    "ASSTFBlock",
+    "ASSTFConv1d",
+    "ASSTFConvBlock",
+    "count_parameters",
+    "BilevelTrainer",
+    "SurpriseMinimizer",
+]