Skip to content

Commit 3ef268a

Browse files
SafewareTaiwanSafewareTaiwan
committed
feat: ASSTF v1.0.0 Stage 1 open-source release
0 parents  commit 3ef268a

101 files changed

Lines changed: 11145 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Auto detect text files and perform LF normalization
2+
* text=auto
3+
4+
# PyTorch checkpoints (large binary files)
5+
*.pt filter=lfs diff=lfs merge=lfs -text
6+
*.pth filter=lfs diff=lfs merge=lfs -text
7+
8+
# Python files
9+
*.py text eol=lf
10+
*.pyi text eol=lf
11+
*.toml text eol=lf
12+
*.yml text eol=lf
13+
*.yaml text eol=lf
14+
*.md text eol=lf
15+
*.txt text eol=lf
16+
*.json text eol=lf
17+
18+
# Images
19+
*.png binary
20+
*.jpg binary
21+
*.jpeg binary
22+
*.gif binary
23+
*.svg text

‎.github/CODEOWNERS‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Global owners
2+
* @safeware/leanai-core
3+
4+
# Core algorithm and framework
5+
/asstf/ @safeware/leanai-core
6+
/shared/ @safeware/leanai-core
7+
/tests/ @safeware/leanai-core
8+
9+
# Documentation and community
10+
/docs/ @safeware/leanai-docs
11+
*.md @safeware/leanai-docs
12+
13+
# Applications
14+
/app_01_gesture/ @safeware/leanai-apps
15+
/app_02_wake_word/ @safeware/leanai-apps
16+
/app_03_anomaly/ @safeware/leanai-apps
17+
/app_04_few_shot/ @safeware/leanai-apps
18+
/app_05_rl/ @safeware/leanai-apps
19+
/app_06_edge_nlp/ @safeware/leanai-apps

‎.github/FUNDING.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Funding and commercial licensing
2+
3+
custom: ["https://github.com/safeware/Project_LeanAI/blob/main/docs/COMMERCIAL_LICENSE.md"]
4+
5+
# For commercial licensing inquiries, contact:
6+
# Bentley@safeware.com.tw

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
name: Bug Report
2+
description: Report a problem with ASSTF
3+
title: "[BUG] "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for reporting a bug! Please fill out the sections below so we can reproduce and fix it.
10+
11+
- type: textarea
12+
id: description
13+
attributes:
14+
label: Describe the bug
15+
description: A clear and concise description of what the bug is.
16+
placeholder: When I run ASSTFLinear with structural_rank=0, it raises...
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: reproduction
22+
attributes:
23+
label: Steps to reproduce
24+
description: Provide a minimal code snippet that reproduces the issue.
25+
placeholder: |
26+
```python
27+
import torch
28+
from asstf import ASSTFLinear
29+
layer = ASSTFLinear(10, 5)
30+
```
31+
validations:
32+
required: true
33+
34+
- type: textarea
35+
id: expected
36+
attributes:
37+
label: Expected behavior
38+
description: What did you expect to happen?
39+
validations:
40+
required: true
41+
42+
- type: textarea
43+
id: actual
44+
attributes:
45+
label: Actual behavior
46+
description: What actually happened? Include full error messages if any.
47+
validations:
48+
required: true
49+
50+
- type: textarea
51+
id: environment
52+
attributes:
53+
label: Environment
54+
description: |
55+
Please provide the following information:
56+
- OS:
57+
- Python version:
58+
- PyTorch version:
59+
- ASSTF version:
60+
- Device (CPU/CUDA/MPS):
61+
placeholder: |
62+
- OS: macOS 14
63+
- Python: 3.11
64+
- PyTorch: 2.1.0
65+
- ASSTF: 1.0.0
66+
- Device: MPS
67+
validations:
68+
required: true
69+
70+
- type: checkboxes
71+
id: terms
72+
attributes:
73+
label: Code of Conduct
74+
description: By submitting this issue, you agree to follow our [Code of Conduct](../../CODE_OF_CONDUCT.md).
75+
options:
76+
- label: I agree to follow this project's Code of Conduct
77+
required: true

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Feature Request
2+
description: Suggest a new feature or improvement for ASSTF
3+
title: "[FEATURE] "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for suggesting a feature! Please describe your idea and why it would be valuable.
10+
11+
- type: textarea
12+
id: problem
13+
attributes:
14+
label: Problem or use case
15+
description: What problem are you trying to solve? What is the use case?
16+
placeholder: I want to use ASSTF with Llama-3 for parameter-efficient fine-tuning...
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: proposal
22+
attributes:
23+
label: Proposed solution
24+
description: Describe the feature or change you would like to see.
25+
validations:
26+
required: true
27+
28+
- type: textarea
29+
id: alternatives
30+
attributes:
31+
label: Alternatives considered
32+
description: Have you considered any alternative approaches?
33+
placeholder: A clear and concise description of any alternative solutions or features you've considered.
34+
35+
- type: textarea
36+
id: context
37+
attributes:
38+
label: Additional context
39+
description: Add any other context, screenshots, or references here.
40+
41+
- type: checkboxes
42+
id: terms
43+
attributes:
44+
label: Code of Conduct
45+
description: By submitting this issue, you agree to follow our [Code of Conduct](../../CODE_OF_CONDUCT.md).
46+
options:
47+
- label: I agree to follow this project's Code of Conduct
48+
required: true

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Pull Request
2+
3+
## Description
4+
5+
Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.
6+
7+
Fixes # (issue)
8+
9+
## Type of Change
10+
11+
Please delete options that are not relevant.
12+
13+
- [ ] Bug fix (non-breaking change which fixes an issue)
14+
- [ ] New feature (non-breaking change which adds functionality)
15+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
16+
- [ ] Documentation update
17+
- [ ] Benchmark or example addition
18+
- [ ] Code refactoring
19+
20+
## How Has This Been Tested?
21+
22+
Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce.
23+
24+
- [ ] `pytest tests/ -v`
25+
- [ ] Manual testing
26+
- [ ] New test(s) added
27+
28+
## Checklist
29+
30+
- [ ] My code follows the style guidelines of this project (black, ruff)
31+
- [ ] I have performed a self-review of my own code
32+
- [ ] I have commented my code, particularly in hard-to-understand areas
33+
- [ ] I have made corresponding changes to the documentation
34+
- [ ] My changes generate no new warnings
35+
- [ ] I have added tests that prove my fix is effective or that my feature works
36+
- [ ] New and existing unit tests pass locally with my changes
37+
- [ ] I have read and agree to the [Code of Conduct](../../CODE_OF_CONDUCT.md)
38+
- [ ] I understand that my contribution may be used under both the Community License and Commercial License
39+
40+
## Screenshots / Logs (if applicable)
41+
42+
Add any relevant screenshots, logs, or benchmark results here.

