Metadata-Version: 2.4
Name: matelab-python-sdk
Version: 0.1.0a3
Summary: Reusable async Python client for the Matelab Integration Contract
Author-email: 朱天念 <zhutiannian@gmail.com>
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<3,>=2.9.1
Requires-Dist: pydantic<3,>=2.13.4
Description-Content-Type: text/markdown

# matelab-python-sdk

Reusable async Python client for the Matelab Integration Contract.

The current alpha is `0.1.0a3`. `[project].version` in `pyproject.toml` is the sole SDK version source;
`uv.lock` only mirrors that source.

The SDK is pinned to the immutable `matelab-spec v0.1.1` Contract Release. The sole release pin is
`contracts/matelab-integration-v1.lock.json`, which records
the source tag, commit, OpenAPI path, local snapshot path, and SHA-256.

## 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.1.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.

## Design

The public module is intentionally small:

```python
from matelab import AsyncMatelab

async with AsyncMatelab() as client:
    session = await client.authenticate("user@example.org", "password")
    assert client.session is session
    notebooks = await client.notebooks.list()
    notebook = notebooks.owned[0].ref
    records = await client.records.list(notebook=notebook)
    record = await client.records.read(notebook=notebook, record=records.records[0].ref)
```

`AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another Provider API root
explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`.

### Session ownership

Each `AsyncMatelab` instance owns at most one current, process-local `Session`. The SDK injects its bearer
token, refreshes it under a per-instance async lock, performs bounded safe retries, and exposes every token
rotation through `client.session`. If refresh succeeds but the subsequent business request fails,
`client.session` still contains the refreshed token pair.

| SDK responsibility | Integrator responsibility |
|---|---|
| Bearer injection, expiry checks, refresh and bounded retry | Redis/database/file persistence and encryption |
| Per-instance, in-process refresh serialization | Cross-process locking and conflict handling |
| Contract validation of token and identity responses | Mapping `userid`/`session_id` to a persisted `Session` |
| Latest immutable `Session` through `client.session` | Revocation, cleanup, and saving after each call |

`Session`, `Token`, and `Identity` are immutable value objects, and token values are excluded from their
representations. The SDK does not read tokens from environment variables and does not provide a session store.

Credential authentication installs the returned Session on the client:

```python
async with AsyncMatelab() as client:
    session = await client.authenticate(username, password)
    assert client.session is session
```

External token exchange validates the original access-token identity, refreshes the supplied refresh token,
validates the refreshed access-token identity, and rejects a userid mismatch. The existing client Session is
replaced only after all three steps succeed:

```python
async with AsyncMatelab() as client:
    session = await client.bind_external_tokens(access_token, refresh_token)
    assert client.session is session
```

Restore a previously validated Session by passing it to the constructor. Construction performs no network request:

```python
persisted_session = await session_store.load(userid, session_id)

async with AsyncMatelab(session=persisted_session) as client:
    result = await handle_request(client)
```

A Web or MCP integration should create one client for one logical session, then save the latest Session in
`finally`, including when a business call fails after refresh:

```python
persisted_session = await session_store.load(userid, session_id)
client = AsyncMatelab(session=persisted_session, http_client=shared_http_client)

try:
    result = await handle_request(client)
finally:
    latest_session = client.session
    try:
        if latest_session is not None:
            await session_store.save(userid, session_id, latest_session)
    finally:
        await client.aclose()
```

If several processes can use the same persisted session, the integration must place its own distributed lock
around load, use, and save. The SDK lock only coordinates refreshes inside one `AsyncMatelab` instance.

Different logical sessions require different clients. They may reuse the same externally managed HTTP connection
pool, but must never share one global `AsyncMatelab` singleton:

```python
alice_client = AsyncMatelab(session=alice_session, http_client=shared_http_client)
bob_client = AsyncMatelab(session=bob_session, http_client=shared_http_client)
```

An injected `http_client` must be an `httpx2.AsyncClient`. The independently distributed `httpx.AsyncClient` has
similar methods but uses incompatible request, response, transport, and exception types.

`src/matelab/_generated` is a private wire layer. Applications should not depend on its file
layout or generated class names. The distribution includes `py.typed`, so type checkers can consume the
public annotations directly from an installed wheel.

The current public domain scope includes authentication, group/user discovery, template and notebook
lifecycle operations, record discovery/lifecycle operations, comment reads, and streaming record or
comment attachment downloads, resumable file staging, literature discovery/lifecycle workflows, and
personal cloud-drive management.

### Staging a record attachment before record creation

`records.stage_attachment` supports the Contract's pre-upload workflow without inventing a target record UID.
The returned `StagedNotebookAttachment` is scoped by the SDK to the resolved authenticated user and the exact
notebook selector used for upload:

