fraclab-sdk 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

README.md

@@ -1,6 +1,6 @@
 # Fraclab SDK Reference
 
-> 版本: 0.1.0
+> 版本: 0.1.1
 > Python: >=3.11
 
 Fraclab SDK 是一个算法开发与执行框架，帮助算法开发者快速构建、测试和部署数据处理算法。
@@ -23,12 +23,26 @@ Fraclab SDK 是一个算法开发与执行框架，帮助算法开发者快速
 
 ## 安装
 
-使用 wheel 文件安装：
+轻量安装（核心 SDK / CLI，自动带上科学计算依赖）：
 
 ```bash
-pip install fraclab_sdk-0.1.0-py3-none-any.whl
+pip install fraclab-sdk
 ```
 
+安装并启用 Workbench UI：
+
+```bash
+pip install "fraclab-sdk[workbench]"
+fraclab-workbench           # CLI entry point
+# 或
+python -m fraclab_sdk.workbench
+```
+
+### 依赖说明
+
+- 核心安装会自动安装并锁定：`numpy>=2.1.1`, `pandas>=2.2.3`, `scipy>=1.13.1`, `matplotlib>=3.9.2`, `fastapi>=0.115.0`, `rich>=13.9.0`。无需手动再装，避免版本冲突。
+- 可选 `workbench` 额外安装 UI 依赖：`streamlit>=1.30`, `pyarrow>=16.0.0`（`pandas` 已在核心里）。
+
 ---
 
 ## 快速开始：编写你的第一个算法
@@ -46,13 +60,63 @@ from fraclab_sdk.runtime import DataClient, ArtifactWriter
 
 ### 2. 编写算法入口
 
-创建 `main.py` 作为算法入口文件：
+创建 `main.py` 作为算法入口文件。
+
+#### 入口函数签名约定
+
+**算法入口函数必须严格遵循以下签名:**
+
+```python
+def run(ctx):
+    ...
+```
+
+| 约定 | 要求 | 说明 |
+|------|------|------|
+| 文件名 | `main.py` | 必须是 `main.py`，不能是其他名称 |
+| 函数名 | `run` | 必须是 `run`，区分大小写 |
+| 参数 | 仅 `ctx` 一个参数 | SDK 使用 `module.run(ctx)` 调用，**不支持**其他签名 |
+| 返回值 | 无要求 | 返回值会被忽略 |
+
+> **警告**: 以下写法都会导致运行失败:
+> ```python
+> # ❌ 错误: 参数名不影响，但参数个数必须是 1
+> def run(ctx, extra_arg):  # TypeError: run() missing required argument
+>
+> # ❌ 错误: 函数名错误
+> def execute(ctx):  # AttributeError: module has no attribute 'run'
+>
+> # ❌ 错误: 放在其他文件
+> # algorithm.py 中定义 run()  # 不会被加载
+> ```
+
+#### 最小可运行模板
 
 ```python
 # main.py
-from fraclab_sdk.runtime import DataClient, ArtifactWriter
-from pathlib import Path
+def run(ctx):
+    """算法入口函数 - 最小模板。
+
+    Args:
+        ctx: RunContext，包含:
+            - ctx.data_client: DataClient 实例
+            - ctx.params: dict[str, Any]，用户参数
+            - ctx.artifacts: ArtifactWriter 实例
+            - ctx.logger: logging.Logger 实例
+            - ctx.run_context: dict，运行上下文
+    """
+    logger = ctx.logger
+    logger.info("算法开始执行")
+
+    # 你的逻辑...
+
+    logger.info("算法执行完成")
+```
+
+#### 完整示例
 
