ReferencePython reference

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#

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

Client.batch_payload#

Retrieve retained batch JSON through the same authenticated origin.

Client.batch_payload(job_id, *, result_reference=None)

Returns: Payload dictionary with ordered predictions/errors/provenance.

Errors and limits: Not-ready/not-owned/expired result or wrong reference; no third-party URL fetching.

Client.causal_result#

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

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.

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.

Client.close()

Returns: None.

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

Client.complete_upload#

Validate owned chunks/checksum/schema and create immutable dataset.

Client.complete_upload(upload_id)

Returns: Dataset dictionary.

Errors and limits: Incomplete/invalid/expired uploads and workload/parser limits; inspect before retrying.

Client.connect#

Explicitly approve workspace access through browser/device authorization; no constructor login.

Client.connect(
    *,
    timeout=600,
    open_browser=True,
    save=False,
    workspace=None,
)

Returns: The same connected Client. Python defaults to process-only origin-bound access; save=True opts into private local persistence.

Errors and limits: AuthenticationError for denied/expired/consumed/unsafe responses or storage, PermissionDeniedError for an existing insufficient key, TransportError or local KeyboardInterrupt; printed link supports headless/remote notebooks.

Client.create_upload#

Declare immutable file format/size/checksum/schema/target before sending chunks.

Client.create_upload(
    *,
    format,
    size_bytes,
    sha256,
    target=None,
    schema=None,
)

Returns: Upload session dictionary with ID and chunk_bytes; save its ID for recovery.

Errors and limits: Server envelope/capacity/parser availability; no automatic mutation replay.

Client.dataset#

Inspect one owned private dataset.

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.

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.

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.

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

Explicitly purge an owned terminal model run input and result.

Client.delete_model_run(job_id)

Returns: Deletion dictionary {id, deleted: true}; job identity, idempotency and usage remain.

Errors and limits: NotFoundError for foreign/missing/non-model-run jobs; conflict for an active run. Subsequent result retrieval is NotFoundError.

Client.discover#

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

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. metadata=True also writes the catalogue detail to <path>.metadata.json after the verified file.

Client.download_research_dataset(
    dataset_id,
    path,
    *,
    version=None,
    max_bytes=134217728,
    metadata=False,
)

Returns: pathlib.Path after atomic verified publication (default). metadata=True: frozen ResearchDownload with path, metadata_path, version, sha256 and the detail dictionary. No automatic extraction or upload.

Errors and limits: FileExistsError for existing destination/symlink (with metadata=True, either file is checked before any request); invalid size/version, integrity or TransportError. Interrupted downloads leave no destination.

Client.evaluate#

Submit an evaluation and wait for it within a local timeout.

Client.evaluate(
    data_or_dataset,
    target=None,
    *,
    task,
    models=None,
    folds=None,
    split='auto',
    group_column=None,
    fold_column=None,
    seed=0,
    primary_metric=None,
    positive_class=None,
    sample_rows=None,
    max_credits=None,
    idempotency_key=None,
    timeout=600,
)

Returns: Finished Evaluation or AsyncEvaluation; partially_completed returns with an EvaluationWarning.

Errors and limits: Submission errors; ExecutionError when no model finished; JobCancelledError; JobTimeoutError naming the evaluation, which keeps running.

Client.evaluation#

Reopen one evaluation by ID under current workspace authority; no new work.

Client.evaluation(evaluation_id)

Returns: Evaluation (await for AsyncClient: AsyncEvaluation).

Errors and limits: NotFoundError for a missing, deleted or foreign evaluation, or code evaluations_unavailable on a server without evaluations; authentication or permission errors.

Client.evaluations#

List the workspace's evaluations.

Client.evaluations()

Returns: List of Evaluation or AsyncEvaluation handles.

Errors and limits: Authentication, permission or transport errors.

Client.forecast_job#

Reconnect to a typed forecast run without submitting work; a regular factory on both clients.

Client.forecast_job(job_id)

Returns: ForecastJob or AsyncForecastJob borrowing this client; typed ForecastResult after waiting.

Errors and limits: Task/identity/provenance validation on inspect/result/cancel; authorization and remote errors. Reconnect cannot reconstruct the original request context.

Client.job#

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

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

Read ready job result without waiting.

Client.job_result(job_id)

Returns: Fit/prediction/native graph/batch result dictionary.

Errors and limits: Not-ready, expired/deleted/not-owned errors retain typed code.

Client.jobs#

List durable jobs in the current workspace.

Client.jobs()

Returns: List of job dictionaries.

Errors and limits: Authentication, permission or transport errors.

Client.load_research_dataset#

Download verified content into a private temporary directory and read it as a pandas DataFrame; version=None uses the current content version. Requires the welt-client[research] extra.