```python
import hashlib

from matelab import RecordImportItem, RecordImportTemplate, TemplateRef

content = b"measurement data"
staged = await client.records.stage_attachment(
    notebook=notebook,
    filename="measurement.csv",
    content=content,
    size=len(content),
    sha256=hashlib.sha256(content).hexdigest(),
)
result = await client.records.import_dataset(
    notebook=notebook,
    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
    items=(
        RecordImportItem(
            record_uid="REC-IMPORT-001",
            title="Imported measurement",
            data={"Attachments": {"File": [staged]}},
        ),
    ),
)
```

The same staged handle may instead be consumed by one safe update that adds a new file field to an existing form
module:

```python
from matelab import RecordFormAttachmentFieldAddition, RecordPatch

# Alternative to the import above; do not run both with the same staged handle.
result = await client.records.update(
    source,
    RecordPatch(
        attachment_changes=(
            RecordFormAttachmentFieldAddition(
                module="Attachments",
                name="Measurement",
                attachment=staged,
            ),
        )
    ),
)
```

Choose exactly one finalizer. A staged name may occur once in either a single-record import or one update
operation; do not reuse it, even after an error whose Provider outcome is unknown. The SDK rejects raw Provider
attachment references, cross-user or cross-notebook handles, unsafe update shapes, duplicate use in one request,
and a second finalization attempt through the same client. A Session imported without identity must first call
`await client.resolve_identity()`. The Provider supplies no staging status, abort, TTL, atomicity, or retry
guarantee, so callers must discard the handle as soon as a finalization request starts.

## Implementation roadmap

`docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
`matelab-spec v0.1.1` operations to ordered work packages, defines the machine-readable coverage that
must be added, records Provider-risk gates, and specifies the final completion checks.

The SDK exposes all 71 Contract operations through public domain interfaces. It deliberately excludes MCP
migration, adjacent-repository changes, external
publishing, and automatic mutation against a real Provider.

Machine-readable status lives in
`docs/operation-coverage.yaml`. An exact-coverage test keeps its 71
operation IDs, methods, paths, work packages, and Provider issue references aligned with the pinned
OpenAPI snapshot.

| Domain | Implemented | Planned | Current public surface |
|---|---:|---:|---|
| Authentication | 4 | 0 | `authenticate`, `bind_external_tokens`, `refresh`, `resolve_identity`, `exchange_chat_sso_code` |
| Groups and users | 2 | 0 | `groups.list`, `users.search` |
| Notebooks | 6 | 0 | `notebooks.list/create/update/shares/share/update_share/unshare` |
| Records | 18 | 0 | Discovery, reads, lifecycle, typed patch/attachments, relations, and downloads |
| Comments | 5 | 0 | Read, staged attachment upload, create/update/delete, and download |
| Templates | 13 | 0 | Discovery, content, lifecycle, sharing, groups, and marketplace |
| File staging | 1 | 0 | Resumable fragment staging and compensating abort request |
| Literature | 13 | 0 | Libraries, items, canonical metadata, comments, sharing, PDF lifecycle and streaming |
| Cloud drive | 9 | 0 | Personal root/folders/files, staged binding, metadata, move/delete and streaming |
| **Total** | **71** | **0** | No operation is intentionally unexposed |

### Stability and known capability limits

Coverage currently contains 15 `stable` and 56 `experimental` operations. The stable operation IDs are
`resolveCurrentIdentity`, `loginTokenSet`, `refreshTokenSet`, `exchangeChatSsoCode`,
`shareMultipleTemplatesWithUsers`, `removeTemplateFromGroup`, `deleteNotebookShare`, `listNotebooks`,
`listNotebookRecords`, `exportRecords`, `deleteRecordsByUid`, `copyRecord`, `readRecord`,
`deletePersonalLiteratureItem`, and `readLiteratureCreateTemplate`.

Every other implemented operation is explicitly `experimental`; the exact per-operation list and its
PVD/PCG references live in
`docs/operation-coverage.yaml`. There are no `intentionally_unexposed`
operations and no `planned` operations. Experimental support means the SDK validates and exposes the
pinned Contract while preserving limitations such as unstable ordering/pagination, incomplete mutation
acknowledgements, missing batch atomicity or idempotency, weak attachment ownership binding, and known
Provider authorization gaps. It does not turn those limitations into SDK guarantees.

Chat iframe SSO consumes a one-time code and shared key. Both arguments are treated as secrets, the request is never
automatically retried, and the returned token set is stored in the same in-memory `Session` shape as credential login:

```python
session = await client.exchange_chat_sso_code(code="chat-sanitizedcode123", key="sanitized-shared-key")
```

Group and user discovery expose sharing identities without inventing Provider pagination:

```python
from matelab import UserSearchScope

