Automation and agent workflows

Use the SDK's Python operations to prepare a model, select an execution route, verify a result, and manage platform jobs. This guide covers workflow decisions; the linked references define signatures, options, fields, and mathematical contracts.

Before executing a task

1. Define the objective, sense, variable domains, constraints, and required output. Choose encoding resolution, penalty controls, feasibility tolerance, solution guarantee, and execution budget where needed.
2. Install with python -m pip install qpiai-opt and select the relevant guide below. Check the installed version with importlib.metadata.version("qpiai-opt").
3. Restore canonical IR with from_ir(problem_ir) when necessary, then inspect the problem before execution. Keep the source model and compiled representation for verification and result retrieval.
4. Select local or platform execution. Platform jobs and paid fallback require the caller's authorization and resource budget.

Obtain a free Opt API key at QpiAI Opt for calls using Client, or a free QCloud API key at QpiAI QCloud for gate-based optimization. Load credentials from the application's secret store. Modelling, inspection, conversion, and result evaluation require no credentials; local solving verifies the appropriate key online before computation.

Choose the right guide

Inspection operations

Call inspect(problem) to validate the representation and obtain problem_class, representation, metrics, and valid=True; invalid inputs raise. Metrics vary by problem class. Inspection does not prove feasibility or guarantee that a problem fits local limits.

For gate-based optimization, compile an algebraic model first with model.compile(target="QUBO", **compile_options) or model.compile(target="ISING", **compile_options), choosing its encoding options explicitly. Construct the algorithm and call inspect(problem, algorithm=algorithm) to check compatibility and circuit metrics. Hamiltonian inputs and higher-order models follow the gate-based optimization input and conversion rules.

Use classify(problem) for identification, provider_capabilities() for execution capabilities, and LOCAL_LIMITS for local capacity. These operations do not solve or submit work. See the inspection API and local limits.

Deterministic decision procedure

Import operations from qpiai_opt.opt_solvers, modelling and IR functions from qpiai_opt.opt_modeller, and gate-based optimization algorithms and configuration from qpiai_opt.quantum.

For gate-based optimization, authenticate with QpiAIQuantumAuth.login(api_key=QCLOUD_API_KEY) and construct execution = QuantumRun(), setting execution options as needed. For calls without algorithm, construct client = Client(api_key=OPT_API_KEY). Assign the result of the selected call below to solve_result.

Gate-based optimization rejects mode="auto", allow_platform=True, and the Opt Client. Configure QCloud device selection through QuantumRun; use the gate-based optimization guide for supported settings.

QP is local-only. Automatic fallback occurs only after LocalLimitExceeded. Authentication, validation, transport, and solver failures do not trigger fallback. Omit options whose value is None; options for the wrong class raise. Use the routing modes and option reference before selecting fallback or class-specific controls.

Blocking solve

Read solve_result.info() before accepting an optimization candidate. Check has_usable_solution, solution_feasible, and optimality_proven against the application's required guarantee; a heuristic candidate is not an optimality proof.

When a usable candidate and source Model are available, call feasibility(model, solve_result.variable_assignment) for QUBO/HUBO/Ising, or feasibility(model, solve_result.solution) for LP/MILP/QP. When no usable candidate exists, report the termination and guarantee and skip assignment evaluation. Generic Hamiltonian results provide eigenvalue without a variable assignment.

Serialize results with model_dump(mode="json"), retaining solve_info. Restore them with the corresponding result class's model_validate() method. Validate stored solve_info with QuantumSolveInfo for QuantumResult, or SolveInfo for other result types. Full fields, guarantees, timings, and serialization are defined in the result contract and gate-based optimization result reference.

Nonblocking platform lifecycle

Use the optimization job lifecycle for platform calls without algorithm. Gate-based optimization algorithms use the blocking workflow above.

Retain the original problem and decoding metadata until retrieval. Omitting problem from result() returns the raw extracted payload. After an ambiguous submission failure, reconcile existing jobs before retrying. See the submission, status, retrieval, and cancellation contracts, including exact return fields and failure conditions.

Conversion and verification

Use convert(problem, target, **options) for an explicit representation change. The conversion reference lists every supported source/target pair, return type, option, and mathematical restriction. Retain conversion records and source metadata for decoding and source-objective interpretation.

feasibility(model, values, tolerance=1e-6) requires a complete source-name assignment and returns feasible, objective, violations, and tolerance. It also accepts the model's deterministic auxiliary columns. Use its input and return contract for domain diagnostics, tolerance rules, and rejected assignments.

Schemas and cross-process requests

Use schemas() to obtain JSON schemas for request envelopes, problems, configurations, results, and platform records:

from qpiai_opt.opt_solvers import schemas

schema_map = schemas()
request_schema = schema_map["solve_request"]
result_schema = schema_map["solve_result"]

The schema inventory defines the available keys. Request envelopes reject unknown outer fields. Validate the selected request schema before dispatch. Use from_ir() to restore problem_ir for inspection, solve, or submission requests, or model_ir for feasibility requests. Pass feasibility values and its optional tolerance; job requests carry job_id. Supply an Opt Client separately for solve() calls without algorithm and for job operations. Inspection and feasibility need no client. Credentials and client/session state stay outside IR, request data, results, and logs.

solve_request does not include algorithm or execution. A gate-based optimization integration selects and constructs its algorithm through the Python API, validates settings with QuantumRun, and supplies QCloud authentication separately; algorithm instances, callbacks, and circuits are not serialized by these request schemas.

Failure handling

Use the exception reference, structured local failures, and platform retry policy for specific recovery rules.