Python reference

Signatures below are inspected from the installed matching SDK wheel. Methods are grouped by their task. Guides teach complete workflows; this page describes returns and failures. Async resource methods use the same contracts with await, except the regular job(id) factory.

Authentication and errors#

Authenticated operations use an explicit constructor key or WELT_API_KEY; missing-key guidance is local. Missing, invalid/expired, and insufficient-permission failures remain distinct. Never log credentials or raw row payloads. Errors expose safe code, request_id, job_id, status_code, retryable and retry_after metadata when available. See waiting and recovery for typed actions.

Client#

python

Client(base_url=None, api_key=None, *, timeout=60, transport=None, max_retries=2, max_retry_delay=5)

Client.causal_result#

Reopen an owned discovery job result and validate identity/provenance.

python

Client.causal_result(job_id)

Returns: Immutable CausalResult with job_id.

Errors and limits: NotFoundError, ResultDeletedError, authentication or InvalidCausalResultError; no graph repair.

Client.causal_scores#

Fetch separate native scores while preserving original axes and score semantics.

python

Client.causal_scores(job_id)

Returns: Score dictionary with values, variables, source_row_target_column axes and score_reference.

Errors and limits: Authorization, deleted/missing result or InvalidCausalResultError; no thresholding or graph rewriting.

Client.close#

Close the synchronous HTTP client; retained remote resources remain.

python

Client.close()

Returns: None.

Errors and limits: Closing is local, not deletion or cancellation.

Client.dataset#

Inspect one owned private dataset.

python

Client.dataset(dataset_id)

Returns: Dataset metadata dictionary.

Errors and limits: Authentication, permissions or NotFoundError for missing/foreign identity.

Client.datasets#

List private workspace datasets visible to the current key.

python

Client.datasets()

Returns: List of dataset dictionaries.

Errors and limits: Authentication, permission or transport errors.

Client.delete_causal_result#

Explicitly delete an owned primary native graph and scores; job/provenance/usage remain.

python

Client.delete_causal_result(result_id)

Returns: None; repeat owned deletion is safe.

Errors and limits: NotFoundError for missing/foreign identity; retryable deletion_pending keeps quota/dependencies reserved. Deleted reads raise ResultDeletedError.

Client.delete_dataset#

Explicitly delete an owned dataset only when no retained predictor/result or active-job dependencies remain.

python

Client.delete_dataset(dataset_id)

Returns: None; repeat owned deletion is safe.

Errors and limits: NotFoundError for missing/foreign identity; ConflictError code dependency_conflict for dependencies. Never automatic cleanup.

Client.discover#

Submit and wait for native observational discovery. Facade closes its temporary client.

python

Client.discover(dataset_id, *, model='arrow', configuration='default', seed=0, constraints=None, model_version=None, idempotency_key=None, timeout=600)

Returns: CausalResult with native graph type, marks, variables, scores reference and pinned provenance.

Errors and limits: Discovery validation/remote errors and JobTimeoutError. Timeout preserves durable work.

Client.download_research_dataset#

Download version-pinned canonical bytes with exact size/SHA verification to a caller-chosen new path.

python

Client.download_research_dataset(dataset_id, path, *, version=None, max_bytes=67108864)

Returns: pathlib.Path after atomic verified publication. No automatic extraction or upload.

Errors and limits: FileExistsError for existing destination/symlink; invalid size/version, integrity or TransportError. Interrupted downloads leave no destination.

Client.job#

Reconnect to durable work by ID. This is a regular factory on both Client and AsyncClient.

python

Client.job(job_id)

Returns: Job or AsyncJob handle; no request until inspection/waiting.

Errors and limits: Subsequent methods require current authorization; a local timeout never cancels work.

Client.jobs#

List durable jobs in the current workspace.

python

Client.jobs()

Returns: List of job dictionaries.

Errors and limits: Authentication, permission or transport errors.

Client.models#

Inspect service-authoritative model task profiles, versions, readiness, configurations and limits.

python

Client.models()

Returns: List of model dictionaries. Presence alone does not qualify execution.

Errors and limits: Transport or service error; public catalogue reads do not require credential preflight.

Client.predict#

Predict on feature-only query rows with the pinned task and fitted version.

python

Client.predict(predictor_id, *, columns, rows, probabilities=False)