+```python
+# main.py
 def run(ctx):
     """算法入口函数。
 
@@ -313,7 +377,7 @@ aw.write_scalar(
     "drsPath": "dist/drs.json"
   },
   "requires": {
-    "sdk": "0.1.0",
+    "sdk": "0.1.1",
     "core": "1.0.0"
   },
   "repository": "https://github.com/example/my-algorithm",

fraclab_sdk/specs/__init__.py

@@ -0,0 +1,22 @@
+"""Spec helpers and manifest definitions."""
+
+from .manifest import FracLabAlgorithmManifestV1, ManifestVersion
+from .output import (
+    BlobSchema,
+    FrameSchema,
+    ObjectSchema,
+    OutputContract,
+    OutputDatasetContract,
+    ScalarSchema,
+)
+
+__all__ = [
+    "FracLabAlgorithmManifestV1",
+    "ManifestVersion",
+    "OutputContract",
+    "OutputDatasetContract",
+    "BlobSchema",
+    "ObjectSchema",
+    "ScalarSchema",
+    "FrameSchema",
+]

fraclab_sdk/specs/output.py

@@ -0,0 +1,33 @@
+"""OutputSpec helpers re-exporting models for schema definitions."""
+
+from fraclab_sdk.models.output_contract import (
+    BlobOutputSchema,
+    Cardinality,
+    DatasetKind,
+    DatasetRole,
+    FrameOutputSchema,
+    ObjectOutputSchema,
+    OutputContract,
+    OutputDatasetContract,
+    OwnerType,
+    ScalarOutputSchema,
+)
+
+# Backward-friendly aliases used by workspace schemas
+BlobSchema = BlobOutputSchema
+ObjectSchema = ObjectOutputSchema
+ScalarSchema = ScalarOutputSchema
+FrameSchema = FrameOutputSchema
+
+__all__ = [
+    "BlobSchema",
+    "ObjectSchema",
+    "ScalarSchema",
+    "FrameSchema",
+    "OutputContract",
+    "OutputDatasetContract",
+    "OwnerType",
+    "DatasetKind",
+    "DatasetRole",
+    "Cardinality",
+]

fraclab_sdk/workbench/Home.py

@@ -0,0 +1,162 @@
+"""Fraclab SDK Workbench - Home Page."""
+
+import streamlit as st
+
+from fraclab_sdk.workbench import ui_styles
+from fraclab_sdk.algorithm import AlgorithmLibrary
+from fraclab_sdk.config import SDKConfig
+from fraclab_sdk.run import RunManager
+from fraclab_sdk.snapshot import SnapshotLibrary
+
+st.set_page_config(
+    page_title="Fraclab SDK Workbench",
+    page_icon="🔬",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
+ui_styles.apply_global_styles()
+
+# --- Page-Specific Styling ---
+st.markdown("""
+<style>
+    /* Title styling */
+    h1 {
+        font-family: 'Source Sans Pro', sans-serif;
+        font-weight: 700;
+        color: #1f2937;
+    }
+
+    /* Metric value highlight */
+    [data-testid="stMetricValue"] {
+        font-size: 2rem !important;
+        color: #2563eb;
+    }
+
+    /* Info box styling */
+    .info-box {
+        background-color: #f8fafc;
+        border: 1px solid #e2e8f0;
+        padding: 15px;
+        border-radius: 8px;
+        font-family: monospace;
+        color: #475569;
+    }
+
+    /* Hero section styling */
+    .hero-container {
+        padding: 2rem 0;
+        margin-bottom: 2rem;
+        border-bottom: 1px solid #e6e9ef;
+    }
+    .hero-sub {
+        font-size: 1.2rem;
+        color: #64748b;
+    }
+</style>
+""", unsafe_allow_html=True)
+
+
+# --- 2. Hero Section ---
+st.markdown("""
+<div class="hero-container">
+    <h1>Fraclab SDK Workbench</h1>
+    <div class="hero-sub">The unified platform for algorithm development, testing, and deployment.</div>
+</div>
+""", unsafe_allow_html=True)
+
+
+def show_dashboard():
+    """Show SDK status overview cards."""
+    try:
+        config = SDKConfig()
+        snapshot_lib = SnapshotLibrary(config)
+        algorithm_lib = AlgorithmLibrary(config)
+        run_manager = RunManager(config)
+        
+        snap_count = len(snapshot_lib.list_snapshots())
+        algo_count = len(algorithm_lib.list_algorithms())
+        run_count = len(run_manager.list_runs())
+        sdk_home = config.sdk_home
+
+    except Exception as e:
+        st.error(f"Failed to initialize SDK: {e}")
+        return
+
+    # --- Metrics Dashboard ---
+    st.subheader("System Status")
+    
+    c1, c2, c3 = st.columns(3)
+    
+    with c1:
+        with st.container(border=True):
+            st.metric("📦 Snapshots", snap_count, delta="Data Bundles")
+            
+    with c2:
+        with st.container(border=True):
+            st.metric("🧩 Algorithms", algo_count, delta="Calculations")
+            
+    with c3:
+        with st.container(border=True):
+            st.metric("🚀 Runs", run_count, delta="Executions")
+
+    # --- Config Info ---
+    st.write("") # Spacer
+    with st.container(border=True):
+        col_lbl, col_val = st.columns([1, 6])
+        with col_lbl:
+            st.markdown("**SDK Home:**")
+        with col_val:
+            st.code(str(sdk_home), language="bash")
+
+
+show_dashboard()
+
+st.divider()
+
+# --- 3. Visual Workflow Guide ---
+st.subheader("Workflow Guide")
+
+# Grid layout for workflow steps
+row1_col1, row1_col2, row1_col3 = st.columns(3)
+row2_col1, row2_col2 = st.columns(2)
+
+# Step 1: Snapshots
+with row1_col1:
+    with st.container(border=True):
+        st.markdown("#### 1. Import Data")
+        st.caption("Go to **Snapshots**")
+        st.markdown("Upload zip bundles containing your input data (Parquet/NDJSON) and Data Requirement Specs (DRS).")
+
+# Step 2: Browse
+with row1_col2:
+    with st.container(border=True):
+        st.markdown("#### 2. Inspect")
+        st.caption("Go to **Browse**")
+        st.markdown("Visualize dataset contents, check schemas, and verify file integrity before running calculations.")
+
+# Step 3: Selection
+with row1_col3:
+    with st.container(border=True):
+        st.markdown("#### 3. Configure")
+        st.caption("Go to **Selection**")
+        st.markdown("Pair an Algorithm with a Snapshot. Select specific data items and tweak JSON parameters.")
+
+# Step 4: Run
+with row2_col1:
+    with st.container(border=True):
+        st.markdown("#### 4. Execute")
+        st.caption("Go to **Run**")
+        st.markdown("Monitor pending jobs, view live execution status, and manage timeout settings.")
+
+# Step 5: Results
+with row2_col2:
+    with st.container(border=True):
+        st.markdown("#### 5. Analyze")
+        st.caption("Go to **Results**")
+        st.markdown("View generated artifacts, plots, metrics, and download output files.")
+
+# Footer spacing
+st.write("")
+st.write("")
+st.caption("© 2026 Fraclab SDK. All systems operational.")

fraclab_sdk/workbench/__init__.py

@@ -0,0 +1,4 @@
+"""Workbench UI packaged with the Fraclab SDK."""
+
+# Export a helper so callers can invoke programmatically without the CLI.
+from fraclab_sdk.workbench.__main__ import main as run_workbench  # noqa: F401

fraclab_sdk/workbench/__main__.py

@@ -0,0 +1,48 @@
+"""CLI entrypoint for launching the Streamlit workbench."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Sequence
+
+
+def _require_optional_deps() -> None:
+    """Fail fast with a clear message when optional deps are missing."""
+    missing = []
+    try:
+        import streamlit  # noqa: F401
+    except ImportError:
+        missing.append("streamlit>=1.30")
+    try:
+        import pandas  # noqa: F401
+    except ImportError:
+        missing.append("pandas")
+
+    if missing:
+        deps = ", ".join(missing)
+        raise SystemExit(
+            f"Workbench dependencies missing ({deps}). "
+            "Install with `pip install fraclab-sdk[workbench]`."
+        )
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Launch the Streamlit app using the bundled Home.py."""
+    _require_optional_deps()
+    from streamlit.web import cli as stcli
+
+    workbench_dir = Path(__file__).resolve().parent
+    home_path = workbench_dir / "Home.py"
+    if not home_path.exists():
+        raise SystemExit(f"Workbench entry script not found: {home_path}")
+
+    extra_args = list(argv) if argv is not None else sys.argv[1:]
+    sys.argv = ["streamlit", "run", str(home_path), *extra_args]
+    os.chdir(workbench_dir)
+    stcli.main()
+
+
+if __name__ == "__main__":
+    main()