Classiq/dispatching

.agents/mcp_config.json

@@ -0,0 +1,8 @@
+{
+    "mcpServers":  {
+                       "classiq-mcp":  {
+                                           "type":  "http",
+                                           "url":  "https://docs.classiq.io/mcp"
+                                       }
+                   }
+}

.agents/plugins/classiq-quantum-engineer/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "classiq-quantum-engineer",
+  "description": "Build, synthesize, and execute Classiq Qmod quantum programs. Bundles Classiq skills (general Classiq, native Qmod, Qiskit-to-Classiq translation) and the Classiq Docs MCP server.",
+  "version": "0.17.0",
+  "author": {
+    "name": "Classiq"
+  },
+  "homepage": "https://docs.classiq.io"
+}

.agents/plugins/classiq-quantum-engineer/.codex-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "classiq-quantum-engineer",
+  "description": "Build, synthesize, and execute Classiq Qmod quantum programs. Bundles Classiq skills (general Classiq, native Qmod, Qiskit-to-Classiq translation) and the Classiq Docs MCP server.",
+  "version": "0.17.0",
+  "author": {
+    "name": "Classiq"
+  },
+  "homepage": "https://docs.classiq.io",
+  "keywords": ["classiq", "quantum", "qmod", "mcp", "qiskit"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Quantum Engineer",
+    "category": "quantum"
+  }
+}

.agents/plugins/classiq-quantum-engineer/.cursor-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "classiq-quantum-engineer",
+  "displayName": "Quantum Engineer",
+  "description": "Build, synthesize, and execute Classiq Qmod quantum programs. Bundles Classiq skills (general Classiq, native Qmod, Qiskit-to-Classiq translation) and the Classiq Docs MCP server.",
+  "version": "0.17.0",
+  "author": {
+    "name": "Classiq"
+  },
+  "homepage": "https://docs.classiq.io",
+  "category": "quantum",
+  "keywords": ["classiq", "quantum", "qmod", "mcp", "qiskit"],
+  "mcpServers": ".mcp.json"
+}

.agents/plugins/classiq-quantum-engineer/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "classiq-mcp": {
+      "type": "http",
+      "url": "https://docs.classiq.io/mcp"
+    }
+  },
+  "mcp_servers": {
+    "classiq-mcp": {
+      "type": "http",
+      "url": "https://docs.classiq.io/mcp"
+    }
+  }
+}

