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

fraclab_sdk/workbench/pages/9_Export_Algorithm.py

@@ -0,0 +1,386 @@
+"""Algorithm export page."""
+
+from __future__ import annotations
+
+import io
+import json
+import shutil
+import tempfile
+from pathlib import Path
+
+import streamlit as st
+
+from fraclab_sdk.algorithm import AlgorithmLibrary
+from fraclab_sdk.config import SDKConfig
+from fraclab_sdk.devkit import (
+    validate_algorithm_signature,
+    validate_inputspec,
+    validate_output_contract,
+)
+from fraclab_sdk.snapshot import SnapshotLibrary
+from fraclab_sdk.workbench import ui_styles
+
+st.set_page_config(page_title="Export Algorithm", page_icon="📦", layout="wide", initial_sidebar_state="expanded")
+st.title("Export Algorithm")
+
+ui_styles.apply_global_styles()
+
+# --- Page-Specific CSS ---
+st.markdown("""
+<style>
+    /* Status badge styling */
+    .status-badge {
+        padding: 4px 8px;
+        border-radius: 4px;
+        font-weight: 600;
+        font-size: 0.85rem;
+    }
+    .status-ok { background-color: #d1fae5; color: #065f46; }
+    .status-missing { background-color: #fee2e2; color: #991b1b; }
+    .status-warning { background-color: #fef3c7; color: #92400e; }
+</style>
+""", unsafe_allow_html=True)
+
+
+config = SDKConfig()
+algo_lib = AlgorithmLibrary(config)
+snap_lib = SnapshotLibrary(config)
+
+algos = algo_lib.list_algorithms()
+if not algos:
+    st.info("No algorithms imported. Use Snapshots page to import or create one.")
+    st.stop()
+
+# ==========================================
+# 1. Source Selection
+# ==========================================
+st.subheader("1. Select Algorithm Source")
+
+with st.container(border=True):
+    c1, c2 = st.columns([3, 1])
+    with c1:
+        algo_options = {f"{a.algorithm_id}:{a.version}": a for a in algos}
+        selected_key = st.selectbox(
+            "Target Algorithm",
+            options=list(algo_options.keys()),
+            format_func=lambda k: f"{algo_options[k].algorithm_id} (v{algo_options[k].version})",
+            label_visibility="collapsed"
+        )
+    with c2:
+        if selected_key:
+            selected_algo = algo_options[selected_key]
+            st.caption(f"ID: `{selected_algo.algorithm_id}`")
+
+if not selected_key:
+    st.stop()
+
+selected_algo = algo_options[selected_key]
+handle = algo_lib.get_algorithm(selected_algo.algorithm_id, selected_algo.version)
+algo_dir = handle.directory
+
+# File paths
+manifest_path = algo_dir / "manifest.json"
+params_schema_path = algo_dir / "dist" / "params.schema.json"
+output_contract_path = algo_dir / "dist" / "output_contract.json"
+drs_path = algo_dir / "dist" / "drs.json"
+
+# ==========================================
+# 2. Validation Status
+# ==========================================
+st.subheader("2. Validation Status")
+
+
+def _get_algo_mtime(algo_dir: Path) -> float:
+    """Get max mtime of source files for cache invalidation."""
+    files = [
+        algo_dir / "main.py",
+        algo_dir / "manifest.json",
+    ]
+    # schema/*.py files
+    schema_dir = algo_dir / "schema"
+    if schema_dir.exists():
+        files.extend(schema_dir.glob("*.py"))
+
+    # dist/*.json (if exists)
+    dist_dir = algo_dir / "dist"
+    if dist_dir.exists():
+        files.extend(dist_dir.glob("*.json"))
+
+    mtimes = [f.stat().st_mtime for f in files if f.exists()]
+    return max(mtimes) if mtimes else 0.0
+
+
+@st.cache_data(ttl=60)
+def _run_all_validations(algo_dir_str: str, _mtime: float) -> dict[str, dict]:
+    """Run all validations. Cached by (path, mtime)."""
+    workspace = Path(algo_dir_str)
+    results: dict[str, dict] = {}
+
+    # InputSpec validation
+    try:
+        inputspec_result = validate_inputspec(workspace)
+        results["inputspec"] = {
+            "valid": inputspec_result.valid,
+            "errors": len(inputspec_result.errors),
+            "warnings": len(inputspec_result.warnings),
+            "issues": [
+                {
+                    "severity": i.severity.value,
+                    "code": i.code,
+                    "message": i.message,
+                    "path": i.path,
+                    "details": i.details,
+                }
+                for i in inputspec_result.issues
+            ],
+        }
+    except Exception as e:
+        results["inputspec"] = {
+            "valid": False,
+            "errors": 1,
+            "warnings": 0,
+            "issues": [{"severity": "error", "code": "VALIDATION_FAILED", "message": str(e), "path": None, "details": {}}],
+        }
+
+    # OutputContract validation
+    try:
+        output_result = validate_output_contract(workspace)
+        results["output_contract"] = {
+            "valid": output_result.valid,
+            "errors": len(output_result.errors),
+            "warnings": len(output_result.warnings),
+            "issues": [
+                {
+                    "severity": i.severity.value,
+                    "code": i.code,
+                    "message": i.message,
+                    "path": i.path,
+                    "details": i.details,
+                }
+                for i in output_result.issues
+            ],
+        }
+    except Exception as e:
+        results["output_contract"] = {
+            "valid": False,
+            "errors": 1,
+            "warnings": 0,
+            "issues": [{"severity": "error", "code": "VALIDATION_FAILED", "message": str(e), "path": None, "details": {}}],
+        }
+
+    # Algorithm signature validation
+    try:
+        algo_result = validate_algorithm_signature(workspace)
+        results["algorithm"] = {
+            "valid": algo_result.valid,
+            "errors": len(algo_result.errors),
+            "warnings": len(algo_result.warnings),
+            "issues": [
+                {
+                    "severity": i.severity.value,
+                    "code": i.code,
+                    "message": i.message,
+                    "path": i.path,
+                    "details": i.details,
+                }
+                for i in algo_result.issues
+            ],
+        }
+    except Exception as e:
+        results["algorithm"] = {
+            "valid": False,
+            "errors": 1,
+            "warnings": 0,
+            "issues": [{"severity": "error", "code": "VALIDATION_FAILED", "message": str(e), "path": None, "details": {}}],
+        }
+
+    return results
+
+
+# Run validations with caching
+mtime = _get_algo_mtime(algo_dir)
+validation_results = _run_all_validations(str(algo_dir), mtime)
+
+# Display validation status badges with revalidate button
+with st.container(border=True):
+    cols = st.columns([1, 1, 1, 0.5])
+    names = ["InputSpec", "OutputContract", "Algorithm"]
+    keys = ["inputspec", "output_contract", "algorithm"]
+
+    for i, (key, name) in enumerate(zip(keys, names)):
+        result = validation_results.get(key, {})
+        error_count = result.get("errors", 0)
+        warning_count = result.get("warnings", 0)
+
+        with cols[i]:
+            if error_count > 0:
+                st.markdown(
+                    f'<span class="status-badge status-missing">❌ {name}: {error_count} error{"s" if error_count > 1 else ""}</span>',
+                    unsafe_allow_html=True,
+                )
+            elif warning_count > 0:
+                st.markdown(
+                    f'<span class="status-badge status-warning">⚠️ {name}: {warning_count} warning{"s" if warning_count > 1 else ""}</span>',
+                    unsafe_allow_html=True,
+                )
+            else:
+                st.markdown(
+                    f'<span class="status-badge status-ok">✅ {name}</span>',
+                    unsafe_allow_html=True,
+                )
+
+    with cols[3]:
+        if st.button("🔄 Revalidate", key="rerun_validation"):
+            _run_all_validations.clear()
+            st.rerun()
+
+# Collect all issues
+all_issues = []
+for key in keys:
+    result = validation_results.get(key, {})
+    for issue in result.get("issues", []):
+        all_issues.append((key, issue))
+
+# Show validation details if there are issues
+if all_issues:
+    with st.expander(f"📋 Validation Details ({len(all_issues)} issue{'s' if len(all_issues) > 1 else ''})", expanded=False):
+        for source, issue in all_issues:
+            icon = {"error": "🔴", "warning": "🟡", "info": "🔵"}.get(issue["severity"], "⚪")
+            path_str = f" at `{issue['path']}`" if issue.get("path") else ""
+            details_str = ""
+            if issue.get("details"):
+                # Show suggested fix for snake_case issues
+                if "suggested" in issue["details"]:
+                    details_str = f" → Suggested: `{issue['details']['suggested']}`"
+                elif "missing" in issue["details"]:
+                    details_str = f" (missing: {issue['details']['missing']})"
+                elif "extra" in issue["details"]:
+                    details_str = f" (extra: {issue['details']['extra']})"
+            st.markdown(f"{icon} **[{source}]** `{issue['code']}`{path_str}: {issue['message']}{details_str}")
+
+# File Inspector
+with st.expander("📂 File Inspector", expanded=True):
+    tab_man, tab_in, tab_out = st.tabs(["Manifest", "Input Spec", "Output Spec"])
+
+    def _show_json_preview(path: Path):
+        if path.exists():
+            try:
+                data = json.loads(path.read_text())
+                st.code(json.dumps(data, indent=2, ensure_ascii=False), language="json", line_numbers=True)
+            except Exception:
+                st.error("Failed to parse JSON")
+        else:
+            st.info("File not generated yet.")
+
+    with tab_man: _show_json_preview(manifest_path)
+    with tab_in: _show_json_preview(params_schema_path)
+    with tab_out: _show_json_preview(output_contract_path)
+
+
+# ==========================================
+# 3. DRS Source Selection
+# ==========================================
+st.subheader("3. Select DRS Source")
+
+snapshots = snap_lib.list_snapshots()
+snapshot_map = {s.snapshot_id: s for s in snapshots}
+
+if not snapshots:
+    st.warning("No snapshots available. Import a snapshot first to provide DRS for export.")
+    st.stop()
+
+with st.container(border=True):
+    st.caption("The DRS (Data Requirement Specification) defines dataset requirements. Select a snapshot to use its DRS in the export package.")
+
+    selected_snapshot_id = st.selectbox(
+        "Snapshot (DRS Source)",
+        options=list(snapshot_map.keys()),
+        format_func=lambda x: f"{x} — {snapshot_map[x].bundle_id}",
+        label_visibility="collapsed"
+    )
+
+if not selected_snapshot_id:
+    st.stop()
+
+snapshot_handle = snap_lib.get_snapshot(selected_snapshot_id)
+
+# ==========================================
+# 4. Export
+# ==========================================
+st.divider()
+st.subheader("4. Export")
+
+def build_zip() -> bytes:
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir_path = Path(tmpdir)
+        # copy installed algorithm content
+        shutil.copytree(algo_dir, tmpdir_path / algo_dir.name, dirs_exist_ok=True)
+        target_root = tmpdir_path / algo_dir.name
+
+        # ensure manifest files paths cover dist outputs if present
+        manifest_data = json.loads(manifest_path.read_text())
+        files = manifest_data.get("files") or {}
+
+        if output_contract_path.exists():
+            files["outputContractPath"] = "dist/output_contract.json"
+        if params_schema_path.exists():
+            files["paramsSchemaPath"] = "dist/params.schema.json"
+        if drs_path.exists():
+            files["drsPath"] = "dist/drs.json"
+
+        if files:
+            manifest_data["files"] = files
+
+        (target_root / "manifest.json").write_text(json.dumps(manifest_data, indent=2), encoding="utf-8")
+
+        # DRS Override Logic
+        # Try to find DRS path from manifest, default to dist/drs.json
+        drs_rel_path = manifest_data.get("files", {}).get("drsPath", "dist/drs.json")
+        target_drs_path = target_root / drs_rel_path
+        target_drs_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Read DRS from Snapshot
+        snap_drs_path = snapshot_handle.directory / snapshot_handle.manifest.specFiles.drsPath
+
+        if snap_drs_path.exists():
+            target_drs_path.write_bytes(snap_drs_path.read_bytes())
+        else:
+            # Fallback if snapshot DRS is missing structure (rare)
+            pass
+
+        # Zip it up (flattened: no top-level version folder)
+        zip_buf = io.BytesIO()
+        shutil.make_archive(
+            base_name=tmpdir_path / "algorithm_export",
+            format="zip",
+            root_dir=target_root,
+            base_dir=".",
+        )
+        zip_path = tmpdir_path / "algorithm_export.zip"
+        zip_buf.write(zip_path.read_bytes())
+        zip_buf.seek(0)
+        return zip_buf.read()
+
+
+# Check if there are validation errors
+has_validation_errors = any(not r.get("valid", True) for r in validation_results.values())
+
+_, col_export_btn = st.columns([3, 1])
+with col_export_btn:
+    if has_validation_errors:
+        st.error("Fix validation errors to export")
+        st.button("📦 Build & Export", type="primary", disabled=True, key="export_disabled")
+    else:
+        if st.button("📦 Build & Export", type="primary", key="export_enabled"):
+            try:
+                with st.spinner("Packaging..."):
+                    zip_bytes = build_zip()
+
+                st.download_button(
+                    label="⬇️ Download Zip",
+                    data=zip_bytes,
+                    file_name=f"{selected_algo.algorithm_id}-{selected_algo.version}.zip",
+                    mime="application/zip",
+                )
+            except Exception as e:
+                st.error(f"Export failed: {e}")