groups = await client.groups.list()
targets = await client.users.search("Example Researcher", scope=UserSearchScope.SAME_INSTITUTE)
```

Ordering remains Provider-unspecified and is documented rather than repeated as a constant result field. Group
members belong only to `groups.members_for`, not to every returned group. These two discovery interfaces are experimental because the
Provider returns members for an unstable first group and user search is unpaged, unordered, and not field-minimized
(PVD-006, PVD-029, PCG-011).

Notebook create/update and direct sharing keep write acknowledgement separate from what a readback can prove:

```python
from matelab import NotebookMetadata, NotebookSharePermissionGrant

await client.notebooks.create(NotebookMetadata(title="Example Notebook"))
shares = await client.notebooks.share(notebook, [target.ref])
updated = await client.notebooks.update_share(shares[0].ref, NotebookSharePermissionGrant(write=True, create=True))
```

Create returns `None` because the Provider returns no identity. Owned updates return the notebook row observed by
database ID, or `None` when it is missing, containing PVD-003 false success without claiming an atomic guarantee.
Share returns only requested relations visible during readback, and permission updates return the observed relation
or `None`. A stored share mask of zero still has effective read access (PVD-010), and share-list order remains
unspecified.

Template discovery keeps a template database identity separate from direct-share, market-acquisition, and group
relation identities:

```python
templates = await client.templates.list()
market = await client.templates.search_market("calibration", page=1, page_size=20)
content = await client.templates.read(templates.owned[0].ref)
```

The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
value derived from the total; it does not claim a stable order or continuation token. Canonical
modules are mapped to public `TemplateModule` values and retain additive module attributes. Template reads remain
experimental because Provider discovery ordering/pagination and historical `images` compatibility are not fully
stable (PCG-003, PCG-009, PVD-013, PVD-022).

Template writes remain separate operations: metadata, canonical modules, and usage HTML are not presented as one
transaction. Metadata create returns the Provider template ID plus an optional observed summary; copy and share
return `None` because the Provider supplies no new identity or per-recipient rows. Group addition and market
acquisition return the observed relation or `None`, while removal returns readback-confirmed absence as `bool`.
Direct-share, market-acquisition, and group relation refs remain distinct. Marketplace revision and uploader-binding
limitations are documented operation semantics rather than constant fields on every result (PVD-021, PVD-026).
`UploadBindingRef.new()` creates the fresh hidden correlation value required by intro attachment binding.

Extended record reads stay behind the same `records` interface:

```python
from matelab import RecordFieldExtraction, RecordLocator

exported = await client.records.export([RecordLocator(notebook=notebook, record=record)])
matches = await client.records.search(
    notebooks=[notebook], extractions=[RecordFieldExtraction(alias="notes", path=("Notes",))]
)
page = await client.records.page(notebook)
deleted = await client.records.recycle_bin(notebook)
relations = await client.records.relations(notebook=notebook, record=record)
```

`records.page` fixes the legacy request to `page_size=0&default=1`, preventing the known owner-preference writes
described by PVD-039; its total is derived from the Provider's complete matching ID list. Public catalog records and
deleted records use identities distinct from active `RecordRef`. Relation targets separately expose declared and
resolved notebook IDs because the Provider may return dangling or incomplete identities. Search and relation order
remain unspecified, and no continuation token is invented.

Record creation keeps blank creation and structured import as separate capabilities:

```python
from matelab import RecordImportItem, RecordImportTemplate, TemplateRef

