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

CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## 0.1.2
+
+### Validation System Upgrade
+- **InputSpec strict validation**:
+  - `json_schema_extra` whitelist enforcement (unknown keys → ERROR, `x_*` prefix → WARNING for extensions)
+  - `show_when` canonical operators only: `equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`
+  - Operator aliases (`eq`, `neq`, `nin`) emit WARNING and normalize to canonical form
+  - snake_case field path detection with camelCase fix suggestions (UI compatibility)
+  - JSON Schema path resolution with `$ref`, `allOf`, `anyOf/oneOf` handling (Pydantic v2 patterns)
+  - `enum_labels` must match enum values exactly (missing/extra keys → ERROR)
+  - Leaf fields missing `title` emit WARNING
+- **OutputContract policy checks**:
+  - Schema structure validation per kind (`frame`, `object`, `blob`, `scalar`)
+  - `dimensions` cannot overlap with owner-level keys (`stageId`, `wellId`, `platformId`)
+  - `groupPath` depth limit warning (max 4 levels)
+  - Invariants validation: dataset references must exist, `sameOwner` level must match
+  - Relations validation: dataset/field references must exist, blob/scalar cannot have field relations
+- **Algorithm signature validation**:
+  - `main.py` must exist with top-level `run` function
+  - `async def run` not supported (sandbox limitation)
+  - Exactly 1 positional parameter required (no `*args`, `**kwargs`, keyword-only args)
+- **Export page integration**:
+  - Cached validation with mtime-based invalidation (avoids re-running on every rerender)
+  - Status badges for InputSpec, OutputContract, Algorithm
+  - Validation details expander with fix suggestions for snake_case issues
+  - Export blocked when validation errors exist
+
+### Other Changes
+- Export page: Replace "File Status" with "Validation Status" as the primary integrity check; File Inspector in expander (expanded by default); Revalidate button inline with status badges.
+- Schema/Output Edit pages: Show warnings even when validation passes; fix incorrect path passed to `validate_output_contract`.
+- Single .py file import: Now creates full template structure (`schema/`, `dist/`) matching "Create New Algorithm".
+- Algorithm scaffold: Now creates `dist/output_contract.json` template.
+- Flatten exported algorithm zip structure (no top-level version folder in Workbench export).
+- Manifest defaults: add `requires.sdk`, `repository`, `homepage`, `license` to scaffolds and bundled examples.
+- Workbench Run/Results pages prompt users to use the InputSpec/OutputSpec editor Validate actions when UI or artifacts are missing.
+- Workbench pages default sidebar to expanded to avoid being trapped when the Streamlit toolbar is hidden.
+- Keep Streamlit toolbar visible (deploy button hidden) so the sidebar toggle is always accessible.
+- Force sidebar to stay visible via CSS so navigation is always reachable.
+- Hide the sidebar collapse control to keep navigation fixed open.
+
+## 0.1.1
+- Package the Streamlit Workbench inside `fraclab_sdk` with the `fraclab-workbench` entrypoint; optional `workbench` extra pulls UI deps.
+- Restore core scientific deps to the base install (numpy/pandas/scipy/matplotlib/fastapi/rich) while keeping Workbench UI deps optional.
+- Add manifest defaults for `requires.sdk`, `repository`, `homepage`, `license`, and embed the SDK version constant for templating.
+- Update bundled example manifests to include the new metadata fields.
+
+## 0.1.0
+- Initial public SDK release with snapshots, algorithm library, run manager, CLI, and devkit tooling.

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",
@@ -826,6 +890,8 @@ $ fraclab-sdk run tail f9e8d7c6
 $ fraclab-sdk run tail f9e8d7c6 --stderr
 ```
 
+> Workbench 提示：结果页面会展示本次运行的输出目录路径（含 `_logs` 日志），即使运行失败也能点开路径定位调试。
+
 #### 6. 运行目录结构
 
 执行完成后，`~/.fraclab/runs/<run_id>/` 目录结构:

fraclab_sdk/__init__.py

@@ -7,6 +7,7 @@ from fraclab_sdk.results import ResultReader
 from fraclab_sdk.run import RunManager, RunMeta, RunResult, RunStatus
 from fraclab_sdk.selection.model import SelectionModel
 from fraclab_sdk.snapshot import SnapshotHandle, SnapshotLibrary, SnapshotMeta
+from fraclab_sdk.version import __version__
 
 __all__ = [
     # Config
@@ -31,4 +32,6 @@ __all__ = [
     "RunStatus",
     # Results
     "ResultReader",
+    # Package metadata
+    "__version__",
 ]

fraclab_sdk/devkit/__init__.py

@@ -9,6 +9,10 @@ This module provides tools for:
 from fraclab_sdk.devkit.compile import compile_algorithm
 from fraclab_sdk.devkit.export import export_algorithm_package
 from fraclab_sdk.devkit.validate import (
+    ValidationIssue,
+    ValidationResult,
+    ValidationSeverity,
+    validate_algorithm_signature,
     validate_bundle,
     validate_inputspec,
     validate_output_contract,
@@ -18,6 +22,10 @@ from fraclab_sdk.devkit.validate import (
 __all__ = [
     "compile_algorithm",
     "export_algorithm_package",
+    "ValidationSeverity",
+    "ValidationIssue",
+    "ValidationResult",
+    "validate_algorithm_signature",
     "validate_bundle",
     "validate_inputspec",
     "validate_output_contract",