feat: async-safe param_scope, hp CLI analyzer, comprehensive test suite

.github/workflows/codecov.yml

@@ -2,6 +2,10 @@ name: codecov
 
 on: [push, pull_request]
 
+permissions:
+  contents: read
+  id-token: write # Required for Codecov tokenless uploads (public repos)
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -10,37 +14,38 @@ jobs:
       run:
         working-directory: .
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v2
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: '3.9'
-    - uses: actions-rs/toolchain@v1
-      with:
-        toolchain: stable
-        override: true
-        profile: minimal
-        components: llvm-tools-preview
+        cache: 'pip'
     - name: Install Rust toolchain
       uses: dtolnay/rust-toolchain@stable
+      with:
+        components: llvm-tools-preview
+    - uses: Swatinem/rust-cache@v2
+      with:
+        workspaces: "src/core -> src/core/target"
     - name: Install cargo-llvm-cov
       uses: taiki-e/install-action@cargo-llvm-cov
     - name: Install requirements
       run: |
-        pip install pytest pytest-cov && pip install -e .
+        pip install pytest pytest-cov pytest-asyncio && pip install -e .
     - name: Run tests and collect coverage
       run: |
-        cd core/
+        cd src/core/
         source <(cargo llvm-cov show-env --export-prefix)
         export CARGO_TARGET_DIR=$CARGO_LLVM_COV_TARGET_DIR
         export CARGO_INCREMENTAL=1
         cargo llvm-cov clean --workspace
         cargo test
-        cd ..
+        cd ../..
         pytest --cov=./ --cov-report=xml
-        cd core/
-        cargo llvm-cov --no-run --lcov --output-path ../coverage.lcov
+        cd src/core/
+        cargo llvm-cov --no-run --lcov --output-path ../../coverage.lcov
     - name: Upload coverage reports to Codecov with GitHub Action
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v5
       with:
         files: coverage.lcov,coverage.xml
-        token: ${{ secrets.CODECOV }}
+        token: ${{ secrets.CODECOV_TOKEN || secrets.CODECOV }}
+        fail_ci_if_error: true

.github/workflows/test.yml

@@ -37,24 +37,24 @@ jobs:
             ~/.cargo/registry/index/
             ~/.cargo/registry/cache/
             ~/.cargo/git/db/
-            core/target/
-            hyperparameter/target/
+            src/core/target/
+            src/py/target/
           key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: |
             ${{ runner.os }}-cargo-
 
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install pytest pytest-cov
+          pip install pytest pytest-cov pytest-asyncio
 
       - name: Build and install hyperparameter
         run: |
           pip install -e .
 
       - name: Run Rust tests
         run: |
-          cd core
+          cd src/core
           cargo test --lib
 
       - name: Run Python tests

README.md

@@ -14,6 +14,30 @@
 
 Hyperparameter is a versatile library designed to streamline the management and control of hyperparameters in machine learning algorithms and system development. Tailored for AI researchers and Machine Learning Systems (MLSYS) developers, Hyperparameter offers a unified solution with a focus on ease of use in Python, high-performance access in Rust and C++, and a set of macros for seamless hyperparameter management.
 
+## 5-Minute Try
+
+```bash
+pip install hyperparameter
+
+# Run a ready-to-use demo
+python -m hyperparameter.examples.quickstart
+
+# Try the @auto_param CLI: override defaults from the command line
+python -m hyperparameter.examples.quickstart --define greet.name=Alice --enthusiasm=3
+
+# Inspect params and defaults
+python -m hyperparameter.examples.quickstart -lps
+python -m hyperparameter.examples.quickstart -ep greet.name
+
+# Running from source? Use module mode or install editable
+# python -m hyperparameter.examples.quickstart
+# or: pip install -e .
+```
+
+What it shows:
+- default values vs scoped overrides (`param_scope`)
+- `@auto_param` + `launch` exposing a CLI with `-D/--define` for quick overrides
+
 ## Key Features
 
 ### For Python Users