blank = await client.records.create_blank(notebook=notebook, title="Blank Record", record_uid="caller-generated-uid")
imported = await client.records.import_dataset(
    notebook=notebook,
    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
    items=[RecordImportItem(record_uid="import-uid", title="Imported", data={"Notes": "value"})],
)
```

A caller-supplied blank-record UID returns its matching readback; when the Provider generates it, create returns
`None` rather than inventing identity. Import validates the complete batch with generated wire models but cannot map returned database
IDs to individual inputs or promise atomicity (PCG-008). Delete means moving records into the recycle bin, not
permanent deletion. Delete and restore results classify only post-write observations; restore never treats an active
row with the same UID but a different database ID as proof of success (PCG-005). Record mutations are not
automatically retried.

Record patching exposes a deliberately narrower capability than the raw Provider operation. Scalar/module changes
cannot smuggle Provider-native attachment strings; staged attachments use separate form-removal, table-replacement,
files append/replace/remove, and rich-text types. Unsafe form replacement and table-file removal are absent, while a
files/images removal is rejected when the observed module contains the same hash more than once (PVD-014 through
PVD-016). `Record.content_sha256` can be supplied as a client-side precondition, documented as advisory
read-before-write rather than Provider CAS. `RecordUpdateResult` retains only the before/after evidence and whether
the acknowledgement means persisted, pending browser save, or unclassified. Database, active-browser, and unclassified acknowledgements
remain distinct, and mutation retries stay disabled.

Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-019
risk but is not an atomic Provider authorization guarantee. Relation addition returns matching relations observed
afterward. Relation deletion refuses an observed cross-notebook target-ID collision because the Provider ignores
target notebook identity (PVD-020), then returns the complete post-write relation snapshot.

Comment upload follows the Provider's literal one-request `upload` field, not the incompatible Front fragment
protocol (PVD-037). Comment create/update return matching post-write comment rows; delete returns whether the selected
comment is absent. Edit and delete require a currently observed caller-owned comment and read it back, containing the
Provider's edit false-success behavior (PVD-004). Staged comment attachments have no Contract abort operation, and
binding remains affected by PVD-026.

Attachment bytes are streamed and must be consumed or closed explicitly:

```python
from matelab import ByteRange

comments = await client.records.comments(notebook=notebook, record=record)
attachment = comments.comments[0].attachments[0]
async with await client.records.download_comment_attachment(attachment, byte_range=ByteRange.from_start(0)) as download:
    async for chunk in download:
        consume(chunk)
```

`DownloadStream` exposes status, content type, length, range, and disposition metadata without buffering the
complete file. Streams are not automatically replayed. `ByteRange` deliberately rejects `bytes=0-0` (PVD-002).
Comment attachment refs preserve the notebook/record/comment context where they were observed, but they are not
Provider authorization credentials: current Providers do not verify that association (PVD-038).

Cross-domain staging keeps resumable state and completed-file identity separate:

```python
import hashlib

from matelab import StagedFile

pdf_bytes = b"sanitized PDF bytes"
staged = await client.uploads.stage(
    pdf_bytes,
    filename="example.pdf",
    fragment_size=len(pdf_bytes),
    complete_sha256=hashlib.sha256(pdf_bytes).hexdigest(),
)
assert isinstance(staged, StagedFile)
```

For multiple fragments, pass `StagedFileFragment.session` into the next call. `next_offset` is explicitly a
caller-side total derived from declared fragment sizes; the Provider does not confirm an offset. A final result
contains the Provider hash, size, temporary row identity and fresh hidden binding value, but does not claim that a
later literature/cloud operation checks the uploader or consumes the file exactly once. `uploads.abort` exposes the
Provider's legacy code-2 cancellation signal as a `None`-returning compensating cleanup that is not independently
verified (PVD-028).
Staging mutations are never automatically retried.

Literature identities distinguish the personal library, shared libraries and pending incoming copies:

```python
from matelab import DoiMetadataSource, LiteratureMetadata

libraries = await client.literature.libraries()
page = await client.literature.list(libraries.personal.ref)
detail = await client.literature.read(page.items[0].ref)
schema = await client.literature.creation_schema()

if schema.metadata_extraction_available:
    candidates = await client.literature.extract_metadata(DoiMetadataSource("10.0000/example"))

await client.literature.create(LiteratureMetadata(title="Example import", doi="10.0000/example"), staged_pdf=staged)
```

Create returns `None` and never guesses the new item from list position because the Provider returns no ID. Canonical update reads the
item first and refuses to drop source/hidden fields unless `allow_source_metadata_loss=True` is explicit (PVD-027).
PDF replace/delete are separate, read-back-verified mutations and are not presented as atomic with metadata
(PCG-010). Permanent personal deletion is named `permanently_delete` and returns snapshot-confirmed absence as a
`bool`; the operation is non-recoverable. Sharing requires list-observed item summaries, user-search summaries and a
resolved caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-012, PVD-036).

Literature comments use one public save intent: detail is read first, an existing caller-owned comment is edited, and
otherwise a comment is created. Multiple caller-owned comments are rejected as ambiguous (PVD-035). A staged
attachment can replace one `matelab-staged-file` marker; raw temporary URLs are rejected. These checks contain common
misuse but do not repair the Provider's cross-user UID lookup (PVD-026). Shared-library reads and writes remain
experimental because the Provider permission JOIN is not scoped to the current user (PVD-011); successful SDK calls
must not be treated as independent authorization proof. Literature PDF downloads reuse `DownloadStream` and the
stable `ByteRange` subset.

The personal cloud-drive surface keeps root, folder, final file and temporary staging identities separate:

```python
from matelab import CloudFolderMetadata

