Update main.py

main.py

@@ -47,6 +47,9 @@ try:
     firebase_db_url = os.environ.get("Firebase_DB")
     firebase_storage_bucket = os.environ.get("Firebase_Storage")
 
+    if not firebase_db_url or not firebase_storage_bucket:
+        raise ValueError("Firebase_DB and Firebase_Storage environment variables must be set.")
+
     cred = credentials.Certificate(credentials_json)
     firebase_admin.initialize_app(cred, {
         'databaseURL': firebase_db_url,
@@ -60,9 +63,9 @@ except Exception as e:
 bucket = storage.bucket()
 db_ref = db.reference()
 
-# --- Google GenAI Client Initialization (Gemini 3.0) ---
+# --- Google GenAI Client Initialization (Gemini 3.0 Ecosystem) ---
 try:
-    logger.info("Initializing Google GenAI Client (Gemini 3.0 Ecosystem)...")
+    logger.info("Initializing Google GenAI Client (Titaness Paradigm)...")
     api_key = os.environ.get("Gemini")
     if not api_key:
         raise ValueError("The 'Gemini' API key is not set.")
@@ -77,16 +80,18 @@ except Exception as e:
 ATHENA_FLASH = "gemini-3-flash-preview"
 ATHENA_PRO = "gemini-3-pro-image-preview"
 
-# Grounding / External API
+# Grounding / External API Keys
 WOLFRAM_APP_ID = os.environ.get("WOLFRAM_APP_ID")
 OPENALEX_MAILTO = os.environ.get("OPENALEX_MAILTO", "rairo@sozofix.tech")
 
 # -----------------------------------------------------------------------------
-# 2. HELPER FUNCTIONS & GROUNDING
+# 2. HELPER FUNCTIONS & AUTHENTICATION
 # -----------------------------------------------------------------------------
 
 def verify_token(auth_header):
+    """Verifies Firebase ID token from the Authorization header."""
     if not auth_header or not auth_header.startswith('Bearer '):
+        logger.warning("Auth Header missing or malformed.")
         return None
     token = auth_header.split('Bearer ')[1]
     try:
@@ -97,39 +102,51 @@ def verify_token(auth_header):
         return None
 
 def verify_admin(auth_header):
+    """Ensures the user has admin privileges in the Realtime Database."""
     uid = verify_token(auth_header)
-    if not uid: raise PermissionError('Invalid token')
+    if not uid: 
+        raise PermissionError('Invalid token')
     user_data = db_ref.child(f'users/{uid}').get()
     if not user_data or not user_data.get('is_admin', False):
+        logger.warning(f"Unauthorized Admin access attempt by UID: {uid}")
         raise PermissionError('Admin access required')
     return uid
 
 def upload_to_storage(data_bytes, destination_blob_name, content_type):
+    """Uploads bytes to Firebase Storage and returns the public URL."""
     try:
         blob = bucket.blob(destination_blob_name)
         blob.upload_from_string(data_bytes, content_type=content_type)
         blob.make_public()
         return blob.public_url
     except Exception as e:
-        logger.error(f"Failed to upload to Firebase Storage: {e}")
+        logger.error(f"Firebase Storage Upload Error: {e}")
         return None
 
 def query_wolfram_alpha(query):
-    if not WOLFRAM_APP_ID: return "Grounded in physical first principles."
+    """Fetches computational facts from Wolfram Alpha for grounding."""
+    if not WOLFRAM_APP_ID: 
+        return "Grounded in first principles."
     try:
         url = f"http://api.wolframalpha.com/v1/result?appid={WOLFRAM_APP_ID}&i={query}"
         response = requests.get(url, timeout=5)
-        return response.text if response.status_code == 200 else "Constants verifying..."
-    except: return "Grounding context pending."
+        if response.status_code == 200:
+            return response.text
+        return "Constants verifying..."
+    except Exception as e:
+        logger.error(f"Wolfram Alpha Query Failed: {e}")
+        return "Grounding in progress."
 
 # -----------------------------------------------------------------------------
 # 3. TITANESS MEDIA ENGINE (CONSOLIDATED MASTER BLUEPRINT + ASYNC AUDIO)
 # -----------------------------------------------------------------------------
 
 def generate_narration_task(text, uid, epiphany_id, layer_name):
-    """Deepgram Aura-Luna task for Athena's voice."""
-    if not text: return layer_name, None
+    """Worker task for generating Deepgram audio in a thread."""
+    if not text or len(text) < 5: 
+        return layer_name, None
     try:
+        logger.info(f"[THREAD] Starting Narration: {layer_name}")
         api_key = os.environ.get("DEEPGRAM_API_KEY")
         if not api_key: return layer_name, None
         
@@ -138,26 +155,33 @@ def generate_narration_task(text, uid, epiphany_id, layer_name):
         response = requests.post(DEEPGRAM_URL, headers=headers, data=text.encode('utf-8'))
         response.raise_for_status()
 
-        path = f"users/{uid}/epiphanies/{epiphany_id}/narrations/{layer_name}.mp3"
-        return layer_name, upload_to_storage(response.content, path, 'audio/mpeg')
+        path = f"users/{uid}/epiphanies/{epiphany_id}/audio/{layer_name}.mp3"
+        url = upload_to_storage(response.content, path, 'audio/mpeg')
+        return layer_name, url
     except Exception as e:
-        logger.error(f"TTS Task Error [{layer_name}]: {e}")
+        logger.error(f"Narration Task Error [{layer_name}]: {e}")
         return layer_name, None
 
 def generate_master_blueprint_task(subject, flattened_data, uid, epiphany_id):
-    """Nano Banana Pro: Generates ONE consolidated 4K Technical Blueprint schematic."""
+    """Worker task for generating the 16:9 Consolidated Master Blueprint."""
     try:
-        logger.info(f"Generating Master Blueprint for: {subject}")
-        # Build context for the visual
-        context_str = f"Genesis: {flattened_data.get('genesis', '')[:100]}... Core: {flattened_data.get('scientific_core', '')[:100]}..."
+        logger.info(f"[THREAD] Starting Nano Banana Master Blueprint for: {subject}")
+        # Build prompt context from synthesis
+        summary = (
+            f"Genesis: {flattened_data.get('genesis', '')[:100]}... "
+            f"Core: {flattened_data.get('scientific_core', '')[:100]}... "
+            f"Edge: {flattened_data.get('engineering_edge', '')[:100]}... "
+            f"Future: {flattened_data.get('cross_pollination', '')[:100]}..."
+        )
         
         prompt = (
-            f"Generate a single high-fidelity 4K Master Technical Blueprint for '{subject}'. "
-            f"Layout: A four-quadrant schematic. Zone 1: Genesis (Origins). Zone 2: Scientific Core (The Physics). "
-            f"Zone 3: Engineering Edge (Design Limits). Zone 4: Cross-Pollination (Future Tech-Tree). "
-            f"Aesthetic: White-line architectural blueprint on midnight navy background. "
-            f"Style: Leonardo Da Vinci meets modern 4K engineering software. High scientific accuracy. "
-            f"Context details: {context_str}"
+            f"Generate a single 4K Master Technical Blueprint for '{subject}'. "
+            f"Layout: A detailed four-quadrant schematic diagram. "
+            f"Quadrant 1: Genesis (Origins). Quadrant 2: Scientific Core (The Physics). "
+            f"Quadrant 3: Engineering Edge (Design Limits). Quadrant 4: Cross-Pollination (Future Tech). "
+            f"Aesthetic: White-line schematic style on a dark midnight navy background. "
+            f"Style: Leonardo Da Vinci meets modern 4K engineering schematics. High accuracy. "
+            f"Details to include: {summary}"
         )
         
         response = client.models.generate_content(
@@ -174,73 +198,77 @@ def generate_master_blueprint_task(subject, flattened_data, uid, epiphany_id):
             return upload_to_storage(image_bytes, path, 'image/png')
         return None
     except Exception as e:
-        logger.error(f"Master Blueprint Engine Error: {e}")
+        logger.error(f"Master Blueprint Thread Error: {e}")
         return None
 
 # -----------------------------------------------------------------------------
-# 4. CORE ENDPOINTS (EPIPHANY GENERATION & THEIA)
+# 4. PRIMARY ENDPOINTS: GENERATE & THEIA SWEEP
 # -----------------------------------------------------------------------------
 
 @app.route('/api/image-proxy', methods=['GET'])
 def image_proxy():
+    """Proxies images to bypass CORS/AI Studio Preview blocks."""
     image_url = request.args.get('url')
-    if not image_url: return jsonify({'error': 'No URL'}), 400
+    if not image_url: return jsonify({'error': 'URL missing'}), 400
     try:
         resp = requests.get(image_url, timeout=10)
-        return Response(resp.content, content_type=resp.headers['Content-Type'])
-    except Exception as e: return jsonify({'error': str(e)}), 500
+        return Response(resp.content, content_type=resp.headers.get('Content-Type', 'image/jpeg'))
+    except Exception as e:
+        return jsonify({'error': str(e)}), 500
 
 @app.route('/api/epiphany/generate', methods=['POST'])
 def generate_epiphany():
-    logger.info(">>> TITANESS GENERATION INITIATED")
+    """The Titaness Core: Synthesis + Feynman Scholar + Consolidated Blueprint."""
+    logger.info(">>> TITANESS GENERATION START")
     uid = verify_token(request.headers.get('Authorization'))
     if not uid: return jsonify({'error': 'Unauthorized'}), 401
 
     user_ref = db_ref.child(f'users/{uid}')
-    user_data = user_ref.get()
+    user_data = user_ref.get() or {}
     
-    # 8 Sparks for Synthesis + Feynman Scholar + Consolidated Master Blueprint
-    if not user_data or user_data.get('credits', 0) < 8:
-        return jsonify({'error': 'Need 8 Sparks for Full Master Synthesis.'}), 402
+    # Cost: 8 Sparks (Consolidated Synthesis + 4K Blueprint)
+    if user_data.get('credits', 0) < 8:
+        return jsonify({'error': 'Insufficient Sparks. (Full Synthesis requires 8 sparks)'}), 402
 
     if 'image' not in request.files:
-        return jsonify({'error': 'Visual input required.'}), 400
+        return jsonify({'error': 'Visual image is required.'}), 400
     
     image_file = request.files['image']
     image_bytes = image_file.read()
     pil_image = Image.open(io.BytesIO(image_bytes)).convert('RGB')
 
     try:
-        # Step 1: Precise Identification
-        id_prompt = "Identify this object or system. Reply with ONLY the name (max 5 words)."
-        subject = client.models.generate_content(model=ATHENA_FLASH, contents=[id_prompt, pil_image]).text.strip()
-        logger.info(f"Synthesis Subject: {subject}")
-
-        # Step 2: Synthesis + Universal Scholar Search
-        physics_fact = query_wolfram_alpha(f"physics laws of {subject}")
+        # Step 1: Accurate Identification
+        id_prompt = "Identify this precisely. Include specific model or species if visible. Reply with ONLY the name (max 5 words)."
+        id_res = client.models.generate_content(model=ATHENA_FLASH, contents=[id_prompt, pil_image])
+        subject = id_res.text.strip()
+        logger.info(f"Subject Identified: {subject}")
+
+        # Step 2: Grounded Feynman Synthesis + Research
+        physics_fact = query_wolfram_alpha(f"physics laws and constants of {subject}")
         synthesis_prompt = f"""
-        Act as Athena. Reveal the first principles of '{subject}' grounded in: {physics_fact}.
-        Style: Richard Feynman. Simple analogies, profound engineering.
+        Act as Athena. Analyze '{subject}' grounded in: {physics_fact}.
+        Style: Richard Feynman. Simple analogies, profound engineering truths.
         
         Tasks:
-        1. Search the web (ArXiv, Patents, Journals) for 3 diverse sources about {subject} via Google Search.
+        1. Search the web (ArXiv, Patents, Journals) for 3 diverse sources about {subject} using Google Search.
         2. Create 4 Discovery Layers (genesis, scientific_core, engineering_edge, cross_pollination).
-        3. For each research source, provide URL, Title, and a 2-sentence Feynman Summary.
+        3. For each research source, provide Title, URL, and a 2-sentence Feynman Summary.
         
         MANDATORY JSON SCHEMA (FLAT):
         {{
-            "title": "string",
-            "genesis": "string",
-            "scientific_core": "string",
-            "engineering_edge": "string",
-            "cross_pollination": "string",
+            "title": "Epic Title",
+            "genesis": "The origin/evolutionary logic.",
+            "scientific_core": "The first principles of physics.",
+            "engineering_edge": "Detailed stress/composition analysis.",
+            "cross_pollination": "Interdisciplinary application.",
             "scholar": [
-                {{"title": "string", "url": "string", "feynman_summary": "string"}}
+                {{"title": "Title", "url": "URL", "feynman_summary": "Summary"}}
             ]
         }}
         """
         
-        res = client.models.generate_content(
+        synth_res = client.models.generate_content(
             model=ATHENA_FLASH,
             contents=[synthesis_prompt, pil_image],
             config=types.GenerateContentConfig(
@@ -249,31 +277,33 @@ def generate_epiphany():
             )
         )
         
-        # --- DATA FLATTENING SENTINEL ---
-        raw_json = res.text.strip()
-        if "```json" in raw_json: raw_json = re.search(r'```json\n(.*?)\n```', raw_json, re.DOTALL).group(1)
+        # --- SCHEMA SENTINEL: Handle JSON Code Blocks & Lists ---
+        raw_json = synth_res.text.strip()
+        if "```json" in raw_json:
+            raw_json = re.search(r'```json\n(.*?)\n```', raw_json, re.DOTALL).group(1)
+        
         data = json.loads(raw_json)
         if isinstance(data, list): data = data[0]
-
-        # Handle nesting variations to prevent KeyErrors
+        
+        # Flatten any AI nesting (e.g. data['epiphany']['genesis'])
         if "epiphany" in data: data = data["epiphany"]
         elif "discovery_layers" in data: data = data["discovery_layers"]
 
-        # Ensure all required keys exist (Prevent 500 errors in threads)
-        required_keys = ['genesis', 'scientific_core', 'engineering_edge', 'cross_pollination']
-        for k in required_keys:
-            if k not in data: data[k] = f"First principles of the {k.replace('_', ' ')} are unfolding."
+        layers_list = ['genesis', 'scientific_core', 'engineering_edge', 'cross_pollination']
+        # Guard against missing keys
+        for k in layers_list:
+            if k not in data: data[k] = f"Analyzing first principles of {k.replace('_', ' ')}..."
 
         epiphany_id = str(uuid.uuid4())
 
-        # Step 3: Parallel Media (Titaness Execution)
+        # Step 3: PARALLEL TITANESS MEDIA ENGINE
+        logger.info(f"Step 3: Launching media threads for {epiphany_id}")
         audios = {}
         master_blueprint_url = None
         
         with ThreadPoolExecutor(max_workers=5) as executor:
-            # 4 Audio Threads
-            aud_futures = [executor.submit(generate_narration_task, data[l], uid, epiphany_id, l) for l in required_keys]
-            # 1 Master Blueprint Thread
+            # 4 Audio Threads + 1 Master Blueprint Thread
+            aud_futures = [executor.submit(generate_narration_task, data.get(l), uid, epiphany_id, l) for l in layers_list]
             blu_future = executor.submit(generate_master_blueprint_task, subject, data, uid, epiphany_id)
             
             for f in aud_futures: 
@@ -281,17 +311,17 @@ def generate_epiphany():
                 audios[k] = v
             master_blueprint_url = blu_future.result()
 
-        # Step 4: Storage & Record Persistence
-        image_url = upload_to_storage(image_bytes, f"users/{uid}/epiphanies/{epiphany_id}/original.jpg", 'image/jpeg')
+        # Step 4: Record Persistence
+        image_url = upload_to_storage(image_bytes, f"users/{uid}/epiphanies/{epiphany_id}/vision.jpg", 'image/jpeg')
         epiphany_record = {
             "epiphanyId": epiphany_id,
             "uid": uid,
-            "title": data.get('title', 'Universal Revelation'),
+            "title": data.get('title', f"Insight: {subject}"),
             "subject": subject,
             "imageURL": image_url,
             "masterBlueprint": master_blueprint_url,
             "layers": {
-                l: {"text": data[l], "audio": audios.get(l)} for l in required_keys
+                l: {"text": data.get(l, ""), "audio": audios.get(l)} for l in layers_list
             },
             "scholar": data.get('scholar', []),
             "createdAt": datetime.utcnow().isoformat()
@@ -304,34 +334,53 @@ def generate_epiphany():
         return jsonify(epiphany_record), 201
 
     except Exception as e:
-        logger.error(f"Global Epiphany Error: {e}\n{traceback.format_exc()}")
+        logger.error(f"Global Epiphany Gen Error: {e}\n{traceback.format_exc()}")
         return jsonify({'error': str(e)}), 500
 
 @app.route('/api/epiphany/theia', methods=['POST'])
 def theia_sweep():
-    """Independent Theia Mode: Bounding Boxes + Micro-Epiphanies via Code Execution."""
+    """Standalone Theia Mode: Bounding Box Annotations via Code Execution."""
+    logger.info(">>> THEIA SWEEP INITIATED")
     uid = verify_token(request.headers.get('Authorization'))
     if not uid: return jsonify({'error': 'Unauthorized'}), 401
+    
+    # 1. Defend against missing parameters (Fixed 400 logic)
+    epiphany_id = request.form.get('epiphanyId')
+    if not epiphany_id:
+        logger.error("Theia Sweep failed: epiphanyId missing from form.")
+        return jsonify({'error': 'epiphanyId is required.'}), 400
+
+    if 'image' not in request.files:
+        logger.error("Theia Sweep failed: Image file missing.")
+        return jsonify({'error': 'image file is required.'}), 400
 
+    # 2. Check Sparks
     user_ref = db_ref.child(f'users/{uid}')
-    if user_ref.get().get('credits', 0) < 4:
-        return jsonify({'error': 'Need 4 Sparks for Theia Sweep.'}), 402
+    user_data = user_ref.get() or {}
+    if user_data.get('credits', 0) < 4:
+        return jsonify({'error': 'Need 4 Sparks for a Theia Sweep.'}), 402
+
+    # 3. Fetch Context from the Epiphany
+    epiphany_context = db_ref.child(f'epiphanies/{epiphany_id}').get() or {}
+    subject = epiphany_context.get('subject', 'Complex System')
 
-    epiphany_id = request.form.get('epiphanyId')
     image_file = request.files['image']
+    image_bytes = image_file.read()
     
-    context = db_ref.child(f'epiphanies/{epiphany_id}').get() or {}
-    subject = context.get('subject', 'Complex System')
-
     sweep_prompt = f"""
-    Theia Mode Activation: {subject}. 
-    Use Python to spatially deconstruct this image. 
-    Identify every functional component. Return JSON list:
-    [ {{ "label": "string", "coordinates": [ymin, xmin, ymax, xmax], "micro_epiphany": "20-word Feynman summary" }} ]
+    Activate Theia Mode for: {subject}.
+    Using Python Code Execution, perform a spatial deconstruction of this image.
+    Identify every functional, biological, or structural component.
+    For each component detected, return a JSON object:
+    1. label: The name of the part.
+    2. coordinates: [ymin, xmin, ymax, xmax] (normalized 0-1000).
+    3. micro_epiphany: A 20-word Feynman-style secret about this part's role.
+    
+    Return a JSON LIST ONLY.
     """
 
     try:
-        pil_image = Image.open(io.BytesIO(image_file.read())).convert('RGB')
+        pil_image = Image.open(io.BytesIO(image_bytes)).convert('RGB')
         res = client.models.generate_content(
             model=ATHENA_FLASH,
             contents=[sweep_prompt, pil_image],
@@ -340,62 +389,97 @@ def theia_sweep():
                 response_mime_type='application/json'
             )
         )
+        
         raw_json = res.text.strip()
-        if "```json" in raw_json: raw_json = re.search(r'```json\n(.*?)\n```', raw_json, re.DOTALL).group(1)
+        if "```json" in raw_json:
+            raw_json = re.search(r'```json\n(.*?)\n```', raw_json, re.DOTALL).group(1)
+            
         annotations = json.loads(raw_json)
+        # Charge 4 sparks for Code Execution
+        user_ref.update({'credits': user_data.get('credits', 0) - 4})
         
-        user_ref.update({'credits': user_ref.get().get('credits', 0) - 4})
+        logger.info(f"THEIA SUCCESS: {len(annotations)} components annotated.")
         return jsonify({"annotations": annotations}), 200
     except Exception as e:
-        logger.error(f"Theia Error: {e}")
+        logger.error(f"Theia Sweep Engine Error: {e}")
         return jsonify({'error': str(e)}), 500
 
 @app.route('/api/epiphany/deep-dive', methods=['POST'])
 def deep_dive():
+    """Manual Zoom analysis (1 Spark)."""
     uid = verify_token(request.headers.get('Authorization'))
     if not uid: return jsonify({'error': 'Unauthorized'}), 401
-    image_file = request.files['image']
+    
+    if 'image' not in request.files: return jsonify({'error': 'No image'}), 400
+    
     try:
-        pil_image = Image.open(io.BytesIO(image_file.read())).convert('RGB')
+        pil_image = Image.open(io.BytesIO(request.files['image'].read())).convert('RGB')
         res = client.models.generate_content(
             model=ATHENA_FLASH,
-            contents=["Feynman style: Explain this zoomed-in detail in 50 words.", pil_image]
+            contents=["In 50 words Feynman style, reveal the hidden significance of this zoomed detail.", pil_image]
         )
-        db_ref.child(f'users/{uid}/credits').set(max(0, (db_ref.child(f'users/{uid}/credits').get() or 0) - 1))
+        # Deduct 1 spark
+        user_ref = db_ref.child(f'users/{uid}')
+        new_val = max(0, (user_ref.get().get('credits', 0) or 0) - 1)
+        user_ref.update({'credits': new_val})
+        
         return jsonify({"analysis": res.text.strip()}), 200
-    except Exception as e: return jsonify({'error': str(e)}), 500
+    except Exception as e:
+        return jsonify({'error': str(e)}), 500
 
 # -----------------------------------------------------------------------------
-# 5. CHIRON & SYSTEM TOOLS
+# 5. THE CHIRON MENTOR & SYSTEM UTILS
 # -----------------------------------------------------------------------------
 
 @app.route('/api/user/call-briefing', methods=['GET'])
 def get_chiron_briefing():
+    """Preps ElevenLabs Chiron with scientific context from the last Epiphany."""
     uid = verify_token(request.headers.get('Authorization'))
     if not uid: return jsonify({'error': 'Unauthorized'}), 401
+    
     try:
-        last = db_ref.child('epiphanies').order_by_child('uid').equal_to(uid).limit_to_last(1).get() or {}
-        ctx = "Exploring new frontiers."
-        if last:
-            e = list(last.values())[0]
-            ctx = f"Subject: {e['subject']}. Recent papers: {e.get('scholar', [])[:1]}"
-        prompt = f"Prep Chiron (Mentor). Context: {ctx}. 4-sentence brief for Socratic tutoring."
-        res = client.models.generate_content(model=ATHENA_FLASH, contents=[prompt])
+        # Fetch last epiphany for context
+        last_eps = db_ref.child('epiphanies').order_by_child('uid').equal_to(uid).limit_to_last(1).get() or {}
+        context_str = "Beginning an academic journey."
+        if last_eps:
+            eid = list(last_eps.keys())[0]
+            e = last_eps[eid]
+            scholar_sample = e.get('scholar', [])[:1]
+            context_str = f"Focus: {e['subject']}. Papers Analyzed: {scholar_sample[0]['title'] if scholar_sample else 'General'}"
+            
+        brief_prompt = f"Prep Chiron (Socratic Mentor). Context: {context_str}. Write a 4-sentence briefing for a voice call."
+        res = client.models.generate_content(model=ATHENA_FLASH, contents=[brief_prompt])
         return jsonify({"memory_summary": res.text.strip()}), 200
-    except Exception as e: return jsonify({'error': str(e)}), 500
+    except Exception as e:
+        return jsonify({'error': str(e)}), 500
 
 @app.route('/api/log-call-usage', methods=['POST'])
-def log_usage():
+def log_call_usage():
+    """Handles Spark deduction (3 per min) for ElevenLabs sessions."""
     uid = verify_token(request.headers.get('Authorization'))
     if not uid: return jsonify({'error': 'Unauthorized'}), 401
-    data = request.json
-    cost = math.ceil(data.get("durationSeconds", 0) / 60) * 3
-    user_ref = db_ref.child(f'users/{uid}')
-    new_bal = max(0, (user_ref.get().get('credits', 0) or 0) - cost)
-    user_ref.update({'credits': new_bal})
-    if data.get("transcript"):
-        db_ref.child(f'transcripts/{uid}').push({"text": data["transcript"], "at": datetime.utcnow().isoformat()})
-    return jsonify({"success": True, "remainingCredits": new_bal})
+    
+    data = request.get_json()
+    duration = data.get("durationSeconds", 0)
+    cost = math.ceil(duration / 60) * 3
+    
+    try:
+        user_ref = db_ref.child(f'users/{uid}')
+        current = user_ref.get().get('credits', 0)
+        new_bal = max(0, current - cost)
+        user_ref.update({'credits': new_bal})
+        
+        if data.get("transcript"):
+            db_ref.child(f'transcripts/{uid}').push({
+                "text": data["transcript"], "createdAt": datetime.utcnow().isoformat()
+            })
+        return jsonify({"success": True, "remainingCredits": new_bal}), 200
+    except Exception as e:
+        return jsonify({'error': str(e)}), 500
+
+# -----------------------------------------------------------------------------
+# 6. ADMIN & FEEDBACK
+# -----------------------------------------------------------------------------
 
 @app.route('/api/admin/dashboard', methods=['GET'])
 def admin_dashboard():
@@ -403,30 +487,36 @@ def admin_dashboard():
         verify_admin(request.headers.get('Authorization'))
         users = db_ref.child('users').get() or {}
         epiphanies = db_ref.child('epiphanies').get() or {}
-        requests = db_ref.child('credit_requests').get() or {}
+        credit_reqs = db_ref.child('credit_requests').get() or {}
         return jsonify({
-            "users": len(users),
-            "epiphanies": len(epiphanies),
-            "pending_spark_requests": len([r for r in requests.values() if r.get('status') == 'pending'])
-        })
-    except Exception as e: return jsonify({'error': str(e)}), 403
+            "total_users": len(users),
+            "total_epiphanies": len(epiphanies),
+            "pending_requests": len([r for r in credit_reqs.values() if r.get('status') == 'pending'])
+        }), 200
+    except Exception as e:
+        return jsonify({'error': str(e)}), 403
 
 @app.route('/api/feedback', methods=['POST'])
-def feedback():
+def submit_feedback():
     uid = verify_token(request.headers.get('Authorization'))
     if not uid: return jsonify({'error': 'Unauthorized'}), 401
-    db_ref.child('feedback').push({"uid": uid, "msg": request.json.get('message'), "at": datetime.utcnow().isoformat()})
-    return jsonify({"success": True})
+    data = request.json
+    db_ref.child('feedback').push({
+        "uid": uid, "message": data.get('message'), "at": datetime.utcnow().isoformat()
+    })
+    return jsonify({"success": True}), 201
 
 @app.route('/api/user/request-credits', methods=['POST'])
 def request_sparks():
     uid = verify_token(request.headers.get('Authorization'))
     if not uid: return jsonify({'error': 'Unauthorized'}), 401
-    db_ref.child('credit_requests').push({"uid": uid, "at": datetime.utcnow().isoformat(), "status": "pending"})
-    return jsonify({"success": True})
+    db_ref.child('credit_requests').push({
+        "uid": uid, "status": "pending", "at": datetime.utcnow().isoformat()
+    })
+    return jsonify({"success": True}), 201
 
 # -----------------------------------------------------------------------------
-# 6. AUTH & PROFILE
+# 7. AUTHENTICATION & USER PROFILE
 # -----------------------------------------------------------------------------
 
 @app.route('/api/auth/signup', methods=['POST'])
@@ -436,7 +526,10 @@ def signup():
     user_ref = db_ref.child(f'users/{uid}')
     if not user_ref.get():
         data = request.json
-        user_ref.set({'email': data.get('email'), 'displayName': data.get('displayName', 'Seeker'), 'credits': 30, 'is_admin': False, 'createdAt': datetime.utcnow().isoformat()})
+        user_ref.set({
+            'email': data.get('email'), 'displayName': data.get('displayName', 'Seeker'),
+            'credits': 30, 'is_admin': False, 'createdAt': datetime.utcnow().isoformat()
+        })
     return jsonify({'uid': uid, **user_ref.get()}), 201
 
 @app.route('/api/auth/social-signin', methods=['POST'])
@@ -444,13 +537,18 @@ def social_signin():
     uid = verify_token(request.headers.get('Authorization'))
     if not uid: return jsonify({'error': 'Unauthorized'}), 401
     user_ref = db_ref.child(f'users/{uid}')
-    if not user_ref.get():
+    u = user_ref.get()
+    if not u:
         fu = auth.get_user(uid)
-        user_ref.set({'email': fu.email, 'displayName': fu.display_name or 'Seeker', 'credits': 30, 'is_admin': False, 'createdAt': datetime.utcnow().isoformat()})
-    return jsonify({'uid': uid, **user_ref.get()}), 200
+        u = {
+            'email': fu.email, 'displayName': fu.display_name or 'Seeker',
+            'credits': 30, 'is_admin': False, 'createdAt': datetime.utcnow().isoformat()
+        }
+        user_ref.set(u)
+    return jsonify({'uid': uid, **u}), 200
 
 @app.route('/api/user/profile', methods=['GET'])
-def profile():
+def get_profile():
     uid = verify_token(request.headers.get('Authorization'))
     if not uid: return jsonify({'error': 'Unauthorized'}), 401
     return jsonify(db_ref.child(f'users/{uid}').get())
@@ -463,9 +561,9 @@ def list_epiphanies():
     return jsonify(list(res.values()))
 
 # -----------------------------------------------------------------------------
-# 7. MAIN EXECUTION
+# 8. MAIN EXECUTION
 # -----------------------------------------------------------------------------
 
 if __name__ == '__main__':
-    logger.info("Titaness Paradigm Paradigm Backbone Active on 7860...")
-    app.run(debug=False, host="0.0.0.0", port=7860)
+    logger.info("Titaness Definitive Backbone Active on port 7860...")
+    app.run(debug=False, host="0.0.0.0", port=int(os.environ.get("PORT", 7860)))