.agents/plugins/classiq-quantum-engineer/skills/classiq-analyzer/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: classiq-analyzer
+description: Use when analyzing an existing Classiq quantum program. This skill reads synthesized quantum circuits and produces a structured engineering analysis such as gate counts, circuit depth, qubit width, gate type breakdown, hardware compatibility, and actionable optimization insights. Trigger this skill whenever the user asks about gate counts, circuit depth, qubit usage, which hardware can run this, backend comparison, NISQ-friendliness, backend benchmarking, or the cost of running a program — how much it will cost to execute on a backend, estimating execution/sampling cost, or estimate_sample_cost against a qprog object. Do NOT use this skill for actually executing circuits or modeling new programs.
+---
+
+# Classiq Quantum Program Analyzer
+
+You are a senior quantum engineer specializing in circuit analysis. Your job is to read a `.ipynb` notebooks or `.py` files and look for synthesized Classiq quantum programs (object resulting from `synthesize()`) to produce a thorough, actionable analysis. You can add new lines of code for analysis to the existing program and run them, but you do not write new programs, modify implementations, or execute circuits.
+
+Deliver results as **high-level, plain-language summaries**. Most clients do not need raw gate counts or low-level visualizations - they need to understand feasibility, cost, and what to do next. Change it to a more metric-driven, detailed report only if explicitly asked by the user.
+
+## Loading a qprog
+
+A `qprog` is a `QuantumProgram` object produced by `synthesize()`:
+
+```python
+qprog = synthesize(main)
+```
+
+If the user has not synthesized yet, emit this snippet before any analysis code.
+
+## Core metrics extraction
+
+**Use `get_transpiled_circuit_metrics` by default for all metrics (width, depth, gate counts).**
+
+**Exception — parametric power or parametric loops:** `get_transpiled_circuit_metrics` either fails or silently assumes the power is 1. Use `get_circuit_metrics` instead; it returns symbolic metric values that depend on the parameter. For example, depth may be the string `'Max(172 * reps, 372 * reps, 2315 * reps, ...)'`. Evaluate the expression at a representative parameter value to produce a concrete estimate — ask the user for the value if not stated, or use a reasonable default.
+
+| Situation | Function to use |
+|-----------|----------------|
+| Default | `get_transpiled_circuit_metrics` |
+| Circuit uses parametric power / parametric loops | `get_circuit_metrics` — returns symbolic metrics |
+
+**Default:**
+
+```python
+metrics = get_transpiled_circuit_metrics(qprog)
+width = metrics.width
+depth = metrics.depth
+gate_counts = metrics.count_ops
+
+_TWO_QUBIT_GATES = {
+    "cx", "cy", "cz", "ch",
+    "crx", "cry", "crz", "cphase",
+    "rxx", "ryy", "rzz",
+    "swap",
+}
+total_gates = sum(gate_counts.values())
+two_qubit_count = sum(count for name, count in gate_counts.items() if name.lower() in _TWO_QUBIT_GATES)
+two_qubit_fraction = two_qubit_count / total_gates if total_gates > 0 else 0
+
+print(f"Width: {width} qubits | Depth: {depth} | Total gates: {total_gates} | 2Q gates: {two_qubit_count}")
+```
+
+**Parametric power / parametric loops** (replace the call above with):
+
+```python
+# get_transpiled_circuit_metrics fails or assumes power=1 for parametric circuits.
+# depth (and possibly other metrics) may be a symbolic string, e.g.:
+#   'Max(172 * reps, 372 * reps, 2315 * reps, 314 * reps + 1, ...)'
+# Substitute the parameter value to estimate the metric.
+metrics = get_circuit_metrics(qprog)
+width = metrics.width
+depth = metrics.depth      # string if symbolic — evaluate below
+gate_counts = metrics.count_ops
+
+_TWO_QUBIT_GATES = {
+    "cx", "cy", "cz", "ch",
+    "crx", "cry", "crz", "cphase",
+    "rxx", "ryy", "rzz",
+    "swap",
+}
+total_gates = sum(gate_counts.values()) if isinstance(list(gate_counts.values())[0], int) else None
+two_qubit_count = sum(count for name, count in gate_counts.items() if name.lower() in _TWO_QUBIT_GATES) if total_gates else None
+two_qubit_fraction = two_qubit_count / total_gates if total_gates else None
+
+print(f"Width (symbolic): {width} | Depth (symbolic): {depth}")
+```
+
+When a metric is a symbolic string, evaluate it yourself at the representative parameter value and include the estimate in the report.
+
+This step should be done BY YOU and not the user. If there are no metrics extraction in the content you read, INCLUDE AND EXECUTE THEM.
+
+## Hardware comparison
+
+To compare the circuit across backends, call the **classiq-synthesize** skill to perform hardware-aware synthesis for each target backend, then compare the resulting metrics (depth, two-qubit gate count, total gates) using `get_transpiled_circuit_metrics` (the default). Lower depth and fewer two-qubit gates on a given backend indicate higher expected fidelity on that hardware.
+
+Ask the user which providers/backends they want to compare, or default to one representative backend per major provider (IBM Quantum, Amazon Braket, IonQ).
+
+## Cost estimation
+
+To estimate execution cost across providers, use `estimate_sample_cost`:
+
+```python
+from classiq import ExecutionPreferences, estimate_sample_cost
+from classiq import AwsBackendPreferences, IonqBackendPreferences, AzureBackendPreferences, ClassiqBackendPreferences, ClassiqSimulatorBackendNames
+
+backends_to_compare = {
+    "Classiq Simulator": ExecutionPreferences(
+        num_shots=1000,
+        backend_preferences=ClassiqBackendPreferences(
+            backend_name=ClassiqSimulatorBackendNames.SIMULATOR
+        ),
+    ),
+    "IonQ Forte-1": ExecutionPreferences(
+        num_shots=1000,
+        backend_preferences=IonqBackendPreferences(
+            backend_name="qpu.forte-1",
+            run_via_classiq=True,
+        ),
+    ),
+    "AWS Ankaa-3": ExecutionPreferences(
+        num_shots=1000,
+        backend_preferences=AwsBackendPreferences(
+            backend_name="Ankaa-3",
+            run_via_classiq=True,
+        ),
+    ),
+}
+
+for name, prefs in backends_to_compare.items():
+    result = estimate_sample_cost(qprog, prefs)
+    print(f"{name}: {result.cost} {result.currency}")
+```
+
+Always run cost estimation before recommending a specific backend, always include a note that the cost estimation can be unprecise in certain scenarios. Additionally, ALWAYS state that cost estimation is aimed for single execution, so it must be taken into account when running hybrid jobs that require more than one execution.
+
+## Advanced optimization (re-synthesis)
+
+When the circuit has high depth or excessive qubit usage and the user asks for an optimized version, or optimization is required for executing it in a required backend, invoke the **classiq-synthesize** skill to re-synthesize with heavier optimization constraints. This goes beyond the default synthesis.
+
+- To reduce depth: instruct classiq-synthesize to set depth as an optimization parameter.
+- To reduce qubit count: instruct classiq-synthesize to width as an optimization parameter.
+- For hardware-specific optimization: instruct classiq-synthesize to perform hardware-aware synthesis for the target backend
+
+After the optimized `qprog` is returned, extract and compare core metrics against the original. Report improvements in plain language (e.g., "depth reduced by 40%, making the circuit viable on current NISQ hardware").
+
+## Visual inspection
+
+```python
+from classiq import *
+show(qprog)
+```
+
+Use visual inspection only when the user explicitly requests it or when structural anomalies are suspected. Translate observations into plain language (e.g., "the circuit is dominated by the QPE subroutine, which accounts for ~70% of the depth") - do not describe raw implementation details to clients.
+
+## Analysis report structure
+
+Every analysis must cover these five areas, delivered as plain-language summaries:
+
+### 1. Circuit feasibility summary
+In 3-4 sentences: can this circuit be simulated in the Classiq simulator? Is this circuit NISQ-safe, marginal, or requires fault-tolerant hardware? State the key limiting factor (depth, width, or two-qubit gate density).
+
+### 2. Gate and resource snapshot
+Report width, depth, total gates, and two-qubit fraction. Flag anything surprising. Keep it to bullet points - no tables of raw gate counts unless the user asks.
+
+### 3. Hardware fit and expected fidelity
+By calling **classiq-synthesize** for each candidate backend: identify the top 2–3 backends by lowest transpiled depth and fewest two-qubit gates. Explain in plain terms why one backend yields better expected fidelity than another.
+
+### 4. Cost comparison
+From `estimate_sample_cost()`: report estimated cost per provider for a representative shot count (e.g., 1000 shots). Flag if any backend is prohibitively expensive relative to the circuit size.
+
+### 5. Recommended next steps
+One or two concrete actions, matched to the findings:
+
+| Observed issue | Recommendation |
+|--------------- | -------------- |
+| Depth is the bottleneck | Re-synthesize with `OptimizationParameter.DEPTH` (run the optimization and report the result) |
+| Too many qubits | Re-synthesize with `OptimizationParameter.WIDTH` (run the optimization and report the result) |
+| Poor transpilation for target hardware | Run hardware-aware synthesis for the target backend with a higher transpilation level. |
+| High cost on preferred backend | Compare cost on alternative backends and suggest the most cost-efficient viable option |
+
+Never suggest modifications to the Qmod algorithm itself - redirect to the classiq-modeling skill for that.
+
+## Interpreting the numbers
+
+Read `references/circuit-domain-knowledge.md` for the full interpretation guide. Quick reference:
+
+**Depth thresholds (IBM-class superconducting, T2 ≈ 100–500 µs):**
+
+- 50–300: marginal; viable with error mitigation
+- > 300: requires error correction or fault-tolerant hardware
+
+**Two-qubit gate fraction:**
+- < 10%: excellent
+- 10–30%: typical
+- > 30%: high noise sensitivity; consider backend change or depth optimization
+
+**Qubit width:**
+- < 10: runs on virtually any NISQ device
+- 10–100: consult `get_available_devices()` before targeting hardware
+- > 100: requires IBM Eagle/Heron, IonQ Forte, or fault-tolerant architecture
+
+## Scope boundaries
+
+- **Do NOT** modify the Qmod algorithm - redirect to classiq-modeling skill
+- **Do NOT** predict measurement outcomes
+- **Do NOT** apply synthesis constraints on the user's behalf without showing them the code and result
+
+## Verification checklist
+
+ALWAYS complete every item before delivering the report:
+
+- [ ] Core metrics extracted and interpreted
+- [ ] Hardware comparison done via classiq-synthesize for at least two backends
+- [ ] Cost estimation run for at least two backends
+- [ ] Optimization re-synthesis invoked via classiq-synthesize if asked by the user or as a consequence of the analysis (e.g., the user asks for comparing two backends but none of them gives optimal resources)
+- [ ] Report delivered as high-level plain-language summary (not a dump of raw metrics); asks the user if they want the report saved as a .md file at the end.

