QuantumWeave

• 

  architecture.md

Inspiration

We were inspired by Google DeepMind's AlphaQubit (2024) and the challenge of Quantum Education. Quantum mechanics is notoriously unintuitive—superposition and entanglement defy human logic. We wanted to bridge the gap between "Talking about Quantum" and "Doing Quantum". We asked: What if you had an AI Co-Architect that didn't just explain the physics, but actually built the circuits with you, guaranteeing mathematical rigor?

What it does

QuantumWeave is an Agentic IDE for the Quantum Realm.

1. Natural Language Design: You tell the Agent, "Create a circuit that prepares a Bell Pair."
2. Rigorous Simulation: The Agent (Gemini 3.0) writes and executes Python code using Google Cirq, a state-vector simulator. It doesn't just guess; it runs the physics.
3. Holographic Visualization: The simulation output is piped into a 3D Visualizer. You see the Qubits (Bloch Spheres) rotate, and you see neon pink Entanglement Bonds form in real-time.
4. Self-Correction: If the user asks for something impossible, the Agent detects the physics error and explains why it failed, acting as a personalized tutor.

How we built it

We built a sophisticated Hybrid "Brain-and-Body" Architecture:

• The Brain (AI): We used the Google Agent Development Kit (ADK) to build a ReAct Agent powered by Gemini 3.0 Flash. It plans, reasons, and uses tools.
• The Body (Physics): A Python 3.11 backend using FastAPI wraps Google Cirq. This ensures every simulation is grounded in real Hilbert space mathematics.
• The Face (UI): A Next.js 16 (Turbopack) frontend uses Three.js (React Three Fiber) to render the quantum state.
• The Infrastructure: We containerized the hybrid stack (Node.js + Python) using Docker and Supervisord, deploying it to Google Cloud Run for serverless scalability.

Challenges we ran into

The "Ghost in the Machine". Our Cloud Run deployment kept crashing with a mysterious ECONNREFUSED error, but no logs were generated. The server would start ("RUNNING") and then immediately vanish.

• The Diagnosis: It was a Binary Incompatibility (Segfault). We were initially using the bleeding-edge Python 3.13. The C++ extensions in Cirq and ADK were crashing silently on the x86 Linux kernel.
• The Fix: We downgraded to Python 3.11 (Industry Standard) and implemented a robust Lazy Loading architecture. By deferring heavy imports until after the server boot, we eliminated startup timeouts and ensured graceful error handling.

Accomplishments that we're proud of

• Dynamic Entanglement Visualization: Parsing raw text output from the Agent to dynamically draw "Entanglement Bonds" between specific qubits in 3D space.
• Robustness: Creating a "Crash-Proof" Agent. Even if the physics engine throws an error or the API hits a rate limit (429), our custom error handling catches it and explains the situation to the user instead of showing a white screen.
• Lazy Loading Architecture: Successfully engineering a backend that keeps a heavy scientific library on standby but responds instantly to health checks.

What we learned

• Grounding is Everything: LLMs can hallucinate quantum gates. By forcing the Agent to use the Cirq tool, we ensure that if the output looks correct, it is physically correct.
• Architecture > Code: The "Lazy Loading" pattern wasn't just an optimization; it was the difference between a failed deployment and a working product.
• Gemini 3.0's Reasoning: The model's ability to self-correct ("Wait, I cannot use a Hadamard on a measured qubit") was surprisingly effective when given a proper ReAct loop.

What's next for QuantumWeave

• Real Hardware Integration: Using Google Quantum AI's Passthrough to run these circuits on actual Sycamore processors.
• Collaborative Holograms: Multiplayer rooms where students can "grab" qubits and wire them together.
• QASM Export: Allowing users to export their designs to OpenQASM format for use in other academic tools.

Built With

• fastapi
• gemini3
• google-adk
• google-cirq
• googlecloudrun
• nextjs
• python
• tailwind
• three.js
• typescript