Returns: Estimator: numpy.ndarray, shape (n_rows,). Client: provenance-bearing result dictionary.

Errors and limits: Unfitted estimator, schema mismatch, authentication, unavailable worker, capacity or execution errors; pending prediction preserves a job ID.

Client.predictor#

Inspect one owned pinned predictor.

python

Client.predictor(predictor_id)

Returns: Predictor metadata dictionary.

Errors and limits: Authentication, permissions or NotFoundError for missing/foreign identity.

Client.predictors#

List durable fitted predictors in the current workspace.

python

Client.predictors()

Returns: List of predictor dictionaries.

Errors and limits: Authentication, permission or transport errors.

Client.request#

Advanced raw versioned HTTP resource access; prefer named public methods for validation and contracts.

python

Client.request(method, path, **kwargs)

Returns: Decoded JSON value, or None for a 204 endpoint (await for AsyncClient).

Errors and limits: Sanitized typed HTTP/transport errors; authenticated routes require credentials. GET retries are bounded; POST mutations never auto-retry.

Client.research_dataset#

Inspect licence, schema, recorded targets/splits and eligible content before download.

python

Client.research_dataset(dataset_id)

Returns: Full research detail dictionary; content=None means bytes are not eligible.

Errors and limits: Authentication/permission or NotFoundError; never infer redistribution rights from catalogue presence.

Client.research_datasets#

Search the research catalogue without uploading or fitting data.

python

Client.research_datasets(*, q=None, source=None, availability=None, license=None, limit=20, cursor=None)

Returns: Page dictionary: items, next_cursor, total, catalogue_version, facets.

Errors and limits: Invalid filters/limit, authentication, permission or transport errors.

Client.submit_discover#

Submit target-free observational discovery without converting the native graph.

python

Client.submit_discover(dataset_id, *, model='arrow', configuration='default', seed=0, constraints=None, model_version=None, idempotency_key=None)

Returns: Job/AsyncJob. Facade jobs own job.client until explicitly closed.

Errors and limits: Schema/unsupported constraints, task/model/worker availability, authentication, capacity or execution errors.

Client.submit_fit#

Submit durable preparation immediately. Estimator submission uploads; Client submission reuses a dataset ID.

python

Client.submit_fit(dataset_id, *, model, task, configuration='default', seed=0, idempotency_key=None)

Returns: Job (or awaited AsyncJob); estimator jobs own job.client, which callers close explicitly.

Errors and limits: Schema/target validation, authentication, permissions, limits, availability or capacity errors. Retain the returned job ID before waiting.

Client.upload#

Create a private workspace dataset from explicit columns and rows; target=None keeps every column for discovery.

python

Client.upload(*, columns, rows, name='SDK dataset', target=None)

Returns: Dataset dictionary with a durable id.

Errors and limits: Authentication, permission, schema/target, or workload-limit errors.

Client.usage#

Inspect operation, lifecycle and attempt workload metadata; count operation IDs rather than events.

python

Client.usage()

Returns: List of usage dictionaries. No rates, credits, pricing or prediction payloads.

Errors and limits: Authentication, permission or transport errors.

Job#

python

Job(client, job_id)

Job.cancel#

Explicitly request remote cancellation of this job.

python

Job.cancel()

Returns: Server job metadata dictionary (await for AsyncJob).

Errors and limits: Authentication, permissions, NotFoundError or job conflict; cancellation races with completion.

Job.inspect#

Read the durable job state and server-reported stages.

python

Job.inspect()

Returns: Job metadata dictionary (await for AsyncJob).

Errors and limits: Authentication, permissions, NotFoundError, transport or service errors.

Job.result#

Poll until completion within a local waiting budget; never resubmit or implicitly cancel.

python

Job.result(*, timeout=600, poll_interval=0.25)

Returns: Supervised fit: predictor dictionary. Predict: result dictionary. Discovery: CausalResult.

Errors and limits: JobTimeoutError with job_id for reconnect; typed failed/cancelled job errors. Synchronous request phase budgets are cooperative, not a hard wall-clock interrupt.

Classifier#

python

Classifier(model='tabicl-v2', configuration='default', base_url=None, api_key=None, random_state=0, timeout=600)

Classifier.export_metadata#

Export provenance only; no weights, executable context or credentials.

python