fraclab_sdk/workbench/pages/__init__.py

@@ -0,0 +1 @@
+"""Streamlit multipage registry for the workbench."""

fraclab_sdk/workbench/ui_styles.py

@@ -0,0 +1,103 @@
+"""Shared UI styling utility for Streamlit pages."""
+
+import streamlit as st
+
+
+def apply_global_styles():
+    """Inject global CSS to hide Streamlit UI elements and apply common styling."""
+    st.markdown("""
+    <style>
+        /* =================================
+           1. Hide Streamlit UI Elements
+           ================================= */
+
+        /* Hide top header bar */
+        header[data-testid="stHeader"] {
+            display: none !important;
+        }
+
+        /* Hide Deploy button; keep toolbar for sidebar toggle */
+        .stDeployButton {
+            display: none !important;
+        }
+
+        /* Force sidebar visible and disable collapse control */
+        [data-testid="stSidebar"] {
+            transform: none !important;
+            min-width: 260px;
+        }
+        [data-testid="stSidebarNav"] {
+            min-width: 240px;
+        }
+        [data-testid="collapsedControl"] {
+            display: none !important;
+        }
+
+        /* Hide footer (Made with Streamlit) */
+        footer {
+            display: none !important;
+        }
+
+        /* Hide element toolbar on tables/dataframes */
+        [data-testid="stElementToolbar"] {
+            display: none !important;
+        }
+
+        /* Adjust main content padding (header hidden, content needs padding) */
+        .main .block-container {
+            padding-top: 2rem !important;
+            padding-bottom: 2rem !important;
+        }
+
+        /* =================================
+           2. Button Styling
+           ================================= */
+
+        div[data-testid="stButton"] button {
+            white-space: nowrap !important;
+            border-radius: 6px !important;
+            min-width: 60px !important;
+            font-weight: 500 !important;
+        }
+
+        /* =================================
+           3. Anti-Copy Protection
+           ================================= */
+
+        /* Disable text selection on key areas */
+        .element-container,
+        [data-testid="stDataFrame"],
+        [data-testid="stDataEditor"],
+        [data-testid="stCode"],
+        [data-testid="stJson"] {
+            user-select: none;
+            -webkit-user-select: none;
+            -moz-user-select: none;
+            -ms-user-select: none;
+        }
+
+        /* Hide copy buttons on st.code / st.json */
+        [data-testid="stCode"] button,
+        [data-testid="stJson"] button {
+            display: none !important;
+        }
+
+        /* =================================
+           4. Component Styling
+           ================================= */
+
+        /* Expander header styling */
+        .streamlit-expanderHeader {
+            font-weight: 600;
+            background-color: #f9f9fb;
+            border-radius: 6px;
+        }
+
+        /* Data Editor border styling */
+        [data-testid="stDataEditor"] {
+            border: 1px solid #e6e9ef;
+            border-radius: 6px;
+        }
+
+    </style>
+    """, unsafe_allow_html=True)

