Common solver API reference

Import routing, local execution, platform records, and automation operations from qpiai_opt.opt_solvers. Solver-specific classes use their problem-class subpackages.

from qpiai_opt.opt_solvers import Client, classify, inspect, solve

Module: milp

Solver-specific namespace qpiai_opt.opt_solvers.milp. See the MILP solver API, LP/MILP modelling guide, and QP modelling guide.

Module: qubo

Solver-specific namespace qpiai_opt.opt_solvers.qubo. See the QUBO solver API and QUBO modelling guide.

Module: hubo

Solver-specific namespace qpiai_opt.opt_solvers.hubo. See the HUBO solver API and HUBO modelling guide.

Module: ising

Native spin-problem namespace qpiai_opt.opt_solvers.ising. It exports IsingProblem; see its constructor and methods below and the Ising workflow.

Class: Client

Client(*, api_key: 'Optional[str]' = None, experiment_id: 'Optional[str]' = None, experiment_name: 'Optional[str]' = None, base_url: 'str' = 'https://opt-server.qpiai.tech/api', timeout: 'float' = 60.0, session: 'Optional[requests.Session]' = None) -> 'None'

Authenticated client for QpiAI Platform resources, jobs, and storage.

Public class attributes: DEFAULT_URL = "https://opt-server.qpiai.tech/api" and DEFAULT_EXPERIMENT_NAME = "Default Experiment".

Construction is keyword-only and performs no HTTP request. api_key must be a nonempty string despite its None signature default; it is stripped and stored. The SDK does not load a key from an environment variable automatically. base_url, optional experiment selectors, and the positive finite non-Boolean timeout are validated locally. experiment_name=None selects the default name. session is an optional requests.Session; a supplied session remains caller-owned. See construction and transport.

Shared argument and failure rules

These rules apply to the client methods below unless a method states a narrower contract:

• IDs inserted into URL paths are nonempty stripped strings using only ASCII letters, digits, ., _, -, and ~; . and .. are rejected. Other names, role strings, email selectors, and search strings must be nonempty after stripping. Email syntax and allowed roles remain server policy.
• description accepts any string, including ""; it is not stripped. Pagination takes positive non-Boolean integral values and normalizes them to Python integers. Boolean options require Python bool values.
• Optional request timeout=None uses the client default; a supplied scalar must be finite and positive. Request timeouts control connection/read waits, not total elapsed download time. Job monitoring has a separate budget; see timeouts.
• Invalid SDK arguments raise ValueError. HTTP 401 raises AuthenticationError; other HTTP error responses raise APIError. Transport exceptions from Requests propagate. Invalid JSON or the wrong top-level object/array shape raises APIError; malformed typed records raise Pydantic validation errors. Server authorization applies to every operation.
• Methods returning dict[str, Any] preserve the endpoint's acknowledgement or raw record; keys are not a uniform schema. Typed returns use the platform record contracts. The client has no automatic write retry or server-side idempotency guarantee.

All methods below use the configured platform transport. Local-solver authentication is a separate runtime operation and does not inherit a custom client base_url or session.

Methods and properties

Method: validate_identifier

validate_identifier(value: 'str', name: 'str') -> 'str'

Return value stripped of surrounding whitespace. value must be a non-empty string; name identifies the argument in the ValueError message.

Method: validate_base_url

validate_base_url(value: 'str') -> 'str'

Return an HTTP(S) base URL without trailing slashes. Empty values, URLs without a network location, other schemes, queries, and fragments raise ValueError.

Method: validate_pagination

validate_pagination(page: 'int', page_size: 'int') -> 'tuple[int, int]'

Return (page, page_size) as Python integers. Both inputs must be positive integral values; booleans are rejected.

Method: validate_boolean

validate_boolean(value: 'bool', name: 'str') -> 'bool'

Return a strict Boolean input. Other values raise ValueError using name to identify the argument.

Method: validate_scheduled_at

validate_scheduled_at(value: 'str') -> 'str'

Return the stripped ISO 8601 timestamp string after verifying that it contains a timezone offset. A trailing Z is accepted; empty, malformed, or timezone-naive values raise ValueError.

Method: validate_timeout

validate_timeout(value: 'float', name: 'str' = 'timeout') -> 'float'

Return a positive finite timeout as float. Booleans, non-real values, zero, negative values, and non-finite values raise ValueError.

Property: headers

headers

Return a new dict[str, str] containing {"X-Secret-Token": client.api_key}. Treat the returned value as secret material; modifying it does not change the client.

Method: verify_api_key

verify_api_key(api_key: 'Optional[str]' = None) -> 'Dict[str, Any]'

Verify the supplied nonempty stripped key, or self.api_key when omitted, and return the raw verification dict. This read does not replace the stored credential. The request uses self.timeout; malformed or rejected responses follow the shared error rules.

Method: me

me(*, timeout: 'Optional[float]' = None) -> 'Dict[str, Any]'

Return the authenticated user's raw dict. timeout optionally overrides the request timeout; no fixed user-field schema is imposed by this method.

Method: get_api_key

get_api_key() -> 'Dict[str, Any]'

Return the current raw access-token dict; it can contain secret material. No local credential value is changed.

Method: regenerate_api_key

regenerate_api_key() -> 'Dict[str, Any]'

Request token regeneration and return its raw dict. This changes server state but does not automatically replace client.api_key; read the returned record through trusted application code before making further authenticated calls. Do not log the record.

Method: get_user_credit_usage

get_user_credit_usage(user_id: 'Optional[str]' = None, *, period: 'str' = 'monthly', by_resource: 'bool' = False, timeout: 'Optional[float]' = None) -> 'Union[CreditUsage, CreditUsageByResource]'

Return CreditUsage by default or CreditUsageByResource for by_resource=True. Omitted user_id is resolved through me(). period is stripped/lowercased and must be daily, weekly, monthly, or yearly; by_resource must be Boolean. timeout applies to each required request. A current-user record without an ID raises APIError.

Method: get_workspace_credit_usage

get_workspace_credit_usage(workspace_id: 'str', *, period: 'str' = 'monthly', by_resource: 'bool' = False, timeout: 'Optional[float]' = None) -> 'Union[CreditUsage, CreditUsageByResource]'

Return usage for the supplied workspace ID. Return type, period choices, by_resource, and per-request timeout rules match get_user_credit_usage(); workspace access is enforced by the server.

Method: get_organization_credit_usage

get_organization_credit_usage(organization_id: 'Optional[str]' = None, *, period: 'str' = 'monthly', by_resource: 'bool' = False, timeout: 'Optional[float]' = None) -> 'Union[CreditUsage, CreditUsageByResource]'

Return usage for the supplied organization ID, or resolve the authenticated organization through me() when omitted. Return type, period choices, grouping, and timeout rules match get_user_credit_usage(). Missing current-organization metadata raises APIError.

Method: get_user_quotas

get_user_quotas(user_id: 'Optional[str]' = None, *, timeout: 'Optional[float]' = None) -> 'List[CreditQuota]'

Return list[CreditQuota]. Omitted user_id is resolved through me(); the platform must return a JSON array. timeout applies to each request. Capacity and remaining-credit formulas are defined by CreditQuota.

Method: get_workspace_quotas

get_workspace_quotas(workspace_id: 'str', *, timeout: 'Optional[float]' = None) -> 'List[CreditQuota]'

Return list[CreditQuota] for the workspace ID. The platform response must contain a quotas list; a missing or malformed collection raises APIError. timeout overrides each request timeout.

