Python and TypeScript SDK

Reviewed 26 September 2026. The supported 0.x SDK reads and publishes bounded scientific curve revisions through the public API. Contracts remain preview contracts. Source installation is qualified on Python 3.10/3.12; stable 1.0, PyPI/npm publication, a complete open-source release and production support are separate release gates.

Install and use

Follow Read data in your own Python for browser login and a complete read. Use a private virtual environment:

python -m pip install 'ophiolite[pandas,numpy,validation] @ git+https://github.com/tuna-soup/ophiolite-sdk@c5c76f70d9348660dcafcc534e8eae480e0f752b'
ophiolite skills path

The installed guides cover authentication, exact reads, local validation, publication, sharing and recovery. They use public APIs and confer no new rights. Source and API examples include sync Client, async AsyncClient, typed descriptors and bounded local validation. Validation and contract imports need no server or credential cache.

Scientific data contract

client.assets() discovers permitted assets. client.read(asset, revision, ["GR", "RHOB"]) selects exact curves explicitly. These names are an example; choose curves returned for your asset. Reads require no binding or run.

data.to_frame() returns a DataFrame and a separate descriptor; data.to_numpy() returns an array and its descriptor. Preserve both together. Metadata is not silently attached: descriptor.attach(frame) is explicit. Missing samples become NaN in numerical views; normalized JSON uses null and zero stays zero. Original LAS bytes preserve their declared NULL marker.

The descriptor preserves source identity, units, axis/depth reference, interpretation and checksums. Multi-curve views require matching axes and scientific context. No unit conversion, interpolation, CRS/datum inference or well identity matching happens automatically. Unknown units remain unknown. Source revisions are opaque; do not generalize a managed-derived checksum rule to all sources. Changed mappings refuse; reader-version differences stay explicit.

data.workspace_url() opens the selected scientific revision and curve in Workspace. Access and retention still apply to old revisions. Synthetic templates show this URL contract but do not serve Workspace themselves.

Local work, publication and recovery

Use client.work_folder(private_folder) for configure/start, local calculation, validation, publication and download. A run-start records/resolves input; it does not execute Python. Inspect your result before explicit publication. Current publication creates a separate derived asset; it does not append to its parent. Sharing is a separate authorized operation.

Preserve the entire private folder. client.recover(private_folder) replays the saved exact request and validates its response; a completed folder returns None. Direct calls without a work folder do not provide recovery after process exit. A command ID alone is insufficient. Changed inputs/code need a new folder. Recovery binds the gateway, project and identity. A fresh approved grant for the same confirmed user is supported; an opaque delegate requires the original fingerprint. Credentials are not stored in the folder. This is process-restart qualification, not a power-loss guarantee.

Operation	Retry and recovery
Reads and inspection	Up to three attempts for transient transport/busy responses
Configure, start, upload and publish	Same command/body on bounded retries; work folders persist the exact request
Sharing	Never automatic; after ShareOutcomeUnknown, read client.grants(receipt) first and decide from current state
Login, refresh and revoke	Never replay an ambiguous request automatically

Error	Meaning and next step
AuthenticationRequired / PermissionRefused	Renew authorized access or ask the owner for the required grant; no credential fallback
VerificationFailed / InterpretationChanged	Bytes or interpretation cannot be trusted; inspect exact artifacts and reader version
AxisMismatch / Incompatible	Read separately or choose and document an explicit supported transformation
ValidationFailed	Correct reported output violations before publication
IntegrityConflict	Saved command and request disagree; preserve evidence, do not invent a new command to bypass uncertainty
CapacityExceeded / Busy	Reduce the bounded request or follow the reported retry guidance
RecoveryUnavailable	Preserve the original folder and evidence; arbitrary disk-loss recovery is not promised
ShareOutcomeUnknown	Read current grants before deciding whether another sharing action is needed

Tested starter templates

Four starter sources provide an agent workflow, executed notebook, Python application and React app. Each records its template/SDK version, locked dependencies, synthetic fixtures, README and explicit test command. Synthetic mode needs no credentials; live mode uses your authorized configuration. The notebook preserves descriptors alongside numerical data; the React starter keeps credentials in its local Python backend. Its loopback server requires explicit browser origin and per-start request proof. Fixture tests establish bounded examples, not production deployment or connectors.

TypeScript

@ophiolite/client provides generated operations and verified readCurve. Build from the reviewed source; npm publication is pending. Host applications own credentials and refresh. Session mode uses Workspace CSRF/cookies; bearer mode uses an explicit supplier and omits browser cookies. Redirects refuse. Calls make one HTTP attempt; sharing never retries. There is no browser work-folder journal. Incomplete server response schemas remain unknown or documented adapters; a generated request alone does not prove scientific integrity.

Versioning, migration and licence

Python and TypeScript share 0.MINOR.PATCH and one release tag. PATCH fixes defects or adds APIs. MINOR may break APIs with a CHANGELOG Breaking entry and a one-minor shim where feasible. A new schema suffix requires a new model/MINOR. A stable 1.0 promise requires supported registry entries for every SDK read and stable OpenAPI.

The old pilot 0.2 modules remain in the 0.3.0 compatibility kit for one announced transition release. Fresh SDK login is required; never copy old credential caches. They are removed in the first versioned distribution release afterward. The SDK, TypeScript client, templates, guides and extracted contracts are Apache-2.0; server licensing and full release qualification are separate.