# QubitFlow — Full Technical Architecture, API Reference & Benchmark Specification

Website: https://getqubitflow.com
Challenge Funnel: https://getqubitflow.com/challenge
OpenAPI Spec: https://getqubitflow.com/openapi.json
Interactive Docs: https://getqubitflow.com/docs
Legal & SLA: https://getqubitflow.com/legal

## 1. Executive Summary: Why QubitFlow Exists
Legacy route planners (such as Samsara dispatch heuristics, Routific, OptimoRoute, or sequential first-fit spreadsheet macros) assign stops to vehicles one truck at a time. When delivery time windows tighten or clinical STAT drops are added, sequential assignment creates 12% to 18% cross-route mileage overlap or forces late deliveries.

QubitFlow solves the entire fleet or clinical roster simultaneously:
1. **Spectral QUBO/Ising Compilation:** Business JSON or CSV/XLSX manifests are compiled into a Binary Quadratic Model (BQM) with logarithmic binary slack variables ($O(\log_2 R)$) and Gershgorin spectral penalty scaling so hard constraints mathematically dominate the objective energy landscape.
2. **Quantum-Inspired Portfolio Race:** Each solve races Replica-Exchange Parallel Tempering and Kerr-Nonlinear Simulated Bifurcation (Toshiba dSB/bSB) in parallel threads, followed by deterministic 1-opt/2-opt local search polish.
3. **100% Classical HiGHS MILP Verification Gate:** Every candidate solution is audited against all original hard business rules (vehicle capacity, stop time-step windows, ICU nurse skill requirements, clopening bans, and portfolio lot budgets). If any heuristic bitstring violates a single hard constraint, QubitFlow repairs it or falls back to exact Classical HiGHS Mixed-Integer Linear Programming (`classical_highs`) before returning the response. Every response includes a verification certificate (`is_feasible: true`, `num_hard_violations: 0`).

## 2. Head-to-Head Comparison: QubitFlow vs. Legacy Route Planners & Raw Solvers
| Capability | Legacy Dispatch SaaS (Routific / OptimoRoute / Samsara) | Raw Solver Libraries (OR-Tools / Gurobi / D-Wave Ocean) | QubitFlow Hybrid Optimization API |
| :--- | :--- | :--- | :--- |
| Multi-Vehicle Optimization | Sequential greedy heuristic (12-18% overlap under tight windows) | Requires PhD-level MILP/QUBO modeling | Simultaneous BQM + HiGHS verification via standard JSON/CSV |
| Hard Constraint Guarantee | Often drops or delays tight time windows | Manual penalty tuning required for QUBO | 100% deterministic verification (`num_hard_violations: 0`) |
| Integration Time | Locked into proprietary UI or months of custom ERP work | 3-6 months of operations research engineering | Under 30 minutes via REST (`POST /v1/solve/routing`) or CSV upload |
| Commercial SLA | Annual seat lock-in regardless of savings | Expensive per-core licensing or raw QPU shot fees | 8% Route Compression Guarantee in 60 seconds or pay $0 |

## 3. Core REST API Endpoints
- `POST /v1/solve/routing`: Capacitated Vehicle Routing with Time Windows (CVRPTW). Accepts `depot`, `stops` (with `demand`, `x`, `y`, `earliest_step`, `latest_step`), and `vehicles` (with `capacity`, `max_stops`, `fixed_cost`, `cost_per_distance`). Returns optimal per-vehicle stop sequences, utilization percentages, distance, cost, and verification certificate.
- `POST /v1/solve/scheduling`: Hospital & workforce shift scheduling. Accepts `num_days`, `employees` (with `hourly_rate`, `skills`, `min_shifts`, `max_shifts`, `unavailable_days`), `shift_types`, `demands`, and `forbid_night_to_morning`. Returns conflict-free clinician rosters with zero clopenings.
- `POST /v1/solve/portfolio`: Discrete multi-lot institutional portfolio allocation. Accepts `assets`, `covariance_matrix`, `risk_aversion`, `total_budget_lots`, and `sector_limits`.
- `POST /v1/solve/qubo`: Direct QUBO / Ising Hamiltonian ground-state solver with linear equality/inequality constraints (`==`, `<=`, `>=`).
- `POST /v1/pilot/run?domain=routing|scheduling|portfolio`: Smart CSV/TSV/XLSX Shadow Pilot engine. Auto-maps arbitrary spreadsheet column headers, runs a dual-solve benchmark comparing the customer's sequential baseline against QubitFlow's Hybrid BQM Engine, and generates a printable Executive Proof-of-Value Audit Report (`/v1/pilot/reports/{report_id}/html`).
- `GET /v1/solvers`: Returns live telemetry and hardware adapter readiness across all 8 solver backends.

## 4. Security, Multi-Tenancy & Commercial Terms
- **Cryptographic API Keys:** Tenant API keys are issued once in plaintext and stored strictly as `key_prefix` + `HMAC-SHA256` digests in SQLite WAL storage.
- **Idempotency & Rate Limiting:** All `/v1/solve/*` endpoints support `Idempotency-Key` headers for safe retry replay and per-tenant token-bucket rate limiting.
- **Zero-Risk 8% Route Compression Guarantee:** Detailed at https://getqubitflow.com/legal#sla and https://getqubitflow.com/challenge.