Method: get_organization_quotas

get_organization_quotas(organization_id: 'Optional[str]' = None, *, timeout: 'Optional[float]' = None) -> 'List[CreditQuota]'

Return list[CreditQuota] for the organization ID, resolving the current organization through me() if omitted. The response must contain a quotas list. Missing current-organization metadata or a malformed collection raises APIError.

Method: get_organization

get_organization(organization_id: 'str') -> 'Organization'

Return an organization by ID.

Method: update_organization

update_organization(organization_id: 'str', *, name: 'str') -> 'Dict[str, Any]'

Rename an organization and return the platform confirmation.

Method: delete_organization

delete_organization(organization_id: 'str') -> 'Dict[str, Any]'

Delete an organization and return the platform confirmation.

Method: invite_member

invite_member(organization_id: 'str', *, email: 'str', role: 'str') -> 'Dict[str, Any]'

Invite one organization member with the requested role.

Method: invite_members

invite_members(organization_id: 'str', users: 'List[Dict[str, str]]') -> 'Dict[str, Any]'

Accept an actual nonempty list[dict]; each dictionary must contain nonempty stripped email and role strings and no other keys. Validate the full batch before sending it and return the server's acknowledgement dict. This does not establish a per-member outcome beyond the returned payload.

Method: list_invitations

list_invitations(organization_id: 'str') -> 'List[Invitation]'

Return invitations for an organization.

Method: cancel_invitation

cancel_invitation(invitation_id: 'str') -> 'Dict[str, Any]'

Cancel an invitation and return the platform confirmation.

Method: update_member_role

update_member_role(organization_id: 'str', user_id: 'str', *, role: 'str') -> 'Dict[str, Any]'

Update an organization member's role.

Method: can_invite_members

can_invite_members(organization_id: 'str') -> 'Dict[str, Any]'

Return invitation capacity and permission data.

Method: get_organization_statistics

get_organization_statistics(organization_id: 'str') -> 'Dict[str, Any]'

Return aggregate organization statistics.

Method: get_organization_compute_resources

get_organization_compute_resources(organization_id: 'str') -> 'List[ComputeResource]'

Return compute resources visible to an organization.

Method: create_workspace

create_workspace(organization_id: 'str', *, name: 'str', description: 'str' = '') -> 'Workspace'

Create a workspace using the supplied organization ID, required name, and string description. Resolve the owner from me() and return Workspace; missing owner metadata raises APIError. The default description is empty.

Method: get_workspace

get_workspace(workspace_id: 'str') -> 'Workspace'

Return a workspace by ID.

Method: update_workspace

update_workspace(workspace_id: 'str', *, name: 'str', description: 'str' = '') -> 'Workspace'

Fetch the current workspace, send the supplied name and description, merge returned fields into the current record, and return validated Workspace. Omitting description sends "", not the old description. This is a server write preceded by a read, not an atomic read/modify/write transaction.

Method: delete_workspace

delete_workspace(workspace_id: 'str') -> 'Dict[str, Any]'

Delete a workspace and return the platform confirmation.

Method: list_workspaces

list_workspaces(organization_id: 'str', *, page: 'int' = 1, page_size: 'int' = 10) -> 'WorkspaceList'

Return a page of workspaces for an organization.

Method: list_my_workspaces

list_my_workspaces(*, page: 'int' = 1, page_size: 'int' = 10, search: 'Optional[str]' = None) -> 'WorkspaceList'

Return a page of workspaces visible to the authenticated user.

Method: list_workspace_members

list_workspace_members(workspace_id: 'str') -> 'List[UserSummary]'

Return members of a workspace.

Method: add_workspace_member

add_workspace_member(workspace_id: 'str', *, user_id: 'Optional[str]' = None, email: 'Optional[str]' = None) -> 'Dict[str, Any]'

Require exactly one of user_id or email; both/none raise ValueError. Validate the workspace ID and selected nonempty selector, then return the server acknowledgement dict. User IDs use path-ID validation; email selectors use stripped nonempty-string validation.

Method: remove_workspace_member

remove_workspace_member(workspace_id: 'str', user_id: 'str') -> 'Dict[str, Any]'

Remove one workspace member.

Method: add_workspace_members

add_workspace_members(workspace_id: 'str', emails: 'List[str]') -> 'Dict[str, Any]'

Accept an actual nonempty list[str] of nonempty stripped email selectors. Validate every entry before the request and return the server acknowledgement dict; the server determines individual membership outcomes.

Method: create_project

create_project(workspace_id: 'str', *, name: 'str', description: 'str' = '') -> 'Project'

Create a project with the supplied workspace ID, required name, and string description; return Project. The default description is empty, and the server assigns ownership.

Method: get_project

get_project(project_id: 'str') -> 'Project'

Return a project by ID.

Method: update_project

update_project(project_id: 'str', *, name: 'str', description: 'str' = '') -> 'Project'

Fetch the project, send name and description, merge returned fields into the current record, and return validated Project. Omitting description sends the empty string. Concurrency behaviour matches update_workspace().

Method: delete_project

delete_project(project_id: 'str') -> 'Dict[str, Any]'

Delete a project and return the platform confirmation.

Method: list_projects

list_projects(workspace_id: 'str', *, page: 'int' = 1, page_size: 'int' = 10, search: 'Optional[str]' = None) -> 'ProjectList'

Return a page of projects in a workspace.

Method: list_my_projects

list_my_projects(*, page: 'int' = 1, page_size: 'int' = 10) -> 'ProjectList'

Return a page of projects visible to the authenticated user.

Method: list_project_members

list_project_members(project_id: 'str') -> 'List[UserSummary]'

Return members of a project.

Method: add_project_member

add_project_member(project_id: 'str', *, user_id: 'Optional[str]' = None, email: 'Optional[str]' = None) -> 'Dict[str, Any]'

Require exactly one of user_id or email and return the server acknowledgement dict. Selector validation and both/none errors match add_workspace_member().

Method: remove_project_member

remove_project_member(project_id: 'str', user_id: 'str') -> 'Dict[str, Any]'

Remove one project member.

Method: create_experiment

create_experiment(project_id: 'str', *, name: 'str', description: 'str' = '') -> 'Experiment'

Create an experiment using the project ID, required name, and string description. Resolve its owner through me() and return Experiment; missing owner metadata raises APIError. The default description is empty.

Method: get_experiment

get_experiment(experiment_id: 'str') -> 'Experiment'

Return an experiment by ID.

Method: update_experiment

update_experiment(experiment_id: 'str', *, name: 'str', description: 'str' = '') -> 'Experiment'

Fetch the experiment, send name and description, merge returned fields into the current record, and return validated Experiment. Omitting description sends the empty string. Concurrency behaviour matches update_workspace().

Method: delete_experiment

delete_experiment(experiment_id: 'str') -> 'Dict[str, Any]'

Delete an experiment and return the platform confirmation.

Method: list_experiments

list_experiments(project_id: 'str', *, page: 'int' = 1, page_size: 'int' = 10, search: 'Optional[str]' = None) -> 'ExperimentList'

Return a page of experiments in a project.

Method: list_my_experiments

list_my_experiments(*, page: 'int' = 1, page_size: 'int' = 10) -> 'ExperimentList'

Return a page of experiments visible to the authenticated user.

Method: list_workspace_experiments

list_workspace_experiments(workspace_id: 'str', *, page: 'int' = 1, page_size: 'int' = 10) -> 'ExperimentList'

