DEV Community

Cover image for Inside Quantum Ball: Building a Playful Oracle with AI Studio + Cloud Run
Akifin
Akifin

Posted on

Inside Quantum Ball: Building a Playful Oracle with AI Studio + Cloud Run

#cloudrunhackathon

Quantum Ball is a voice-powered manifestation oracle that fuses:

  • your spoken question
  • a hashed “voice signature”
  • true quantum randomness
  • and Gemini 2.5 Flash

…into a single, short, on-brand answer that leans hopeful—but can still say “unclear” or even “no” when that feels honest.

Built for the Google Cloud Run Hackathon (AI Studio Category).

Try it / Code

Live demo
👉 https://gen-lang-client-0524129649.web.app

YouTube demo
👉 https://youtu.be/yDDZvLX93AE?si=H2q6BpWb7YAFCQhG

The demo may be rate-limited at times; please see the repo README for details.

Source code
👉 https://github.com/memetcircus/Quantum_Ball

The core idea

Most people don’t run out of options.

They run out of belief.

Quantum Ball is designed as a tiny cinematic ritual:

  1. You speak a personal, future-facing question.
  2. The system checks: is this safe, relevant, and in-scope?
  3. If yes, it entangles your voice hash with quantum randomness.
  4. Gemini turns that into a constrained, in-character answer.

Not fortune-telling. Not toxic positivity.

A gentle nudge back toward “good things can happen — to me — from here”.

High-level architecture

Frontend

  • Static, responsive web app on Firebase Hosting
  • HTML + CSS + vanilla JS
  • Voice capture via MediaRecorder
  • Canvas-based “Quantum Grid” background
  • Sends audio.bin via multipart/form-data → /ask

Backend

  • Python + Flask on Google Cloud Run
  • CORS locked to Firebase origins
  • Flask-Limiter:
    • global: 200/day, 50/hour
    • /ask: 10/min per IP
  • Uses:
    • Google Cloud Speech-to-Text (WEBM_OPUS → LINEAR16 fallback)
    • Gemini 2.5 Flash via google-genai
    • ANU QRNG API for true randomness
    • Pydantic for strict JSON schemas

Designed first in Google AI Studio

We built two dedicated prompt “components” in Google AI Studio, then embedded them into main.py:

1. The Classifier

Gemini 2.5 Flash prompt with structured output:

  • relevant
  • irrelevant_statement
  • harmful_query
  • inappropriate_query
  • plus relevance_score

Used as the primary gate:

  • Harmful → static crisis-style support message
  • Inappropriate → short, firm mystical refusal
  • Irrelevant / command → charismatic nudge to ask a real question
  • Relevant → allowed into the quantum path

2. The Creative Generator

A second Gemini 2.5 Flash prompt:

  • Input:
    • USER_QUESTION
    • JUDGMENT_TYPE (Positive / Non-committal / Negative)
    • INSPIRATION_PHRASE (one of 20 classic-style outcomes)
  • Output (JSON):
    • creative_answer
    • judgment_type

This keeps answers:

  • short
  • poetic
  • consistently “Quantum Ball” in voice

Quantum randomness + voice entanglement

For relevant queries:

Quantum cache

  • Fetches batches of uint8 values from ANU QRNG.
  • Thread-safe cache (lock + FIFO).
  • Respects rate limits; falls back to pseudo-random only if empty.

Voice hash

  • SHA-256 of raw audio → voice_signature_bytes
  • Never stored as identity; used purely as entropy.

Entanglement

  1. Take one quantum byte.
  2. XOR with all bytes of voice_signature_bytes.
  3. Map result into [0..19] → 20 Magic 8-Ball–style outcomes:
    • 10 Positive
    • 5 Non-committal
    • 5 Negative

Gemini final pass

  • The Creative Generator rewrites that chosen outcome into a custom line.
  • Frontend renders it inside the Quantum Ball with adaptive typography.

Net effect: answers feel personal, repeatable per ritual, and more than just “LLM says stuff”.

Safety & reliability

Key decisions:

Layered safety

  • Command prefix filter (e.g. “tell me…”, meta prompts).
  • AI Studio–tuned 4-way classifier.
  • Hardcoded self-harm support message.
  • Strict mystical refusals for harassment/violence.
  • Gemini safety as an extra guardrail.

Production-ish hygiene

  • Rate limiting on /ask
  • CORS locked to official frontend
  • Clear JSON errors (no speech detected, etc.)
  • No secrets in repo (env vars only)

This lets us keep the experience playful and responsible.

Why this stack works

  • AI Studio → design prompts like real backend components, with structured output.
  • Cloud Run → one clean container for the oracle brain.
  • Firebase Hosting → fast, global frontend.
  • Gemini + STT + QRNG → modern Magic 8-Ball with real entropy & personality.

Submitted for the Google Cloud Run Hackathon – AI Studio Category

CloudRunHackathon #GoogleCloud #AIStudio #Gemini #CloudRun #Firebase #QRNG

Top comments (0)