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

Akifin — Tue, 11 Nov 2025 00:56:56 +0000

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:

You speak a personal, future-facing question.
The system checks: is this safe, relevant, and in-scope?
If yes, it entangles your voice hash with quantum randomness.
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

Take one quantum byte.
XOR with all bytes of voice_signature_bytes.
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

DEV Community: Akifin