solve_optimization
Solve combinatorial optimization problems—selecting items within a budget, assigning shifts, or ordering visits—by returning ranked feasible solutions that meet hard and soft constraints.
Instructions
Solve a structured binary or bounded-integer combinatorial optimization problem.
Use this when the user asks which items to take within a budget, weight or
capacity, how to assign people or jobs to seats, shifts or machines, in
which order to visit a handful of places, or how to split things into
groups or pick a subset that meets several requirements at once — anything
expressible as yes/no or bounded-count decisions with a linear or quadratic
score and linear rules, even when the user never says "optimization".
Call this only after translating the user's request into explicit binary or
bounded-integer variables, an objective (linear/quadratic, minimize or
maximize), and hard or soft linear constraints. Do not pass natural-language
requirements.
An integer variable is declared with "type": "integer" plus integer
lower_bound and upper_bound (both required), and the problem must then carry
"version": "1.1" at its top level. A backend that compiles to bqm encodes
each integer in binary, so the compiled size grows with the range of the
bounds; a backend that compiles to cqm takes integers natively. Integer
values come back as ints inside their declared bounds.
Inequality constraints (<=, >=) require integer coefficients and right-hand
sides. Soft constraint weights are in objective units.
Leave solver.penalty_multiplier at its default unless a previous result was
infeasible on a remote backend; hard constraint penalties are managed by the
server. Call validate_optimization_problem first when planning to use a
remote backend or when the problem is large; on a local backend an invalid
document comes back as status invalid_problem with the same errors and
recommended_action, so solving directly spends nothing. Use
get_optimization_capabilities when you need the backend list or the full
schema. Use recommend_backend to compare backends; the choice remains yours.
Returns ranked feasible solutions with per-constraint evaluations, or a
structured error with a recommended_action. When the status is infeasible,
read infeasibility for the candidate that came closest to feasibility and
the share of candidates each hard constraint rejected, so the answer can
name the binding requirement instead of only reporting failure. Whatever
the status, the result's warnings are the same advisory warnings
validate_optimization_problem gives for this backend (an ignored seed or
parameter, a wide integer range, a negligible soft weight, ...) followed
by any raised during the run; read them before trusting a weaker answer
than expected. A field the schema does not declare is a tool error naming
its path, never ignored. If the user did not name a backend, say in the
answer which backend ran and why.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| problem | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| errors | No | Structured failures. Empty on success. | |
| status | Yes | The single verdict for the request. success: at least one feasible solution was found and ranked. infeasible: the pipeline ran but no candidate satisfied every hard constraint under re-validation — check infeasibility_proven before concluding none exists. invalid_problem: the problem failed validation and no backend was invoked. solver_error: the backend failed while executing, or a remote vendor reported an error. backend_unavailable: the requested backend is not registered, not installed, disabled by policy or missing credentials — there is never a silent fallback. resource_limit_exceeded: a request parameter or the compiled size exceeded a server-side ceiling; values are refused, never clamped. configuration_error: the server's own configuration is wrong, not the problem. | |
| backend | Yes | Registry name of the backend that ran, or null when the request failed before a backend was chosen. | |
| message | No | Human-readable one-line summary of the result. On success: which backend produced it, whether optimality is proven, the rank-1 objective with its direction (and its soft violation when non-zero), how many distinct candidates the attempt saw, how many were feasible and how many are returned, and the attempt number when a retry produced it. On infeasible: why nothing feasible was found. On a failure: the first error's message. Deterministic — it never contains timings. Null when there is nothing to add. | |
| attempts | Yes | One entry per compile/solve/validate attempt, in order. | |
| metadata | No | Sanitized execution facts about the last completed attempt, local backends included. Null when the request failed before any solve finished; the service never invents it. | |
| warnings | No | Non-blocking advice, same structure as an error: the warnings validate gives for this backend, then any raised during the run. Present whatever the status, except invalid_problem. | |
| solutions | Yes | Ranked feasible solutions, best first, at most solver.top_k. Empty unless status is success. | |
| elapsed_ms | No | Wall-clock milliseconds measured by the service from entering solve to returning, problem validation and any wait for a concurrency slot included. Unrelated to metadata.timing_us, which is what a vendor reports about its own side, and different on every run. | |
| infeasibility | No | Why the last attempt found nothing feasible. Present only when status is infeasible and that attempt had candidates to diagnose; null on every other status, and on an attempt that received no samples at all. | |
| optimality_proven | No | True only on success when an exhaustive backend enumerated every assignment: rank 1 is then the global optimum of ranking_score, not merely the best candidate seen. Always false on a heuristic or remote backend. | |
| objective_direction | Yes | Echoed from the problem, so a consumer can interpret objective_value without re-reading the input. Null when the request failed before the problem was read. | |
| annealbridge_version | No | The installed package version that produced this result; "unknown" outside an installed distribution. | |
| infeasibility_proven | No | True only when an exhaustive backend actually enumerated every assignment and found none feasible. On a heuristic or remote backend an infeasible result only means 'not found under this configuration'. |