@@ -60,7 +84,7 @@ with param_scope(**{"foo.x": 2}):
 ```rust
 fn foo() -> i32 {
     with_params! {
-        get x = foo.x or 1i32; // Read hyperparameter with default value
+        @get x = foo.x or 1i32; // Read hyperparameter with default value
 
         println!("x={}", x);
     }
@@ -70,7 +94,7 @@ fn main() {
     foo(); // x=1
 
     with_params! {
-        set foo.x = 2i32; // Set hyperparameter
+        @set foo.x = 2i32; // Set hyperparameter
 
         foo(); // x=2
     }
@@ -106,7 +130,7 @@ x = param_scope.foo.x | "default value"
 #### Rust
 
 ```rust
-get x = foo.x or "default value";
+@get x = foo.x or "default value";
 ```
 
 ### Scope Control of Parameter Values
@@ -126,10 +150,10 @@ with param_scope() as ps: # 1st scope start
 
 ```rust
 with_params!{ // 1st scope start
-    set foo.x=1;
+    @set foo.x=1;
 
     with_params!{ //2nd scope start
-        set foo.y=2
+        @set foo.y=2
 
         ...
     } // 2nd scope end
@@ -157,15 +181,15 @@ with param_scope() as ps:
 ```rust
 fn foo() { // Print hyperparameter foo.x
     with_params!{
-        get x = foo.x or 1;
+        @get x = foo.x or 1;
 
         println!("foo.x={}", x);
     }
 }
 
 fn main() {
     with_params!{
-        set foo.x = 2; // Modify foo.x in the current thread
+        @set foo.x = 2; // Modify foo.x in the current thread
 
         foo(); // foo.x=2
         thread::spawn(foo); // foo.x=1, new thread's hyperparameter value is not affected by the main thread
@@ -223,8 +247,8 @@ fn main() {
 
 fn foo() {
     with_params! {
-        get a = example.a or 0;
-        get b = example.b or 1;
+        @get a = example.a or 0;
+        @get b = example.b or 1;
 
         println!("example.a={}, example.b={}",a ,b);
     }

README.zh.md

@@ -60,7 +60,7 @@ with param_scope(**{"foo.x": 2}):
 ```rust
 fn foo() -> i32 {
     with_params! {
-        get x = foo.x or 1i32; // 读取带有默认值的超参数
+        @get x = foo.x or 1i32; // 读取带有默认值的超参数
 
         println!("x={}", x);
     }
@@ -70,7 +70,7 @@ fn main() {
     foo(); // x=1
 
     with_params! {
-        set foo.x = 2i32; // 设置超参数
+        @set foo.x = 2i32; // 设置超参数
 
         foo(); // x=2
     }
@@ -106,7 +106,7 @@ x = param_scope.foo.x | "default value"
 #### Rust
 
 ```rust
-get x = foo.x or "default value";
+@get x = foo.x or "default value";
 ```
 
 ### 控制参数值的作用域
@@ -126,10 +126,10 @@ with param_scope() as ps: # 第1个作用域开始
 
 ```rust
 with_params!{ // 第1个作用域开始
-    set foo.x=1;
+    @set foo.x=1;
 
     with_params!{ //第2个作用域开始
-        set foo.y=2
+        @set foo.y=2
 
         ...
     } // 第2个作用域结束
@@ -159,15 +159,15 @@ with param_scope() as ps:
 ```rust
 fn foo() { // 打印超参数 foo.x
     with_params!{
-        get x = foo.x or 1;
+        @get x = foo.x or 1;
 
         println!("foo.x={}", x);
     }
 }
 
 fn main() {
     with_params!{
-        set foo.x = 2; // 在当前线程中修改 foo.x
+        @set foo.x = 2; // 在当前线程中修改 foo.x
 
         foo(); // foo.x=2
         thread::spawn(foo); // foo.x=1，新线程的超参数值不受主线程的影响
@@ -225,8 +225,8 @@ fn main() {
 
 fn foo() {
     with_params! {
-        get a = example.a or 0;
-        get b = example.b or 1;
+        @get a = example.a or 0;
+        @get b = example.b or 1;
 
         println!("example.a={}, example.b={}",a ,b);
     }