Return a page of experiments in a workspace.

Method: list_experiment_members

list_experiment_members(experiment_id: 'str') -> 'List[UserSummary]'

Return members of an experiment.

Method: add_experiment_member

add_experiment_member(experiment_id: 'str', user_id: 'str') -> 'Dict[str, Any]'

Add one experiment member by user ID.

Method: remove_experiment_member

remove_experiment_member(experiment_id: 'str', user_id: 'str') -> 'Dict[str, Any]'

Remove one experiment member.

Method: associate_compute_resource

associate_compute_resource(experiment_id: 'str', compute_resource_id: 'str') -> 'Dict[str, Any]'

Associate an experiment with a discovered compute resource.

Method: default_problem_name

default_problem_name(method: 'str', detail: 'Optional[str]' = None) -> 'str'

Return SDK {METHOD} problem[: {detail}] - {timestamp}, where METHOD is converted to uppercase and timestamp is the current UTC ISO 8601 time with millisecond precision and a trailing Z. method and a supplied detail must be non-empty strings after stripping.

Method: resolve_experiment

resolve_experiment(name: 'str', *, timeout: 'Optional[float]' = None) -> 'str'

Strip and validate name, resolve its exact match within the authenticated organization, and return the experiment ID as str. Successful lookups are cached per client/name; a cached lookup performs no new request. This method does not create an experiment. A response without an experiment ID raises APIError. timeout overrides an uncached request's timeout.

Method: create_problem

create_problem(payload: 'Dict[str, Any]', *, timeout: 'Optional[float]' = None) -> 'Problem'

Require an actual dict containing nonempty name and method strings. Copy the payload, normalize those two fields, pass other fields to the platform, and return Problem. This method does not validate a problem-class payload as fully as its high-level solver; prefer the solver's submit() when creating solver work.

Method: get_problem

get_problem(problem_id: 'str', *, timeout: 'Optional[float]' = None) -> 'Problem'

Return a platform problem by ID.

Method: list_problems

list_problems(*, page: 'int' = 1, page_size: 'int' = 10) -> 'ProblemList'

Return a page of platform problems.

Method: update_problem

update_problem(problem_id: 'str', payload: 'Dict[str, Any]') -> 'Problem'

Require a nonempty payload dict; copy it and normalize name and method if supplied. Other fields are passed to the service. Return the validated Problem from the update response. Invalid IDs or payloads raise ValueError before the write request.

Method: delete_problem

delete_problem(problem_id: 'str', *, timeout: 'Optional[float]' = None) -> 'Dict[str, Any]'

Delete a problem and return the platform confirmation.

Method: submit_job

submit_job(problem_id: 'str', *, experiment_id: 'Optional[str]' = None, experiment_name: 'Optional[str]' = None, compute_resource_id: 'Optional[str]' = None, method: 'Optional[str]' = None, scheduled_at: 'Optional[str]' = None, timeout: 'Optional[float]' = None) -> 'JobSubmission'

Submit the existing problem ID and return JobSubmission. Optional experiment selectors follow experiment precedence; a supplied ID takes precedence over a name. Optional compute_resource_id pins a platform resource; method is a nonempty string passed to the service. scheduled_at requires a timezone-aware ISO 8601 string and requests scheduled submission. timeout applies independently to experiment lookup and job creation. This operation can consume credits and is not retried automatically.

Method: schedule_job

schedule_job(problem_id: 'str', scheduled_at: 'str', *, experiment_id: 'Optional[str]' = None, experiment_name: 'Optional[str]' = None, compute_resource_id: 'Optional[str]' = None, method: 'Optional[str]' = None) -> 'JobSubmission'

Schedule an existing problem and return JobSubmission. scheduled_at is required and follows validate_scheduled_at(). Experiment precedence, resource pinning, method validation, and paid-work implications match submit_job(); this method uses the client request timeout and the dedicated scheduling operation.

Method: get_job

get_job(job_id: 'str', *, timeout: 'Optional[float]' = None) -> 'Job'

Return a platform job by ID.

Method: cancel_job

cancel_job(job_id: 'str') -> 'Dict[str, Any]'

Request job cancellation and return the platform confirmation.

Method: list_jobs

list_jobs(*, page: 'int' = 1, page_size: 'int' = 10, period: 'Optional[str]' = None, status: 'Optional[JobStatus | str]' = None, compute_resource_id: 'Optional[str]' = None) -> 'JobList'

Return JobList for the authenticated user. page/page_size are positive integers. Optional period and compute_resource_id are nonempty stripped strings. status accepts the five non-unknown JobStatus members or exactly their lowercase values, with surrounding whitespace ignored; uppercase strings and "unknown" raise ValueError.

period recognizes daily, weekly, and monthly; None leaves dates unrestricted. Other nonempty strings are forwarded but apply no time filter. See Reading and filtering jobs for time boundaries and resource-filter scope.

Method: list_problem_jobs

list_problem_jobs(problem_id: 'str', **params: 'Any') -> 'JobList'

Return JobList for the supplied problem ID. Accepted params are only page, page_size, period, status, and compute_resource_id; unknown names raise ValueError. Pagination uses positive integers; period/resource filters are nonempty strings. Status and period choices match list_jobs(). The platform problem-job endpoint ignores compute_resource_id.

Method: list_experiment_jobs

list_experiment_jobs(experiment_id: 'Optional[str]' = None, *, experiment_name: 'Optional[str]' = None, **params: 'Any') -> 'JobList'

Resolve the experiment using the standard ID/name precedence and return JobList. Accepted params and validation match list_problem_jobs(); lookup can use the per-client experiment-name cache.

Method: list_solvers

list_solvers(*, method: 'Optional[str]' = None, active_only: 'bool' = False) -> 'List[ComputeResource]'

Return list[ComputeResource]. active_only requires a Boolean. A supplied method is split into uppercase alphanumeric tokens and matched as a prefix of the resource's type, or its backend_name when type is absent. A method with no alphanumeric token raises ValueError. active_only=True keeps status active ignoring case. Discovery does not reserve a resource.

Method: get_solver

get_solver(resource_id: 'str') -> 'ComputeResource'

Return one compute resource by ID.

Method: upload_file

upload_file(path: 'Path', *, user_id: 'Optional[str]' = None, organization_id: 'Optional[str]' = None, workspace_id: 'Optional[str]' = None, project_id: 'Optional[str]' = None, timeout: 'Optional[float]' = None) -> 'Dict[str, Any]'

Accept a path convertible to Path, require an existing regular file, and upload its bytes under the basename. A missing file raises FileNotFoundError. Optional ownership IDs are validated; omitted user or organization IDs are resolved through me(), with APIError if unavailable. timeout applies independently to lookup and upload. The file handle is closed after the request.

Return the raw nested storage dictionary. Missing/non-dictionary storage raises APIError; individual fields, including the conventional ID, are not validated here. Validate the storage identifier before using it in another operation.

Method: download_result

download_result(s3_path: 'str', *, timeout: 'Optional[float]' = None) -> 'Any'

Accept a nonempty stripped S3-path string, obtain its presigned download URL, fetch the object, and return the decoded JSON value (Any). timeout applies separately to the platform request and storage GET. Missing URL metadata or non-JSON content raises APIError; transport errors propagate. The client does not save a local file.

Method: download_result_by_id

download_result_by_id(storage_id: 'str', *, timeout: 'Optional[float]' = None) -> 'Any'