Client.load_research_dataset(
    dataset_id,
    *,
    version=None,
    metadata=False,
    max_bytes=134217728,
)

Returns: pandas.DataFrame, or (DataFrame, ResearchMetadata) with metadata=True. A notice ZIP also exposes license_text/attribution_text and emits ResearchNoticeWarning. No file is left behind.

Errors and limits: OptionalDependencyError (an ImportError) without pandas/pyarrow; content unavailable, version mismatch or size above max_bytes before download; invalid_research_archive for unexpected ZIP members; integrity or TransportError.

Client.model#

Inspect a catalogue model or explicitly named hidden model under current workspace authority.

Client.model(model_id)

Returns: Model metadata dictionary; hidden entries carry tasks, limits, resolved version/configuration, rights and availability.

Errors and limits: NotFoundError for unknown or licence-restricted entries; unavailable native worker remains explicit.

Client.models#

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

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.

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.

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.

Client.predictors()

Returns: List of predictor dictionaries.

Errors and limits: Authentication, permission or transport errors.

Client.pricing#

Read public pricing without purchasing.

Client.pricing()

Returns: Public pricing dictionary (await for AsyncClient).

Errors and limits: Transport/server availability; no payment authority.

Client.put_upload_chunk#

Send bytes with SHA256 for an explicit chunk index.

Client.put_upload_chunk(upload_id, index, content)

Returns: Updated upload progress dictionary.

Errors and limits: ValueError for invalid index/bytes; conflicts for changed content; transport errors do not silently retry.

Client.request#

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

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.

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.

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_batch_predict#

Submit durable prediction on an owned dataset using a pinned predictor.

Client.submit_batch_predict(
    predictor_id,
    dataset_id,
    *,
    probabilities=False,
    idempotency_key=None,
)

Returns: Job/AsyncJob with durable ID.

Errors and limits: Availability/envelope/capacity and idempotency conflicts; does not silently resubmit.

Client.submit_discover#

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

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_evaluation#

Cross-validate models on a dataset ID, or upload a DataFrame, array, CSV or Parquet table with its target first. Empty models lets Welt choose every eligible model. Options are checked locally before any upload.

Client.submit_evaluation(
    data_or_dataset,
    target=None,
    *,
    task,
    models=None,
    folds=None,
    split='auto',
    group_column=None,
    fold_column=None,
    seed=0,
    primary_metric=None,
    positive_class=None,
    sample_rows=None,
    max_credits=None,
    idempotency_key=None,
)

Returns: Evaluation (await for AsyncClient: AsyncEvaluation) with its ID, models, skipped models and estimated_credits.

Errors and limits: ValueError for invalid options, targets or split columns before upload; InvalidInputError for server refusals (codes invalid_input, workload_limit, budget_exceeded, no_eligible_models with error.details); ModelUnavailableError; ConflictError for a reused key with different inputs; NotFoundError code evaluations_unavailable on a server without evaluations; TransportError names the dataset ID and key for a replay. Not retried automatically.

Client.submit_fit#

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

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

Submit one bounded hidden-model run with an explicit task payload and replay key.

Client.submit_model_run(
    payload,
    *,
    idempotency_key=None,
    expected_model_version=None,
    expected_configuration_version=None,
)

Returns: Job or awaited AsyncJob. Job.result() returns the task-specific result dictionary.

Errors and limits: Input/envelope, licence scope, worker availability, capacity or idempotency conflicts. No fitted predictor is created; resubmission with a new key executes again.

Client.upload#

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

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

Hash a local CSV/Parquet file, verify resume metadata, skip acknowledged chunks and complete.

Client.upload_file(
    path,
    *,
    target=None,
    schema=None,
    format=None,
    upload_id=None,
)

Returns: Dataset dictionary; uses bounded chunk memory.

Errors and limits: Local file/metadata ValueError; remote errors. Use create_upload and retain its ID for recovery. Async local hashing/reads are blocking disk I/O.

Client.upload_session#

Inspect an owned upload and acknowledged chunks.

Client.upload_session(upload_id)

Returns: Upload metadata/progress dictionary.

Errors and limits: NotFoundError for another tenant; explicit expired/failed status.

Client.usage#

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

Client.usage()

Returns: List of usage dictionaries, including nullable credits and rate_card_version accounting fields. credits records the operation's reservation until settlement, then its net credit charge; null means unpriced, not a promise of free execution, and differs from zero. Usage contains no raw prediction payloads or quality scores. Read current rates with pricing() and manage credits in Workspace Billing.

Errors and limits: Authentication, permission or transport errors.

Client.workspace#

Inspect the credential workspace, role, metadata and resolved limits.

