Platform client

qpiai_opt.opt_solvers.Client is the authenticated interface to QpiAI Opt Platform records and job execution. Use it for discovery, scheduling, monitoring, storage, or administrative problem and job operations.

Direct solver constructors accept either their normal api_key arguments or an initialized Client instance. Arbitrary client-like objects are not part of the public contract.

Construction

Register for a free Opt API key at QpiAI Opt, then supply it to Client from your application's secret store.

import os

from qpiai_opt.opt_solvers import Client

client = Client(
    api_key=os.environ["QPIAI_OPT_API_KEY"],
    experiment_name="Default Experiment",
    base_url="https://opt-server.qpiai.tech/api",
    timeout=60,
)

When a caller supplies a requests.Session, the caller owns its lifecycle. The current Client has no context-manager or close() method and does not close a supplied session. A client-created session is retained for the Client object's lifetime.

Construction validates local configuration without contacting the platform. API keys are stripped and must be nonempty; this check does not prove that a key is accepted. Entity IDs used in URL paths are stripped strings containing only ASCII letters, digits, ., _, -, or ~, and cannot be . or ... Names, roles, email selectors, and search values use the nonempty-string rule rather than this path-ID grammar. The server enforces role, membership, and account permissions.

Authentication and account operations

verification = client.verify_api_key()
user = client.me()
token_record = client.get_api_key()

Token-returning dictionaries can contain secret material. Do not log, commit, or attach them to exception telemetry.

Methods returning JSON records validate the response's required object or array shape. Object endpoints reject arrays and scalars, list endpoints reject objects, and invalid JSON raises APIError with the HTTP status when available. Nested required objects, such as an uploaded storage record, also fail closed when missing.

Organizations and collaboration

The secret-token middleware authorizes normal collaboration routes. Root-only global listing and organization creation are not exposed.

Organization and invitations

Identifiers, email, and role must be nonempty strings. Valid roles and authorization remain server policy.

Bulk invitations require an actual nonempty list of dictionaries, each containing exactly email and role. Unknown fields are rejected. All entries are validated before the invitation request. A successful response is the server's acknowledgement dictionary; the client does not infer a per-member outcome beyond that payload.

Workspaces

Bulk workspace membership accepts an actual nonempty list[str] of nonempty stripped email selectors. Single-member workspace and project calls require exactly one of user_id or email; supplying both, neither, or an empty supplied value fails validation.

Projects and experiments

Pagination values are strict positive integers. Optional search strings must be nonempty when provided. Entity identifiers are exposed as id.

Create/update description accepts any string, including the default "". Updates to workspaces, projects, and experiments send both name and description; omitting description therefore requests the empty string rather than retaining the previous description. These updates fetch the current typed record first, merge the returned update payload, and return the validated record. The merge does not make the operation atomic against concurrent server changes.

Collection records use None for optional data that a list operation does not supply. In particular, membership summaries can omit status and organization_id, and experiments returned by list_my_experiments() can omit workspace_id. Supplied text remains validated as nonempty.

Experiment selection

Every submitted job requires an experiment ID. Selection order is:

1. experiment_id passed to the operation;
2. experiment_name passed to the operation;
3. client-wide experiment_id;
4. client-wide experiment_name;
5. exact Default Experiment.

experiment_id = client.resolve_experiment("Benchmarks")

resolve_experiment() requests an exact name within the authenticated organization. Successful resolutions are cached by name on the client. A missing experiment_id in the lookup response raises APIError.

Problems

problem = client.create_problem(
    {
        "name": "External problem",
        "method": "QUBO",
        "qubo_dict": {"0,0": -1.0},
        "num_variables": 1,
    }
)

same_problem = client.get_problem(problem.id)
page = client.list_problems(page=1, page_size=20)
updated = client.update_problem(problem.id, {"name": "Renamed problem"})
confirmation = client.delete_problem(problem.id)

create_problem() requires a dictionary with non-empty name and method. Method-specific payload fields are passed to the platform. High-level solvers should be preferred for QUBO/HUBO/MILP creation because they validate and serialize those fields.

Returns:

• create_problem(), get_problem(), and update_problem() return Problem;
• list_problems() returns a pagination response containing .problems and .pagination;
• delete_problem() returns the platform confirmation dictionary.

Page and page size are strict positive integers.

Advanced solver discovery and resource pinning

resources = client.list_solvers(method="QUBO", active_only=True)
resource = client.get_solver(resources[0].id)

list_solvers() returns list[ComputeResource]. method filters by problem class, such as "QUBO", "HUBO", or "MILP".

active_only=True retains resources whose status is "active" ignoring case. Resource availability and allocation can change between discovery and submission; a discovered record is not a reservation.

Most applications should skip this section and omit compute_resource_id. The platform selects an eligible resource from the submitted problem method. A compute-resource ID is an opaque platform UUID for a particular solver deployment; it is useful only when an advanced workflow must pin that specific deployment.

Job submission and scheduling