Resolve the storage ID to a presigned URL and return the downloaded JSON value (Any). Request timing, malformed URL metadata, JSON failures, and transport behaviour match download_result().

Method: delete_storage

delete_storage(storage_id: 'str', *, timeout: 'Optional[float]' = None) -> 'Dict[str, Any]'

Delete a storage record and return the platform confirmation.

Method: stream_job

stream_job(job_id: 'str', *, connect_timeout: 'Optional[float]' = None, read_timeout: 'float' = 30.0) -> 'Iterator[SSEEvent]'

Return a generator of SSEEvent for the job ID. Validation and HTTP connection occur when iteration starts. connect_timeout=None uses the client timeout; both timeout values must be positive finite non-Boolean real numbers. The iterator decodes UTF-8 and dispatches blank-line-delimited events; JSON data becomes any decoded JSON value and other data remains text. See SSE parsing and closure. Close the generator if iteration stops early.

Method: wait_for_job

wait_for_job(job_id: 'str', *, timeout: 'float' = 5400.0, poll_interval: 'float' = 5.0, use_sse: 'bool' = True) -> 'Job'

Monitor the existing job and return its completed Job. timeout and poll_interval require positive finite non-Boolean real values; use_sse requires Boolean. Read current state first, optionally make up to three SSE connection attempts, then poll. Transient HTTP statuses and transport exceptions can trigger monitoring retries; no job is resubmitted.

Failed/cancelled states raise JobFailedError/JobCancelledError; unknown states raise APIError; exhausted monitoring budget raises TimeoutError. The budget does not cancel the server job or guarantee that in-flight requests finish within that wall time. See waiting and timeouts.

Method: extract_result

extract_result(job: 'Job', *, timeout: 'Optional[float]' = None) -> 'Any'

Require Job, otherwise raise TypeError. Read inline server_response, or fetch server_response_id when inline data is None; an inline s3:// string is downloaded, while other strings are parsed as JSON when possible. Unparseable non-S3 text remains text. Unwrap a dictionary/list under result or results and return it; otherwise return the decoded value unchanged, including None when no payload exists.

This low-level method does not itself check the job's lifecycle state or validate a class-specific result. High-level solver retrieval performs those checks. timeout applies separately to any required download requests.

Method: health

health() -> 'bool'

Request the authenticated user endpoint with a five-second Requests timeout and return True for a successful HTTP status. Return False on a Requests transport exception or APIError. The method does not parse or validate the response's user JSON.

Platform record conventions

The following platform records are Pydantic models. Constructors use keyword arguments; model_validate(), model_validate_json(), model_dump(), model_dump_json(), and model_json_schema() follow the Pydantic API. Platform records preserve unknown service fields as model extras. They are mutable; construction validation does not imply validation of subsequent field assignment.

Required identifiers and required descriptive names/statuses are nonempty strings, stripped where their validators specify. Datetime fields accept Pydantic's supported datetime inputs. Optional fields default to None unless their signatures state otherwise. List defaults create a separate empty list for each record. Credit fields declared as integer counts are nonnegative integral values and reject Boolean values; durations and rates are finite nonnegative non-Boolean real numbers normalized to float.

Entity records and CreditQuota accept either id or ID; ComputeResource also normalizes those aliases to public id. Supplying both with different stripped values raises validation error. Timing aliases from service payloads are normalized only for declared duration fields: execution_time to compute_time_s, solver_time to solver_time_s, and total_execution_time to total_compute_time_s. Conflicting duplicate durations raise validation error.

Collection and submission records

These return types are importable from qpiai_opt.opt_solvers.platform_models. All constructors are keyword-only and retain unknown service fields. Every collection below defaults to a separate empty list; pagination defaults to a new Pagination().

Class: Problem

Problem(*, id: str, name: str, method: str, created_at: Optional[datetime.datetime] = None, updated_at: Optional[datetime.datetime] = None, **extra_data: Any) -> None

Platform problem record.

Fields: id, name, method, created_at, updated_at.

Class: Job

Job(*, id: str, status: str, method: Optional[str] = None, problem_id: Optional[str] = None, experiment_id: Optional[str] = None, server_response: Any = None, server_response_id: Optional[str] = None, error: Optional[str] = None, compute_time_s: Optional[float] = None, solver_time_s: Optional[float] = None, created_at: Optional[datetime.datetime] = None, updated_at: Optional[datetime.datetime] = None, cancelled_at: Optional[datetime.datetime] = None, cancellation_reason: Optional[str] = None, credits_used: Optional[int] = None, credits_reserved: Optional[int] = None, **extra_data: Any) -> None

Platform job record and lifecycle metadata.

Fields: id, status, method, problem_id, experiment_id, server_response, server_response_id, error, compute_time_s, solver_time_s, created_at, updated_at, cancelled_at, cancellation_reason, credits_used, credits_reserved.

Methods and properties

Property: normalized_status

normalized_status

Return the platform status as a stable SDK lifecycle state.

Enum: JobStatus

JobStatus(value: str) -> JobStatus

Normalized lifecycle states used by SDK job operations. Construct from an exact lowercase value listed below; an unrecognized value raises ValueError. Use normalize() for platform aliases.

Methods and properties

Method: normalize

normalize(value: 'Any') -> "'JobStatus'"

Class method returning a JobStatus. Normalize via lowercase text with surrounding whitespace and underscores removed. pending/queued/scheduled map to pending; running/cancelrequested/inprogress to running; success/completed/complete/succeeded to completed; failed/failure/error to failed; cancelled/canceled to cancelled. Other or absent values return unknown. This is response normalization; list-operation status filters accept a narrower set.

Class: ComputeResource

ComputeResource(*, ID: str, backend_name: Optional[str] = None, type: Optional[str] = None, device_name: Optional[str] = None, status: Optional[str] = None, usage_rate: Optional[float] = None, **extra_data: Any) -> None

Discoverable solver deployment for advanced resource pinning.

The generated constructor signature uses the platform validation alias ID; id is also accepted. Both forms populate the public id field. Remaining fields: backend_name, type, device_name, status, and non-negative finite usage_rate.

Class: CreditQuota

CreditQuota(*, id: str, compute_resource_id: str, allocated_credits: int, used_credits: int = 0, reserved_credits: int = 0, total_credits: Optional[int] = None, top_up_credits: int = 0, top_up_expiry_date: Optional[datetime.datetime] = None, from_date: Optional[datetime.datetime] = None, to_date: Optional[datetime.datetime] = None, user_id: Optional[str] = None, workspace_id: Optional[str] = None, organization_id: Optional[str] = None, compute_resource: Optional[dict[str, Any]] = None, **extra_data: Any) -> None

A current credit allocation and its remaining capacity.

Fields: id, compute_resource_id, allocated_credits, used_credits, reserved_credits, total_credits, top_up_credits, top_up_expiry_date, from_date, to_date, user_id, workspace_id, organization_id, compute_resource.

Supplied credit fields are nonnegative integers, excluding Boolean values. used_credits cannot exceed total_credits when present, otherwise allocated_credits. If both period endpoints are present, to_date >= from_date. compute_resource must be a dictionary or None. Optional ownership IDs normalize an empty string to None and otherwise require nonempty text.

Methods and properties

Property: capacity_credits

capacity_credits

Return int: total_credits when supplied, otherwise allocated_credits.

Property: remaining_credits

remaining_credits

Return int: capacity_credits - used_credits. This property does not subtract reservations or independently add top-ups.

Class: CreditResourceUsage