Client.workspace()

Returns: Workspace dictionary (await for AsyncClient).

Errors and limits: Missing/invalid credential or workspace selection mismatch; no account-wide authority.

Job#

Job(client, job_id)

Job.cancel#

Explicitly request remote cancellation of this job.

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.

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.

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

Returns: Supervised fit: predictor dictionary. Predict or model_run: result dictionary. Discovery: CausalResult. Batch prediction: manifest dictionary for succeeded or partially_completed jobs, with row_count, successful_ranges, failed_ranges, result_reference and expires_at. Ranges are zero-based [start, stop), with stop excluded. Inspect failed_ranges before using the result; retrieve ordered predictions, probabilities and per-range errors separately through client.batch_payload(job.id, result_reference=manifest["result_reference"]). Failed rows have null predictions; partial completion is not success for every row.

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. Batch payload retrieval requires current workspace authorization and unexpired retention; no third-party download URL is followed.

Classifier#

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.

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.

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.

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.

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.

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.

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.

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

Use the inherited sklearn scoring convention on explicit held-out rows.

Classifier.score(X, y, sample_weight=None)

Returns: Classifier: accuracy. Regressor: R². This is not an automatic hosted benchmark.

Errors and limits: Prediction/schema/task errors; caller owns the split and evaluation protocol.

Classifier.set_params#

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

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.

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#

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.

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.

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.

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.

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.

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.

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

Use the inherited sklearn scoring convention on explicit held-out rows.

Regressor.score(X, y, sample_weight=None)

Returns: Classifier: accuracy. Regressor: R². This is not an automatic hosted benchmark.

Errors and limits: Prediction/schema/task errors; caller owns the split and evaluation protocol.

Regressor.set_params#

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

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.

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#

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

AsyncClient.aclose#

Close the asynchronous HTTP client.

AsyncClient.aclose()

Returns: Awaited None.

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

AsyncClient.batch_payload#

Retrieve retained batch JSON through the same authenticated origin.

AsyncClient.batch_payload(job_id, *, result_reference=None)

Returns: Payload dictionary with ordered predictions/errors/provenance.

Errors and limits: Not-ready/not-owned/expired result or wrong reference; no third-party URL fetching.

AsyncClient.causal_result#

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

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.

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

Validate owned chunks/checksum/schema and create immutable dataset.

AsyncClient.complete_upload(upload_id)

Returns: Dataset dictionary.

Errors and limits: Incomplete/invalid/expired uploads and workload/parser limits; inspect before retrying.

AsyncClient.create_upload#

Declare immutable file format/size/checksum/schema/target before sending chunks.

AsyncClient.create_upload(
    *,
    format,
    size_bytes,
    sha256,
    target=None,
    schema=None,
)

Returns: Upload session dictionary with ID and chunk_bytes; save its ID for recovery.

Errors and limits: Server envelope/capacity/parser availability; no automatic mutation replay.

AsyncClient.dataset#

Inspect one owned private dataset.

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.

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.

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.

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

Explicitly purge an owned terminal model run input and result.

AsyncClient.delete_model_run(job_id)

Returns: Deletion dictionary {id, deleted: true}; job identity, idempotency and usage remain.

Errors and limits: NotFoundError for foreign/missing/non-model-run jobs; conflict for an active run. Subsequent result retrieval is NotFoundError.

AsyncClient.discover#

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

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. metadata=True also writes the catalogue detail to <path>.metadata.json after the verified file.

AsyncClient.download_research_dataset(
    dataset_id,
    path,
    *,
    version=None,
    max_bytes=134217728,
    metadata=False,
)

Returns: pathlib.Path after atomic verified publication (default). metadata=True: frozen ResearchDownload with path, metadata_path, version, sha256 and the detail dictionary. No automatic extraction or upload.

Errors and limits: FileExistsError for existing destination/symlink (with metadata=True, either file is checked before any request); invalid size/version, integrity or TransportError. Interrupted downloads leave no destination.

AsyncClient.evaluate#

Submit an evaluation and wait for it within a local timeout.

AsyncClient.evaluate(
    data_or_dataset,
    target=None,
    *,
    task,
    models=None,
    folds=None,
    split='auto',
    group_column=None,
    fold_column=None,
    seed=0,
    primary_metric=None,
    positive_class=None,
    sample_rows=None,
    max_credits=None,
    idempotency_key=None,
    timeout=600,
)

Returns: Finished Evaluation or AsyncEvaluation; partially_completed returns with an EvaluationWarning.

Errors and limits: Submission errors; ExecutionError when no model finished; JobCancelledError; JobTimeoutError naming the evaluation, which keeps running.

AsyncClient.evaluation#

