feat(doc and api): Revamp README and add CLI API module

Updated the README with improved setup instructions, usage examples, and a new project logo. Added a new CLI API module (spectrumlab/cli/api.py), updated CLI and benchmark modules, and included a backup for benchmark/__init__.py. Also updated project metadata in pyproject.toml.

Author: little1d

README.md

@@ -1,18 +1,20 @@
-# SpectrumLab
+<!-- # SpectrumLab -->
 
 <div align="center">
-A pioneering unified platform designed to systematize and accelerate deep learning research in spectroscopy.
+  <img src="assets/spectrumlab.svg" alt="SpectrumLab" width="600"/>
+  
+  <p><strong>A pioneering unified platform designed to systematize and accelerate deep learning research in spectroscopy.</strong></p>
 </div>
 
-## Quick Start
+## 🚀 Quick Start
 
 ### Environment Setup
 
 We recommend using conda and uv for environment management:
 
 ```bash
 # Clone the repository
-git clone https://github.com/your-org/SpectrumLab.git
+git clone https://github.com/little1d/SpectrumLab.git
 cd SpectrumLab
 
 # Create conda environment
@@ -23,38 +25,71 @@ pip install uv
 uv pip install -e .
 ```
 
-### One-Click Evaluation
+### Data Setup
 
-1. **Switch to evaluation branch**
+Download benchmark data from Hugging Face:
 
