examples for 1.0

examples/full_examples/dentist-scheduler/README.md

@@ -0,0 +1,90 @@
+# :tooth: Building a Dentist Scheduler Assistant
+Build an AI-powered dentist assistant that manages appointments, takes messages, and answers inquiries
+
+This example integrates the Cal.com and Supabase APIs with LiveKit and exhibits the functionality of a multi-agent framework. To curate a complete assistant, this recipe includes a Recepionist, Scheduler, and Messenger.
+
+# Prerequisites
+For this example, you need to create an VoiceAgent using the [Voice Agent quickstart](https://docs.livekit.io/agents/quickstarts/voice-agent/).
+
+### Setting up the Cal API
+You need to [create an account](https://app.cal.com/signup) and enroll in a plan. The `.env.local` file should have your API key and Cal.com username:
+```
+CAL_API_KEY="<cal_api_key>"
+CAL_API_USERNAME="<cal_api_username>"
+```
+
+We'll set up the details for this example for you in-house upon running the agent, this includes the schedule and necessary event types.
+
+### Setting up Supabase
+1. [Create an account](https://supabase.com/dashboard/sign-up) and a new project for this example. 
+2. After configuring your RLS settings (SELECT and INSERT policies for this example), create a table in the public schema. 
+
+    Your table should have these text columns: `name`, `message`, and `phone_number`. You can optionally add a datetime column that     automatically records the time the message was received.
+
+    Here is what your table should look like:
+    | date | name | message | phone_number |
+    | ---- | ---- | ------- | ------------ |
+
+
+3. Add your project API key and URL into the `.env.local` file:
+```
+SUPABASE_API_KEY="<supabase_api_key>"
+SUPABASE_URL="<supabase_project_url>"
+```
+
+# Storing data across agents
+Agents can access shared data through `VoiceAgent.userdata`. You can store information about the user, tasks, and API information. 
+
+In this example, we create `UserInfo` to store user information:
+```
+@dataclass
+class UserInfo:
+    name: str | None = None
+    email: str | None = None
+    phone: str | None = None
+    message: str | None = None
+```
+
+We also use `Agents` as an agents bank for smooth transfers:
+```
+@dataclass
+class Agents:
+    @property
+    def receptionist(self) -> Agent:
+        return Receptionist()
+
+    @property
+    def messenger(self) -> Agent:
+        return Messenger()
+
+    def scheduler(self, service: str) -> Agent:
+        return Scheduler(service=service)
+
+```
+
+
+This example stores event IDs from setting up the Cal API, an instance of `UserInfo`, and an instance of `Agents()`. Modify `VoiceAgent`'s arguments to include `userdata`:
+```
+userdata = {"event_ids": event_ids, "userinfo": UserInfo(), "agents": Agents()}
+    agent = VoiceAgent(
+        task=Receptionist(),
+        userdata=userdata,
+        stt=deepgram.STT(),
+        llm=openai.LLM(),
+        tts=cartesia.TTS(),
+        vad=silero.VAD.load(),
+    )
+```
+
+# Running the example
+After setting up the environment, run `python dental_agent.py dev` to meet the Receptionist.
+
+Try out:
+- Scheduling a new appointment 
+- Asking about the office hours and location
+- Leaving a message for the office
+- Transferring between agents
+
+
+
+

examples/full_examples/dentist-scheduler/api_setup.py

@@ -0,0 +1,148 @@
+import os
+
+import aiohttp
+from dotenv import load_dotenv
+
+load_dotenv()
+
+HEADERS = {
+    "cal-api-version": "2024-06-14",
+    "Authorization": "Bearer " + os.getenv("CAL_API_KEY"),
+}
+
+SESSION_LENGTH = 60
+
+
+async def get_event_id(slug: str) -> str | None:
+    """Searches for an event type. Returns the event ID if found, None if not
+
+    Args:
+        slug (str): The unique identifier of the event type
+    """
+    payload = {"username": os.getenv("CAL_API_USERNAME"), "eventSlug": slug}
+    async with aiohttp.ClientSession() as session:
+        async with session.get(
+            "https://api.cal.com/v2/event-types", params=payload, headers=HEADERS
+        ) as response:
+            response = await response.json()
+            if response["status"] == "success" and response["data"]:
+                return response["data"][0]["id"]
+            if response["status"] == "error":
+                raise Exception("Error retrieving event type")
+            else:
+                return None
+
+
+async def search_schedule(name: str) -> str | None:
+    """Checks if needed schedule already exists, returns schedule ID"""
+    async with aiohttp.ClientSession() as session:
+        async with session.get(
+            "https://api.cal.com/v2/schedules/default", headers=HEADERS
+        ) as response:
+            response = await response.json()
+            if (
+                response["status"] == "success"
+                and response["data"]
+                and response["data"]["name"] == name
+            ):
+                return response["data"]["id"]
+            else:
+                return None
+
+
+async def create_schedule() -> str:
+    """Sets schedule for example, returns schedule ID"""
+    payload = {
+        "name": "LiveKit Dental Office Hours",
+        "timeZone": "America/Los_Angeles",
+        "isDefault": True,
+        "availability": [
+            {
+                "days": [
+                    "Monday",
+                    "Tuesday",
+                    "Wednesday",
+                    "Thursday",
+                    "Friday",
+                    "Saturday",
+                ],
+                "startTime": "10:00",
+                "endTime": "12:00",
+            },
+            {
+                "days": [
+                    "Monday",
+                    "Tuesday",
+                    "Wednesday",
+                    "Thursday",
+                    "Friday",
+                    "Saturday",
+                ],
+                "startTime": "13:00",
+                "endTime": "16:00",
+            },
+        ],
+    }
+    async with aiohttp.ClientSession() as session:
+        async with session.post(
+            "https://api.cal.com/v2/schedules", json=payload, headers=HEADERS
+        ) as response:
+            response = await response.json()
+            if response["status"] == "success" and response["data"]:
+                return response["data"]["id"]
+            if response["status"] == "error":
+                raise Exception(f"Error creating schedule: {response}")
+
+
+async def create_event_type(*, title: str, slug: str, schedule_id: str) -> str:
+    """Creates specified event type and returns the event ID
+
+    Args:
+        title (str): The title of the event type
+        slug (str): The unique identifier of the event type, typically with dashes instead of spaces
+    """
+    payload = {
+        "lengthInMinutes": SESSION_LENGTH,
+        "title": title,
+        "slug": slug,
+        "scheduleId": schedule_id,
+    }
+    async with aiohttp.ClientSession() as session:
+        async with session.post(
+            "https://api.cal.com/v2/event-types", json=payload, headers=HEADERS
+        ) as response:
+            response = await response.json()
+            if response["status"] == "success":
+                return response["data"]["id"]
+            else:
+                raise Exception(f"{response['error']['code']}")
+
+
+async def setup_event_types() -> dict:
+    """Ensures that the schedule and event types are set up correctly in Cal.com for this example.
+    Returns a dictionary with event slugs and their respective IDs
+    """
+
+    schedule_id = await search_schedule("LiveKit Dental Office Hours")
+    if not schedule_id:
+        schedule_id = await create_schedule()
+
+    event_ids = {}
+
+    checkup_event_id = await get_event_id("routine-checkup")
+    if not checkup_event_id:
+        checkup_event_id = await create_event_type(
+            title="Routine Checkup", slug="routine-checkup", schedule_id=schedule_id
+        )
+
+    event_ids["routine-checkup"] = checkup_event_id
+
+    extraction_event_id = await get_event_id("tooth-extraction")
+    if not extraction_event_id:
+        extraction_event_id = await create_event_type(
+            title="Tooth Extraction", slug="tooth-extraction", schedule_id=schedule_id
+        )
+
+    event_ids["tooth-extraction"] = extraction_event_id
+
+    return event_ids

examples/full_examples/dentist-scheduler/dental_agent.py

@@ -0,0 +1,62 @@
+import logging
+from dataclasses import dataclass
+
+from api_setup import setup_event_types
+from dotenv import load_dotenv
+from pydantic import BaseModel
+from tasks import Messenger, Receptionist, Scheduler
+
+from livekit.agents import (
+    JobContext,
+    WorkerOptions,
+    cli,
+)
+from livekit.agents.voice import Agent, AgentSession
+from livekit.plugins import cartesia, deepgram, openai, silero
+
+
+class UserInfo(BaseModel):
+    name: str | None = None
+    email: str | None = None
+    phone: str | None = None
+    message: str | None = None
+
+
+@dataclass
+class Agents:
+    @property
+    def receptionist(self) -> Agent:
+        return Receptionist()
+
+    @property
+    def messenger(self) -> Agent:
+        return Messenger()
+
+    def scheduler(self, service: str) -> Agent:
+        return Scheduler(service=service)
+
+
+load_dotenv()
+
+logger = logging.getLogger("dental-scheduler")
+logger.setLevel(logging.INFO)
+
+
+async def entrypoint(ctx: JobContext):
+    event_ids = await setup_event_types()
+    userdata = {"event_ids": event_ids, "userinfo": UserInfo(), "agents": Agents()}
+
+    session = AgentSession(
+        userdata=userdata,
+        stt=deepgram.STT(),
+        llm=openai.LLM(),
+        tts=cartesia.TTS(),
+        vad=silero.VAD.load(),
+    )
+
+    await ctx.connect()
+    await session.start(agent=userdata["agents"].receptionist, room=ctx.room)
+
+
+if __name__ == "__main__":
+    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))