CreditResourceUsage(*, compute_resource_id: str, used_credits: int, job_count: int, compute_backend: Optional[str] = None, **extra_data: Any) -> None

Credit consumption for one compute resource in a usage report.

Fields: compute_resource_id, used_credits, job_count, compute_backend.

The identifier is nonempty and stripped. Both counts are nonnegative integers, excluding Boolean values. An absent or empty backend string becomes None; other backend values must be nonempty text.

Class: CreditUsage

CreditUsage(*, used_credits: int, start_date: datetime.datetime, end_date: datetime.datetime, jobs: List[qpiai_opt.opt_solvers.platform_models.CreditUsageJob] = <factory>, **extra_data: Any) -> None

Credit consumption for one user, workspace, or organization period.

Fields: used_credits, start_date, end_date, jobs.

used_credits must be a nonnegative integer, excluding Boolean values; end_date cannot precede start_date. This model does not require the listed job credits to sum to the total.

Class: CreditUsageByResource

CreditUsageByResource(*, used_credits: int, start_date: datetime.datetime, end_date: datetime.datetime, compute_resource_usages: List[qpiai_opt.opt_solvers.platform_models.CreditResourceUsage] = <factory>, **extra_data: Any) -> None

Credit consumption grouped by compute resource for one period.

Fields: used_credits, start_date, end_date, compute_resource_usages.

Count and period validation match CreditUsage. Additionally, sum(item.used_credits for item in compute_resource_usages) must equal used_credits; inconsistent grouped reports raise validation error.

Class: CreditUsageJob

CreditUsageJob(*, job_id: str, credits_used: int, name: Optional[str] = None, user_name: Optional[str] = None, device_name: Optional[str] = None, method: Optional[str] = None, status: Optional[str] = None, compute_resource_id: Optional[str] = None, compute_backend: Optional[str] = None, executed_at: Optional[datetime.datetime] = None, **extra_data: Any) -> None

One job included in a credit-usage report.

Fields: job_id, credits_used, name, user_name, device_name, method, status, compute_resource_id, compute_backend, executed_at.

Class: Organization

Organization(*, id: str, organization_name: str, billing_details: Optional[str] = None, min_booking_minutes: Annotated[Optional[int], Strict(strict=True), Ge(ge=0)] = None, max_booking_minutes: Annotated[Optional[int], Strict(strict=True), Ge(ge=0)] = None, max_daily_minutes: Annotated[Optional[int], Strict(strict=True), Ge(ge=0)] = None, current_seat_count: Annotated[Optional[int], Strict(strict=True), Ge(ge=0)] = None, users: List[qpiai_opt.opt_solvers.platform_models.UserSummary] = <factory>, created_at: Optional[datetime.datetime] = None, updated_at: Optional[datetime.datetime] = None, **extra_data: Any) -> None

Organization, limits, and member summaries.

Fields: id, organization_name, billing_details, min_booking_minutes, max_booking_minutes, max_daily_minutes, current_seat_count, users, created_at, updated_at.

Booking limits and seat count are strict nonnegative integers when present. If both booking endpoints are present, min_booking_minutes <= max_booking_minutes. users contains parsed UserSummary records and defaults to an empty list.

Class: Workspace

Workspace(*, id: str, owner_id: Optional[str] = None, name: str, description: str = '', organization_id: str, is_default: bool = False, created_at: Optional[datetime.datetime] = None, updated_at: Optional[datetime.datetime] = None, **extra_data: Any) -> None

Workspace record.

Fields: id, owner_id, name, description, organization_id, is_default, created_at, updated_at.

owner_id may be omitted; supplied owner, name, and organization values must be nonempty stripped text. is_default requires an actual Boolean value. description defaults to the empty string.

Class: Project

Project(*, id: str, owner_id: str, name: str, description: str = '', workspace_id: str, is_default: bool = False, created_at: Optional[datetime.datetime] = None, updated_at: Optional[datetime.datetime] = None, **extra_data: Any) -> None

Project record.

Fields: id, owner_id, name, description, workspace_id, is_default, created_at, updated_at.

Owner, name, and workspace identifiers are required nonempty stripped strings. is_default requires a Boolean; description defaults to the empty string.

Class: Experiment

Experiment(*, id: str, owner_id: str, name: str, description: str = '', project_id: str, workspace_id: Optional[str] = None, compute_resource_id: Optional[str] = None, is_default: bool = False, total_compute_time_s: float = 0.0, total_credits_used: int = 0, created_at: Optional[datetime.datetime] = None, updated_at: Optional[datetime.datetime] = None, **extra_data: Any) -> None

Experiment record and aggregate usage.

Fields: id, owner_id, name, description, project_id, workspace_id, compute_resource_id, is_default, total_compute_time_s, total_credits_used, created_at, updated_at.

Required owner, name, and project values are nonempty stripped strings. Optional workspace_id accepts None or an empty string as absent. is_default requires a Boolean. Total compute time is finite and nonnegative; total credits are a nonnegative integer excluding Boolean values.

Class: Invitation

Invitation(*, id: str, organization_id: str, email: str, role: str, status: str, invitation_type: Optional[str] = None, invited_by: Optional[str] = None, expires_at: Optional[datetime.datetime] = None, created_at: Optional[datetime.datetime] = None, updated_at: Optional[datetime.datetime] = None, **extra_data: Any) -> None

Organization invitation record.

Fields: id, organization_id, email, role, status, invitation_type, invited_by, expires_at, created_at, updated_at.

Class: UserSummary

UserSummary(*, id: str, name: Optional[str] = None, email: Optional[str] = None, role: Optional[str] = None, status: Optional[str] = None, organization_id: Optional[str] = None, is_revoked: Optional[bool] = None, **extra_data: Any) -> None

User membership summary returned inside collaboration records.

Fields: id, name, email, role, status, organization_id, is_revoked.

Optional name, email, and role must be nonempty stripped text when present. Optional status and organization_id normalize an empty string to None. is_revoked accepts only Boolean values or None.

Class: SSEEvent

SSEEvent(*, event: str, data: Any, **extra_data: Any) -> None

One decoded server-sent job event.

Fields: event, data.

event must be a nonempty string without CR/LF; it is retained without stripping. data is the decoded event payload and may have any JSON-compatible shape supplied by the service.

Exception: PlatformError

PlatformError

Base exception for SDK solver and platform-client errors.

Exception: APIError

APIError(message: 'str', *, status_code: 'Optional[int]' = None, code: 'Optional[str]' = None, details: 'Any' = None) -> 'None'

Subclass of PlatformError. Stores status_code: int | None, code: str | None, and details: Any unchanged; str(error) is the supplied message. HTTP and response-shape failures can supply a status, while locally detected malformed metadata may leave it None.

Exception: AuthenticationError

AuthenticationError(message: 'str', *, status_code: 'Optional[int]' = None, code: 'Optional[str]' = None, details: 'Any' = None) -> 'None'

Subclass of APIError with the same constructor and attributes. Used for unverifiable local credentials and the platform client's HTTP 401 responses; other HTTP errors from Client remain APIError. A 401 with code ACCOUNT_REVOKED preserves the service message; other 401 responses use the SDK's API-key guidance. Obtain a free Opt API key at QpiAI Opt or a free QCloud API key at QpiAI QCloud, according to the execution route.

Exception: CapabilityError

CapabilityError(problem_class: 'str', *, requested_mode: 'str', available_providers: 'Mapping[str, tuple[str, ...]]', reason: 'str | None' = None, compatible_alternatives: 'tuple[str, ...]' = ()) -> 'None'