High-level solvers package the class-specific payload. Direct submission is available when a problem already exists:

submission = client.submit_job(
    problem.id,
    method="QUBO",
    experiment_name="Benchmarks",
)

pinned_submission = client.submit_job(
    problem.id,
    method="QUBO",
    experiment_name="Benchmarks",
    compute_resource_id=resource.id,
)

scheduled = client.schedule_job(
    problem.id,
    "2030-01-01T09:30:00+05:30",
    method="QUBO",
)

scheduled_at must be an ISO 8601 timestamp with an explicit timezone. Direct submit_job(..., scheduled_at=...) sets the platform scheduling fields; schedule_job() uses the dedicated scheduling endpoint.

Both methods return an acknowledgement with .message, optional .expected_run_at, and the new .job:

• .message: acknowledgement text;
• .expected_run_at: optional datetime parsed from the platform response;
• .job: the created Job.

Submission is nonblocking; the response contains the job state supplied by the platform.

pinned_submission places the discovered resource ID in the job request. Use an ID returned for the same method; omit it to let the platform choose.

Reading and filtering jobs

job = client.get_job(submission.job.id)

user_jobs = client.list_jobs(
    page=1,
    page_size=20,
    status="running",
    compute_resource_id=resource.id,
)
problem_jobs = client.list_problem_jobs(problem.id, page=1, page_size=20)
experiment_jobs = client.list_experiment_jobs(
    experiment_name="Benchmarks",
    page=1,
    page_size=20,
)

get_job() returns Job. List methods return a pagination response containing .jobs, .pagination, and optional aggregate execution/credit totals. status accepts JobStatus.PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED, or the corresponding lowercase strings. Surrounding whitespace is ignored; uppercase strings, "unknown", and other values are rejected. period and compute_resource_id must be nonempty strings when supplied.

Job-list period filters use job creation time: daily starts at the current UTC day's boundary, weekly starts seven days before the request, and monthly starts one calendar month before the request. Omit period for all dates. The SDK strips whitespace but does not validate these choices; other strings apply no time filter. compute_resource_id filters list_jobs() and list_experiment_jobs(). The problem-job endpoint does not apply this filter, although list_problem_jobs() accepts the argument.

Credit usage and allocations

Platform usage charges are based on compute time (compute_time_s), not solver time (solver_time_s). Credit usage reports contain the service-recorded charges.

Credit information is read-only account information. A completed or retrieved Job exposes credits_used and credits_reserved when the platform supplies them. Period reports and current allocations are available through the same authenticated client:

job = client.get_job(submission.job.id)
job_credits = job.credits_used

usage = client.get_user_credit_usage(period="monthly")
usage_summary = (usage.used_credits, len(usage.jobs))

quota_balances = {
    quota.compute_resource_id: quota.remaining_credits
    for quota in client.get_user_quotas()
}

The methods are:

period accepts daily, weekly, monthly, or yearly. Set by_resource=True to receive one CreditResourceUsage record per compute resource; the SDK checks that those records add up to the report total. CreditUsage.jobs contains typed job identifiers, statuses, resource names, execution times, and credits used when present.

For a quota, capacity_credits is the platform's enforceable allocation (total_credits for an organization quota, otherwise allocated_credits) and remaining_credits is that capacity minus used_credits. remaining_credits reports the balance before reservations. The platform also accounts for reserved_credits when deciding whether a new job can run. A quota with inconsistent values is rejected rather than presented as a misleading balance. Access to another user, workspace, or organization is still controlled by the platform; an authorization error is returned as AuthenticationError or APIError.

Cancel a job with:

confirmation = client.cancel_job(job.id)

This returns the platform dictionary. Cancellation is a request; read the job again or wait for a terminal state to confirm the final result.

Server-Sent Events and waiting

for event in client.stream_job(
    job.id,
    connect_timeout=10,
    read_timeout=30,
):
    event_record = (event.event, event.data)

stream_job() yields SSEEvent. Multi-line data: fields are joined with newlines. JSON data is decoded; other content remains a string. Its response is closed when the generator is exhausted, explicitly closed, or raises. Close the generator when stopping iteration early. Each event_record contains the event name and its decoded JSON value or text; JSON scalars and null are valid payloads.

The stream is decoded as UTF-8. A leading UTF-8 byte-order mark is ignored, comment lines beginning with : and unknown fields are ignored, and an omitted or empty event field becomes "message". An event is dispatched only at a blank-line boundary and only when at least one data field was received. Invalid UTF-8 raises requests.exceptions.ContentDecodingError.

The common waiter uses SSE first:

completed_job = client.wait_for_job(
    job.id,
    timeout=3600,
    poll_interval=5,
    use_sse=True,
)

Behavior:

• reads the current job before opening the stream;
• makes at most three SSE connection attempts, with bounded exponential backoff after transient failures;
• falls back to polling;
• never schedules a sleep beyond the total timeout;
• returns a completed Job;
• raises JobFailedError or JobCancelledError for those terminal states;
• raises TimeoutError when the monitoring budget is exhausted;
• raises APIError for an unknown platform state.

