[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80067":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":19,"hasPages":19,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":22,"readmeContent":23,"aiSummary":24,"trendingCount":15,"starSnapshotCount":15,"syncStatus":25,"lastSyncTime":26,"discoverSource":27},80067,"quantum_boost","kyleparratt-98\u002Fquantum_boost","kyleparratt-98","Give Your AI Agents Access to Quantum Compute","",null,"Python",58,6,61,0,1,2.54,"MIT License",false,"main",[],"2026-06-12 02:03:57","# `quantum_boost` — Give Your AI Agents Access to Quantum Compute\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.9+-blue\" alt=\"Python 3.9+\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-green\" alt=\"MIT License\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FIBM%20Quantum-free%20QPUs-purple\" alt=\"IBM Quantum\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FAWS%20Braket-IonQ%20%7C%20Rigetti-orange\" alt=\"AWS Braket\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-native-black\" alt=\"MCP Native\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FQAOA-quantum-red\" alt=\"QAOA\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fopen%20source-%E2%9D%A4-pink\" alt=\"Open Source\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"public\u002Fassets\u002Fquantum_shot.png\" alt=\"quantum_boost — Give Your AI Agents Access to Quantum Compute\" width=\"600\" \u002F>\n\u003C\u002Fp>\n\n**QUBO → QAOA → Cloud QPUs.** A Python 3.9+ library that offloads combinatorial optimization to real quantum hardware — without writing a single line of quantum code. Includes a dynamic QUBO formulator, multi-source data aggregator, and MCP server for LLM agent auto-discovery.\n\n```python\nfrom quantum_boost import quantum_boost\nimport numpy as np\n\n@quantum_boost\ndef optimize_portfolio(qubo_matrix: np.ndarray) -> dict:\n    \"\"\"Classical fallback for small problems — called automatically.\"\"\"\n    from scipy.optimize import dual_annealing\n    # ...\n\nresult = optimize_portfolio(my_qubo)          # Transparent. No quantum code.\nprint(result.solution)   # {0: 1, 1: 0, 2: 1, ...}\nprint(result.energy)     # -12.34\nprint(result.backend_used)  # \"ionq\" | \"rigetti\" | \"ibm\" | \"classical\"\n```\n\n---\n\n## Why quantum_boost?\n\n| Feature | What It Means |\n|---------|---------------|\n| 🔬 **Zero Physics Required** | You bring a QUBO matrix. `quantum_boost` handles Hamiltonians, QAOA circuits, and cloud dispatch. |\n| 🤖 **AI-Native via MCP** | LLM agents (Claude, Cline, etc.) auto-discover `quantum_boost` as a tool. Just say *\"optimize my portfolio\"* and the agent formulates the QUBO, calls quantum hardware, and returns the answer. |\n| ☁️ **Three QPU Providers** | IonQ & Rigetti via AWS Braket, plus IBM Quantum on the free Open Plan. Real hardware, no simulators. |\n| 🛡️ **Budget Guard** | The only quantum library that protects your cloud bill with an interactive cost confirmation *before* submitting a job. |\n| 🧩 **Dynamic QUBO Formulation** | Build QUBOs programmatically with constraint gadgets (equality, inequality, cardinality, AND\u002FOR\u002FNOT logic). No manual matrix math. |\n| 🔍 **Multi-Source Aggregation** | Pull data from stock prices, graphs, CSV, JSON, arrays, or web search — then auto-formulate into a QUBO. |\n| 💰 **IBM Quantum: Free** | IBM's Open Plan gives you real 127+ qubit QPUs at $0.00. Tested live on `ibm_kingston` (156 qubits). |\n\n---\n\n## QPU Comparison\n\n| Provider | Access Via | Cost | Qubits | Status |\n|----------|-----------|------|--------|--------|\n| **IonQ** | AWS Braket | ~$0.33\u002Ftask | 11 | Requires AWS keys |\n| **Rigetti** | AWS Braket | ~$0.32\u002Ftask | 30+ | Requires AWS keys |\n| **IBM Quantum** | Direct API | **$0.00** (free tier) | 127–156 | Requires IBM key |\n\n---\n\n## Installation\n\n```bash\npip install quantum_boost\n```\n\nRequires Python ≥ 3.9 and PennyLane ≥ 0.38.\n\n### Optional: IBM Quantum (free QPUs)\n\n```bash\npip install quantum_boost[qiskit]\n```\n\nThen set your IBM Quantum API key (get one at [quantum.ibm.com](https:\u002F\u002Fquantum.ibm.com\u002F)):\n\n```bash\nexport IBM_QUANTUM_KEY=\"your-ibm-key-here\"\n```\n\n### Optional: AWS Braket (IonQ \u002F Rigetti)\n\n```bash\nexport AWS_ACCESS_KEY_ID=\"your-access-key\"\nexport AWS_SECRET_ACCESS_KEY=\"your-secret-key\"\nexport AWS_DEFAULT_REGION=\"us-east-1\"\n```\n\n---\n\n## Quickstart\n\n### 1. The Decorator\n\n```python\nimport numpy as np\nfrom quantum_boost import quantum_boost\n\n@quantum_boost\ndef solve(qubo_matrix: np.ndarray) -> dict:\n    \"\"\"Classical fallback — runs only for QUBOs with \u003C 20 variables.\"\"\"\n    return {\"energy\": 0.0, \"solution\": {}}\n\n# Small QUBO → classical path (free)\nsmall = np.eye(5)\nresult = solve(small)\nprint(result.backend_used)  # \"classical\"\n\n# Large QUBO → Cloud QPU (cost estimate shown first)\nlarge = np.random.randn(30, 30)\nresult = solve(large)\nprint(result.backend_used)  # \"ionq\"\nprint(result.wall_time_ms)  # 4523.1\n```\n\n### 2. Dynamic QUBO Formulation\n\nBuild QUBOs programmatically — no manual matrix construction:\n\n```python\nfrom quantum_boost import QUBOFormulator, formulate\n\n# Maximize returns, pick exactly 2 assets\nf = QUBOFormulator(3, \"Pick 2 of 3 assets\")\nf.add_objective_maximize({0: 0.10, 1: 0.07, 2: 0.12})  # expected returns\nf.add_cardinality_constraint([0, 1, 2], k=2)           # pick exactly 2\nqubo = f.build()\n\nprint(f.explain())\n# QUBO Formulation: Pick 2 of 3 assets\n# Variables: 3 binary (x_0 ... x_2)\n# Total terms accumulated: 12\n#   • OBJECTIVE (maximize): linear={0: 0.1, 1: 0.07, 2: 0.12}\n#   • CONSTRAINT (cardinality): exactly 2 of [0, 1, 2], penalty=5.00\n```\n\n**Supported constraints:**\n\n| Constraint | Example |\n|-----------|---------|\n| `add_objective_minimize` | Minimize cost |\n| `add_objective_maximize` | Maximize returns |\n| `add_equality_constraint` | x₀ + x₁ == 1 |\n| `add_inequality_constraint` | x₀ + x₁ + x₂ \u003C= 2 (auto slack variables) |\n| `add_cardinality_constraint` | Exactly k of N items |\n| `add_and_constraint` | x₂ = x₀ AND x₁ |\n| `add_or_constraint` | x₂ = x₀ OR x₁ |\n| `add_not_constraint` | x₁ = NOT x₀ |\n\n### 3. Data Aggregation\n\nPull data from multiple sources, then auto-formulate:\n\n```python\nfrom quantum_boost import aggregate_data, AggregationSource\n\n# From a graph (e.g., MaxCut)\ndata = aggregate_data(source=\"graph\", edges=[(0,1), (1,2), (2,3), (3,0)])\n# → {\"source\": \"graph\", \"n_variables\": 4, \"edges\": [...], \"ready\": True}\n\n# From stock prices\ndata = aggregate_data(source=\"stock_prices\", tickers=[\"AAPL\", \"GOOGL\", \"MSFT\"])\n\n# From web search (Tavily API)\ndata = aggregate_data(source=\"web_search\", query=\"top 5 AI stocks 2025\")\n\n# From CSV\ndata = aggregate_data(source=\"csv\", filepath=\"data\u002Fportfolio.csv\")\n\n# Then formulate directly\nfrom quantum_boost import formulate\nqubo = formulate(data)\n```\n\n**Aggregation sources:** `stock_prices`, `graph`, `csv`, `json`, `array`, `list`, `web_search`\n\n### 4. Standalone Functions\n\n```python\nfrom quantum_boost import cost_estimate, set_config, list_available_qpus\n\n# Check price before committing\nprice = cost_estimate(my_qubo, backend=\"ionq\")\nprint(f\"Estimated: ${price:.3f}\")\n\n# IBM Quantum is always free\nprice = cost_estimate(my_qubo, backend=\"ibm\")\nprint(f\"Estimated: ${price:.4f}\")  # $0.0000\n\n# Check which QPUs are available\nprint(list_available_qpus())\n# {\"ionq\": \"requires-keys\", \"rigetti\": \"requires-keys\", \"ibm\": \"available\"}\n\n# Configure library-wide defaults\nset_config(\n    quantum_threshold=15,\n    default_qpu=\"ibm\",\n    auto_approve=False,  # BudgetGuard ON by default\n)\n```\n\n---\n\n## MCP Server (LLM Agent Integration)\n\nStart the MCP server for any MCP-compatible agent:\n\n```bash\npython -m quantum_boost.mcp_server\n# or\nquantum-boost-mcp\n```\n\n**MCP Client Configuration** (Claude Desktop, Cline, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"quantum-boost\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"quantum_boost.mcp_server\"],\n      \"env\": {\n        \"IBM_QUANTUM_KEY\": \"your-ibm-key\",\n        \"QUANTUM_BOOST_DEFAULT_QPU\": \"ibm\"\n      }\n    }\n  }\n}\n```\n\n**MCP Tools Exposed (5 tools):**\n\n| Tool | Description |\n|------|-------------|\n| `solve_qubo` | Submit a QUBO matrix, get back optimal binary solution + energy. Small QUBOs solve classically at no cost. |\n| `estimate_qubo_cost` | Get a USD cost estimate without executing. |\n| `list_available_qpus` | List available QPUs (IonQ, Rigetti, IBM) and their status. |\n| `formulate_qubo` | Build a QUBO programmatically from objectives and constraints. |\n| `aggregate_data` | Pull data from stock prices, graphs, CSV, JSON, arrays, or web search. |\n\n**Agent Reasoning Flow:**\n\n1. User says: *\"Pick 10 stocks from this list of 50 that maximize Sharpe ratio.\"*\n2. LLM agent calls `aggregate_data` with ticker list → gets historical returns and correlations.\n3. Agent calls `formulate_qubo` → constructs QUBO with Sharpe ratio objective and cardinality constraint.\n4. Agent calls `solve_qubo` → warm-starts QAOA, dispatches to cloud QPU, returns optimal 10-stock selection.\n5. Agent presents: *\"Optimal portfolio: stocks [3, 7, 12, 18, 22, 29, 34, 41, 45, 49].\"*\n\n---\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────┐\n│  @quantum_boost  decorator                       │  ← User's classical function\n├──────────────────────────────────────────────────┤\n│  orchestrator  (router)                          │  ← Complexity check → classical or QPU\n├──────────────────────────────────────────────────┤\n│  circuits.py  (PennyLane QAOA)                   │  ← Builds QAOA circuit with warm-start\n├──────────────────────────────────────────────────┤\n│  providers.py  (QPU factories + BudgetGuard)     │  ← IonQ, Rigetti, IBM device wrappers\n├──────────────────────────────────────────────────┤\n│  formulator\u002F  (QUBO builder + aggregator)        │  ← Dynamic formulation from data\n├──────────────────────────────────────────────────┤\n│  mcp_server.py  (MCP JSON-RPC 2.0)               │  ← LLM agent auto-discovery layer\n└──────────────────────────────────────────────────┘\n         │\n         ▼\n   AWS Braket (IonQ \u002F Rigetti)  •  IBM Quantum (free tier)\n```\n\n**Decision flow:**\n\n1. QUBO \u003C 20 variables → **classical solver** (SciPy `dual_annealing`). Free. Zero cloud calls.\n2. QUBO ≥ 20 variables → **BudgetGuard** prompts cost confirmation → **QAOA circuit** built → **Cloud QPU** → results decoded and returned.\n\n---\n\n## API Reference\n\n### Decorator\n\n```python\n@quantum_boost\ndef my_solver(qubo_matrix: np.ndarray) -> dict: ...\n\n@quantum_boost(threshold=15, target_qpu=\"ibm\", auto_approve=True)\ndef my_solver(qubo_matrix: np.ndarray) -> dict: ...\n```\n\n### Configuration\n\n```python\nfrom quantum_boost import set_config, QuantumBoostConfig\n\nset_config(\n    quantum_threshold=20,   # Min variables for quantum path\n    default_qpu=\"ionq\",     # \"ionq\" | \"rigetti\" | \"ibm\"\n    auto_approve=False,     # Skip BudgetGuard?\n    shots=1024,             # Measurement shots\n    qaoa_layers=1,          # QAOA depth (p)\n)\n```\n\n### Cost Estimation\n\n```python\nfrom quantum_boost import cost_estimate\n\ncost_estimate(qubo_matrix, backend=\"ionq\", shots=1024)   # → 0.33\ncost_estimate(qubo_matrix, backend=\"ibm\", shots=1024)    # → 0.0  (free)\n```\n\n### Formulator\n\n```python\nfrom quantum_boost import QUBOFormulator, formulate\n\nf = QUBOFormulator(n_vars=5, description=\"My problem\")\nf.add_objective_minimize({0: 1.0, 1: 2.0})\nf.add_equality_constraint({0: 1.0, 1: 1.0}, rhs=1.0)\nqubo = f.build()\nprint(f.explain())\n```\n\n### Aggregator\n\n```python\nfrom quantum_boost import aggregate_data, AggregationSource\n\ndata = aggregate_data(source=\"stock_prices\", tickers=[\"AAPL\", \"GOOGL\"])\ndata = aggregate_data(source=\"graph\", edges=[(0,1), (1,2)])\ndata = aggregate_data(source=\"web_search\", query=\"top AI companies 2025\")\n```\n\n### Result Type\n\n```python\n@dataclass\nclass QuantumBoostResult:\n    solution: dict[int, int]   # {0: 1, 1: 0, 2: 1}\n    energy: float              # x^T Q x\n    backend_used: str          # \"ionq\" | \"rigetti\" | \"ibm\" | \"classical\"\n    num_shots: int             # 0 for classical\n    wall_time_ms: float        # Execution time\n```\n\n### QPU Utilities\n\n```python\nfrom quantum_boost import (\n    get_braket_device,   # → PennyLane device for AWS Braket\n    get_ibm_device,      # → PennyLane device for IBM Quantum\n    list_available_qpus, # → {\"ionq\": \"...\", \"rigetti\": \"...\", \"ibm\": \"...\"}\n)\n```\n\n### Low-Level Utilities\n\n```python\nfrom quantum_boost import (\n    validate_qubo,       # Validate QUBO matrix\n    qubo_to_ising,       # QUBO → Ising Hamiltonian\n    decode_bitstring,    # Measurement samples → binary solution\n    compute_energy,      # x^T Q x for a bitstring\n    normalize_qubo,      # Scale QUBO to [-1, 1]\n)\n```\n\n---\n\n## Expected Performance\n\n| QUBO Variables | Path | Expected Behavior |\n|----------------|------|-------------------|\n| **\u003C 20** | Classical (SciPy) | Exact or near-exact solution in milliseconds. Free. |\n| **20–50** | Cloud QPU | NISQ-era hardware. Useful for research and exploration. |\n| **50+** | Cloud QPU | Designed for future fault-tolerant hardware. QAOA circuit depth scales as O(n²). |\n\n---\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| PennyLane | ≥ 0.38.0 | Differentiable quantum computing |\n| NumPy | ≥ 1.26.0 | Matrix operations |\n| SciPy | ≥ 1.14.0 | Classical fallback solver |\n| python-dotenv | ≥ 1.0.0 | Auto-load `.env` credentials |\n| tavily-python | ≥ 0.7.0 | Web search aggregation |\n\n**Optional — IBM Quantum QPUs:**\n\n| Package | Purpose |\n|---------|---------|\n| pennylane-qiskit | PennyLane ↔ Qiskit bridge |\n| qiskit-ibm-runtime | IBM Quantum Runtime client |\n| qiskit-aer | Local Aer simulator fallback |\n\n**Optional — AWS Braket QPUs:**\n\n| Package | Purpose |\n|---------|---------|\n| amazon-braket-sdk | AWS Braket SDK |\n| amazon-braket-pennylane-plugin | PennyLane ↔ Braket bridge |\n\n---\n\n## License\n\nMIT\n","`quantum_boost` 是一个让AI代理能够访问量子计算资源的Python库。它支持将组合优化问题卸载到真实的量子硬件上处理，无需编写任何量子代码。该库的核心功能包括动态QUBO公式化、多源数据聚合以及通过MCP服务器实现LLM代理自动发现。它支持IBM Quantum、AWS Braket（IonQ和Rigetti）等多家量子处理器提供商，并且在提交任务前提供交互式成本确认以保护用户的云账单。适用于需要高效解决复杂优化问题但又不想深入了解量子物理原理的应用场景，如投资组合优化、物流规划等。",2,"2026-06-11 03:59:06","CREATED_QUERY"]