Classifier.export_metadata()

Returns: JSON-compatible server metadata dictionary.

Errors and limits: Same errors as metadata.

Classifier.fit#

Prepare a new immutable predictor; wait for durable remote preparation.

python

Classifier.fit(X, y=None, *, target=None)

Returns: The same fitted estimator (self).

Errors and limits: ValueError for schema/target conflicts before upload; authentication, input, unavailable-model, capacity, execution or JobTimeoutError during remote preparation.

Classifier.from_predictor#

Reopen an owned predictor using the current credentials, without a new fit or training-table upload.

python

Classifier.from_predictor(predictor_id, *, base_url=None, api_key=None)

Returns: A fitted estimator of the matching task, with pinned model/configuration/version/seed.

Errors and limits: NotFoundError for missing/foreign identity; authentication/permission errors; ValueError for a task mismatch.

Classifier.metadata#

Inspect a fitted predictor under current workspace authorization.

python

Classifier.metadata()

Returns: Server predictor metadata dictionary.

Errors and limits: Unfitted estimator, authentication, permission, or NotFoundError.

Classifier.predict#

Predict on feature-only query rows with the pinned task and fitted version.

python

Classifier.predict(X)

Returns: Estimator: numpy.ndarray, shape (n_rows,). Client: provenance-bearing result dictionary.

Errors and limits: Unfitted estimator, schema mismatch, authentication, unavailable worker, capacity or execution errors; pending prediction preserves a job ID.

Classifier.predict_details#

Return predictions plus operation/model/version provenance.

python

Classifier.predict_details(X, *, probabilities=False)

Returns: JSON-compatible result dictionary; probabilities requested explicitly.

Errors and limits: Same validation and remote errors as predict.

Classifier.predict_proba#

Return native class probabilities in classes_ column order.

python

Classifier.predict_proba(X)

Returns: numpy.ndarray, shape (n_rows, n_classes). No calibrated coverage guarantee.

Errors and limits: Prediction errors; ValueError if the model returns no probabilities.

Classifier.set_params#

Set sklearn constructor parameters; a changed model/configuration requires a new fit.

python

Classifier.set_params(**params)

Returns: The same estimator (self).

Errors and limits: ValueError for an invalid parameter. Does not mutate existing pinned server artifacts.

Classifier.submit_fit#

Submit durable preparation immediately. Estimator submission uploads; Client submission reuses a dataset ID.

python

Classifier.submit_fit(X, y=None, *, target=None)

Returns: Job (or awaited AsyncJob); estimator jobs own job.client, which callers close explicitly.

Errors and limits: Schema/target validation, authentication, permissions, limits, availability or capacity errors. Retain the returned job ID before waiting.

Regressor#

python

Regressor(model='tabicl-v2', configuration='default', base_url=None, api_key=None, random_state=0, timeout=600)

Regressor.export_metadata#

Export provenance only; no weights, executable context or credentials.

python

Regressor.export_metadata()

Returns: JSON-compatible server metadata dictionary.

Errors and limits: Same errors as metadata.

Regressor.fit#

Prepare a new immutable predictor; wait for durable remote preparation.

python

Regressor.fit(X, y=None, *, target=None)

Returns: The same fitted estimator (self).

Errors and limits: ValueError for schema/target conflicts before upload; authentication, input, unavailable-model, capacity, execution or JobTimeoutError during remote preparation.

Regressor.from_predictor#

Reopen an owned predictor using the current credentials, without a new fit or training-table upload.

python

Regressor.from_predictor(predictor_id, *, base_url=None, api_key=None)

Returns: A fitted estimator of the matching task, with pinned model/configuration/version/seed.

Errors and limits: NotFoundError for missing/foreign identity; authentication/permission errors; ValueError for a task mismatch.

Regressor.metadata#

Inspect a fitted predictor under current workspace authorization.

python

Regressor.metadata()

Returns: Server predictor metadata dictionary.

Errors and limits: Unfitted estimator, authentication, permission, or NotFoundError.

Regressor.predict#

Predict on feature-only query rows with the pinned task and fitted version.

python

Regressor.predict(X)

Returns: Estimator: numpy.ndarray, shape (n_rows,). Client: provenance-bearing result dictionary.

Errors and limits: Unfitted estimator, schema mismatch, authentication, unavailable worker, capacity or execution errors; pending prediction preserves a job ID.