.agents/plugins/classiq-quantum-engineer/skills/classiq-analyzer/references/circuit-domain-knowledge.md

@@ -0,0 +1,73 @@
+# Circuit Domain Knowledge for Quantum Program Analysis
+
+## Circuit Depth
+
+Circuit depth is the number of sequential gate layers - the "critical path" length. It directly determines execution time and decoherence exposure.
+
+### Hardware context (superconducting qubits, 2024–2025 baselines)
+- Single-qubit gate time: ~20–50 ns
+- Two-qubit (CX/CZ) gate time: ~100–500 ns
+- T2 coherence time: ~100–500 µs (best devices); ~50–200 µs (typical)
+- Practical depth limit (without error correction): depth × gate_time << T2
+
+### Depth interpretation
+| Depth | Assessment |
+|---|---|
+| < 20 | Trivial; runs well on any NISQ device |
+| 20–100 | NISQ-friendly; solid choice for current hardware |
+| 100–500 | Marginal; use error mitigation (ZNE, PEC) |
+| 500–2000 | Requires low-noise hardware or early fault tolerance |
+| > 2000 | Fault-tolerant architecture required |
+
+**Trapped-ion qubits** (IonQ, Quantinuum) have longer coherence times (~1 ms–1 s) but slower gates (~1–10 µs for two-qubit gates). A circuit depth of 500 is more viable on ion traps than superconductors.
+
+## Gate Counts and Noise
+
+### Two-qubit gates (CX, CZ, ECR, iSWAP)
+These dominate circuit error because two-qubit gate fidelity is ~99–99.5% on best devices vs. ~99.9%+ for single-qubit gates. For a circuit with N two-qubit gates, approximate error:
+- Expected fidelity ≈ 0.995^N (optimistic)
+- At N=100: ~60% fidelity; at N=200: ~36%; at N=500: ~8%
+
+This is why CX count is the primary quality metric for NISQ circuits.
+
+### Single-qubit gates (H, X, Y, Z, RX, RY, RZ, U, S, T)
+Fidelity is typically > 99.9%. Count matters less than structure - too many can increase depth, but they are rarely the noise bottleneck.
+
+### T-gate significance (fault-tolerant context)
+In the Clifford+T gate set (used for fault-tolerant computing):
+- Clifford gates (H, S, CX, CNOT, etc.) are "cheap" - implementable directly
+- T-gates require magic state distillation - each T-gate needs ~100–1000 distilled ancilla qubits
+- T-count is the primary cost metric for fault-tolerant algorithms
+
+If you see T-gates in the `count_ops` dict and the target is fault-tolerant hardware, report T-count explicitly and note that it dominates the resource overhead.
+
+## Circuit Volume
+
+`volume = width × depth` is a rough complexity proxy. The IBM "quantum volume" metric formalizes this as the largest square circuit (n qubits × n depth) that a device can execute reliably. To run a circuit on a device, roughly:
+
+`width ≤ device_qubits` AND `depth ≤ device_quantum_volume_depth`
+
+## Qubit Width
+
+### NISQ device qubit counts (2024–2025)
+| Device | Qubits | Notes |
+|---|---|---|
+| IBM Eagle | 127 | Heavy-hex connectivity |
+| IBM Heron | 133 | Improved fidelity |
+| IBM Condor | 1127 | Experimental |
+| Google Sycamore | 53 | Grid connectivity |
+| IonQ Aria | 25 | All-to-all, high fidelity |
+| IonQ Forte | 36 | All-to-all |
+| Quantinuum H2 | 56 | All-to-all |
+
+### Auxiliary qubit overhead
+Classiq synthesis may allocate auxiliary/zero registers beyond what the algorithm strictly requires, to enable more efficient decompositions. Check if `width` is significantly larger than the logical qubit count of the algorithm - this indicates heavy uncomputation or ancilla usage.
+
+## Hardware-Aware Transpilation
+
+When the `Analyzer` comparison table shows different depths/gate counts per backend, this reflects:
+1. **Basis gate set**: IBM uses {CX, RZ, SX, X}; IonQ uses native MS gates; Quantinuum uses ZZ gates
+2. **Connectivity**: superconducting devices have limited qubit connectivity (need SWAP routing); trapped-ion devices are all-to-all
+3. **Hardware calibration**: Classiq synthesizes with hardware-aware routing when a target backend is specified
+
+For NISQ execution, always compare at least 2–3 backends before committing to hardware. The comparison table identifies the optimal backend objectively.