-   ```bash
-   git checkout evaluation
-   ```
+- [SpectrumBench v1.0](https://huggingface.co/datasets/SpectrumWorld/spectrumbench_v_1.0)
 
-2. **Download benchmark data**
+Extract the data to the `data` directory in the project root.
 
-   Benchmark data is hosted on Hugging Face. Please download it from the following link:
+### API Keys Configuration
 
-   [https://huggingface.co/datasets/SpectrumWorld/spectrumbench_v_1.0](https://huggingface.co/SpectrumWorld/spectrumbench_v_1.0/tree/main)
+```bash
+# Copy and edit environment configuration
+cp .env.example .env
+# Configure your API keys in the .env file
+```
+
+## 💻 Usage
+
+### Python API
 
-   After downloading, extract the data to the `data` directory in the project root.
+```python
+from spectrumlab.benchmark import get_benchmark_group
+from spectrumlab.models import GPT4o
+from spectrumlab.evaluator import get_evaluator
 
-3. **Configure model parameters**
+# Load benchmark data
+benchmark = get_benchmark_group("perception")
+data = benchmark.get_data_by_subcategories("all")
 
-   ```bash
-   # Copy and edit environment configuration
-   cp .env.example .env
-   # Configure your API keys in the .env file
-   ```
+# Initialize model
+model = GPT4o()
+
+# Get evaluator
+evaluator = get_evaluator("perception")
+
+# Run evaluation
+results = evaluator.evaluate(
+    data_items=data,
+    model=model,
+    save_path="./results"
+)
+
+print(f"Overall accuracy: {results['metrics']['overall']['accuracy']:.2f}%")
+```
 
-4. **Run evaluation**
+### Command Line Interface
 
-   ```bash
-   python run_evaluation.py
-   
-   # Run in background
-   nohup python run_evaluation.py > run_eval.log 2>&1 &
-   ```
+The CLI provides a simple way to run evaluations:
+
+```bash
+# Basic evaluation
+spectrumlab eval --model gpt4o --level perception
+
+# Specify data path and output directory
+spectrumlab eval --model claude --level signal --data-path ./data --output ./my_results
+
+# Evaluate specific subcategories
+spectrumlab eval --model deepseek --level semantic --subcategories "IR_spectroscopy" "Raman_spectroscopy"
+
+# Customize output length
+spectrumlab eval --model internvl --level generation --max-length 1024
+
+# Get help
+spectrumlab eval --help
+```
 
 ## 🤝 Contributing
 
@@ -63,4 +98,4 @@ We welcome community contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md
 ## Acknowledgments
 
 - **Experiment Tracking**: [SwanLab](https://github.com/SwanHubX/SwanLab/) for experiment management and visualization
-- **Evaluation Framework**: Inspired by [MMAR](https://github.com/ddlBoJack/MMAR)
+- **Choice Evaluator Framework**: Inspired by [MMAR](https://github.com/ddlBoJack/MMAR)

assets/spectrumlab.svg

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "spectrumlab"
 version = "0.0.1"
-description = "Comprehensive toolkit for spectroscopy deep learning: dataset loading, training, evaluation, inference, and more"
+description = "A pioneering unified platform designed to systematize and accelerate deep learning research in spectroscopy."
 readme = "README.md"
 requires-python = ">=3.10"
 authors = [

pyproject.toml

@@ -3,4 +3,25 @@
 from .generation_group import GenerationGroup
 from .semantic_group import SemanticGroup
 
-__all__ = ["SignalGroup", "PerceptionGroup", "GenerationGroup", "SemanticGroup"]
+__all__ = [
+    "SignalGroup",
+    "PerceptionGroup",
+    "GenerationGroup",
+    "SemanticGroup",
+    "get_benchmark_group",
+]
+
+
+def get_benchmark_group(level: str, path: str = "./data"):
+    level_map = {
+        "signal": SignalGroup,
+        "perception": PerceptionGroup,
+        "semantic": SemanticGroup,
+        "generation": GenerationGroup,
+    }
+
+    level_lower = level.lower()
+    if level_lower not in level_map:
+        raise ValueError(f"不支持的评估级别: {level}. 可选值: {list(level_map.keys())}")
+
+    return level_map[level_lower](path=path)

spectrumlab/benchmark/__init__.py

@@ -0,0 +1,6 @@
+from .signal_group import SignalGroup
+from .perception_group import PerceptionGroup
+from .generation_group import GenerationGroup
+from .semantic_group import SemanticGroup
+
+__all__ = ["SignalGroup", "PerceptionGroup", "GenerationGroup", "SemanticGroup"]

spectrumlab/benchmark/__init__.py.bak

@@ -1,7 +1,3 @@
-"""
-SpectrumLab - 化学谱学大模型 Benchmark 引擎
-"""
-
 __version__ = "0.0.1"
 
 

spectrumlab/cli/__init__.py

@@ -0,0 +1,43 @@
+from typing import List, Dict, Optional, Any
+from ..benchmark import get_benchmark_group
+from ..evaluator import get_evaluator
+
+
+def run_evaluation(
+    model,
+    level: str,
+    subcategories: Optional[List[str]] = None,
+    data_path: str = "./data",
+    save_path: str = "./results",
+    max_out_len: int = 512,
+) -> Dict[str, Any]:
+    print("🚀 Starting evaluation")
+    print(f"📊 Model: {model.__class__.__name__}")
+    print(f"📁 Level: {level}")
+    print(f"📂 Data path: {data_path}")
+    print(f"💾 Save path: {save_path}")
+
+    print("\n📥 Loading benchmark data...")
+    benchmark = get_benchmark_group(level, data_path)
+
+    if subcategories:
+        data = benchmark.get_data_by_subcategories(subcategories)
+        print(f"📋 Subcategories: {subcategories}")
+    else:
+        data = benchmark.get_data_by_subcategories("all")
+        print("📋 Subcategories: all")
+
+    print(f"📊 Total data items: {len(data)}")
+
+    print("\n⚙️ Getting evaluator...")
+    evaluator = get_evaluator(level)
+
+    print("\n🔄 Running evaluation...")
+    results = evaluator.evaluate(
+        data_items=data,
+        model=model,
+        max_out_len=max_out_len,
+        save_path=save_path,
+    )
+
+    return results

spectrumlab/cli/api.py

@@ -1,40 +1,135 @@
-"""
-SpectrumLab 命令行界面
-"""
-
 import argparse
+import sys
 from typing import Optional, List
 
+from .api import run_evaluation
+from spectrumlab.models import (
+    GPT4o,
+    Claude_Sonnet_3_5,
+    DeepSeek_VL2,
+    InternVL,
+    Qwen_2_5_VL_32B,
+)
+
+AVAILABLE_MODELS = {
+    "gpt4o": GPT4o,
+    "claude": Claude_Sonnet_3_5,
+    "deepseek": DeepSeek_VL2,
+    "internvl": InternVL,
+    "qwen-vl": Qwen_2_5_VL_32B,
+}
+
 
 def main(argv: Optional[List[str]] = None) -> int:
-    """
-    SpectrumLab 主命令行入口点
-    """
     parser = argparse.ArgumentParser(
-        prog="spectrumlab", description="化学谱学大模型 Benchmark 引擎"
+        prog="spectrumlab",
+        description="A pioneering unified platform designed to systematize and accelerate deep learning research in spectroscopy",
+    )
+
+    parser.add_argument("--version", action="version", version="%(prog)s 0.1.0")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    eval_parser = subparsers.add_parser("eval", help="Run model evaluation")
+
+    eval_parser.add_argument(
+        "--model",
+        "-m",
+        required=True,
+        choices=list(AVAILABLE_MODELS.keys()),
+        help=f"Model name, options: {', '.join(AVAILABLE_MODELS.keys())}",
+    )
+
+    eval_parser.add_argument(
+        "--level",
+        "-l",
+        required=True,
+        choices=["signal", "perception", "semantic", "generation"],
+        help="Evaluation level",
     )
 
-    parser.add_argument("--version", action="version", version="%(prog)s 0.0.1")
+    eval_parser.add_argument(
+        "--subcategories",
+        "-s",
+        nargs="*",
+        help="Specify subcategories (optional, default: all)",
+    )
 
-    subparsers = parser.add_subparsers(dest="command", help="可用命令")
+    eval_parser.add_argument(
+        "--data-path", "-d", default="./data", help="Data path (default: ./data)"
+    )
+
+    eval_parser.add_argument(
+        "--output", "-o", default="./results", help="Output path (default: ./results)"
+    )
 
-    # 示例子命令
-    eval_parser = subparsers.add_parser("eval", help="运行评估")
-    eval_parser.add_argument("--model", help="模型名称", required=True)
-    eval_parser.add_argument("--dataset", help="数据集名称", required=True)
+    eval_parser.add_argument(
+        "--max-length", type=int, default=512, help="Max output length (default: 512)"
+    )
 
     args = parser.parse_args(argv)
 
     if args.command == "eval":
-        print(f"正在评估模型: {args.model}")
-        print(f"使用数据集: {args.dataset}")
-        return 0
+        try:
+            # Initialize the model
+            if args.model not in AVAILABLE_MODELS:
+                available = ", ".join(AVAILABLE_MODELS.keys())
+                raise ValueError(
+                    f"Unsupported model: {args.model}. Available: {available}"
+                )
+
+            model_class = AVAILABLE_MODELS[args.model]
+            model_instance = model_class()
+
+            results = run_evaluation(
+                model=model_instance,
+                level=args.level,
+                subcategories=args.subcategories,
+                data_path=args.data_path,
+                save_path=args.output,
+                max_out_len=args.max_length,
+            )
+
+            print("\n" + "=" * 50)
+            print("📊 Evaluation Results")
+            print("=" * 50)
+
+            if "error" in results:
+                print(f"❌ Evaluation failed: {results['error']}")
+                return 1
+
+            metrics = results.get("metrics", {})
+            overall = metrics.get("overall", {})
+
+            print("✅ Evaluation completed!")
+            print(f"📈 Overall accuracy: {overall.get('accuracy', 0):.2f}%")
+            print(f"✅ Correct answers: {overall.get('correct', 0)}")
+            print(f"📝 Total questions: {overall.get('total', 0)}")
+
+            subcategory_metrics = metrics.get("subcategory_metrics", {})
+            if subcategory_metrics:
+                print("\n📋 Subcategory details:")
+                for subcategory, sub_metrics in subcategory_metrics.items():
+                    acc = sub_metrics.get("accuracy", 0)
+                    correct = sub_metrics.get("correct", 0)
+                    total = sub_metrics.get("total", 0)
+                    print(f"  {subcategory}: {acc:.2f}% ({correct}/{total})")
+
+            print(f"\n💾 Results saved to: {args.output}")
+            return 0
+
+        except Exception as e:
+            print(f"❌ Evaluation failed: {e}")
+            return 1
+
     elif args.command is None:
         parser.print_help()
         return 0
-
-    return 0
+    else:
+        print(f"❌ Unknown command: {args.command}")
+        parser.print_help()
+        return 1
 
 
 if __name__ == "__main__":
-    exit(main())
+    sys.exit(main())