Regressor.predict_details#

Return predictions plus operation/model/version provenance.

python

Regressor.predict_details(X, *, probabilities=False)

Returns: JSON-compatible result dictionary; probabilities requested explicitly.

Errors and limits: Same validation and remote errors as predict.

Regressor.set_params#

Set sklearn constructor parameters; a changed model/configuration requires a new fit.

python

Regressor.set_params(**params)

Returns: The same estimator (self).

Errors and limits: ValueError for an invalid parameter. Does not mutate existing pinned server artifacts.

Regressor.submit_fit#

Submit durable preparation immediately. Estimator submission uploads; Client submission reuses a dataset ID.

python

Regressor.submit_fit(X, y=None, *, target=None)

Returns: Job (or awaited AsyncJob); estimator jobs own job.client, which callers close explicitly.

Errors and limits: Schema/target validation, authentication, permissions, limits, availability or capacity errors. Retain the returned job ID before waiting.

AsyncClient#

python

AsyncClient(base_url=None, api_key=None, *, timeout=60, transport=None, max_retries=2, max_retry_delay=5)

AsyncClient.aclose#

Close the asynchronous HTTP client.

python

AsyncClient.aclose()

Returns: Awaited None.

Errors and limits: Closing is local, not deletion or cancellation.

AsyncClient.causal_result#

Reopen an owned discovery job result and validate identity/provenance.

python

AsyncClient.causal_result(job_id)

Returns: Immutable CausalResult with job_id.

Errors and limits: NotFoundError, ResultDeletedError, authentication or InvalidCausalResultError; no graph repair.

AsyncClient.causal_scores#

Fetch separate native scores while preserving original axes and score semantics.

python

AsyncClient.causal_scores(job_id)

Returns: Score dictionary with values, variables, source_row_target_column axes and score_reference.

Errors and limits: Authorization, deleted/missing result or InvalidCausalResultError; no thresholding or graph rewriting.

AsyncClient.dataset#

Inspect one owned private dataset.

python

AsyncClient.dataset(dataset_id)

Returns: Dataset metadata dictionary.

Errors and limits: Authentication, permissions or NotFoundError for missing/foreign identity.

AsyncClient.datasets#

List private workspace datasets visible to the current key.

python

AsyncClient.datasets()

Returns: List of dataset dictionaries.

Errors and limits: Authentication, permission or transport errors.

AsyncClient.delete_causal_result#

Explicitly delete an owned primary native graph and scores; job/provenance/usage remain.

python

AsyncClient.delete_causal_result(result_id)

Returns: None; repeat owned deletion is safe.

Errors and limits: NotFoundError for missing/foreign identity; retryable deletion_pending keeps quota/dependencies reserved. Deleted reads raise ResultDeletedError.

AsyncClient.delete_dataset#

Explicitly delete an owned dataset only when no retained predictor/result or active-job dependencies remain.

python

AsyncClient.delete_dataset(dataset_id)

Returns: None; repeat owned deletion is safe.

Errors and limits: NotFoundError for missing/foreign identity; ConflictError code dependency_conflict for dependencies. Never automatic cleanup.

AsyncClient.discover#

Submit and wait for native observational discovery. Facade closes its temporary client.

python

AsyncClient.discover(dataset_id, *, model='arrow', configuration='default', seed=0, constraints=None, model_version=None, idempotency_key=None, timeout=600)

Returns: CausalResult with native graph type, marks, variables, scores reference and pinned provenance.

Errors and limits: Discovery validation/remote errors and JobTimeoutError. Timeout preserves durable work.

AsyncClient.download_research_dataset#

Download version-pinned canonical bytes with exact size/SHA verification to a caller-chosen new path.

python

AsyncClient.download_research_dataset(dataset_id, path, *, version=None, max_bytes=67108864)

Returns: pathlib.Path after atomic verified publication. No automatic extraction or upload.

Errors and limits: FileExistsError for existing destination/symlink; invalid size/version, integrity or TransportError. Interrupted downloads leave no destination.

AsyncClient.job#

Reconnect to durable work by ID. This is a regular factory on both Client and AsyncClient.

python

AsyncClient.job(job_id)

Returns: Job or AsyncJob handle; no request until inspection/waiting.