Raised when no available provider can solve the detected problem class.

Methods and properties

Method: as_dict

as_dict() -> 'dict[str, Any]'

Return a dict with error="capability_error", problem_class: str, requested_mode: str, reason: str, available_providers: dict[str, tuple[str, ...]], and compatible_alternatives: list[str]. Construction copies the supplied capabilities mapping and normalizes alternatives to a tuple; a missing/falsey reason gets the default unsupported-provider explanation.

Exception: JobFailedError

JobFailedError(job_id: 'str', message: 'str') -> 'None'

Subclass of PlatformError; stores job_id and formats the message as Job {job_id} failed: {message}.

Exception: JobCancelledError

JobCancelledError(job_id: 'str', message: 'str' = 'cancelled') -> 'None'

Subclass of PlatformError; stores job_id and formats the message as Job {job_id} was cancelled: {message}.

Exception: LocalLimitExceeded

LocalLimitExceeded(problem_class: 'str', *, observed: 'Mapping[str, int | float | str]', limits: 'Mapping[str, int | float]', explanation: 'str', next_action: 'str') -> 'None'

A structured refusal when a problem exceeds a documented local limit.

Methods and properties

Method: as_dict

as_dict() -> 'dict[str, Any]'

Return a dict with error="local_limit_exceeded", problem_class: str, observed: dict[str, int | float | str], limits: dict[str, int | float], explanation: str, and next_action: str. Construction copies the two supplied mappings and retains the descriptive fields as exception attributes.

Type alias: SolveResult

SolveResult = QUBOSolveResult | HUBOSolveResult | MILPSolveResult | IsingSolveResult | QPSolveResult

Union of completed LP, MILP, QP, QUBO, HUBO, and Ising result types. Gate-based optimization algorithms return QuantumResult from qpiai_opt.quantum; that type is not part of this Python alias. The machine-readable schemas()["solve_result"] union also includes QuantumResult.

Class: SolveInfo

SolveInfo(*, problem_class: Literal['LP', 'MILP', 'QP', 'QUBO', 'HUBO', 'ISING'], execution_mode: Literal['local', 'platform'], provider: str, solver: str | None = None, method: str | None = None, termination: Literal['optimal', 'completed', 'limit_reached', 'infeasible', 'unbounded', 'failed', 'unknown'], has_usable_solution: bool, solution_feasible: bool | None, optimality_proven: bool | None, guarantee: Literal['global_optimum', 'best_found', 'best_bound', 'feasible_only', 'infeasibility_proven', 'unboundedness_proven', 'none', 'unknown'], source_objective: float | None = None, transformed: bool | None = None, settings: dict[str, int | float | str | bool] = <factory>) -> None

Common validated interpretation returned by result.info() and carried in ordinary result dumps as solve_info. Field meanings are defined in common solve information.

provider and non-null solver/method values are stripped nonempty strings. Literal fields use the exact values in the signature. source_objective is None or a finite non-Boolean real normalized to float. settings is an actual dictionary with nonempty string keys and Boolean, integer, finite floating-point, or string values; the default is a separate empty dictionary for each instance. Unknown fields and invalid values raise pydantic.ValidationError. Field assignment is frozen; the nested settings dictionary remains mutable.

Construction enforces these relationships:

• has_usable_solution is true exactly when solution_feasible is true.
• termination="optimal", optimality_proven=True, and guarantee="global_optimum" must occur together.
• termination="infeasible" requires guarantee="infeasibility_proven" and no usable solution; termination="unbounded" requires guarantee="unboundedness_proven". Each proof guarantee also requires its corresponding termination.
• guarantee="best_found" or "feasible_only" requires a usable solution.

When attached to a result, the information must match its problem class and execution mode. A non-null source_objective must equal the result's objective, and a usable solution requires a non-null result solution. These checks validate the record's consistency; they do not execute a solver or independently verify its mathematical claims.

Fields: problem_class, execution_mode, provider, solver, method, termination, has_usable_solution, solution_feasible, optimality_proven, guarantee, source_objective, transformed, settings.

Class: IsingSolveResult

IsingSolveResult(*, problem_class: Literal['ISING'] = 'ISING', execution_mode: Literal['local', 'platform'], job_id: str | None = None, problem_id: str | None = None, solver_time_s: typing.Annotated[float | None, Ge(ge=0)] = None, compute_time_s: typing.Annotated[float | None, Ge(ge=0)] = None, solve_info: qpiai_opt.opt_solvers.result_base.SolveInfo | None = None, num_variables: typing.Annotated[int, Strict(strict=True), Ge(ge=0)], objective: float, variable_assignment: Dict[str, Union[int, float]], solution: List[int]) -> None

Completed Ising result. num_variables is a strict nonnegative integer; solution is a list/tuple of exactly that many finite real -1/+1 spins, excluding Booleans, normalized to Python integers. objective is finite and non-Boolean. variable_assignment maps nonempty names to finite non-Boolean numeric values and may contain decoded binary or numeric source variables. These shape checks do not independently verify the objective or source feasibility. Unknown fields and invalid values raise pydantic.ValidationError. Identity and timing use the common result contract.

Fields: problem_class, execution_mode, job_id, problem_id, solver_time_s, compute_time_s, solve_info, num_variables, objective, variable_assignment, solution.

Methods and properties

Method: runtime

runtime(unit: 'str' = 's', *, kind: 'str' = 'compute') -> 'float | None'

Return the compute or solver duration in seconds, milliseconds, or microseconds. kind="compute" is the default; unknown durations return None.

Method: info

info() -> 'SolveInfo'

Return the common provider, method, termination, feasibility, proof, guarantee, source-objective, transformation, and settings view.

Class: QPSolveResult

QPSolveResult(*, problem_class: Literal['QP'] = 'QP', execution_mode: Literal['local'] = 'local', job_id: str | None = None, problem_id: str | None = None, solver_time_s: typing.Annotated[float | None, Ge(ge=0)] = None, compute_time_s: typing.Annotated[float | None, Ge(ge=0)] = None, solve_info: qpiai_opt.opt_solvers.result_base.SolveInfo | None = None, sense: Literal['MIN', 'MAX'], status: str, model_status: str, objective: Optional[float] = None, solution: Optional[Dict[str, float]] = None, iteration_count: typing.Annotated[int, Strict(strict=True), Ge(ge=0)] = 0) -> None

Continuous quadratic-program result, with execution_mode="local". sense is the exact MIN/MAX literal; status is stripped/lowercased, while model_status is stripped without changing case. Both status fields must be nonempty. Optional objective and solution values are finite non-Boolean reals; solution keys are nonempty strings. iteration_count is a strict nonnegative integer. No incumbent is represented by objective=None and/or solution=None; inspect info() before using values. Unknown fields and invalid values raise pydantic.ValidationError. Identity and timing use the common result contract.

Fields: problem_class, execution_mode, job_id, problem_id, solver_time_s, compute_time_s, solve_info, sense, status, model_status, objective, solution, iteration_count.

Methods and properties

Method: runtime

runtime(unit: 'str' = 's', *, kind: 'str' = 'compute') -> 'float | None'

Return the compute or solver duration in seconds, milliseconds, or microseconds. kind="compute" is the default; unknown durations return None.

Method: info

info() -> 'SolveInfo'

Return the common provider, method, termination, feasibility, proof, guarantee, source-objective, transformation, and settings view.