Reopen one evaluation by ID under current workspace authority; no new work.

AsyncClient.evaluation(evaluation_id)

Returns: Evaluation (await for AsyncClient: AsyncEvaluation).

Errors and limits: NotFoundError for a missing, deleted or foreign evaluation, or code evaluations_unavailable on a server without evaluations; authentication or permission errors.

AsyncClient.evaluations#

List the workspace's evaluations.

AsyncClient.evaluations()

Returns: List of Evaluation or AsyncEvaluation handles.

Errors and limits: Authentication, permission or transport errors.

AsyncClient.forecast_job#

Reconnect to a typed forecast run without submitting work; a regular factory on both clients.

AsyncClient.forecast_job(job_id)

Returns: ForecastJob or AsyncForecastJob borrowing this client; typed ForecastResult after waiting.

Errors and limits: Task/identity/provenance validation on inspect/result/cancel; authorization and remote errors. Reconnect cannot reconstruct the original request context.

AsyncClient.job#

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

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

Read ready job result without waiting.

AsyncClient.job_result(job_id)

Returns: Fit/prediction/native graph/batch result dictionary.

Errors and limits: Not-ready, expired/deleted/not-owned errors retain typed code.

AsyncClient.jobs#

List durable jobs in the current workspace.

AsyncClient.jobs()

Returns: List of job dictionaries.

Errors and limits: Authentication, permission or transport errors.

AsyncClient.load_research_dataset#

Download verified content into a private temporary directory and read it as a pandas DataFrame; version=None uses the current content version. Requires the welt-client[research] extra.

AsyncClient.load_research_dataset(
    dataset_id,
    *,
    version=None,
    metadata=False,
    max_bytes=134217728,
)

Returns: pandas.DataFrame, or (DataFrame, ResearchMetadata) with metadata=True. A notice ZIP also exposes license_text/attribution_text and emits ResearchNoticeWarning. No file is left behind.

Errors and limits: OptionalDependencyError (an ImportError) without pandas/pyarrow; content unavailable, version mismatch or size above max_bytes before download; invalid_research_archive for unexpected ZIP members; integrity or TransportError.

AsyncClient.model#

Inspect a catalogue model or explicitly named hidden model under current workspace authority.

AsyncClient.model(model_id)

Returns: Model metadata dictionary; hidden entries carry tasks, limits, resolved version/configuration, rights and availability.

Errors and limits: NotFoundError for unknown or licence-restricted entries; unavailable native worker remains explicit.

AsyncClient.models#

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

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.

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.

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.

AsyncClient.predictors()

Returns: List of predictor dictionaries.

Errors and limits: Authentication, permission or transport errors.

AsyncClient.pricing#

Read public pricing without purchasing.

AsyncClient.pricing()

Returns: Public pricing dictionary (await for AsyncClient).

Errors and limits: Transport/server availability; no payment authority.

AsyncClient.put_upload_chunk#

Send bytes with SHA256 for an explicit chunk index.

AsyncClient.put_upload_chunk(upload_id, index, content)

Returns: Updated upload progress dictionary.

Errors and limits: ValueError for invalid index/bytes; conflicts for changed content; transport errors do not silently retry.

AsyncClient.request#

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

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.

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.

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_batch_predict#

Submit durable prediction on an owned dataset using a pinned predictor.

AsyncClient.submit_batch_predict(
    predictor_id,
    dataset_id,
    *,
    probabilities=False,
    idempotency_key=None,
)

Returns: Job/AsyncJob with durable ID.

Errors and limits: Availability/envelope/capacity and idempotency conflicts; does not silently resubmit.

AsyncClient.submit_discover#

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

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_evaluation#

Cross-validate models on a dataset ID, or upload a DataFrame, array, CSV or Parquet table with its target first. Empty models lets Welt choose every eligible model. Options are checked locally before any upload.

AsyncClient.submit_evaluation(
    data_or_dataset,
    target=None,
    *,
    task,
    models=None,
    folds=None,
    split='auto',
    group_column=None,
    fold_column=None,
    seed=0,
    primary_metric=None,
    positive_class=None,
    sample_rows=None,
    max_credits=None,
    idempotency_key=None,
)

Returns: Evaluation (await for AsyncClient: AsyncEvaluation) with its ID, models, skipped models and estimated_credits.

Errors and limits: ValueError for invalid options, targets or split columns before upload; InvalidInputError for server refusals (codes invalid_input, workload_limit, budget_exceeded, no_eligible_models with error.details); ModelUnavailableError; ConflictError for a reused key with different inputs; NotFoundError code evaluations_unavailable on a server without evaluations; TransportError names the dataset ID and key for a replay. Not retried automatically.

