WiraHati

Project Details Project Name: WiraHati Overview: WiraHati is an AI-powered emotional reflection designed to bridge the gap between human vulnerability and cinematic storytelling. When users are feeling overwhelmed, burnt out, or lost, articulating those feelings can be difficult. WiraHati acts as a non-clinical, empathetic listener. It takes unstructured emotional messages (like venting about a hard day at work) and uses Google's Gemini models to decode the underlying psychological narrative. Instead of offering generic advice or medical diagnoses, WiraHati translates the user's emotional state into a specific "Cinematic Narrative Pattern" (e.g., Struggle to Perseverance) and dynamically generates a curated YouTube search link for movie scenes that mirror their current emotional journey. It provides users with a moment of reflection, validation, and hope through the power of film.
Technical Explanation Architecture Flow:
Client Request: A frontend application sends a raw user message via a POST request to the Cloud Run /analyze endpoint.
AI Processing: The Flask backend securely forwards the message to Vertex AI (Gemini 2.5 Flash), utilizing strict JSON schema enforcement to map the raw text into predefined emotional categories.
Dynamic Routing: The Python backend parses the AI's structured output, extracts specific scene_tags and the narrative_pattern, and dynamically constructs a URL-encoded YouTube search query.
Unified Response: The API returns a perfectly structured, frontend-friendly JSON envelope containing the user's emotional profile, a supportive display message, and the actionable YouTube link. Tech Stack: ● Language: Python 3.12 ● Framework: Flask (API routing) + Gunicorn (Production WSGI server) ● AI Backend: Google Cloud Vertex AI SDK (gemini-2.5-flash) ● Infrastructure: Google Cloud Run (Serverless compute for auto-scaling and zero downtime) ● Containerization: Docker (Dockerfile build) ● Security: Google Cloud IAM (Service Account authentication, meaning no API keys are hardcoded or exposed).
Prompt Design & Engineering Our prompt engineering strategy focused on three core pillars: Safety, Determinism, and Structure. Because this API drives frontend UI components, we could not rely on standard conversational LLM outputs.
Persona and Strict Guardrails: We began by defining WiraHati's exact boundaries in the SYSTEM_INSTRUCTION. We explicitly instructed the model: "This is NOT therapy, diagnosis, or treatment. Do not diagnose mental illness." If a user inputs a severe crisis, the prompt safely degrades to gentle, non-clinical emotional labels without overstepping ethical boundaries.
Enforced JSON Schema (Structured Outputs): Instead of just asking the prompt to "return JSON," we deeply integrated Vertex AI's response_schema parameter. We defined the exact shape of the object we needed, ensuring the backend would never crash due to a JSONDecodeError or a missing key.
Enum-Driven Emotion Mapping: To ensure our cinematic recommendation engine worked flawlessly, we stripped the AI of its ability to "invent" emotions. We used Enum Constraints in the schema: ● primary_emotion was strictly limited to 8 options (e.g., discouragement, burnout). ● narrative_pattern was limited to 9 cinematic arcs (e.g., isolation_to_connection, fear_to_courage). By forcing the LLM to categorize the user's free-text input into our exact enumerated lists, we turned an unpredictable LLM into a highly deterministic classification engine.
Parameter Tuning: We set the model's temperature to 0.2. While high temperatures are great for creative writing, our use case required strict adherence to the schema and precise analytical mapping of the user's text. A lower temperature guaranteed the model prioritized logical accuracy and system instructions over creative hallucinations.