fraclab-sdk 0.1.0__tar.gz → 0.1.2__tar.gz

fraclab_sdk-0.1.2/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.

fraclab_sdk-0.1.0/README.md → fraclab_sdk-0.1.2/PKG-INFO

@@ -1,6 +1,29 @@
+Metadata-Version: 2.4
+Name: fraclab-sdk
+Version: 0.1.2
+Summary: SDK for managing snapshots, algorithms, and run execution
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+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 是一个算法开发与执行框架，帮助算法开发者快速构建、测试和部署数据处理算法。
@@ -23,12 +46,26 @@ Fraclab SDK 是一个算法开发与执行框架，帮助算法开发者快速
 
 ## 安装
 
-使用 wheel 文件安装：
+轻量安装（核心 SDK / CLI，自动带上科学计算依赖）：
+
+```bash
+pip install fraclab-sdk
+```
+
+安装并启用 Workbench UI：
 
 ```bash
-pip install fraclab_sdk-0.1.0-py3-none-any.whl
+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 +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):
     """算法入口函数。
 
@@ -313,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",
@@ -826,6 +913,8 @@ $ fraclab-sdk run tail f9e8d7c6
 $ fraclab-sdk run tail f9e8d7c6 --stderr
 ```
 
+> Workbench 提示：结果页面会展示本次运行的输出目录路径（含 `_logs` 日志），即使运行失败也能点开路径定位调试。
+
 #### 6. 运行目录结构
 
 执行完成后，`~/.fraclab/runs/<run_id>/` 目录结构:
@@ -1599,3 +1688,4 @@ drs_hash = compute_sha256("drs.json")
 print(f"dsSha256: {ds_hash}")
 print(f"drsSha256: {drs_hash}")
 ```
+

fraclab_sdk-0.1.0/PKG-INFO → fraclab_sdk-0.1.2/README.md

@@ -1,26 +1,6 @@
-Metadata-Version: 2.4
-Name: fraclab-sdk
-Version: 0.1.0
-Summary: SDK for managing snapshots, algorithms, and run execution
-Requires-Python: >=3.11,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-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: 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: 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 +23,26 @@ Fraclab SDK 是一个算法开发与执行框架，帮助算法开发者快速
 
 ## 安装
 
-使用 wheel 文件安装：
+轻量安装（核心 SDK / CLI，自动带上科学计算依赖）：
+
+```bash
+pip install fraclab-sdk
+```
+
+安装并启用 Workbench UI：
 
 ```bash
-pip install fraclab_sdk-0.1.0-py3-none-any.whl
+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 +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):
     """算法入口函数。
 
@@ -333,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",
@@ -846,6 +890,8 @@ $ fraclab-sdk run tail f9e8d7c6
 $ fraclab-sdk run tail f9e8d7c6 --stderr
 ```
 
+> Workbench 提示：结果页面会展示本次运行的输出目录路径（含 `_logs` 日志），即使运行失败也能点开路径定位调试。
+
 #### 6. 运行目录结构
 
 执行完成后，`~/.fraclab/runs/<run_id>/` 目录结构:
@@ -1619,4 +1665,3 @@ drs_hash = compute_sha256("drs.json")
 print(f"dsSha256: {ds_hash}")
 print(f"drsSha256: {drs_hash}")
 ```
-

{fraclab_sdk-0.1.0 → fraclab_sdk-0.1.2}/pyproject.toml

@@ -1,11 +1,12 @@
 [tool.poetry]
 name = "fraclab-sdk"
-version = "0.1.0"
+version = "0.1.2"
 description = "SDK for managing snapshots, algorithms, and run execution"
 authors = []
 readme = "README.md"
 include = [
-    { path = "README.md", format = ["sdist", "wheel"] }
+    { path = "README.md", format = ["sdist", "wheel"] },
+    { path = "CHANGELOG.md", format = ["sdist", "wheel"] },
 ]
 packages = [{ include = "fraclab_sdk", from = "src" }]
 
@@ -19,15 +20,21 @@ pandas = "^2.2.3"
 scipy = "^1.13.1"
 matplotlib = "^3.9.2"
 fastapi = "^0.115.0"
+streamlit = {version = ">=1.30", optional = true}
+pyarrow = {version = ">=16.0.0", optional = true}
 
 [tool.poetry.group.dev.dependencies]
 ruff = "^0.8.0"
 pytest = "^8.3.0"
 pytest-cov = "^6.0.0"
 
+[tool.poetry.extras]
+workbench = ["streamlit", "pyarrow"]
+
 [tool.poetry.scripts]
 fraclab-runner = "fraclab_sdk.runtime.runner_main:main"
 fraclab-sdk = "fraclab_sdk.cli:main"
+fraclab-workbench = "fraclab_sdk.workbench.__main__:main"
 
 [build-system]
 requires = ["poetry-core"]

{fraclab_sdk-0.1.0 → fraclab_sdk-0.1.2}/src/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-0.1.0 → fraclab_sdk-0.1.2}/src/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",