AsyncClient.submit_fit#

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

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

Submit one bounded hidden-model run with an explicit task payload and replay key.

AsyncClient.submit_model_run(
    payload,
    *,
    idempotency_key=None,
    expected_model_version=None,
    expected_configuration_version=None,
)

Returns: Job or awaited AsyncJob. Job.result() returns the task-specific result dictionary.

Errors and limits: Input/envelope, licence scope, worker availability, capacity or idempotency conflicts. No fitted predictor is created; resubmission with a new key executes again.

AsyncClient.upload#

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

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

Hash a local CSV/Parquet file, verify resume metadata, skip acknowledged chunks and complete.

AsyncClient.upload_file(
    path,
    *,
    target=None,
    schema=None,
    format=None,
    upload_id=None,
)

Returns: Dataset dictionary; uses bounded chunk memory.

Errors and limits: Local file/metadata ValueError; remote errors. Use create_upload and retain its ID for recovery. Async local hashing/reads are blocking disk I/O.

AsyncClient.upload_session#

Inspect an owned upload and acknowledged chunks.

AsyncClient.upload_session(upload_id)

Returns: Upload metadata/progress dictionary.

Errors and limits: NotFoundError for another tenant; explicit expired/failed status.

AsyncClient.usage#

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

AsyncClient.usage()

Returns: List of usage dictionaries, including nullable credits and rate_card_version accounting fields. credits records the operation's reservation until settlement, then its net credit charge; null means unpriced, not a promise of free execution, and differs from zero. Usage contains no raw prediction payloads or quality scores. Read current rates with pricing() and manage credits in Workspace Billing.

Errors and limits: Authentication, permission or transport errors.

AsyncClient.workspace#

Inspect the credential workspace, role, metadata and resolved limits.

AsyncClient.workspace()

Returns: Workspace dictionary (await for AsyncClient).

Errors and limits: Missing/invalid credential or workspace selection mismatch; no account-wide authority.

AsyncJob#

AsyncJob(client, job_id)

AsyncJob.cancel#

Explicitly request remote cancellation of this job.

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.

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.

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

Returns: Supervised fit: predictor dictionary. Predict or model_run: result dictionary. Discovery: CausalResult. Batch prediction: manifest dictionary for succeeded or partially_completed jobs, with row_count, successful_ranges, failed_ranges, result_reference and expires_at. Ranges are zero-based [start, stop), with stop excluded. Inspect failed_ranges before using the result; retrieve ordered predictions, probabilities and per-range errors separately through client.batch_payload(job.id, result_reference=manifest["result_reference"]). Failed rows have null predictions; partial completion is not success for every row.

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. Batch payload retrieval requires current workspace authorization and unexpired retention; no third-party download URL is followed.

CausalDiscovery#

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.

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.

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.

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#

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#

Return an independent JSON-compatible copy of the native result.

CausalResult.to_dict()

Returns: Dictionary preserving native result fields; job_id remains a separate property.

Errors and limits: No remote call; mutations do not affect the immutable result.

CausalResult.to_ergodic#

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

CausalResult.to_ergodic()

Returns: ergodic.MixedGraph (install welt-client[ergodic]). Use to_adjacency(order=list(result.variables)) for original axes.

Errors and limits: OptionalDependencyError when ergodic is missing or reads no supported graph format (ergodic.GRAPH_FORMAT); UnsupportedGraphConversionError for every non-declared-DAG graph.

Forecast#

Forecast(
    model='chronos-2',
    configuration='default',
    base_url=None,
    api_key=None,
    workspace=None,
    timeout=600,
)

Zero-shot local history context, not a durable Predictor. See forecasting for input/time/version/ownership rules; no score or automatic cross-validation contract.

Forecast.fit#

Copy and validate local univariate history, then resolve workspace/model versions. No history upload, predictor or training job.

Forecast.fit(
    history,
    *,
    time=None,
    target=None,
    start=None,
    frequency_seconds=None,
)

Returns: The same fitted Forecast (self); zero-shot context only.

Errors and limits: ValueError before transport for invalid history/time/parameters; authentication, metadata or unsupported-capability errors. Failed refit clears old context.

Forecast.predict#

Submit one guarded run with copied history; wait within timeout.

Forecast.predict(horizon, *, idempotency_key=None)

Returns: numpy.ndarray, shape (horizon,), containing native medians.

Errors and limits: Unfitted or changed context/connection, invalid horizon/levels, version conflicts, availability, capacity, execution, JobTimeoutError or InvalidForecastResultError.

Forecast.predict_details#

Submit one guarded run, wait and validate native provenance and exact request expectations.