Errors and limits: Subsequent methods require current authorization; a local timeout never cancels work.

AsyncClient.jobs#

List durable jobs in the current workspace.

python

AsyncClient.jobs()

Returns: List of job dictionaries.

Errors and limits: Authentication, permission or transport errors.

AsyncClient.models#

Inspect service-authoritative model task profiles, versions, readiness, configurations and limits.

python

AsyncClient.models()

Returns: List of model dictionaries. Presence alone does not qualify execution.

Errors and limits: Transport or service error; public catalogue reads do not require credential preflight.

AsyncClient.predict#

Predict on feature-only query rows with the pinned task and fitted version.

python

AsyncClient.predict(predictor_id, *, columns, rows, probabilities=False)

Returns: Estimator: numpy.ndarray, shape (n_rows,). Client: provenance-bearing result dictionary.

Errors and limits: Unfitted estimator, schema mismatch, authentication, unavailable worker, capacity or execution errors; pending prediction preserves a job ID.

AsyncClient.predictor#

Inspect one owned pinned predictor.

python

AsyncClient.predictor(predictor_id)

Returns: Predictor metadata dictionary.

Errors and limits: Authentication, permissions or NotFoundError for missing/foreign identity.

AsyncClient.predictors#

List durable fitted predictors in the current workspace.

python

AsyncClient.predictors()

Returns: List of predictor dictionaries.

Errors and limits: Authentication, permission or transport errors.

AsyncClient.request#

Advanced raw versioned HTTP resource access; prefer named public methods for validation and contracts.

python

AsyncClient.request(method, path, **kwargs)

Returns: Decoded JSON value, or None for a 204 endpoint (await for AsyncClient).

Errors and limits: Sanitized typed HTTP/transport errors; authenticated routes require credentials. GET retries are bounded; POST mutations never auto-retry.

AsyncClient.research_dataset#

Inspect licence, schema, recorded targets/splits and eligible content before download.

python

AsyncClient.research_dataset(dataset_id)

Returns: Full research detail dictionary; content=None means bytes are not eligible.

Errors and limits: Authentication/permission or NotFoundError; never infer redistribution rights from catalogue presence.

AsyncClient.research_datasets#

Search the research catalogue without uploading or fitting data.

python

AsyncClient.research_datasets(*, q=None, source=None, availability=None, license=None, limit=20, cursor=None)

Returns: Page dictionary: items, next_cursor, total, catalogue_version, facets.

Errors and limits: Invalid filters/limit, authentication, permission or transport errors.

AsyncClient.submit_discover#

Submit target-free observational discovery without converting the native graph.

python

AsyncClient.submit_discover(dataset_id, *, model='arrow', configuration='default', seed=0, constraints=None, model_version=None, idempotency_key=None)

Returns: Job/AsyncJob. Facade jobs own job.client until explicitly closed.

Errors and limits: Schema/unsupported constraints, task/model/worker availability, authentication, capacity or execution errors.

AsyncClient.submit_fit#

Submit durable preparation immediately. Estimator submission uploads; Client submission reuses a dataset ID.

python

AsyncClient.submit_fit(dataset_id, *, model, task, configuration='default', seed=0, idempotency_key=None)

Returns: Job (or awaited AsyncJob); estimator jobs own job.client, which callers close explicitly.

Errors and limits: Schema/target validation, authentication, permissions, limits, availability or capacity errors. Retain the returned job ID before waiting.

AsyncClient.upload#

Create a private workspace dataset from explicit columns and rows; target=None keeps every column for discovery.

python

AsyncClient.upload(*, columns, rows, name='SDK dataset', target=None)

Returns: Dataset dictionary with a durable id.

Errors and limits: Authentication, permission, schema/target, or workload-limit errors.

AsyncClient.usage#

Inspect operation, lifecycle and attempt workload metadata; count operation IDs rather than events.

python

AsyncClient.usage()

Returns: List of usage dictionaries. No rates, credits, pricing or prediction payloads.

Errors and limits: Authentication, permission or transport errors.

AsyncJob#

python

AsyncJob(client, job_id)

AsyncJob.cancel#

Explicitly request remote cancellation of this job.

python

AsyncJob.cancel()

Returns: Server job metadata dictionary (await for AsyncJob).