Class: LocalProvider

LocalProvider(client: 'Client | None' = None)

Execute supported problem classes locally with a registered Opt credential. A missing client raises AuthenticationError at construction; a non-Client value raises TypeError. The compiled runtime verifies the key online before each solve; local computation remains free. Prefer the high-level solve() entry point when automatic classification, normalization, and complete compute timing are required.

The public capabilities class attribute is a ProviderCapabilities record. It has name: str, mode: str, problem_classes: tuple[str,...], aggregate exact: bool and heuristic: bool, requires_authentication: bool, diagnostics: tuple[str,...], and problem_capabilities: dict[str,dict[str,bool]] with class-specific exact/heuristic flags. capabilities.as_dict() returns a new dictionary with tuple fields converted to lists and nested capability dictionaries copied. These flags describe available methods, not a guarantee for an individual solve.

Methods and properties

Method: solve

solve(problem: 'Any', *, problem_class: 'str', time_limit: 'float | None' = None, mip_rel_gap: 'float | None' = None, node_limit: 'int | None' = None, num_reads: 'int | None' = None, num_sweeps: 'int | None' = None, seed: 'int | None' = None, **options: 'Any') -> 'SolveResult'

Execute the supplied problem using its explicit canonical problem_class: LP, MILP, QP, QUBO, HUBO, or ISING. This direct provider call does not perform the high-level classification/normalization step. Options use the local option contracts; unsupported options, invalid models, authentication failures, and structural limits propagate as documented there. Return the class-specific result. An unavailable compiled runtime raises ImportError with installation instructions. Direct provider timing does not add the high-level end-to-end compute_time_s measurement.

Constant: LOCAL_LIMITS

LOCAL_LIMITS: Mapping[str, Mapping[str, int]]

Read-only class-to-limit mapping, including read-only nested metric mappings. Keys and inclusive integer thresholds are listed in structural limits. Assigning entries raises TypeError. Limits govern local execution; inspection reports structural metrics without refusing a model solely because it exceeds them.

Function: classify

classify(problem: 'Any') -> 'str'

Return LP, MILP, QP, QUBO, HUBO, ISING, or QUBIT_HAMILTONIAN without solving or authenticating. Accept the documented Model, native problem, LP/MPS path, and dictionary inputs; native MILPProblem returns its declared class. Hamiltonian classification requires the optional QpiAI Quantum SDK and its QubitHamiltonian type. A file is read to determine integrality; missing files or unsupported suffixes raise.

Classification identifies a representation; it does not fully revalidate already constructed native problems or every coefficient in a raw dictionary. Use inspect() for normalization and structural validation. Models use Model.validate() and normalize its MIP label to MILP. Conflicting or unsupported dictionary markers and ambiguous low-degree tuple-key polynomials raise ValueError; unsupported objects raise TypeError.

Function: inspect

inspect(problem: 'Any', *, algorithm: 'Any' = None) -> 'dict[str, Any]'

Normalize and validate the representation, then return dict with problem_class: str, representation: str, metrics: dict[str,int], and valid=True. Invalid inputs raise their validation errors rather than returning valid=False. representation names the normalized input type; the metric inventory and inspection procedure vary by class. Native problem inputs are revalidated; in-memory linear matrices and QP curvature are checked. Inspection does not require authentication or enforce all local size limits, and valid=True is not proof of feasibility or local eligibility.

algorithm=None selects structural inspection. An explicit gate-based optimization algorithm configuration adds the validated quantum report, including compatibility and statically available circuit metrics. Unsupported algorithm/problem combinations raise before execution. Inspection can compile a Model and update its encoding/transformation state, but performs no solve or platform submission.

Function: provider_capabilities

provider_capabilities(*, include_platform: 'bool' = True) -> 'list[dict[str, Any]]'

Return a new list containing the local capability dictionary and, by default, the platform dictionary. include_platform must be an actual Boolean; other values raise TypeError. Each dictionary has name, mode, problem_classes, aggregate exact/heuristic, requires_authentication, diagnostics, and the per-class problem_capabilities map described above. Use class-specific flags when selecting a method. No client, authentication, resource query, or solve is needed.

Function: solve

solve(problem: 'Any', *, mode: 'str' = 'local', client: 'Client | None' = None, allow_platform: 'bool' = False, **options: 'Any') -> 'SolveResult | QuantumResult'

Classify, normalize, and execute a supported problem, returning its class-specific completed result. mode is case-insensitive local, platform, or auto, without whitespace stripping; invalid values raise ValueError. allow_platform must be Boolean or raises TypeError. Without algorithm, local/auto execution requires an Opt Client and fresh online Opt verification; platform execution also requires an Opt Client and can consume credits. Auto fallback occurs only after LocalLimitExceeded and only with allow_platform=True; authentication, validation, infeasibility, and transport failures do not trigger it.

Accepted representations, class-specific options, limits, result semantics, and failure handling are defined in local solving and routing. Local compute_time_s includes this entry point's normalization and result processing; platform durations remain service-reported. An explicit algorithm selects the gate-based optimization route with execution configuration and independent QCloud authentication; it rejects algorithm=None, Opt Client, auto mode, paid fallback, and solver-call options such as time_limit or num_reads. Obtain a free QCloud API key at QpiAI QCloud. execution without algorithm raises ValueError. See the gate-based optimization workflow.

Function: convert

convert(problem: 'Any', target: 'str', **options: 'Any') -> 'Any'

Accept a supported model/problem/dictionary or canonical IR and a case-insensitive target string. Return the representation-specific object listed below. Targets include IR, QUBO, HUBO, ISING, LP, MPS, QUBIT_HAMILTONIAN, and OMMX; support depends on the source type. Whitespace is not stripped.

A non-string target raises TypeError; unsupported routes or options raise ValueError, or the relevant exporter/compiler's typed error. Conversions do not solve or authenticate. Preserve conversion records for decoding, and distinguish raw minimization QUBO/HUBO exports from source-coordinate Ising dictionaries. The optional gate-based optimization and OMMX targets require their integrations.

Conversion routes

Polynomial dictionaries use the same conversion routes as their normalized native problem objects. MILPProblem file parsing remains limited to its documented model-domain scope; unsupported semantics raise. HUBO-to-Hamiltonian conversion uses the exact substitution \(x=(1-Z)/2\) and retains higher-locality terms without auxiliary qubits. Its expansion-work estimate, the sum of 2**len(term) over stored polynomial terms, cannot exceed 100,000; an oversized expansion raises ModelCompilationError and requires explicit quadratization. Arbitrary real Pauli Hamiltonians can convert to canonical IR; reverse Ising/QUBO conversion requires exactly identity/Z/ZZ terms.

Typed conversions preserve the source MIN or MAX objective. Conversion objects expose original_sense, with source_objective() or original_objective() reporting source coordinates; the dict returned by an ISING conversion instead carries source coefficients and a sense field. QUBO/Ising to qubit-Hamiltonian conversion uses the exact \(s=2x-1\), \(z=-s\) map. Reverse conversion rejects X/Y terms, terms above locality two, and every other structure that is not exactly identity/Z/ZZ. HUBO to QUBO additionally exposes complete_sample(), decode(), and verify_auxiliaries(). The conversion chapters explain these objects beside their mathematical substitutions.

Unsupported options raise rather than being ignored:

ValueError: IR conversion does not accept options: unknown_option
ValueError: QUBOProblem to ISING does not accept options: matrix_format
ValueError: HUBOProblem to QUBO contains unsupported options: sense
ValueError: IsingProblem to QUBO contains unsupported options: strength