listing = await client.cloud_drive.list()
folder_result = await client.cloud_drive.create_folder(CloudFolderMetadata(name="Example data"))
matches = await client.cloud_drive.bind_staged_file(staged, target=folder_result.folder)

if len(matches) == 1:
    renamed = await client.cloud_drive.update_file(
        matches[0], filename="example-renamed.pdf", description="Sanitized description"
    )
```

`CloudDriveListing` contains a typed file page, complete folder tree, quota usage and personal-root permissions rather
than flattening them into one ambiguous collection. Folder browse results retain their location; filename searches
are explicitly root-wide and return `location=None` because the Provider omits each match's folder ID. Ordering has
no stable ID tie-breaker (PCG-003, PVD-013).

Folder create returns the Provider ID plus an optional observed folder, and all folder mutations read back the
complete tree. Staged finalize accepts a completed `StagedFile`, then paginates the target folder and returns all
exact filename/hash/size matches; zero, one, or multiple results preserve missing and ambiguous observations without
another result model. This is useful evidence, not an uploader-ownership guarantee: the Provider binds by
temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain absent (PCG-012).
Batch move returns identities observed in the target, while permanent delete returns identities confirmed absent;
neither claims Provider per-item results or atomicity. Permanent deletion is named `permanently_delete_files` and is
non-recoverable. Cloud downloads
resolve bytes from the final file identity and reuse `DownloadStream`, thumbnail/preview choices and the PVD-002-safe
range subset. Cloud mutations are not automatically retried.

To run the implementation as a persistent Codex goal, start a task in this repository and use:

> 完整阅读并严格遵循 `AGENTS.md`、`README.md` 和 `docs/roadmap.md`。创建并持续执行一个 goal：
> 只修改当前仓库，按照 roadmap 从第一个未完成 work package 开始，完成 71-operation 精确覆盖和全部
> SDK 领域 interface；每个 package 通过局部验证后自动继续，最终让 generation `--check`、Ruff、
> Ruff format、Basedpyright、Pytest 和 package build 全部通过。不要修改相邻仓库，不执行生产 Provider
> mutation，不 commit、push、tag 或发布。

Owned/shared `NotebookRef`, public `PublicNotebookRef`, `RecordRef`, and `RecordVersionRef` keep
Provider identifiers distinct. Historical reads first re-read the authorized current record and confirm
that the requested version is still present in its `modify_log`; both reads write Provider audit entries.

Errors are separated into Provider business errors, authentication errors, HTTP/transport errors,
Integration Contract response errors, and client-side usage errors. Token values and sensitive response
fields are redacted from error text and retained diagnostic payloads.

## Development

```bash
uv sync
uv run python scripts/generate_models.py
uv run python scripts/generate_models.py --check
uv run ruff check .
uv run ruff format --check .
uv run basedpyright
uv run pytest
uv build
```

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. The projection only flattens pure
object inheritance that the generator cannot otherwise preserve correctly; the checked-in release
snapshot remains unchanged. `--check` performs the same validation and deterministic generation without
writing the checked-in models. The current lock resolves `datamodel-code-generator 0.71.0` and
`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3` and
`pydantic>=2.13.4,<3`; the build backend requires `hatchling>=1.27,<2`. These lower bounds are verified
against the complete test suite on the supported Python boundary versions rather than inferred from
`uv.lock`. The exact toolchain remains locked for development and release builds. Basedpyright and its
Node wheel retain the compatible exact pair `basedpyright==1.39.9` and
`nodejs-wheel-binaries==22.20.0`.

## 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, extraction of the returned token pair, exchange through a new
`AsyncMatelab.bind_external_tokens` instance, userid consistency checks, and notebook discovery. It is not Provider
Verification and is skipped by default.

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 external-token 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.

Copy `.env.example` to the git-ignored local `.env.test`, then fill in the shared Provider connection settings:

- `MATELAB_PROVIDER_BASE_URL`
- `MATELAB_PROVIDER_USERNAME`
- `MATELAB_PROVIDER_PASSWORD`

These names intentionally match `matelab-spec` Provider Verification. The isolated target may copy them from the spec
`.env` into this repository's `.env.test`. The identities returned by authentication and external token binding must
agree. With the environment prepared:

```bash
uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
```

The file is never loaded implicitly, so the normal test suite remains safely skipped. Do not use this flow against
production, and never commit its 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 release is bound to `matelab-spec v0.1.1`,
commit `047746ad37d827a85f93d947942f1e5fab80d54c`, and OpenAPI SHA-256
`1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca`.