Forecast.predict_details(
    horizon,
    *,
    quantile_levels=(0.1, 0.5, 0.9),
    idempotency_key=None,
)

Returns: Immutable ForecastResult; properties and conversions share this one run.

Errors and limits: Unfitted or changed context/connection, invalid horizon/levels, version conflicts, availability, capacity, execution, JobTimeoutError or InvalidForecastResultError.

Forecast.predict_quantiles#

Submit one guarded zero-shot forecast run with owned history and native quantile levels.

Forecast.predict_quantiles(
    horizon,
    *,
    quantile_levels=(0.1, 0.5, 0.9),
    idempotency_key=None,
)

Returns: numpy.ndarray, shape (horizon, n_quantiles), in requested level order.

Errors and limits: Unfitted or changed context/connection, invalid horizon/levels, version conflicts, availability, capacity, execution, JobTimeoutError or InvalidForecastResultError.

Forecast.set_params#

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

Forecast.set_params(**params)

Returns: The same estimator (self).

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

Forecast.submit_predict#

Submit one guarded durable forecast without waiting; retain job.id.

Forecast.submit_predict(
    horizon,
    *,
    quantile_levels=(0.1, 0.5, 0.9),
    idempotency_key=None,
)

Returns: ForecastJob owning its new client; close explicitly or use a context manager.

Errors and limits: Unfitted or changed context/connection, invalid horizon/levels, version conflicts, availability, capacity, execution, JobTimeoutError or InvalidForecastResultError.

ForecastResult#

ForecastResult(payload, *, job_id)

Immutable native result with job_id, model_id, model_version, configuration, timestamps, predictions, quantile_levels and quantiles properties. Arrays/dictionaries are owned copies; native medians and quantiles carry no calibrated coverage claim.

ForecastResult.to_dict#

Return an independent JSON-compatible copy of the native result.

ForecastResult.to_dict()

Returns: Dictionary preserving native result fields; job_id remains a separate property.

Errors and limits: No remote call; mutations do not affect the immutable result.

ForecastResult.to_frame#

Copy native future UTC rows into a DataFrame; no remote call.

ForecastResult.to_frame()

Returns: pandas.DataFrame with median and q_<level> columns.

Errors and limits: No result repair, calibrated coverage or evaluation claim.

ForecastJob#

ForecastJob(job, *, expected=None, owns_client=False)

ForecastJob.cancel#

Validate the forecast task/identity before explicitly requesting remote cancellation.

ForecastJob.cancel()

Returns: Validated server job metadata (await for AsyncForecastJob).

Errors and limits: Task/version/provenance validation, authentication, permission, NotFoundError or job conflict; cancellation may race completion.

ForecastJob.close#

Close an estimator-submitted job’s owned client. Reconnected handles borrow and leave their client open.

ForecastJob.close()

Returns: None; no cancellation or deletion.

Errors and limits: Local cleanup only.

ForecastJob.inspect#

Read the durable job state and server-reported stages.

ForecastJob.inspect()

Returns: Job metadata dictionary (await for AsyncJob).

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

ForecastJob.result#

Wait within a local budget, validate durable task/version/result identities and preserve native values.

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

Returns: ForecastResult (await for AsyncForecastJob). Estimator jobs also validate exact submitted context/horizon/future times/levels; reconnects cannot reconstruct missing original context.

Errors and limits: Typed remote errors, JobTimeoutError retaining job_id, or InvalidForecastResultError. No resubmission, repair or implicit cancellation.

AsyncForecastJob#

AsyncForecastJob(job)

AsyncForecastJob.aclose#

Finish a reconnected async handle; its borrowed AsyncClient remains open.

AsyncForecastJob.aclose()

Returns: Awaited None; no cancellation or deletion.

Errors and limits: Local cleanup only.

AsyncForecastJob.cancel#

Validate the forecast task/identity before explicitly requesting remote cancellation.

AsyncForecastJob.cancel()

Returns: Validated server job metadata (await for AsyncForecastJob).

Errors and limits: Task/version/provenance validation, authentication, permission, NotFoundError or job conflict; cancellation may race completion.

AsyncForecastJob.inspect#

Read the durable job state and server-reported stages.

AsyncForecastJob.inspect()

Returns: Job metadata dictionary (await for AsyncJob).

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

AsyncForecastJob.result#

Wait within a local budget, validate durable task/version/result identities and preserve native values.

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

Returns: ForecastResult (await for AsyncForecastJob). Estimator jobs also validate exact submitted context/horizon/future times/levels; reconnects cannot reconstruct missing original context.

Errors and limits: Typed remote errors, JobTimeoutError retaining job_id, or InvalidForecastResultError. No resubmission, repair or implicit cancellation.

Evaluation#

Evaluation(client, payload)