Function: feasibility

feasibility(model: 'Model', values: 'dict[str, float]', *, tolerance: 'float' = 1e-06) -> 'dict'

Require Model and an actual dict keyed by source variable names; other container/input types raise TypeError. Every source variable must be present, and unknown keys raise ValueError. Deterministic auxiliary column names from that model's linear reformulation are accepted. tolerance follows Model.constraint_violations() and defaults to 1e-6.

Return {"feasible": bool, "objective": float, "violations": dict[str, float], "tolerance": tolerance}. Hard-constraint and domain violations follow the modeller verification contract. The source objective is always evaluated; invalid or unrepresentable objective arithmetic raises instead of returning an incomplete report. No solve or authentication occurs.

For a complete evaluable assignment, every evaluated hard constraint appears in violations, including zero residuals; domain keys appear for violated domains. Model.constraint_violations() can also diagnose incomplete or malformed assignments without evaluating constraints, whereas feasibility() requires complete source coordinates and an evaluable objective. Unknown source keys fail before evaluation:

ValueError: values are missing source variables: 'x'
ValueError: values contain unknown source variables: 'unknown_name'

Function: submit

submit(problem: 'Any', *, client: 'Client', **options: 'Any') -> 'dict[str, Any]'

Require client=Client(...), normalize a supported problem, and create platform work in one submission attempt. A missing/wrong client raises TypeError. LP/MILP accepts a Model, supported LP/MPS file path, or MILPProblem; local matrix dictionaries are not accepted by the platform. QUBO, HUBO, and Ising use their normalized native representations. QP and generic Hamiltonian submission raise CapabilityError; gate-based optimization uses the blocking algorithm route.

Options follow the platform option mapping and the corresponding QUBO, HUBO, or MILP submission contract. Return a JSON-safe dict containing job_id: str, normalized status: str, message: str, problem_id: str | None, detected_class: str, and mode="platform". Linear submissions also contain storage_id: str. Ising is explicitly converted to QUBO for submission; retain the original problem for result decoding.

This call can consume credits. It does not automatically retry an ambiguous failure; preserve identifiers and reconcile existing jobs before a manual retry. Validation, transport, and platform errors propagate. See the nonblocking procedure.

Function: status

status(client: 'Client', job_id: 'str') -> 'dict[str, Any]'

Require a Client and nonempty job_id: str accepted by Client.get_job(). Return dict with job_id: str, status as one of pending, running, completed, failed, cancelled, or unknown, raw_status: str, and error: str | None. This is a single read; it neither waits for completion nor resubmits. Transport/API errors propagate; a wrong client type raises TypeError.

Function: result

result(client: 'Client', job_id: 'str', *, problem: 'Any' = None) -> 'Any'

Fetch one job using Client. Any normalized lifecycle state other than completed raises RuntimeError, including pending, failed, and cancelled jobs. Without problem, return the extracted platform payload (Any): inline or storage-backed data, with supported result wrappers removed. That raw value is not guaranteed to be an SDK SolveResult.

With problem, normalize the same source representation used for submission and return its typed QUBO, HUBO, Ising, or linear result, restoring source coordinates and feasibility where the supplied representation retains them. Preserve the submitted model or compiled snapshot and its decoding information; passing an edited model can change result interpretation. Unsupported QP restoration raises CapabilityError. Wrong client types raise TypeError; parsing, transport, and platform errors propagate. This call retrieves existing work and does not submit a job.

Function: cancel

cancel(client: 'Client', job_id: 'str') -> 'dict[str, Any]'

Require Client and the nonempty job identifier accepted by Client.cancel_job(). Return that method's platform acknowledgement as dict[str, Any]. Cancellation acceptance does not prove terminal cancellation; call status() to observe the lifecycle state. Wrong client types raise TypeError; identifier, transport, and platform errors propagate. It does not submit replacement work.

Function: schemas

schemas() -> 'dict[str, Any]'

Return a fresh dict[str, dict] of JSON schemas for request envelopes, problem/configuration models, results, and platform records. Result schemas use anyOf and $defs where needed; request envelopes reject unknown outer fields. Callbacks and circuits are constructed through the Python API. Schema generation requires no credentials. See cross-process request handling for validation and execution.

Schema inventory

• requests: inspect_request, solve_request, submit_request, job_request, feasibility_request;
• outputs: solve_result, solve_info, qubo_result, hubo_result, ising_result, qp_result, milp_result, quantum_result, quantum_solve_info, quantum_sample, quantum_logical_circuit, quantum_diagnostics, job, job_submission, credit_usage, credit_usage_by_resource, credit_usage_job, credit_resource_usage, credit_quota;
• inputs/configuration: qubo_problem, hubo_problem, ising_problem, milp_problem, milp_solver_config, milp_warm_start, quantum_run, quantum_cvar, quantum_warm_start, quantum_xy_mixer.

submit_request contains problem_ir. solve_request does not contain algorithm or execution. Gate-based optimization configuration schemas validate QuantumRun, CVaR, WarmStart, and XYMixer; they do not serialize algorithm instances, custom callbacks, or circuits. The solve_result schema includes QuantumResult alongside the other result models; solve_info and quantum_solve_info describe their respective information models. Credentials and authenticated client/session state are excluded.

Class: IsingProblem

Import from qpiai_opt.opt_solvers.ising.

IsingProblem(*, problem_type: Literal['ISING'] = 'ISING', num_variables: typing.Annotated[int, Strict(strict=True), Ge(ge=0)], sense: Literal['MIN', 'MAX'] = 'MIN', offset: float = 0.0, variable_names: tuple[str, ...] = (), linear: dict[int, float], quadratic: dict[tuple[int, int], float]) -> None

Validated spin objective with coefficients in source coordinates. num_variables is a strict nonnegative integer; linear and quadratic are actual dictionaries with nonnegative non-Boolean integral indices below that count and finite non-Boolean real coefficients. Mirrored couplings aggregate, diagonal couplings contribute to offset, and zero coefficients disappear. Offset is finite and non-Boolean. Names are absent as () or contain one unique nonempty single-line string per spin. Sense and marker normalize case without stripping; unknown fields and malformed values raise pydantic.ValidationError. Construction copies coefficient dictionaries. from_model() retains an independent source/decoding snapshot.

Fields: problem_type, num_variables, sense, offset, variable_names, linear, quadratic.

Methods

IsingProblem.from_model(model, **compile_options) -> IsingProblem
energy(sample) -> float
decode(sample) -> dict[str, int | float]
source_objective(sample) -> float

from_model requires a Model, compiles it to the Ising representation, and stores an independent source/decoding snapshot. Native spin models accept no encoding options; other supported source models accept the options of Model.to_ising_dict. A failed compilation leaves the model's previous compilation state intact.

The three sample methods accept a complete spin sequence of length num_variables, a dictionary covering every integer index, or a dictionary covering every declared name. Mixed partial coverage is insufficient; if both complete views are present they must agree. Extra dictionary keys are ignored. Spins must be finite real -1/+1 values excluding Booleans. Invalid samples raise ValueError, and a noniterable sample raises TypeError. energy evaluates the stored source polynomial including its offset, without negating MAX coefficients; evaluation overflow raises ValueError. decode returns source coordinates when a model snapshot exists, otherwise declared names or generated s[index] names. source_objective evaluates the original model after decoding, or returns energy(sample) for direct construction. See sample contracts.