‎.github/workflows/ci.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main, master]
6+
pull_request:
7+
branches: [main, master]
8+
9+
jobs:
10+
test:
11+
runs-on: ${{ matrix.os }}
12+
strategy:
13+
fail-fast: false
14+
matrix:
15+
os: [ubuntu-latest, macos-latest]
16+
python-version: ["3.9", "3.10", "3.11", "3.12"]
17+
18+
steps:
19+
- name: Checkout repository
20+
uses: actions/checkout@v4
21+
22+
- name: Set up Python ${{ matrix.python-version }}
23+
uses: actions/setup-python@v5
24+
with:
25+
python-version: ${{ matrix.python-version }}
26+
27+
- name: Install dependencies
28+
run: |
29+
python -m pip install --upgrade pip
30+
pip install -r requirements.txt
31+
pip install -r requirements-dev.txt
32+
33+
- name: Lint with ruff
34+
run: |
35+
ruff check asstf shared tests
36+
37+
- name: Check formatting with black
38+
run: |
39+
black --check asstf shared tests
40+
41+
- name: Type check with mypy
42+
run: |
43+
mypy asstf shared
44+
45+
- name: Run unit tests
46+
run: |
47+
pytest tests/ -v

‎.github/workflows/docs.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
paths:
9+
- "docs/**"
10+
- "mkdocs.yml"
11+
- "assets/**"
12+
13+
permissions:
14+
contents: write
15+
16+
jobs:
17+
deploy:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@v4
21+
22+
- name: Set up Python
23+
uses: actions/setup-python@v5
24+
with:
25+
python-version: "3.11"
26+
27+
- name: Install MkDocs
28+
run: |
29+
pip install mkdocs-material
30+
31+
- name: Deploy to GitHub Pages
32+
run: |
33+
mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
.venv/
8+
venv/
9+
env/
10+
.pytest_cache/
11+
.mypy_cache/
12+
13+
# PyTorch checkpoints (large binary files)
14+
checkpoints/**/*.pt
15+
checkpoints/**/*.pth
16+
17+
# Data / results: keep the folder structure and JSON reports, ignore raw caches
18+
data/*
19+
!data/.gitkeep
20+
results/*
21+
!results/benchmarks.json
22+
!results/app_*/
23+
results/app_*/*
24+
!results/app_*/result.json
25+
26+
# Build artifacts
27+
dist/
28+
build/
29+
*.egg-info/
30+
31+
# IDE
32+
.idea/
33+
.vscode/
34+
*.swp
35+
*.swo
36+
37+
# OS
38+
.DS_Store
39+
Thumbs.db

‎CHANGELOG.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Changelog
2+
3+
All notable changes to the ASSTF project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6+
7+
## [1.0.0] - 2026-07-05
8+
9+
### Added
10+
11+
- Initial public release of the ASSTF reference implementation.
12+
- `ASSTFLinear` and `ASSTFConv1d` drop-in PyTorch layers.
13+
- `BilevelTrainer` for alternating core/structural parameter updates.
14+
- `SurpriseMinimizer` for inference-time structural adaptation.
15+
- Six reproducible application demos (gesture, wake-word, anomaly, few-shot, RL, edge NLP).
16+
- Open data-generation scripts for all synthetic demos.
17+
- Real SST-2 validation for the edge NLP demo.
18+
- English-first documentation: Introduction, Architecture, Usage, API, and Open-Source Stages.
19+
- Dual licensing: Community License for non-commercial use, Commercial License for commercial use.
20+
- `pyproject.toml` and PyPI package `leanai-asstf`.
21+
- GitHub Actions CI workflow.
22+
- Community files: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CHANGELOG.md`.
23+
24+
### Fixed
25+
26+
- `structural_gate` initialized to a negative value for near-zero structural contribution at startup.
27+
- `SurpriseMinimizer` no longer forces `model.train()` during adaptation.
28+
- Self-supervised adaptation loss now produces meaningful gradients.
29+
- App 05 RL adaptation target changed from self-distillation to policy-gradient objective.
30+
- `BilevelTrainer.evaluate` now correctly returns custom metrics.
31+
- `ASSTFConv1d` now honors the selected `svd_method`.
32+
- `shared.metrics.accuracy` broadcasting edge case resolved.
33+
34+
---
35+
36+
## Unreleased
37+
38+
### Planned
39+
40+
- Real-world benchmarks on public datasets for Apps 01–05.
41+
- Hugging Face `peft` integration.
42+
- Edge deployment examples (Raspberry Pi, Arduino, ONNX).
43+
- arXiv technical report.
44+
- Community benchmark leaderboard.

0 commit comments

Comments
 (0)