fraclab_sdk/workbench/utils.py

@@ -0,0 +1,43 @@
+"""Shared helpers for the Streamlit workbench."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from fraclab_sdk.config import SDKConfig
+
+# Keep a dedicated workspace separate from the installed algorithm library.
+WORKSPACE_ALGOS_SUBDIR = "workspace_algorithms"
+
+
+def get_workspace_dir(config: SDKConfig) -> Path:
+    """Return the workspace directory for editable algorithms."""
+    workspace = config.sdk_home / WORKSPACE_ALGOS_SUBDIR
+    workspace.mkdir(parents=True, exist_ok=True)
+    return workspace
+
+
+def run_workspace_script(workspace: Path, script: str, timeout: int = 30) -> subprocess.CompletedProcess:
+    """Run a Python snippet with the workspace on PYTHONPATH."""
+    pythonpath = [str(workspace)]
+    existing = os.environ.get("PYTHONPATH")
+    if existing:
+        pythonpath.append(existing)
+
+    env = {
+        **os.environ,
+        "PYTHONPATH": os.pathsep.join(pythonpath),
+        "PYTHONUNBUFFERED": "1",
+    }
+
+    return subprocess.run(
+        [sys.executable, "-c", script],
+        cwd=workspace,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )

{fraclab_sdk-0.1.0.dist-info → fraclab_sdk-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fraclab-sdk
-Version: 0.1.0
+Version: 0.1.2
 Summary: SDK for managing snapshots, algorithms, and run execution
 Requires-Python: >=3.11,<4.0
 Classifier: Programming Language :: Python :: 3
@@ -8,19 +8,22 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: workbench
 Requires-Dist: fastapi (>=0.115.0,<0.116.0)
 Requires-Dist: matplotlib (>=3.9.2,<4.0.0)
 Requires-Dist: numpy (>=2.1.1,<3.0.0)
 Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: pyarrow (>=16.0.0) ; extra == "workbench"
 Requires-Dist: pydantic (>=2.10.0,<3.0.0)
 Requires-Dist: rich (>=13.9.0,<14.0.0)
 Requires-Dist: scipy (>=1.13.1,<2.0.0)
+Requires-Dist: streamlit (>=1.30) ; extra == "workbench"
 Requires-Dist: typer (>=0.15.0,<0.16.0)
 Description-Content-Type: text/markdown
 
 # Fraclab SDK Reference
 
-> 版本: 0.1.0
+> 版本: 0.1.1
 > Python: >=3.11
 
 Fraclab SDK 是一个算法开发与执行框架，帮助算法开发者快速构建、测试和部署数据处理算法。
@@ -43,12 +46,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` 已在核心里）。
+
 ---
 
 ## 快速开始：编写你的第一个算法
@@ -66,13 +83,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):
     """算法入口函数。
 
@@ -333,7 +400,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",
@@ -846,6 +913,8 @@ $ fraclab-sdk run tail f9e8d7c6
 $ fraclab-sdk run tail f9e8d7c6 --stderr
 ```
 
+> Workbench 提示：结果页面会展示本次运行的输出目录路径（含 `_logs` 日志），即使运行失败也能点开路径定位调试。
+
 #### 6. 运行目录结构
 
 执行完成后，`~/.fraclab/runs/<run_id>/` 目录结构: