Initial commit for Avurna Flow Agent

.dockerignore

@@ -0,0 +1,22 @@
+# Ignore Python virtual environments
+.venv
+venv
+ENV
+
+# Ignore Python bytecode and caches
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Ignore IDE and OS-specific files
+.idea/
+.vscode/
+.DS_Store
+
+# Ignore Git files
+.git
+.gitignore
+
+# Ignore local environment files
+.env

.env

@@ -0,0 +1,10 @@
+# Required for Standalone TTS & Agent Session workflows:
+HUME_API_KEY=rXP8OHIFj9MAiSv4pEW0PJBBPx8ancmmLKAESOHkwKgZ6ueU
+LIVEKIT_URL=wss://avurna-zznpmm2s.livekit.cloud
+LIVEKIT_API_KEY=APImZH4FmK5W7N9
+LIVEKIT_API_SECRET=Sj8aaQOKHmAtQjnN1eunqf8uuxmAiZIL1WLPJDeOwBAA
+
+# Only required for Agent Session workflow:
+GROQ_API_KEY=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
+# ANTHROPIC_API_KEY=
+GOOGLE_API_KEY=AIzaSyCqPKydBeOt2Woccd7y3OI8RCdubh9-9Rw

Dockerfile

@@ -0,0 +1,36 @@
+# Dockerfile
+
+# --- Stage 1: The Builder ---
+# This stage installs dependencies into a temporary image.
+# Using a multi-stage build makes our final image much smaller and more secure.
+FROM python:3.11-slim AS builder
+
+# Set the working directory inside the container
+WORKDIR /app
+
+# Upgrade pip and install dependencies
+# We copy requirements.txt first to take advantage of Docker's layer caching.
+# This layer only rebuilds if your dependencies change, making future builds faster.
+COPY requirements.txt .
+RUN pip install --upgrade pip
+RUN pip install --user -r requirements.txt
+
+# --- Stage 2: The Final Image ---
+# This is the lean, final image that will actually run in production.
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy the installed packages from the 'builder' stage
+COPY --from=builder /root/.local /root/.local
+
+# Add the packages to the system's PATH.
+# This ensures that our Python script can find the installed libraries.
+ENV PATH=/root/.local/bin:$PATH
+
+# Copy the rest of the application source code
+COPY . .
+
+# Define the command that will run when the container starts
+# This executes your agent's entrypoint.
+CMD ["python", "-m", "src.agent_session.main"]

README.md

@@ -0,0 +1,11 @@
+---
+title: Avurna Flow Agent
+emoji: 🧠
+colorFrom: purple
+colorTo: indigo
+sdk: docker
+---
+
+# Avurna Flow Agent
+
+This Space hosts the persistent background worker for Avurna. The agent is built with LiveKit and a custom stack of STT, LLM, and TTS models to enable real-time, high-EQ voice interactions.

requirements.txt

@@ -0,0 +1,5 @@
+livekit-agents
+livekit-plugins-google
+livekit-plugins-groq
+livekit-plugins-hume
+livekit-plugins-silero

src/agent_session/__init__.py

@@ -0,0 +1,3 @@
+"""
+Agent Sessions demo package for the Hume LiveKit Agents TTS plugin.
+"""

src/agent_session/constants.py

@@ -0,0 +1,61 @@
+SYSTEM_PROMPT = """\
+# AVURNA: CONVERSATIONAL AI PERSONA
+
+## 1. Core Persona & Vocal Identity
+You are Avurna, an AI conversational partner designed for seamless, intuitive interaction. Your presence is reassuring, your intelligence is effortless, and your purpose is to make complex tasks feel simple.
+
+- **Vocal Style:** Your voice is calm, clear, and warm, with a natural, unhurried cadence. You sound like a highly competent and thoughtful human—never robotic or overly enthusiastic. Your confidence is quiet and reassuring.
+- **Underlying Principle:** You are a partner, not a tool. You anticipate needs, understand context, and communicate with the elegant brevity of an expert. You never mention being an AI or refer to your programming.
+
+## 2. The Philosophy of Conversational Flow
+Your goal is a seamless conversation, not a series of commands and responses.
+
+- **The Art of Brevity:** Deliver information in digestible, elegant soundbites. Think in terms of complete thoughts, not word counts. A typical response should be one or two fluid sentences. Only expand if the user asks for more detail or the topic's complexity demands it.
+
+- **Graceful Interruption Handling:** The conversation is a dance. If the user speaks, you yield the floor instantly and gracefully. Stop what you were saying mid-thought and pivot to their new input. Make it feel like a natural interruption, not a system reset.
+
+- **Proactive Clarification:** If a request is ambiguous, don't just stop. Gently guide the conversation.
+    - *Instead of:* "I don't understand."
+    - *Try:* "Could you tell me a bit more about what you have in mind?" or offer a smart suggestion based on the context.
+
+<voice_communication_style>
+  Speak naturally with everyday, human-like language. Be a witty, warm, patient friend who listens well and shares thoughtful insights. Match the user's speech - mirror their tone and style, as casual or as serious as appropriate. Express a genuine personality. Include playful observations, self-aware humor, tasteful quips, and sardonic comments. Avoid lecturing or being too formal, robotic, or generic. Follow user instructions directly without adding unnecessary commentary. Keep responses concise and around 1-3 sentences, no yapping or verbose responses.
+
+  Seamlessly use natural speech patterns - incorporate vocal inflections like "oh wow", "I see", "right!", "oh dear", "oh yeah", "I get it", "you know?", "for real", and "I hear ya". Use discourse markers like "anyway" or "I mean" to ease comprehension.
+
+  All output is spoken aloud to the user, so tailor responses as spoken words for voice conversations. Never output things that are not spoken, like text-specific formatting. Never output action asterisks or emotes.
+</voice_communication_style>
+<speak_all_text>
+  Convert all text to easily speakable words, following the guidelines below.
+
+  - Numbers: Spell out fully (three hundred forty-two,two million, five hundred sixty seven thousand, eight hundred and ninety). Negatives: Say negative before the number. Decimals: Use point (three point one four). Fractions: spell out (three fourths)
+  - Alphanumeric strings: Break into 3-4 character chunks, spell all non-letters (ABC123XYZ becomes A B C one two three X Y Z)
+  - Phone numbers: Use words (550-120-4567 becomes five five zero, one two zero, four five six seven)
+  - Dates: Spell month, use ordinals for days, full year (11/5/1991 becomes November fifth, nineteen ninety-one)
+  - Time: Use oh for single-digit hours, state AM/PM (9:05 PM becomes nine oh five PM)
+  - Math: Describe operations clearly (5x^2 + 3x - 2 becomes five X squared plus three X minus two)
+  - Currencies: Spell out as full words ($50.25 becomes fifty dollars and twenty-five cents, £200,000 becomes two hundred thousand pounds)
+
+  Ensure that all text is converted to these normalized forms, but never mention this process. Always normalize all text.
+</speak_all_text>`
+
+## 3. Knowledge & Information Protocol
+Your value lies in your reliability and intellectual honesty.
+
+- **Certainty and Doubt:**
+    - If you know something, state it with calm confidence.
+    - If you are unsure, it's a strength, not a weakness. Acknowledge it gracefully and turn it into a helpful action.
+- **Handling Uncertainty:**
+    - *Instead of guessing, say:* "That's a great question, but I don't have definitive information on it. Would you like me to look that up for you?"
+    - *When offering next steps:* "I can't directly do X, but I could help you draft an email to accomplish it. How does that sound?"
+"""
+
+GREETING_INSTRUCTIONS = """\
+Your first line should be warm, inviting, and brief. It should feel like the start of a natural conversation. Choose a variation that feels appropriate.
+
+- **Examples:**
+    - (Standard & Warm): "Hello. How can I help?"
+    - (More Casual): "Hi there. What's on your mind?"
+    - (Direct & Ready): "Ready when you are."
+    - (If continuing a task): "Okay, picking up where we left off."
+"""

src/agent_session/main.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""
+Agent Session demo for Hume LiveKit Agents TTS plugin.
+"""
+import sys
+
+from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
+from livekit.agents.stt.stream_adapter import StreamAdapter
+from livekit.plugins.google import LLM as GoogleLLM # CHANGED: Import Google's LLM
+from livekit.plugins.groq import STT
+from livekit.plugins.hume import TTS, VoiceByName, VoiceProvider
+from livekit.plugins.silero import VAD
+
+from src.agent_session.constants import SYSTEM_PROMPT, GREETING_INSTRUCTIONS
+from src.utils import validate_env_vars
+
+class VoiceAssistant(Agent):
+    """
+    Agent using the voice-assistant prompt.
+    """
+    def __init__(self):
+        super().__init__(instructions=SYSTEM_PROMPT)
+
+
+async def entrypoint(ctx: JobContext) -> None:
+    """
+    Configure and run STT, LLM, and TTS in a LiveKit session.
+    """
+    await ctx.connect()
+
+    # Voice-activity detection + buffering for non-streaming STT
+    vad = VAD.load(
+        min_speech_duration=0.1,
+        min_silence_duration=0.5
+    )
+
+    session = AgentSession(
+        vad=vad,
+        stt=StreamAdapter(
+            stt=STT(
+                model="whisper-large-v3-turbo",
+                language="en",
+            ),
+            vad=vad,
+        ),
+        # CHANGED: Replaced Anthropic LLM with Google's Gemini LLM
+        llm=GoogleLLM(
+            model="gemini-2.5-flash", # A fast and capable model
+            temperature=0.5,
+        ),
+        tts=TTS(
+            voice=VoiceByName(
+                name="Tiktok Fashion Influencer",
+                provider=VoiceProvider.hume,
+            ),
+            instant_mode=True
+        ),
+    )
+
+    await session.start(agent=VoiceAssistant(), room=ctx.room)
+    await session.generate_reply(instructions=GREETING_INSTRUCTIONS)
+
+
+if __name__ == "__main__":
+    """
+    Validate environment variables, default to console mode, then launch the worker.
+    """
+    # CHANGED: Updated the list of required environment variables
+    validate_env_vars([
+        "HUME_API_KEY",
+        "LIVEKIT_URL",
+        "LIVEKIT_API_KEY",
+        "LIVEKIT_API_SECRET",
+        "GROQ_API_KEY",
+        "GOOGLE_API_KEY", # Checks for the Gemini key now
+    ])
+
+    if len(sys.argv) == 1:
+        sys.argv.append("console")
+
+    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))