Errors and limits: Authentication, permissions, NotFoundError or job conflict; cancellation races with completion.

AsyncJob.inspect#

Read the durable job state and server-reported stages.

python

AsyncJob.inspect()

Returns: Job metadata dictionary (await for AsyncJob).

Errors and limits: Authentication, permissions, NotFoundError, transport or service errors.

AsyncJob.result#

Poll until completion within a local waiting budget; never resubmit or implicitly cancel.

python

AsyncJob.result(*, timeout=600, poll_interval=0.25)

Returns: Supervised fit: predictor dictionary. Predict: result dictionary. Discovery: CausalResult.

Errors and limits: JobTimeoutError with job_id for reconnect; typed failed/cancelled job errors. Synchronous request phase budgets are cooperative, not a hard wall-clock interrupt.

CausalDiscovery#

python

CausalDiscovery(model='arrow', configuration='default', base_url=None, api_key=None, random_state=0, timeout=600)

CausalDiscovery.discover#

Submit and wait for native observational discovery. Facade closes its temporary client.

python

CausalDiscovery.discover(X=None, *, dataset_id=None, constraints=None, model_version=None, idempotency_key=None)

Returns: CausalResult with native graph type, marks, variables, scores reference and pinned provenance.

Errors and limits: Discovery validation/remote errors and JobTimeoutError. Timeout preserves durable work.

CausalDiscovery.set_params#

Set sklearn constructor parameters; a changed model/configuration requires a new fit.

python

CausalDiscovery.set_params(**params)

Returns: The same estimator (self).

Errors and limits: ValueError for an invalid parameter. Does not mutate existing pinned server artifacts.

CausalDiscovery.submit_discover#

Submit target-free observational discovery without converting the native graph.

python

CausalDiscovery.submit_discover(X=None, *, dataset_id=None, constraints=None, model_version=None, idempotency_key=None)

Returns: Job/AsyncJob. Facade jobs own job.client until explicitly closed.

Errors and limits: Schema/unsupported constraints, task/model/worker availability, authentication, capacity or execution errors.

CausalResult#

python

CausalResult(payload)

Immutable native result. Read id, dataset_id, job_id, variables, edge_marks, native_graph_type, model_version, configuration_version, score_reference, decoder, assumptions and diagnostics. The result retains no HTTP client or credentials. Scores remain a separate authenticated read.

CausalResult.to_dict#

Make an independent ordinary copy of the original native wire payload.

python

CausalResult.to_dict()

Returns: Fresh dictionary retaining graph type, endpoint marks and provenance.

Errors and limits: No remote request and no hidden client or credentials.

CausalResult.to_ergodic#

Convert only a declared native DAG locally, preserving isolates and direction; never project directed graphs.

python

CausalResult.to_ergodic()

Returns: Approved Ergodic MixedGraph. Use to_adjacency(order=list(result.variables)) for original axes.

Errors and limits: OptionalDependencyError for missing/unrelated co-release dependency; UnsupportedGraphConversionError for every non-declared-DAG graph.

Error types#

All remote errors inherit WeltError. Table/schema validation may raise ordinary ValueError before upload. Do not catch every error and silently fit again.

Type	Next action
`AuthenticationError`	Configure a missing key locally; replace an invalid, expired or revoked key in Account.
`PermissionDeniedError`	Use a key with the required workspace write/fit/predict permission.
`InvalidInputError`	Check the named schema, explicit target and task limits.
`ModelUnavailableError`	Inspect current task_profiles and worker readiness; no automatic model fallback.
`CapacityError / RateLimitError`	Respect retry_after and workspace admission limits; inspect existing work.
`JobTimeoutError / PredictionPendingError`	Retain job_id and reconnect; local timeout does not cancel.
`ExecutionError / JobCancelledError`	Inspect the durable job and safe request/job IDs; intentional retry needs a new decision.
`NotFoundError / ConflictError`	Check workspace ownership and resource dependencies.
`TransportError`	Inspect existing job state before replaying a mutation; GET retries are bounded.
`ResultExpiredError / ResultDeletedError`	Temporary access expiry and explicit primary deletion are distinct.
`InvalidCausalResultError`	Reject malformed native payload without repair.
`UnsupportedGraphConversionError / OptionalDependencyError`	Preserve native graph; convert declared DAGs only with approved local co-release dependency.