matelab-python-sdk 0.2.0a3__tar.gz → 0.2.0a4__tar.gz

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a4}/.github/workflows/release.yml

@@ -84,7 +84,7 @@ jobs:
           uv pip install \
             --python "${RUNNER_TEMP}/matelab-consumer/bin/python" \
             dist/release/*.whl \
-            "basedpyright<2,>=1.40.1" \
+            "basedpyright>=1.40.1" \
             "nodejs-wheel-binaries==22.20.0"
           "${RUNNER_TEMP}/matelab-consumer/bin/python" scripts/check_installed_package.py
           "${RUNNER_TEMP}/matelab-consumer/bin/basedpyright" \

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a4}/AGENTS.md

@@ -4,14 +4,16 @@
 
 ## 维护顺序
 
-1. **定界**：先读 `git status` 和适用权威；完成标准是任务范围、用户现有改动和所需外部权限均已识别。
+1. **定界**：先读 `git status` 和适用权威，确定任务范围、用户现有改动和所需权限。
 2. **查证**：涉及 SDK 行为或 Contract 时，沿 public intent → wire operation → Provider evidence 核对受影响
    operation 的 request、response、security、examples、成功码及 PVD/PCG，明确报告 Contract 缺口。文档、排版和
    工具配置修改只核对相关权威。
 3. **收敛**：只修改任务必需的层，检查 public、adapter、generated、tests、coverage 和 docs 中受影响的内容。
-4. **验证**：按变更类型选择 [delivery gate](docs/agent-workflows.md#delivery-gate)，先运行相关检查；代码变更先跑
-   聚焦测试，再跑完整门槛。完成标准是必需命令全部退出为零，skip 和 deselected 分别说明。
-5. **交付**：复核最终 diff、状态和验证证据；完成标准是结果、限制和未执行项都可由用户独立核对。
+4. **验证**：按变更类型执行 [delivery gate](docs/agent-workflows.md#delivery-gate)，复用仍覆盖当前变更的有效结果。
+5. **交付**：复核最终 diff 和状态，报告结果、验证证据、限制及未执行项。
+
+本地仅为打包配置、构建元数据、发布脚本变化或制品故障按需构建。正式可复现构建、制品审计和安装后消费由
+发布 CI 执行，本地无需重复构建或保留历史 `dist/` 产物。
 
 ## 分支指针
 
@@ -23,8 +25,6 @@
   [`docs/agent-workflows.md#contract-adoption`](docs/agent-workflows.md#contract-adoption)。
 - **Configuration and dependencies**：修改 `pyproject.toml`、依赖范围、lock 或对应 CI 配置时读
   [`docs/agent-workflows.md#configuration-and-dependencies`](docs/agent-workflows.md#configuration-and-dependencies)。
-- **Delivery gate**：交付前按变更类型执行
-  [`docs/agent-workflows.md#delivery-gate`](docs/agent-workflows.md#delivery-gate)。
 - **Provider validation**：任何实时 Provider smoke、读取或 mutation 前执行
   [`docs/agent-workflows.md#provider-validation`](docs/agent-workflows.md#provider-validation)。
 - **Release**：准备版本或发布制品时执行；普通 commit/push 只应用其中的授权与 diff 审查要求
@@ -34,16 +34,16 @@
 
 | 权威 | 负责内容 |
 | --- | --- |
-| `README.md` | 当前 public interface、集成语义、示例及人类流程 |
+| `README.md` | 项目介绍、安装及快速入门 |
+| `docs/api.md` | 当前 public interface、集成语义、完整示例和 Provider 限制 |
+| `docs/development.md` | 开发、验证、版本与构建流程 |
 | `CONTEXT.md` | public 类型和命名采用的领域词汇 |
-| `CHANGELOG.md` | SDK 版本变化与迁移影响；不定义当前接口 |
 | `docs/operation-coverage.yaml` | operation 状态、公开入口、稳定性和已知问题 |
 | `pyproject.toml` | SDK 版本、依赖范围、构建与工具配置；`uv.lock` 只锁定本仓库环境 |
 | Contract lock 与 snapshot | Contract pin 与 wire schema |
 | `src/matelab/__init__.py::__all__` | 公开导入边界 |
 
-机器权威变化时，同一变更同步受影响的当前态文档；历史只追加到 `CHANGELOG.md`。测试提供行为证据，不替代
-接口、coverage 或 Contract 权威。
+机器权威变化时，同一变更同步受影响的当前态文档。测试提供行为证据，不替代接口、coverage 或 Contract 权威。
 
 ## 范围与授权
 

matelab_python_sdk-0.2.0a4/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: matelab-python-sdk
+Version: 0.2.0a4
+Summary: Reusable async Python client for the Matelab Integration Contract
+Author: CMPDC, Institute of Physics, Chinese Academy of Sciences
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: asyncio,electronic-lab-notebook,eln,matelab,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.13.1
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: typing-extensions>=4.16.0
+Description-Content-Type: text/markdown
+
+# matelab-python-sdk
+
+Async Python client for the Matelab Integration Contract, with typed interfaces for authentication,
+notebooks, records, attachments, cloud files, templates, and literature. Requires Python 3.11 or newer.
+
+## Installation
+
+```bash
+uv add matelab-python-sdk
+```
+
+Or use `python -m pip install matelab-python-sdk`.
+
+## Quick start
+
+Replace the example credentials with your own:
+
+```python
+import asyncio
+
+from matelab import AsyncMatelab
+
+
+async def main() -> None:
+    async with AsyncMatelab() as client:
+        await client.authenticate("user@example.org", "password")
+        notebooks = await client.notebooks.list()
+        for notebook in notebooks.owned:
+            print(notebook.ref)
+
+
+asyncio.run(main())
+```
+
+`AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another API root as its first argument.
+
+## Documentation
+
+- [API reference](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/api.md): Session persistence, errors, examples, and Provider limits.
+- [Operation coverage](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/operation-coverage.yaml): supported operations.
+- [Development and releases](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/development.md): checks, Provider smoke, versioning, and builds.

matelab_python_sdk-0.2.0a4/README.md

@@ -0,0 +1,41 @@
+# matelab-python-sdk
+
+Async Python client for the Matelab Integration Contract, with typed interfaces for authentication,
+notebooks, records, attachments, cloud files, templates, and literature. Requires Python 3.11 or newer.
+
+## Installation
+
+```bash
+uv add matelab-python-sdk
+```
+
+Or use `python -m pip install matelab-python-sdk`.
+
+## Quick start
+
+Replace the example credentials with your own:
+
+```python
+import asyncio
+
+from matelab import AsyncMatelab
+
+
+async def main() -> None:
+    async with AsyncMatelab() as client:
+        await client.authenticate("user@example.org", "password")
+        notebooks = await client.notebooks.list()
+        for notebook in notebooks.owned:
+            print(notebook.ref)
+
+
+asyncio.run(main())
+```
+
+`AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another API root as its first argument.
+
+## Documentation
+
+- [API reference](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/api.md): Session persistence, errors, examples, and Provider limits.
+- [Operation coverage](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/operation-coverage.yaml): supported operations.
+- [Development and releases](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/development.md): checks, Provider smoke, versioning, and builds.

matelab_python_sdk-0.2.0a4/docs/agent-workflows.md

@@ -0,0 +1,100 @@
+# Agent Maintenance Workflows
+
+本文件只在对应分支触发时加载。机器值始终从仓库读取；这里记录顺序、授权边界和完成标准。
+
+## Contract adoption
+
+1. 读取 Contract lock 和远端 release refs。只选择新的 annotated tag；移动分支和改写后的旧
+   snapshot 不能成为 SDK pin。记录 tag object、peeled commit、OpenAPI path 与 SHA-256。完成标准：四者固定且
+   互相一致。
+2. 比较当前 snapshot 与 release commit。逐项核对 operation request、response、security、examples、成功码、
+   Provider evidence 及 PVD/PCG。完成标准：每个 schema/operation 差异都分类为 generated-only、adapter、public
+   interface、test、coverage 或 docs 影响。
+3. request/response 均由生成 wire model 校验，adapter 只映射 public Python 名称与 wire 字段。required nullable
+   使用无默认值的 `T | None`；request 拒绝未知字段，response 接受新增字段。若专用 schema、顶层 request 或
+   Provider evidence 相互矛盾，保留当前安全边界并报告缺口。
+4. 从 release commit 复制 OpenAPI snapshot；同一变更更新 lock 的 tag、commit、snapshot path 和 SHA-256，运行
+   生成脚本并审查完整 generated diff。`_generated` 只由生成脚本修改；projection 只补偿生成器表达能力并保留
+   inherited required、`if/then`、`oneOf`、`anyOf` 和 `not`。完成标准：snapshot hash 与 lock 相等，生成差异
+   全部可由 OpenAPI 差异解释，`--check` 确定、非写入且能发现 stale output。
+5. 同步 runtime、测试、operation coverage、README、`docs/api.md`、`docs/development.md`、`pyproject.toml` 与 `uv.lock`
+   中受影响的当前态。
+   完成标准：每个 Contract 差异都有实现或明确 containment，当前文档与采用后的 Contract 一致。
+6. 执行 [delivery gate](#delivery-gate)。
+
+## Configuration and dependencies
+
+配置值以 `pyproject.toml` 为准，`uv.lock` 固定本仓库的解析环境，不反向定义发布依赖范围。
+
+- `[project]` 字段依次为 `name`、`version`、`description`、`requires-python`、`keywords`、`authors`、
+  `dependencies`，其他字段放在其后。
+- `[tool.basedpyright]` 字段依次为 `pythonVersion`、`typeCheckingMode`、`include`、`exclude`、
+  `reportUnannotatedClassAttribute`、`reportIncompatibleUnannotatedOverride`，其他设置放在其后。沿用 SDK 的目标
+  Python 版本与检查路径，不照搬其他项目的值。
+- runtime、build 和 dev 依赖仅声明已验证的 `>=` 下限；`nodejs-wheel-binaries` 保留系统所需的精确版本。
+  更新声明时同步 lock 和安装后消费检查使用的 CI requirement。
+- 构建后端依赖和 wheel package 显式配置；metadata 与制品检查从这些声明推导预期值。
+
+完成标准：配置可解析、声明与 lock 一致、受影响 CI 使用同一约束；字段重排不改变配置含义。
+
+## Delivery gate
+
+按本次变更选择验证范围：
+
+- 纯文档修改检查相关事实、本地路径和 Markdown 引用；示例或接口说明变化要对照当前 public interface。
+- 字段重排或显式写出既有默认值，检查语法与有效配置一致性。工具配置的有效设置变化运行对应工具。
+- SDK 代码、测试行为、Contract、依赖范围或影响制品的构建元数据变化，先跑聚焦测试，再完成下列完整门槛。
+
+### SDK test scope
+
+SDK 测试覆盖 public interface 到 wire adapter 的映射、认证与 Session、错误与重试、stream/上传生命周期及
+分发制品；Provider 的逐路由原始 HTTP conformance 由 `matelab-spec` 负责。
+
+新增或修改 operation 覆盖 method/path/encoding、认证、成功映射及适用的空结果、
+required nullable 和 additive response fields；operation coverage 与 pinned OpenAPI exact match，implemented
+operation 同时具备 public interface、wire adapter 和测试。删除或收紧 public interface 时同步移除过时测试，
+不保留无承诺的墓碑 alias。生成测试覆盖 metadata/checksum、schema、required/nullable、extra policy、确定性和
+stale detection。
+
+优先使用 pinned sanitized examples 或小型受控 fixture 验证稳定行为。operation 数量从 pinned Contract 推导，
+不固定当前数量；当前服务地址和依赖版本值不作为回归断言，除非它们本身就是明确的稳定契约。
+配置值变化只验证语法、约束及相关行为，不另加冻结新值或重复实现逻辑的测试。
+
+Ruff/Basedpyright 诊断通过修复代码或精确 ignore 解决，不缩小检查范围；Basedpyright 目标为 0 errors / 0 warnings。
+
+### Full gate
+
+完整命令见 [开发文档](development.md#development)。离线验证不配置 Provider 连接变量；实时 smoke 按
+[Provider validation](#provider-validation) 执行。
+
+检查因权限失败或无进展时，先查看输出和自己启动的进程，区分普通失败与文件、socket、网络或子进程限制。
+有沙箱阻塞证据后停止自己启动的停滞测试，通过工具审批机制申请最小范围重试；保留配置，不改权限、凭证或测试
+行为来绕过限制。超时本身不是沙箱拒绝的证据；无法升级或被拒绝时报告阻塞。
+
+完成标准：必需检查退出为零，`git diff --check` 无错误；skip 报告测试名称和原因，deselected 说明筛选范围。
+
+## Provider validation
+
+1. 实时验证仅在任务需要且会话授权覆盖目标及副作用时执行；连接设置和 smoke 命令见
+   [开发文档](development.md#opt-in-provider-consumer-smoke)。
+2. 执行前确认目标是隔离服务、`.env.test` 处于 Git ignore、命令显式加载该文件，并列出 authentication、refresh、
+   mutation 或带写痕迹读取的副作用。
+3. mutation 场景在写前记录 fixture，在写后回读，并尽力清理。完成标准：目标、Provider commit、命令、通过数、
+   skip/failure 和清理结果均可追溯；凭证及敏感 payload 未进入输出或提交。
+
+## Release
+
+普通 commit/push 只处理已授权的 diff，不自动改版本、建 tag 或发布。发布准备完成但缺少外部操作授权时，
+先交付可审查结果，再请求执行授权。以下步骤适用于实际发布：
+
+1. 按 [版本规则](development.md#versioning) 选择 SDK 版本，读取 `[project].version`，确认待发布版本未发布
+   且 Contract pin 完整。公开接口删除、重命名、类型收紧或不兼容行为变化按 breaking change 处理。
+   完成标准：版本、当前文档和 tag 名 `v{version}` 一致。
+2. 提交前同步受影响的当前文档，完成 [delivery gate](#delivery-gate)。构建元数据或发布流程变化时，核对
+   metadata 版本与固定的 PyPI 发布 Action 是否兼容；需要本地制品证据时使用
+   [手工构建命令](development.md#reproducible-release-build)。创建已审查、已授权的 release commit。
+3. 创建指向 release commit 的 annotated `v{version}` tag。先推送 `origin` 的 main/tag，再推送 GitHub mirror 的
+   main/tag；只有与项目版本完全匹配的 tag 触发 Trusted Publishing workflow，第三方 Action 固定 immutable
+   commit SHA。
+4. 跟踪 [发布 CI](../.github/workflows/release.yml) 的测试、可复现构建、制品审计、安装后消费和 PyPI publish。
+   完成标准：两个远端 main/tag 对应 release commit，CI 全部通过，PyPI 对应版本可读取。

matelab_python_sdk-0.2.0a3/README.md → matelab_python_sdk-0.2.0a4/docs/api.md

@@ -1,69 +1,22 @@
-# matelab-python-sdk
+# API reference
 
-Reusable async Python client for the Matelab Integration Contract.
+Current public interface, integration semantics, examples, and Provider capability limits.
+See the [README](../README.md) for installation and quick start and [CONTEXT.md](../CONTEXT.md) for domain terminology.
 
-This README describes the current SDK interface, integration semantics, examples, and runnable workflows. See
-[CONTEXT.md](CONTEXT.md) for domain terminology, [CHANGELOG.md](CHANGELOG.md) for version deltas,
-[AGENTS.md](AGENTS.md) for durable maintenance rules, and `docs/operation-coverage.yaml` for the machine-readable
-operation inventory.
-
-The current alpha is `0.2.0a3`. `[project].version` in `pyproject.toml` is the sole SDK version source;
-`uv.lock` only mirrors that source.
+## Contract
 
 The SDK is pinned to the immutable `matelab-spec v2026.10.1` Contract Release. The sole pin,
-`contracts/matelab-integration-v1.lock.json`, records peeled commit `9941e2d623a1c2633adb459b823d78d4e62d3802`,
-source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path, and SHA-256
-`a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813`. The annotated tag object is
+[contracts/matelab-integration-v1.lock.json](../contracts/matelab-integration-v1.lock.json), records peeled commit
+`9941e2d623a1c2633adb459b823d78d4e62d3802`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
+and SHA-256 `a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813`. The annotated tag object is
 `ae8098e1b5178b69706bddd8b70c1b4cfe3e09ba`.
 
-## Installation
-
-Python 3.11 or newer is required. Install the alpha from a package index with either:
-
-```bash
-uv add matelab-python-sdk
-```
-
-```bash
-python -m pip install matelab-python-sdk
-```
-
-Development installs use the locked checkout:
-
-```bash
-uv sync --frozen
-```
-
-To test the same artifact a downstream Consumer will install, build and install the wheel:
-
-```bash
-uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.2.0a3-py3-none-any.whl
-```
-
-Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
-tag, commit, and checksum recorded below.
-
 The Contract uses Provider source evidence from `3f39d47b7ad43bed618b029a7d9cc51fab852eb6`; v2026.10.1 validation ran
-against an isolated test instance and does not establish production behavior. The corresponding Front Consumer evidence
-is `0c985f5b6da8e8ef4627ca7065cea85e408ae981`; it informs cross-Consumer capability review but does not define the SDK
-interface. Provider limitations that remain relevant to integrations are documented alongside the affected interfaces
-below.
-
-Contract releases now use calendar versions to identify Provider-specific snapshots. This snapshot covers the
-Workerman runtime with the `localhost` data-server branch for ELN records and attachments; remote data-server
-forwarding is outside its verified callable scope (PVD-049).
-
-## Versioning
+against an isolated test instance and does not establish production behavior. The Front Consumer evidence
+`0c985f5b6da8e8ef4627ca7065cea85e408ae981` informs cross-Consumer capability review but does not define the SDK interface.
 
-SDK versions express compatibility of the public Python interface and behavior. Python prerelease spelling follows
-PEP 440: `0.2.0a3` is the third alpha candidate for `0.2.0`. During `0.x` development, incompatible changes advance
-the minor version. From `1.0.0`, compatible fixes advance patch, compatible additions advance minor, and incompatible
-changes advance major. Successive candidates for the same target version use `aN`, `bN`, or `rcN`.
-
-Contract calendar versions identify Provider wire snapshots independently. Each SDK release records its exact
-Contract tag, commit and checksum in the lock; multiple SDK fixes can use the same Contract release. Adopting a new
-Contract changes the SDK version according to its public impact. See [CHANGELOG.md](CHANGELOG.md) for migration details.
+This snapshot covers the Workerman runtime with the `localhost` data-server branch for ELN records and attachments;
+remote data-server forwarding is outside its verified callable scope (PVD-049).
 
 ## Design
 
@@ -868,94 +821,3 @@ Errors are separated into semantic Provider errors, authentication errors, HTTP/
 Integration Contract response errors, and client-side usage errors. Semantic Provider errors retain only the
 Contract-defined top-level code plus an SDK-owned safe summary; Provider-authored messages, response bodies, legacy
 aliases, and unrelated fields do not enter exceptions.
-
-## Development
-
-```bash
-uv sync --frozen
-uv run python scripts/generate_models.py --check
-uv run ruff check .
-uv run ruff format --check .
-uv run basedpyright
-uv run pytest -m 'not provider'
-uv build --no-build-isolation
-```
-
-This gate checks the SDK with offline fixtures and excludes the real Provider smoke. Run focused tests first when
-changing code; documentation and configuration-only edits use the relevant checks described in
-[the maintenance workflows](docs/agent-workflows.md#delivery-gate). Contract or generator changes regenerate the
-private models with `uv run python scripts/generate_models.py` before running the gate.
-
-The generator first verifies the contract lock, OpenAPI release metadata, and snapshot digest. It then
-creates a temporary OpenAPI 3.1 generation projection, resolves references without network access, and
-generates private component, operation-response, and parameter models. Generator emission uses its built-in formatter;
-the checked-in output is then normalized using the repository `pyproject.toml` as the sole Ruff configuration. The
-projection flattens pure
-object inheritance and preserves constraints the model generator cannot express as self-contained JSON Schema
-2020-12 metadata; the checked-in release snapshot remains unchanged. `--check` performs the same validation and
-deterministic generation without writing the checked-in models. `WireModel` applies that metadata with the standard
-`jsonschema` Draft 2020-12 validator; the SDK does not maintain a second hand-written schema interpreter.
-
-`pyproject.toml` declares runtime, build, and development compatibility ranges; `uv.lock` fixes the exact environment
-for development and release builds. Runtime and build lower bounds are verified against the complete test suite on
-the supported Python boundary versions. The sole exact development requirement is `nodejs-wheel-binaries`, retained
-for system compatibility. The `0.x` generator and Ruff ranges allow patch updates within their current minor versions.
-
-## Opt-in Provider consumer smoke
-
-`tests/provider/test_provider_smoke.py` exercises the consumer flow through only the public SDK interface. Its base
-scenario covers credential authentication, persistence of the complete returned Session, restoration through a new
-`AsyncMatelab` instance, refresh with identity preservation, and notebook discovery. The development gate excludes it;
-a direct pytest run skips it if any of its three connection variables are missing.
-
-Raw Provider conformance remains the responsibility of `matelab-spec`, which sends direct HTTP requests and validates
-the unmodified responses. The SDK does not repeat its route-by-route, cross-account, sharing, or attachment-isolation
-verification. Representative SDK adapter tests instead feed the pinned OpenAPI's sanitized response examples through
-`MockTransport` and assert the resulting public values; synthetic fixtures remain where SDK-specific encoding,
-error, retry, and compatibility boundaries require evidence beyond those examples.
-
-Provider smoke is restricted to the confirmed isolated test service. Authentication and refresh persist Provider
-token state. This side effect is inherent to the tested Provider operations; it cannot be disabled by a test setting.
-Explicitly loading `.env.test` and selecting the `provider` marker is the opt-in for this flow.
-
-SDK smoke can use the same isolated `matelab-test` service as `matelab-spec`. Each repository keeps its own test
-configuration: the SDK uses `.env.test`, and spec keeps its existing `.env`.
-
-Copy this repository's `.env.example` to the git-ignored local `.env.test`, then fill in the SDK connection settings:
-
-- `MATELAB_PROVIDER_BASE_URL`
-- `MATELAB_PROVIDER_USERNAME`
-- `MATELAB_PROVIDER_PASSWORD`
-
-These names intentionally match `matelab-spec` Provider Verification. Refreshing the restored Session must preserve
-its authenticated identity. With the SDK environment prepared, run the public-interface smoke:
-
-```bash
-uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
-```
-
-This command runs only the SDK public-interface smoke; Provider Verification is maintained in
-`matelab-spec` with its own configuration and run instructions.
-SDK tests do not load `.env.test` implicitly; without Provider environment variables, the real smoke remains skipped.
-Offline SDK tests continue to use `MockTransport`. Do not use the smoke flow against production, and never commit
-Provider credentials.
-
-## Reproducible release build
-
-Build from a clean release commit (or its tag) and set the archive timestamp to that commit's
-committer timestamp. `pyproject.toml` declares the supported Hatchling range, while `uv.lock` supplies the
-exact version used by the frozen, no-build-isolation release environment:
-
-```bash
-export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
-uv sync --frozen
-uv run python scripts/generate_models.py --check
-uv build --no-build-isolation --out-dir dist/release
-uv run python scripts/check_release.py dist/release/*.whl dist/release/*.tar.gz
-(cd dist/release && sha256sum *.whl *.tar.gz > SHA256SUMS)
-```
-
-Rebuilding the same commit with the same locked environment and `SOURCE_DATE_EPOCH` must produce
-byte-identical wheel and source distribution hashes. The SDK Contract pin is immutable `matelab-spec v2026.10.1`, commit
-`9941e2d623a1c2633adb459b823d78d4e62d3802`, and OpenAPI SHA-256
-`a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813`.

matelab_python_sdk-0.2.0a4/docs/development.md

@@ -0,0 +1,68 @@
+# Development and releases
+
+Development, testing, versioning, and build procedures. See the [README](../README.md) for installation and quick start.
+
+## Versioning
+
+SDK versions describe public Python compatibility. During `0.x`, incompatible changes advance the minor version.
+From `1.0.0`, compatible fixes advance patch, compatible additions advance minor, and incompatible changes advance major.
+PEP 440 prereleases use `aN`, `bN`, or `rcN`; counters increase within each phase and restart at 1 for a new target version.
+`[project].version` in `pyproject.toml` is the sole SDK version source.
+
+Contract calendar versions identify wire snapshots independently. Each SDK release records its exact pin in the
+Contract lock. Multiple SDK releases can share a Contract pin; adopting a new Contract changes the SDK version
+according to its public impact.
+
+## Development
+
+```bash
+uv sync --frozen
+uv run python scripts/generate_models.py --check
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest
+```
+
+Choose checks by change type using the
+[maintenance workflows](agent-workflows.md#delivery-gate).
+Contract or generator changes regenerate private models with `uv run python scripts/generate_models.py` before checking.
+`pyproject.toml` declares dependency minimums; `uv.lock` fixes the development and release environment.
+
+## Opt-in Provider consumer smoke
+
+The smoke checks authentication, complete Session persistence and restoration, refresh with identity preservation,
+and notebook discovery through the SDK. Raw HTTP conformance remains in `matelab-spec`.
+Both repositories can use the same isolated `matelab-test` service, with separate configuration files:
+SDK `.env.test` and spec's existing `.env`.
+
+Copy [.env.example](../.env.example) to the git-ignored SDK
+`.env.test` and fill in `MATELAB_PROVIDER_BASE_URL`, `MATELAB_PROVIDER_USERNAME`, and `MATELAB_PROVIDER_PASSWORD`.
+Tests read process environment variables; they do not load environment files implicitly. Ordinary `pytest` skips the
+smoke when any variable is missing and runs it when all are set.
+
+```bash
+uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
+```
+
+Authentication and refresh persist Provider token state. Follow
+[Provider validation](agent-workflows.md#provider-validation)
+for target authorization and keep credentials out of Git.
+
+## Reproducible release build
+
+A `v*` release tag pushed to GitHub triggers CI to build twice, compare wheel/sdist bytes, audit artifacts, verify an
+installed-wheel consumer, and publish to PyPI. Preparation follows the
+[release workflow](agent-workflows.md#release).
+
+Local builds are only needed for packaging changes or artifact diagnostics. To reproduce CI artifacts, use the release
+tag's checkout and committer timestamp, the locked environment, and a temporary output directory:
+
+```bash
+export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
+sdk_release_build_dir="$(mktemp -d)"
+uv sync --frozen
+uv build --no-build-isolation --out-dir "$sdk_release_build_dir"
+uv run python scripts/check_release.py "$sdk_release_build_dir"/*.whl "$sdk_release_build_dir"/*.tar.gz
+(cd "$sdk_release_build_dir" && sha256sum *.whl *.tar.gz > SHA256SUMS)
+```

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a4}/docs/operation-coverage.yaml

@@ -1,4 +1,4 @@
-# Machine-readable operation inventory only. Current usage belongs in README.md, release history in CHANGELOG.md,
+# Machine-readable operation inventory only. Full interface documentation belongs in docs/api.md,
 # and durable maintenance policy in AGENTS.md.
 schema_version: 1
 contract:

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a4}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["hatchling>=1.32.4,<2"]
+requires = ["hatchling>=1.32.4"]
 build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.2.0a3"
+version = "0.2.0a4"
 description = "Reusable async Python client for the Matelab Integration Contract"
 requires-python = ">=3.11"
 keywords = ["matelab", "electronic-lab-notebook", "eln", "asyncio", "sdk"]
@@ -12,11 +12,12 @@ authors = [
     { name = "CMPDC, Institute of Physics, Chinese Academy of Sciences" },
 ]
 dependencies = [
-    "httpx2>=2.13.1,<3",
-    "jsonschema>=4.26.0,<5",
-    "pydantic>=2.13.5,<3",
-    "typing-extensions>=4.16.0,<5",
+    "httpx2>=2.13.1",
+    "jsonschema>=4.26.0",
+    "pydantic>=2.13.5",
+    "typing-extensions>=4.16.0",
 ]
+readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 classifiers = [
@@ -36,14 +37,14 @@ classifiers = [
 
 [dependency-groups]
 dev = [
-    "basedpyright>=1.40.1,<2",
+    "basedpyright>=1.40.1",
     "nodejs-wheel-binaries==22.20.0",
-    "datamodel-code-generator>=0.83.0,<0.84",
-    "hatchling>=1.32.4,<2",
-    "pytest>=9.1.1,<10",
-    "pytest-asyncio>=1.4.0,<2",
-    "pyyaml>=6.0.3,<7",
-    "ruff>=0.16.10,<0.17",
+    "datamodel-code-generator>=0.83.0",
+    "hatchling>=1.32.4",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pyyaml>=6.0.3",
+    "ruff>=0.16.10",
 ]
 
 [tool.ruff]

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a4}/scripts/check_release.py

@@ -147,7 +147,6 @@ def _audit_sdist(path: Path) -> None:
         if root != expected_root or path.name != f"{root}.tar.gz":
             raise ValueError(f"{path.name} contains an unexpected source-distribution root")
         required = {
-            f"{root}/CHANGELOG.md",
             f"{root}/LICENSE",
             f"{root}/NOTICE",
             f"{root}/PKG-INFO",

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a4}/tests/test_release.py

@@ -113,7 +113,7 @@ def test_lockfile_mirrors_project_version() -> None:
     assert sdk_packages[0]["version"] == project["version"]
 
 
-def test_release_dependencies_publish_verified_compatibility_ranges() -> None:
+def test_release_dependencies_publish_minimum_versions() -> None:
     pyproject = tomllib.loads((_ROOT / "pyproject.toml").read_text())
     build_system = cast(dict[str, object], pyproject["build-system"])
     project = cast(dict[str, object], pyproject["project"])
@@ -124,7 +124,7 @@ def test_release_dependencies_publish_verified_compatibility_ranges() -> None:
     dev = {requirement.name: requirement for requirement in map(Requirement, dependency_groups["dev"])}
     assert all(requirement.specifier and requirement.url is None for requirement in (*runtime, *build, *dev.values()))
     ranged = (*runtime, *build, *(requirement for name, requirement in dev.items() if name != "nodejs-wheel-binaries"))
-    assert all({bound.operator for bound in requirement.specifier} == {">=", "<"} for requirement in ranged)
+    assert all({bound.operator for bound in requirement.specifier} == {">="} for requirement in ranged)
     assert {bound.operator for bound in dev["nodejs-wheel-binaries"].specifier} == {"=="}
     assert build == [dev["hatchling"]]
     assert project["license"] == "Apache-2.0"

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a4}/uv.lock

@@ -362,7 +362,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.2.0a3"
+version = "0.2.0a4"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },
@@ -385,22 +385,22 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "httpx2", specifier = ">=2.13.1,<3" },
-    { name = "jsonschema", specifier = ">=4.26.0,<5" },
-    { name = "pydantic", specifier = ">=2.13.5,<3" },
-    { name = "typing-extensions", specifier = ">=4.16.0,<5" },
+    { name = "httpx2", specifier = ">=2.13.1" },
+    { name = "jsonschema", specifier = ">=4.26.0" },
+    { name = "pydantic", specifier = ">=2.13.5" },
+    { name = "typing-extensions", specifier = ">=4.16.0" },
 ]
 
 [package.metadata.requires-dev]
 dev = [
-    { name = "basedpyright", specifier = ">=1.40.1,<2" },
-    { name = "datamodel-code-generator", specifier = ">=0.83.0,<0.84" },
-    { name = "hatchling", specifier = ">=1.32.4,<2" },
+    { name = "basedpyright", specifier = ">=1.40.1" },
+    { name = "datamodel-code-generator", specifier = ">=0.83.0" },
+    { name = "hatchling", specifier = ">=1.32.4" },
     { name = "nodejs-wheel-binaries", specifier = "==22.20.0" },
-    { name = "pytest", specifier = ">=9.1.1,<10" },
-    { name = "pytest-asyncio", specifier = ">=1.4.0,<2" },
-    { name = "pyyaml", specifier = ">=6.0.3,<7" },
-    { name = "ruff", specifier = ">=0.16.10,<0.17" },
+    { name = "pytest", specifier = ">=9.1.1" },
+    { name = "pytest-asyncio", specifier = ">=1.4.0" },
+    { name = "pyyaml", specifier = ">=6.0.3" },
+    { name = "ruff", specifier = ">=0.16.10" },
 ]
 
 [[package]]