Cross-validated comparison handle; see evaluations. Properties: id, status, stage, finished, task, dataset_id, target, rows, primary_metric, positive_class, classes, models, skipped, estimated_credits, credits (settled, None until then), runtime, comparison, warnings and predictions_expires_at. Values are owned copies. Reads borrow the client.

Evaluation.cancel#

Cancel every unfinished model; reserved credits are released.

Evaluation.cancel()

Returns: The same handle with status cancelled, or its final state if already finished.

Errors and limits: NotFoundError; authentication or permission errors; cancellation may race completion.

Evaluation.delete#

Delete a terminal (finished, failed or cancelled) evaluation: results, predictions, report and its links.

Evaluation.delete()

Returns: None.

Errors and limits: ConflictError (dependency_conflict) while running; retryable deletion_pending; NotFoundError.

Evaluation.fit#

Submit a new fit of the chosen model (default: the leaderboard's first) on the full stored dataset with the evaluation's seed and the model's current version; warns with EvaluationWarning if that differs from the evaluated version. Not a promotion of a fold context.

Evaluation.fit(model_id=None, *, timeout=600, idempotency_key=None)

Returns: Fitted Classifier or Regressor (await for AsyncEvaluation).

Errors and limits: ValueError for an unranked model or an evaluation with split columns; ConflictError before results exist; fit errors and JobTimeoutError.

Evaluation.folds#

Read per-fold metrics for every model and the baseline.

Evaluation.folds()

Returns: Long pandas.DataFrame with model_id, fold, rows, metric and value (NaN when undefined).

Errors and limits: ConflictError result_not_ready or result_unavailable; NotFoundError.

Evaluation.predictions#

Read out-of-fold predictions for every evaluated row.

Evaluation.predictions()

Returns: pandas.DataFrame with row_index, fold, actual, one column per model and baseline, and <model>:p(<class>) probabilities for classification.

Errors and limits: ResultExpiredError (410) after seven days; ConflictError before results exist.

Evaluation.refresh#

Read the evaluation's current state and per-model progress.

Evaluation.refresh()

Returns: The same handle (self), updated (await for AsyncEvaluation).

Errors and limits: NotFoundError after deletion; authentication, permission or transport errors.

Evaluation.report_html#

Read the self-contained HTML report (no script, no external resources); cached once read.

Evaluation.report_html()

Returns: HTML document string.

Errors and limits: ConflictError result_not_ready or result_unavailable; NotFoundError.

Evaluation.report_link#

Create a signed report URL that anyone holding it can open without signing in, for 1–7 days. A key-created link never outlives the key.

Evaluation.report_link(days=7)

Returns: ReportLink whose url is returned only now; repr hides it.

Errors and limits: ValueError for days outside 1–7; ConflictError when no report exists; at most 20 live links.

Evaluation.report_links#

List the evaluation's report links without their URLs.

Evaluation.report_links()

Returns: List of ReportLink with url None.

Errors and limits: NotFoundError; authentication or permission errors.

Evaluation.revoke_report_link#

Revoke one report link by ID or ReportLink; it then returns 410.

Evaluation.revoke_report_link(link_id)

Returns: None.

Errors and limits: NotFoundError for an unknown link; PermissionDeniedError for a read-only key.

Evaluation.show#

Display the report in Jupyter inside a sandboxed iframe (no script, no network loads, no notebook restyling), or the status of an unfinished evaluation.

Evaluation.show()

Returns: None (await for AsyncEvaluation).

Errors and limits: OptionalDependencyError without IPython; report read errors.

Evaluation.summary#

Build the leaderboard locally from the finished evaluation; no request.

Evaluation.summary()

Returns: pandas.DataFrame indexed by model_id: ranked models, then the baseline, with name, rank (nullable) and <metric>_mean / <metric>_sd columns.

Errors and limits: ConflictError result_not_ready before it finishes, result_unavailable after failure or cancellation.

Evaluation.to_dict#

Copy the last evaluation resource read from the server.

Evaluation.to_dict()

Returns: Independent dictionary with status, provenance (fold_sha256, versions), models, skipped and summary.

Errors and limits: No remote call.

Evaluation.wait#

Poll with backoff until the evaluation finishes; timeout=None waits without a local limit.

Evaluation.wait(timeout=600, *, poll_interval=0.25)

Returns: The same finished handle. partially_completed returns with an EvaluationWarning; models[].error explains the rest.

Errors and limits: ExecutionError when no model finished, JobCancelledError after cancellation, JobTimeoutError naming the evaluation. A timeout never cancels.

AsyncEvaluation#

AsyncEvaluation(client, payload)

AsyncEvaluation.cancel#

Cancel every unfinished model; reserved credits are released.

AsyncEvaluation.cancel()

Returns: The same handle with status cancelled, or its final state if already finished.

Errors and limits: NotFoundError; authentication or permission errors; cancellation may race completion.

AsyncEvaluation.delete#

Delete a terminal (finished, failed or cancelled) evaluation: results, predictions, report and its links.

AsyncEvaluation.delete()

Returns: None.

Errors and limits: ConflictError (dependency_conflict) while running; retryable deletion_pending; NotFoundError.

AsyncEvaluation.fit#

Submit a new fit of the chosen model (default: the leaderboard's first) on the full stored dataset with the evaluation's seed and the model's current version; warns with EvaluationWarning if that differs from the evaluated version. Not a promotion of a fold context.

AsyncEvaluation.fit(model_id=None, *, timeout=600, idempotency_key=None)

Returns: Fitted Classifier or Regressor (await for AsyncEvaluation).

Errors and limits: ValueError for an unranked model or an evaluation with split columns; ConflictError before results exist; fit errors and JobTimeoutError.

AsyncEvaluation.folds#

Read per-fold metrics for every model and the baseline.

AsyncEvaluation.folds()

Returns: Long pandas.DataFrame with model_id, fold, rows, metric and value (NaN when undefined).

Errors and limits: ConflictError result_not_ready or result_unavailable; NotFoundError.

AsyncEvaluation.predictions#

Read out-of-fold predictions for every evaluated row.

AsyncEvaluation.predictions()

Returns: pandas.DataFrame with row_index, fold, actual, one column per model and baseline, and <model>:p(<class>) probabilities for classification.

Errors and limits: ResultExpiredError (410) after seven days; ConflictError before results exist.

AsyncEvaluation.refresh#

Read the evaluation's current state and per-model progress.

AsyncEvaluation.refresh()

Returns: The same handle (self), updated (await for AsyncEvaluation).

Errors and limits: NotFoundError after deletion; authentication, permission or transport errors.

AsyncEvaluation.report_html#

Read the self-contained HTML report (no script, no external resources); cached once read.

AsyncEvaluation.report_html()

Returns: HTML document string.

Errors and limits: ConflictError result_not_ready or result_unavailable; NotFoundError.

AsyncEvaluation.report_link#

Create a signed report URL that anyone holding it can open without signing in, for 1–7 days. A key-created link never outlives the key.

AsyncEvaluation.report_link(days=7)

Returns: ReportLink whose url is returned only now; repr hides it.

Errors and limits: ValueError for days outside 1–7; ConflictError when no report exists; at most 20 live links.

AsyncEvaluation.report_links#

List the evaluation's report links without their URLs.

AsyncEvaluation.report_links()

Returns: List of ReportLink with url None.

Errors and limits: NotFoundError; authentication or permission errors.

AsyncEvaluation.revoke_report_link#

Revoke one report link by ID or ReportLink; it then returns 410.

AsyncEvaluation.revoke_report_link(link_id)

Returns: None.

Errors and limits: NotFoundError for an unknown link; PermissionDeniedError for a read-only key.

AsyncEvaluation.show#

Display the report in Jupyter inside a sandboxed iframe (no script, no network loads, no notebook restyling), or the status of an unfinished evaluation.

AsyncEvaluation.show()

Returns: None (await for AsyncEvaluation).

Errors and limits: OptionalDependencyError without IPython; report read errors.

AsyncEvaluation.summary#

Build the leaderboard locally from the finished evaluation; no request.

AsyncEvaluation.summary()

Returns: pandas.DataFrame indexed by model_id: ranked models, then the baseline, with name, rank (nullable) and <metric>_mean / <metric>_sd columns.

Errors and limits: ConflictError result_not_ready before it finishes, result_unavailable after failure or cancellation.

AsyncEvaluation.to_dict#

Copy the last evaluation resource read from the server.

AsyncEvaluation.to_dict()

Returns: Independent dictionary with status, provenance (fold_sha256, versions), models, skipped and summary.

Errors and limits: No remote call.

AsyncEvaluation.wait#

Poll with backoff until the evaluation finishes; timeout=None waits without a local limit.

AsyncEvaluation.wait(timeout=600, *, poll_interval=0.25)

Returns: The same finished handle. partially_completed returns with an EvaluationWarning; models[].error explains the rest.

Errors and limits: ExecutionError when no model finished, JobCancelledError after cancellation, JobTimeoutError naming the evaluation. A timeout never cancels.

ReportLink#

ReportLink(
    id: str,
    evaluation_id: str,
    url: str | None,
    created_at: str,
    expires_at: str,
    revoked: bool,
    created_by: str | None = None,
) -> None

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.