Set use_sse=False for polling only.

Transient HTTP statuses are 408, 425, 429, 500, 502, 503, and 504; other API errors propagate. Request exceptions can also trigger retry or polling fallback. Monitoring retries do not submit another job. See the timeout contract for in-flight request behaviour at the budget boundary.

Storage and result extraction

from pathlib import Path

storage = client.upload_file(
    Path("model.lp"),
    workspace_id="workspace-id",
    project_id="project-id",
    timeout=120,
)

path must identify an existing regular file; a missing file raises FileNotFoundError before upload. If user_id or organization_id is omitted, upload_file() obtains them from me(). It uploads the bytes with the basename and the supplied ownership fields. The file handle is closed after the request.

The return is the platform's nested storage dictionary. The client validates that this is a dictionary, but does not validate individual storage fields. The platform's storage identifier is conventionally ID; validate that value before passing it to another operation. High-level MILP submission performs its own storage-ID validation.

Download a JSON object by storage ID or S3 path:

by_id = client.download_result_by_id(storage["ID"], timeout=60)
by_path = client.download_result("s3://bucket/key", timeout=60)

The timeout applies separately to the platform request that obtains the presigned URL and the subsequent object-storage GET. Non-JSON object content raises APIError.

extract_result(job) handles all supported result locations:

1. inline job.server_response;
2. job.server_response_id;
3. an inline s3://... string;
4. JSON encoded as a string.

If the decoded value has a dictionary/list under result or results, that inner value is returned. Otherwise the decoded value is returned unchanged. Class-specific solvers require a completed job to contain a valid result object. A completed lifecycle state with no retrievable result raises instead of producing a partial solve result.

Delete storage explicitly:

confirmation = client.delete_storage(storage["ID"])

Timeouts

There are two distinct timeout concepts.

Individual request timeouts configure connection and read waits:

• Client(timeout=...) sets the default;
• method-level timeout=... overrides it where exposed;
• solver request_timeout is passed through create, submit, upload, and result requests.

A scalar timeout applies to both connection establishment and periods waiting for response data. It is not a total download deadline; a response that continues sending data can take longer. This follows the Requests timeout contract.

Job wait timeouts set a monitoring budget:

• Client.wait_for_job(timeout=...);
• QUBOSolver.solve(timeout=...);
• HUBOSolver.solve(timeout=...);
• MILPSolver.solve(timeout=...).

The waiter checks its monotonic budget between operations and bounds requested sleeps and request timeouts by the remaining time. An in-flight request can still finish after that budget, so the value is not a strict wall-clock cancellation deadline. It does not cancel the platform job.

A request timeout raises requests.Timeout; a streamed read can instead surface a Requests connection error. Budget exhaustion in the job waiter raises the built-in TimeoutError.

Failure and retry policy

Do not automatically retry a failed submission without determining whether the platform accepted it. A transport failure or HTTP 408, 425, 429, or server error can occur after record creation.

High-level solver behavior:

• definitive non-transient 4xx rejection triggers best-effort cleanup of SDK-created problem records;
• MILP also attempts cleanup of SDK-owned uploaded storage after definitive rejection;
• ambiguous outcomes retain records and add reconciliation instructions to the exception;
• the SDK never resubmits a paid optimization job inside its wait/reconnect logic.

Use the problem ID from the exception note or submission response:

jobs = client.list_problem_jobs(problem_id, page=1, page_size=20)

Solver-specific response fields are documented in the QUBO, HUBO, and MILP guides. Common results and failures are in Local solving and Automation.

Response models

Typed platform records are Pydantic models. Timestamps are timezone-aware when the platform includes an offset. The fields below are the supported contract. Serialize a record with model_dump(mode="json"):

job = client.get_job("job-123")
payload = job.model_dump(mode="json")

Jobs and problems

job.normalized_status maps the raw status to JobStatus.PENDING, RUNNING, COMPLETED, FAILED, CANCELLED, or UNKNOWN. It does not modify the raw field.

Compute resources and credit records

ComputeResource accepts the public field name id and the platform payload alias ID; serialization uses id.

CreditQuota fields are:

All credit counts reject Booleans, negative values, and non-integers. used_credits cannot exceed quota capacity.

Collaboration records

Organization.min_booking_minutes cannot exceed max_booking_minutes. Text identifiers are stripped and must be non-empty when present.

Server-sent events

SSEEvent contains event: str and decoded data: Any. The event name is non-empty. JSON data becomes its Python value; other data remains text.

Error reference

Confirmation endpoints return the platform acknowledgement dictionary. Its keys depend on the endpoint; treat a successful return as confirmation and use the typed retrieval operation when current entity state is required.

Common failures are:

For APIError, status_code is available when the failure came from an HTTP response. Validation errors occur before a network side effect whenever the SDK has all required information locally.