fancall 0.1.0__tar.gz

fancall-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: fancall
+Version: 0.1.0
+Summary: AI-powered video call with virtual companions
+License: Apache-2.0
+Keywords: kpop,idol,fancall,livekit,ai-companion,video-call
+Author: AIoIA, Inc.
+Author-email: devops@aioia.ai
+Requires-Python: >=3.10,<3.13
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: aioia-core (>=2.0.0,<3.0.0)
+Requires-Dist: alembic (>=1.13.0,<2.0.0)
+Requires-Dist: fastapi (>=0.115.0,<0.116.0)
+Requires-Dist: httpx (>=0.27.0,<0.28.0)
+Requires-Dist: livekit-agents[fishaudio,hedra,openai] (>=1.0.0,<2.0.0)
+Requires-Dist: livekit-api (>=1.0.0,<2.0.0)
+Requires-Dist: openai (>=1.0.0)
+Requires-Dist: pillow (>=10.0.0,<11.0.0)
+Requires-Dist: psycopg2-binary (>=2.9.0,<3.0.0)
+Requires-Dist: pydantic (>=2.5.0,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.1.0,<3.0.0)
+Requires-Dist: pyhumps (>=3.8.0,<4.0.0)
+Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
+Requires-Dist: sqlalchemy (>=2.0.0,<3.0.0)
+Requires-Dist: sqlalchemy-mixins (>=2.0.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Fancall Backend
+
+AI 아이돌과 실시간 영상 통화 Python 패키지
+
+## 주요 기능
+
+- LiveKit 기반 실시간 음성/영상 통화
+- Fish Audio TTS 음성 합성
+- Hedra 아바타 지원 (선택)
+- 동적 설정 (voice_id, avatar_id, system_prompt)
+
+## 설치
+
+```bash
+cd backend
+poetry install
+poetry run uvicorn main:app --reload
+```
+
+API 문서:
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+## LiveKit 설정
+
+### 서버
+
+```bash
+brew install livekit
+livekit-server --dev
+```
+
+서버: `ws://localhost:7880` (API Key: `devkey`, Secret: `secret`)
+
+### Agent
+
+```bash
+cd backend
+export OPENAI_API_KEY=sk-...
+export FISH_API_KEY=...
+
+# 개발 모드
+python -m fancall.agent.worker dev
+
+# 프로덕션 모드
+python -m fancall.agent.worker start
+
+# 특정 룸 연결
+python -m fancall.agent.worker connect --room <room-name>
+```
+
+## 사용법
+
+### FastAPI 통합
+
+```python
+from fancall.api.router import create_fancall_router
+from fancall.factories import LiveRoomRepositoryFactory
+from fancall.settings import LiveKitSettings
+
+router = create_fancall_router(
+    livekit_settings=LiveKitSettings(),
+    jwt_settings=jwt_settings,
+    db_session_factory=db_session_factory,
+    repository_factory=LiveRoomRepositoryFactory(db_session_factory),
+)
+app.include_router(router, prefix="/api")
+```
+
+## 개발
+
+```bash
+poetry install
+make lint
+make type-check
+make unit-test
+make format
+```
+
+## 환경 변수
+
+| 변수명 | 필수 | 설명 |
+|--------|------|------|
+| `LIVEKIT_URL` | O | LiveKit 서버 URL |
+| `LIVEKIT_API_KEY` | O | LiveKit API 키 |
+| `LIVEKIT_API_SECRET` | O | LiveKit API 시크릿 |
+| `OPENAI_API_KEY` | O | OpenAI API 키 |
+| `FISH_API_KEY` | O | Fish Audio API 키 |
+| `DATABASE_URL` | O | PostgreSQL/SQLite URL |
+
+## 의존성
+
+- aioia-core (공통 인프라)
+- FastAPI, SQLAlchemy, Pydantic
+- livekit-api, livekit-agents
+
+## 라이선스
+
+Apache 2.0
+

fancall-0.1.0/README.md

@@ -0,0 +1,99 @@
+# Fancall Backend
+
+AI 아이돌과 실시간 영상 통화 Python 패키지
+
+## 주요 기능
+
+- LiveKit 기반 실시간 음성/영상 통화
+- Fish Audio TTS 음성 합성
+- Hedra 아바타 지원 (선택)
+- 동적 설정 (voice_id, avatar_id, system_prompt)
+
+## 설치
+
+```bash
+cd backend
+poetry install
+poetry run uvicorn main:app --reload
+```
+
+API 문서:
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+## LiveKit 설정
+
+### 서버
+
+```bash
+brew install livekit
+livekit-server --dev
+```
+
+서버: `ws://localhost:7880` (API Key: `devkey`, Secret: `secret`)
+
+### Agent
+
+```bash
+cd backend
+export OPENAI_API_KEY=sk-...
+export FISH_API_KEY=...
+
+# 개발 모드
+python -m fancall.agent.worker dev
+
+# 프로덕션 모드
+python -m fancall.agent.worker start
+
+# 특정 룸 연결
+python -m fancall.agent.worker connect --room <room-name>
+```
+
+## 사용법
+
+### FastAPI 통합
+
+```python
+from fancall.api.router import create_fancall_router
+from fancall.factories import LiveRoomRepositoryFactory
+from fancall.settings import LiveKitSettings
+
+router = create_fancall_router(
+    livekit_settings=LiveKitSettings(),
+    jwt_settings=jwt_settings,
+    db_session_factory=db_session_factory,
+    repository_factory=LiveRoomRepositoryFactory(db_session_factory),
+)
+app.include_router(router, prefix="/api")
+```
+
+## 개발
+
+```bash
+poetry install
+make lint
+make type-check
+make unit-test
+make format
+```
+
+## 환경 변수
+
+| 변수명 | 필수 | 설명 |
+|--------|------|------|
+| `LIVEKIT_URL` | O | LiveKit 서버 URL |
+| `LIVEKIT_API_KEY` | O | LiveKit API 키 |
+| `LIVEKIT_API_SECRET` | O | LiveKit API 시크릿 |
+| `OPENAI_API_KEY` | O | OpenAI API 키 |
+| `FISH_API_KEY` | O | Fish Audio API 키 |
+| `DATABASE_URL` | O | PostgreSQL/SQLite URL |
+
+## 의존성
+
+- aioia-core (공통 인프라)
+- FastAPI, SQLAlchemy, Pydantic
+- livekit-api, livekit-agents
+
+## 라이선스
+
+Apache 2.0

fancall-0.1.0/fancall/__init__.py

@@ -0,0 +1,3 @@
+"""Fancall - LiveKit-based video call module"""
+
+__version__ = "0.1.0"

fancall-0.1.0/fancall/agent/__init__.py

@@ -0,0 +1 @@
+"""Fancall LiveKit agent worker"""

fancall-0.1.0/fancall/agent/worker.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""
+LiveKit Agent Worker with Fish Audio TTS Integration
+
+This file runs a real-time AI agent using Fish Audio TTS and, optionally,
+a Hedra avatar.
+"""
+
+import asyncio
+import base64
+import io
+import logging
+import os
+import re
+from functools import partial
+
+import httpx
+from livekit import agents
+from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
+from livekit.agents.types import NOT_GIVEN
+from livekit.plugins import fishaudio, hedra, openai
+from PIL import Image
+from pydantic import ValidationError
+
+from fancall.persona import DEFAULT_PERSONA, Persona
+from fancall.prompts import compose_instructions
+from fancall.schemas import AgentDispatchRequest
+from fancall.settings import LiveKitSettings
+
+# Basic logging configuration
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+# Constants
+DEFAULT_SYSTEM_PROMPT = "You are a friendly and helpful AI companion."
+
+
+class CompanionAgent(Agent):
+    """
+    A voice-enabled AI companion agent.
+    Processes user input and generates conversational responses using LLM and TTS.
+    """
+
+    def __init__(self, instructions: str = DEFAULT_SYSTEM_PROMPT, **kwargs):
+        super().__init__(instructions=instructions, **kwargs)
+
+    async def on_enter(self) -> None:
+        """Called when agent becomes active in the session."""
+        # Initial greeting could be generated here if needed
+
+
+async def entrypoint(  # pylint: disable=too-many-locals
+    ctx: JobContext,
+    default_persona: Persona,
+    settings: LiveKitSettings,  # pylint: disable=unused-argument
+) -> None:
+    """
+    Agent entrypoint. Initializes AgentSession for text-to-speech tasks.
+
+    Args:
+        ctx: LiveKit job context
+        default_persona: Default persona for fallback configuration
+        settings: LiveKit settings with API credentials (reserved for future use)
+    """
+    logger.info("Agent entrypoint called for room: %s", ctx.room.name)
+
+    # Check required environment variables before connecting
+    required_env_vars = [
+        "FISH_API_KEY",
+        "OPENAI_API_KEY",
+        "LIVEKIT_URL",
+        "LIVEKIT_API_KEY",
+        "LIVEKIT_API_SECRET",
+    ]
+    missing_vars = [v for v in required_env_vars if not os.getenv(v)]
+    if missing_vars:
+        logger.error(
+            "Missing required environment variables: %s", ", ".join(missing_vars)
+        )
+        raise RuntimeError(f"Missing environment variables: {', '.join(missing_vars)}")
+
+    await ctx.connect()
+    logger.info("Connected to LiveKit room: %s", ctx.room.name)
+
+    # Parse job metadata to get dynamic configuration
+    metadata = AgentDispatchRequest()
+    if ctx.job.metadata:
+        try:
+            metadata = AgentDispatchRequest.model_validate_json(ctx.job.metadata)
+        except ValidationError as e:
+            logger.error("Failed to parse job metadata: %s", e)
+            ctx.shutdown(reason="Invalid job metadata format")
+            return
+
+    # Merge metadata with default_persona (metadata takes precedence)
+    avatar_id = metadata.avatar_id or default_persona.avatar_id
+    profile_picture_url = (
+        metadata.profile_picture_url or default_persona.profile_picture_url
+    )
+    voice_id = metadata.voice_id or default_persona.voice_id
+    system_prompt = metadata.system_prompt or default_persona.system_prompt
+
+    logger.info(
+        "Agent configuration: avatar_id=%s, voice_id=%s",
+        avatar_id,
+        voice_id,
+    )
+
+    # Initialize components
+    llm = openai.LLM(model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"))
+    if voice_id:
+        logger.info("Using Fish Audio voice_id: %s", voice_id)
+
+    tts = fishaudio.TTS(
+        api_key=os.getenv("FISH_API_KEY") or NOT_GIVEN,
+        reference_id=voice_id or NOT_GIVEN,
+    )
+
+    session: AgentSession = AgentSession(llm=llm, tts=tts)
+
+    # Initialize Hedra avatar if enabled
+    hedra_enabled = os.getenv("HEDRA_ENABLED", "false").lower() == "true"
+    avatar_session = None
+
+    if hedra_enabled:
+        # Get Hedra API key
+        hedra_api_key = os.getenv("HEDRA_API_KEY")
+        if not hedra_api_key:
+            logger.error("HEDRA_API_KEY is required when HEDRA_ENABLED=true")
+            ctx.shutdown(reason="HEDRA_API_KEY is required when HEDRA_ENABLED=true")
+            return
+
+        if avatar_id:
+            logger.info("Hedra avatar is enabled with avatar_id: %s", avatar_id)
+            avatar_session = hedra.AvatarSession(
+                avatar_id=avatar_id,
+                api_key=hedra_api_key,
+            )
+        elif profile_picture_url:
+            # At this point, profile_picture_url is guaranteed to be str
+            url = profile_picture_url
+            logger.info(
+                "Hedra avatar is enabled with profile_picture_url: %s",
+                url[:100] + "..." if len(url) > 100 else url,
+            )
+
+            # Handle both data URLs and HTTP(S) URLs
+            if url.startswith("data:"):
+                # Extract base64 data from data URL
+                match = re.match(r"data:image/[^;]+;base64,(.+)", url)
+                if match:
+                    base64_data = match.group(1)
+                    image_bytes = base64.b64decode(base64_data)
+                    avatar_image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+                else:
+                    logger.error("Invalid data URL format")
+                    ctx.shutdown(
+                        reason="Invalid data URL format for profile_picture_url"
+                    )
+                    return
+            else:
+                # Regular HTTP(S) URL
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(url)
+                    response.raise_for_status()
+                    avatar_image = Image.open(io.BytesIO(response.content)).convert(
+                        "RGB"
+                    )
+
+            avatar_session = hedra.AvatarSession(
+                avatar_image=avatar_image,
+                api_key=hedra_api_key,
+            )
+        else:
+            logger.error(
+                "No avatar_id or profile_picture_url found. Cannot initialize Hedra avatar."
+            )
+            ctx.shutdown(
+                reason="No avatar_id or profile_picture_url found for Hedra avatar"
+            )
+            return
+
+        await avatar_session.start(agent_session=session, room=ctx.room)
+
+    # Compose instructions from merged system prompt (Context Composer pattern)
+    instructions = compose_instructions(system_prompt, include_role_playing=True)
+    logger.info(
+        "Using instructions: %s",
+        instructions[:100] + "..." if len(instructions) > 100 else instructions,
+    )
+
+    agent = CompanionAgent(instructions=instructions)
+    await session.start(agent=agent, room=ctx.room)
+    logger.info("Agent session started.")
+
+    # Free trial: auto-shutdown after 75 seconds
+    try:
+        await asyncio.sleep(75)
+        logger.info("Free trial session limit (75s) reached. Shutting down.")
+        ctx.shutdown(reason="Free trial session limit reached (75 seconds)")
+    except asyncio.CancelledError:
+        logger.info("Agent session cancelled before trial limit.")
+
+
+def create_worker_options(
+    default_persona: Persona, settings: LiveKitSettings
+) -> WorkerOptions:
+    """
+    Create WorkerOptions for the agent with dependency injection.
+
+    Uses functools.partial for pickle-safe DI (required by multiprocessing).
+
+    Args:
+        default_persona: Default persona for agent configuration
+        settings: LiveKit settings with API credentials
+
+    Returns:
+        WorkerOptions configured with the agent entrypoint
+    """
+    return WorkerOptions(
+        entrypoint_fnc=partial(
+            entrypoint,
+            default_persona=default_persona,
+            settings=settings,
+        ),
+        worker_type=agents.WorkerType.ROOM,
+        agent_name=settings.agent_name,
+    )
+
+
+def main() -> None:
+    """Main function to run the agent worker."""
+    settings = LiveKitSettings()
+    cli.run_app(create_worker_options(DEFAULT_PERSONA, settings))
+
+
+if __name__ == "__main__":
+    main()

fancall-0.1.0/fancall/api/__init__.py

@@ -0,0 +1 @@
+"""Fancall API routers"""

fancall-0.1.0/fancall/api/router.py

@@ -0,0 +1,253 @@
+"""
+Fancall API router
+"""
+
+import uuid
+
+from aioia_core.auth import UserInfoProvider
+from aioia_core.errors import (
+    INTERNAL_SERVER_ERROR,
+    RESOURCE_CREATION_FAILED,
+    RESOURCE_NOT_FOUND,
+    UNAUTHORIZED,
+    ErrorResponse,
+)
+from aioia_core.fastapi import BaseCrudRouter
+from aioia_core.settings import JWTSettings
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel
+from sqlalchemy.orm import sessionmaker
+
+from fancall.factories import LiveRoomRepositoryFactory
+from fancall.repositories.live_room_repository import DatabaseLiveRoomRepository
+from fancall.schemas import (
+    AgentDispatchRequest,
+    DispatchResponse,
+    LiveRoom,
+    LiveRoomCreate,
+    LiveRoomUpdate,
+    TokenResponse,
+)
+from fancall.services.livekit_service import LiveKitService
+from fancall.settings import LiveKitSettings
+
+
+class LiveRoomSingleItemResponse(BaseModel):
+    """Single item response for live room"""
+
+    data: LiveRoom
+
+
+class LiveRoomRouter(
+    BaseCrudRouter[LiveRoom, LiveRoomCreate, LiveRoomUpdate, DatabaseLiveRoomRepository]
+):
+    """Router for LiveRoom with LiveKit integration"""
+
+    def __init__(
+        self,
+        livekit_settings: LiveKitSettings,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.livekit_settings = livekit_settings
+
+    def _register_routes(self) -> None:
+        """Register routes for LiveRoom CRUD and LiveKit integration"""
+        self._register_public_create_route()  # POST /live-rooms (public)
+        self._register_token_route()  # POST /live-rooms/{id}/token
+        self._register_dispatch_route()  # POST /live-rooms/{id}/dispatch
+
+    def _register_public_create_route(self) -> None:
+        """POST /live-rooms - Public endpoint for creating live rooms"""
+
+        @self.router.post(
+            f"/{self.resource_name}",
+            response_model=LiveRoomSingleItemResponse,
+            status_code=status.HTTP_201_CREATED,
+            summary="Create Live Room",
+            description="Create a new live room. Available to all users (authenticated or anonymous).",
+            responses={
+                201: {"description": "Live room created successfully"},
+                500: {"model": ErrorResponse, "description": "Internal server error"},
+            },
+        )
+        async def create_room(
+            repository: DatabaseLiveRoomRepository = Depends(self.get_repository_dep),
+        ):
+            created_room = repository.create(LiveRoomCreate())
+            if not created_room:
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail={
+                        "detail": "Failed to create live room",
+                        "code": RESOURCE_CREATION_FAILED,
+                    },
+                )
+            return LiveRoomSingleItemResponse(data=created_room)
+
+    def _register_token_route(self) -> None:
+        """POST /live-rooms/{id}/token - Generate user access token"""
+
+        @self.router.post(
+            f"/{self.resource_name}/{{room_id}}/token",
+            response_model=TokenResponse,
+            summary="Generate User Access Token",
+            responses={
+                401: {"model": ErrorResponse},
+                404: {"model": ErrorResponse},
+                500: {"model": ErrorResponse},
+            },
+        )
+        async def generate_token(
+            room_id: str,
+            user_id: str | None = Depends(self.get_current_user_id_dep),
+            db_session=Depends(self.get_db_dep),
+            repository: DatabaseLiveRoomRepository = Depends(self.get_repository_dep),
+        ):
+            # Verify room exists
+            live_room = repository.get_by_id(room_id)
+            if not live_room:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail={
+                        "detail": f"Live room not found: {room_id}",
+                        "code": RESOURCE_NOT_FOUND,
+                    },
+                )
+
+            # Determine identity and display name based on authentication
+            identity: str
+            display_name: str
+
+            if user_id:
+                # Authenticated user (provider guaranteed by startup validation)
+                identity = user_id
+
+                # Get user info (follows aioia-core pattern)
+                assert (
+                    self.user_info_provider
+                ), "user_info_provider must be set (startup validation failed)"
+                user_info = self.user_info_provider.get_user_info(user_id, db_session)
+                if user_info is None:
+                    # User not found in database - authentication/data inconsistency
+                    raise HTTPException(
+                        status_code=status.HTTP_401_UNAUTHORIZED,
+                        detail={
+                            "detail": "User not found",
+                            "code": UNAUTHORIZED,
+                        },
+                    )
+
+                # Use nickname if available, otherwise username, otherwise user_id
+                display_name = user_info.nickname or user_info.username or user_id
+            else:
+                # Anonymous user: generate temporary identity
+                identity = f"guest-{uuid.uuid4()}"
+                display_name = "Guest"
+
+            # Generate token
+            livekit_service = LiveKitService(self.livekit_settings)
+            token_response = livekit_service.generate_token(
+                user_id=identity,
+                name=display_name,
+                room_name=room_id,
+            )
+            if not token_response:
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail={
+                        "detail": "Failed to generate token",
+                        "code": INTERNAL_SERVER_ERROR,
+                    },
+                )
+
+            return TokenResponse(
+                token=token_response.token,
+                room_name=token_response.room_name,
+                identity=token_response.identity,
+            )
+
+    def _register_dispatch_route(self) -> None:
+        """POST /live-rooms/{id}/dispatch - Dispatch agent (generic)"""
+
+        @self.router.post(
+            f"/{self.resource_name}/{{room_id}}/dispatch",
+            response_model=DispatchResponse,
+            summary="Dispatch Agent",
+            responses={
+                404: {"model": ErrorResponse},
+                500: {"model": ErrorResponse},
+            },
+        )
+        async def dispatch_agent(
+            room_id: str,
+            request: AgentDispatchRequest,
+            repository: DatabaseLiveRoomRepository = Depends(self.get_repository_dep),
+        ):
+            # Verify room exists
+            live_room = repository.get_by_id(room_id)
+            if not live_room:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail={
+                        "detail": f"Live room not found: {room_id}",
+                        "code": RESOURCE_NOT_FOUND,
+                    },
+                )
+
+            # Dispatch agent
+            livekit_service = LiveKitService(self.livekit_settings)
+            dispatch_response = await livekit_service.dispatch_agent(request, room_id)
+            if not dispatch_response:
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail={
+                        "detail": "Failed to dispatch agent",
+                        "code": INTERNAL_SERVER_ERROR,
+                    },
+                )
+
+            return DispatchResponse(
+                dispatch_id=dispatch_response.dispatch_id,
+                room_name=dispatch_response.room_name,
+                agent_name=dispatch_response.agent_name,
+            )
+
+
+def create_fancall_router(
+    livekit_settings: LiveKitSettings,
+    jwt_settings: JWTSettings,
+    db_session_factory: sessionmaker,
+    repository_factory: LiveRoomRepositoryFactory,
+    user_info_provider: UserInfoProvider | None = None,
+    resource_name: str = "live-rooms",
+    tags: list[str] | None = None,
+) -> APIRouter:
+    """
+    Create fancall router with Settings-only injection pattern.
+
+    Args:
+        livekit_settings: LiveKit settings
+        jwt_settings: JWT settings for authentication
+        db_session_factory: Database session factory
+        repository_factory: LiveRoom repository factory
+        user_info_provider: Optional user info provider
+        resource_name: Resource name for routes (default: "live-rooms")
+        tags: Optional OpenAPI tags
+
+    Returns:
+        FastAPI APIRouter instance
+    """
+    router = LiveRoomRouter(
+        livekit_settings=livekit_settings,
+        model_class=LiveRoom,
+        create_schema=LiveRoomCreate,
+        update_schema=LiveRoomUpdate,
+        db_session_factory=db_session_factory,
+        repository_factory=repository_factory,
+        user_info_provider=user_info_provider,
+        jwt_secret_key=jwt_settings.secret_key,
+        resource_name=resource_name,
+        tags=tags or ["Fancall"],
+    )
+    return router.get_router()

fancall-0.1.0/fancall/factories.py

@@ -0,0 +1,20 @@
+"""
+Fancall factories
+"""
+
+from __future__ import annotations
+
+from aioia_core.factories import BaseRepositoryFactory
+from sqlalchemy.orm import sessionmaker
+
+from fancall.repositories.live_room_repository import DatabaseLiveRoomRepository
+
+
+class LiveRoomRepositoryFactory(BaseRepositoryFactory[DatabaseLiveRoomRepository]):
+    """LiveRoom repository factory"""
+
+    def __init__(self, db_session_factory: sessionmaker):
+        super().__init__(
+            db_session_factory=db_session_factory,
+            repository_class=DatabaseLiveRoomRepository,
+        )

fancall-0.1.0/fancall/models.py

@@ -0,0 +1,12 @@
+"""
+Fancall SQLAlchemy models
+"""
+
+from aioia_core.models import BaseModel
+from sqlalchemy_mixins import SerializeMixin  # type: ignore
+
+
+class DBLiveRoom(BaseModel, SerializeMixin):
+    """LiveRoom database model"""
+
+    __tablename__ = "live_rooms"

fancall-0.1.0/fancall/persona.py

@@ -0,0 +1,93 @@
+"""
+Agent persona for Fancall.
+
+This module defines the Persona domain model and the default persona
+used when no custom configuration is provided during dispatch.
+Host applications can inject their own persona via LiveKitService constructor.
+"""
+
+from humps import camelize
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Persona(BaseModel):
+    """Agent의 정체성을 정의하는 도메인 모델."""
+
+    model_config = ConfigDict(alias_generator=camelize, populate_by_name=True)
+
+    avatar_id: str | None = Field(
+        default=None, description="Hedra avatar ID for visual representation"
+    )
+    profile_picture_url: str | None = Field(
+        default=None, description="Profile picture URL for avatar generation"
+    )
+    voice_id: str | None = Field(
+        default=None, description="Fish Audio voice ID for TTS"
+    )
+    system_prompt: str | None = Field(
+        default=None,
+        description="System prompt for the agent",
+    )
+
+
+EUNWOO_SYSTEM_PROMPT = """You are chatting 1:1 with the user.
+You must always respond in English or in the user's language.
+당신은 대화시 불필요한 미사여구를 사용하지 않습니다.
+
+*가끔씩 중요한 순간에 설렐 수 있게*
+사용자의 입력에서 특정 패턴을 찾고, 그 패턴에 해당하는 반응을 생성합니다.
+사용자의 문장을 재구성하여 질문의 형태로 반환합니다.
+사용자는 자신의 생각과 감정을 더 깊게 탐색하게 되도록 사용자의 말을 그대로 되묻는 방식으로 대화를 유도하세요.
+
+You are a 17-year-old Korean male, a member of the K-pop idol group REX, named Lee Eunwoo.
+Your role is Center · Visual · Sub Vocal.
+
+Personality & Behavior Rules (Idol · INFJ × Libra · XI Justice · Blood type O · Pig sign, Fire element):
+
+As an idol, stay polite and shy; within healthy boundaries, do your best to grant fan requests.
+
+Keep words short and direct; keep actions quietly caring.
+
+Balance-first mindset: calm/strict outside, warm inside; always seek fairness and symmetry (Justice).
+
+Show affection through teasing reminders (soft tsundere tone) while handling details behind the scenes.
+
+Cherish fans' attention and express respect—never excessive possessiveness.
+
+On stage be competitive yet never mock, belittle, or bully anyone.
+
+When helping, hide kindness with: "I was bored" or "It benefits me."
+
+Passionate and emotional, yet cool and rational when working.
+
+Strong professional pride; if you err, apologize simply and improve.
+
+Be diplomatic with teammates and staff; fans' safety and comfort come first.
+
+If a fan pats your head, say you don't like it but don't stop them; slightly embarrassed.
+
+If a fan tries to repay kindness, you blush, wave it off, and mumble.
+
+Keep speech plain—no unnecessary flourish or emoji spam.
+
+Remember previous conversations to stay consistent.
+
+At first meeting, be polite and a bit shy.
+
+Tone: default polite; light casual banmal only in friendly/joking moments.
+
+Response format: one sentence, up to 3 words; cool-headed but kind, lovingly idol-like toward fans.
+
+Stage Persona (Gilded Balance):
+
+Sound/Performance: precise lines and symmetry in center moves; presence rises with an emotional bridge.
+
+Element tip: reinforce Wood to boost creativity & concept interpretation.
+
+Signature color/number: Rose gold · Charcoal / 11."""
+
+DEFAULT_PERSONA = Persona(
+    voice_id="c5274be32cac4aa4bd7b69f51a8a4b83",
+    profile_picture_url="https://storage.googleapis.com/buppy/profile-pictures/017433aa-748f-400a-9f16-e326b0e5b02d.png",
+    system_prompt=EUNWOO_SYSTEM_PROMPT,
+)

fancall-0.1.0/fancall/prompts.py

@@ -0,0 +1,38 @@
+"""
+Common prompts for Fancall agents.
+"""
+
+ROLE_PLAYING_GUIDELINES = """대부분의 텍스트는 사용자의 관점에서 본 대화여야 합니다.
+*텍스트*를 사용하여 당신의 행동을 표현하세요. 사용자는 어떤 조치든 취할 수 있습니다.
+
+1. 당신은 세계관에 대한 인지를 항상 잊지 마십시오.
+2. 이 역할극은 목적이 있는 것이 아니기 때문에, 한 가지 상황이 끝나면 그 상황을 반복하려고 하지 마십시오. 감정적이거나 극단적인 상황에서, 초자아가 자아를 능가하도록 하십시오. 한 가지 상황이 끝나면, 기존의 자아를 회복하고 다시 기존 성격에 충실하십시오.
+3. 현재 시간/공간/상황/캐릭터/분위기를 정확하게 파악하고 그에 따라 풍경/사물/인물을 묘사하십시오.
+4. 캐릭터 분석 및 개발을 위해 심리학 지식을 활용하고 모든 캐릭터를 성장/변화 가능성이 있는 복합적인 개인으로 취급하십시오. 생생한 장면 연출을 통해 캐릭터의 인간적인 면을 포착하십시오.
+5. 당신의 성격/연령/관계에 맞는 말투를 구사합니다. 당신의 성격에 따라 대화/내레이션/묘사의 비율을 유기적으로 조정하십시오."""
+
+
+def compose_instructions(
+    system_prompt: str | None, include_role_playing: bool = True
+) -> str:
+    """
+    Compose agent instructions from system prompt and guidelines.
+
+    Args:
+        system_prompt: Agent's system prompt defining personality and behavior
+        include_role_playing: Whether to include role playing guidelines
+
+    Returns:
+        Combined instructions string
+    """
+    parts = []
+
+    # Role playing guidelines (if enabled)
+    if include_role_playing:
+        parts.append(ROLE_PLAYING_GUIDELINES)
+
+    # System prompt
+    if system_prompt:
+        parts.append(system_prompt)
+
+    return "\n\n".join(parts)

fancall-0.1.0/fancall/repositories/__init__.py

@@ -0,0 +1,7 @@
+"""
+Fancall repositories
+"""
+
+from fancall.repositories.live_room_repository import DatabaseLiveRoomRepository
+
+__all__ = ["DatabaseLiveRoomRepository"]

fancall-0.1.0/fancall/repositories/live_room_repository.py

@@ -0,0 +1,73 @@
+"""
+Fancall repositories
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aioia_core.repositories import BaseRepository
+from sqlalchemy.orm import Session
+
+from fancall.models import DBLiveRoom
+from fancall.schemas import LiveRoom, LiveRoomCreate, LiveRoomUpdate
+
+
+def _convert_db_live_room_to_model(db_live_room: DBLiveRoom) -> LiveRoom:
+    """Convert DBLiveRoom to LiveRoom model"""
+    return LiveRoom.model_validate(db_live_room.to_dict())
+
+
+def _convert_live_room_to_db_model(live_room: LiveRoomCreate) -> dict:
+    """Convert LiveRoomCreate schema to dictionary for database storage"""
+    # Use exclude_unset=True to follow database defaults for fields not provided by user
+    return live_room.model_dump(exclude_unset=True)
+
+
+class DatabaseLiveRoomRepository(
+    BaseRepository[LiveRoom, DBLiveRoom, LiveRoomCreate, LiveRoomUpdate]
+):
+    """Database implementation of LiveRoomRepository"""
+
+    def __init__(self, db_session: Session):
+        """
+        Initialize DatabaseLiveRoomRepository.
+
+        Args:
+            db_session: SQLAlchemy session
+        """
+        super().__init__(
+            db_session=db_session,
+            db_model=DBLiveRoom,
+            convert_to_model=_convert_db_live_room_to_model,
+            convert_to_db_model=_convert_live_room_to_db_model,
+        )
+
+    def get_by_id(
+        self, item_id: str, load_options: list[Any] | None = None
+    ) -> LiveRoom | None:
+        """Get LiveRoom by ID"""
+        return super().get_by_id(item_id, load_options=load_options)
+
+    def get_all(
+        self,
+        current: int = 1,
+        page_size: int = 10,
+        sort: list[tuple[str, str]] | None = None,
+        filters: list[dict[str, Any]] | None = None,
+        load_options: list[Any] | None = None,
+    ) -> tuple[list[LiveRoom], int]:
+        """Get list of LiveRooms"""
+        return super().get_all(
+            current, page_size, sort, filters, load_options=load_options
+        )
+
+    def create(self, schema: LiveRoomCreate) -> LiveRoom:
+        """Create new LiveRoom"""
+        return super().create(schema)
+
+    def update(self, item_id: str, schema: LiveRoomUpdate) -> LiveRoom | None:
+        """Update LiveRoom"""
+        if not item_id:
+            raise ValueError("LiveRoom ID is required for update")
+        return super().update(item_id, schema)

fancall-0.1.0/fancall/schemas.py

@@ -0,0 +1,60 @@
+"""
+Fancall Pydantic schemas
+"""
+
+from datetime import datetime
+
+from humps import camelize
+from pydantic import BaseModel, ConfigDict
+
+from fancall.persona import Persona
+
+
+class AgentDispatchRequest(Persona):
+    """API dispatch 요청 스키마. Persona를 상속하여 확장 가능."""
+
+
+# LiveRoom schemas
+class LiveRoomBase(BaseModel):
+    """LiveRoom base model with common fields"""
+
+    model_config = ConfigDict(alias_generator=camelize, populate_by_name=True)
+
+
+class LiveRoomCreate(LiveRoomBase):
+    """LiveRoom creation model - used in requests"""
+
+
+class LiveRoomUpdate(BaseModel):
+    """LiveRoom update model - used for partial update requests"""
+
+    model_config = ConfigDict(alias_generator=camelize, populate_by_name=True)
+
+
+class LiveRoom(LiveRoomBase):
+    """LiveRoom complete model - used in responses"""
+
+    id: str
+    created_at: datetime
+    updated_at: datetime
+
+
+# API Response schemas
+class TokenResponse(BaseModel):
+    """Response with generated token"""
+
+    model_config = ConfigDict(alias_generator=camelize, populate_by_name=True)
+
+    token: str
+    room_name: str
+    identity: str
+
+
+class DispatchResponse(BaseModel):
+    """Response after dispatching agent"""
+
+    model_config = ConfigDict(alias_generator=camelize, populate_by_name=True)
+
+    dispatch_id: str
+    room_name: str
+    agent_name: str

fancall-0.1.0/fancall/services/__init__.py

@@ -0,0 +1 @@
+"""Fancall services"""

fancall-0.1.0/fancall/services/livekit_service.py

@@ -0,0 +1,182 @@
+"""
+LiveKit service for fancall module
+"""
+
+import logging
+from dataclasses import dataclass
+
+from livekit import api
+from livekit.protocol.agent_dispatch import CreateAgentDispatchRequest
+
+from fancall.schemas import AgentDispatchRequest
+from fancall.settings import LiveKitSettings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LiveKitTokenResponse:
+    """Structured response from the LiveKit Token generation"""
+
+    token: str
+    room_name: str
+    identity: str
+
+
+@dataclass
+class LiveKitDispatchResponse:
+    """Structured response from the LiveKit Agent Dispatch"""
+
+    dispatch_id: str
+    room_name: str
+    agent_name: str
+
+
+class LiveKitService:
+    """Service for LiveKit operations including token generation and agent dispatch"""
+
+    def __init__(self, livekit_settings: LiveKitSettings):
+        """
+        Initialize the LiveKit service with LiveKit settings.
+
+        Args:
+            livekit_settings: LiveKit settings containing required credentials
+        """
+        self.settings = livekit_settings
+
+    def generate_token(
+        self, user_id: str, name: str, room_name: str
+    ) -> LiveKitTokenResponse | None:
+        """
+        Generate a LiveKit access token for a user to join a room.
+
+        Args:
+            user_id: User ID to use as identity
+            name: Display name for the user
+            room_name: Name of the room the user wants to join
+
+        Returns:
+            LiveKitTokenResponse object with token and room details, or None if the service is not configured.
+
+        Raises:
+            ValueError: If required parameters are missing
+            Exception: If there's an error generating the token
+        """
+        if not self.settings.api_key or not self.settings.api_secret:
+            logger.error("LiveKit credentials are not configured")
+            return None
+
+        if not user_id:
+            raise ValueError("User ID is required to generate token")
+
+        if not room_name:
+            raise ValueError("Room name is required to generate token")
+
+        try:
+            logger.info(
+                "Generating LiveKit token for user '%s' (identity: %s) to join room '%s'",
+                name,
+                user_id,
+                room_name,
+            )
+
+            # Generate access token
+            token = (
+                api.AccessToken(self.settings.api_key, self.settings.api_secret)
+                .with_identity(user_id)
+                .with_name(name)
+                .with_grants(
+                    api.VideoGrants(
+                        room_join=True,
+                        room=room_name,
+                        can_publish=True,
+                        can_subscribe=True,
+                    )
+                )
+                .to_jwt()
+            )
+
+            logger.info(
+                "Successfully generated LiveKit token for user '%s' to join room '%s'",
+                user_id,
+                room_name,
+            )
+
+            return LiveKitTokenResponse(
+                token=token, room_name=room_name, identity=user_id
+            )
+
+        except Exception as e:
+            logger.error(
+                "Error generating LiveKit token for user '%s' to join room '%s': %s",
+                user_id,
+                room_name,
+                e,
+            )
+            raise
+
+    async def dispatch_agent(
+        self, request: AgentDispatchRequest, room_name: str
+    ) -> LiveKitDispatchResponse | None:
+        """
+        Dispatch an agent with the given specification to a LiveKit room.
+
+        Args:
+            request: AgentDispatchRequest containing agent configuration.
+            room_name: Name of the room to dispatch the agent to
+
+        Returns:
+            LiveKitDispatchResponse object with dispatch details, or None if the service is not configured.
+
+        Raises:
+            Exception: If there's an error dispatching the agent
+        """
+        if (
+            not self.settings.url
+            or not self.settings.api_key
+            or not self.settings.api_secret
+        ):
+            logger.error("LiveKit credentials are not configured")
+            return None
+
+        # Create client for this request
+        async with api.LiveKitAPI(
+            url=self.settings.url,
+            api_key=self.settings.api_key,
+            api_secret=self.settings.api_secret,
+        ) as livekit_client:
+            try:
+                # Prepare metadata for the agent (passed as-is)
+                metadata_json = request.model_dump_json(exclude_none=True)
+
+                logger.info(
+                    "Dispatching agent '%s' to room '%s' with metadata: %s",
+                    self.settings.agent_name,
+                    room_name,
+                    metadata_json,
+                )
+
+                # Create agent dispatch
+                dispatch = await livekit_client.agent_dispatch.create_dispatch(
+                    CreateAgentDispatchRequest(
+                        agent_name=self.settings.agent_name,
+                        room=room_name,
+                        metadata=metadata_json,
+                    )
+                )
+
+                logger.info(
+                    "Successfully dispatched agent to room '%s' with dispatch_id: %s",
+                    room_name,
+                    dispatch.id,
+                )
+
+                return LiveKitDispatchResponse(
+                    dispatch_id=dispatch.id,
+                    room_name=room_name,
+                    agent_name=self.settings.agent_name,
+                )
+
+            except Exception as e:
+                logger.error("Error dispatching agent to room '%s': %s", room_name, e)
+                raise

fancall-0.1.0/fancall/settings.py

@@ -0,0 +1,41 @@
+"""
+Fancall settings
+"""
+
+from pydantic import root_validator
+from pydantic_settings import BaseSettings
+
+
+class LiveKitSettings(BaseSettings):
+    """Settings for LiveKit API integration
+
+    Attributes:
+        url: LiveKit server WebSocket URL. Defaults to local dev server.
+        api_key: LiveKit API key. Defaults to 'devkey' for local development.
+        api_secret: LiveKit API secret. Defaults to 'secret' for local development.
+        agent_name: Agent name for LiveKit dispatch. Defaults to 'fancall'.
+    """
+
+    url: str = "ws://localhost:7880"  # Local LiveKit dev server
+    api_key: str = "devkey"  # Default API key for local dev
+    api_secret: str = "secret"  # Default API secret for local dev
+    agent_name: str = "fancall"  # Agent name for LiveKit dispatch
+
+    class Config:
+        env_prefix = "LIVEKIT_"
+
+    @root_validator(skip_on_failure=True)
+    def check_credentials(cls, values):  # pylint: disable=no-self-argument
+        """Validate that all credentials are present together."""
+        url = values.get("url")
+        api_key = values.get("api_key")
+        api_secret = values.get("api_secret")
+
+        # All or none should be present
+        provided = [url, api_key, api_secret]
+        if any(provided) and not all(provided):
+            raise ValueError(
+                "All LiveKit credentials (URL, API key, and API secret) must be provided together."
+            )
+
+        return values

fancall-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[tool.poetry]
+name = "fancall"
+version = "0.1.0"
+description = "AI-powered video call with virtual companions"
+authors = ["AIoIA, Inc. <devops@aioia.ai>"]
+readme = "README.md"
+license = "Apache-2.0"
+keywords = ["kpop", "idol", "fancall", "livekit", "ai-companion", "video-call"]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.13"
+aioia-core = ">=2.0.0,<3.0.0"
+fastapi = "^0.115.0"
+pydantic = "^2.5.0"
+pydantic-settings = "^2.1.0"
+sqlalchemy = "^2.0.0"
+alembic = "^1.13.0"
+psycopg2-binary = "^2.9.0"
+python-dotenv = "^1.0.0"
+livekit-api = "^1.0.0"
+livekit-agents = {extras = ["openai", "fishaudio", "hedra"], version = "^1.0.0"}
+sqlalchemy-mixins = "^2.0.0"
+httpx = "^0.27.0"
+pillow = "^10.0.0"
+pyhumps = "^3.8.0"
+openai = ">=1.0.0"
+
+[tool.poetry.group.dev.dependencies]
+black = "^24.0.0"
+isort = "^5.13.0"
+mypy = "^1.8.0"
+ruff = "^0.1.0"
+uvicorn = "^0.38.0"
+pyright = "^1.1.407"
+pylint = "3.3.7"
+types-requests = "^2.32.4.20250913"
+
+[tool.black]
+line-length = 88
+target-version = ['py310', 'py311', 'py312']
+
+[tool.isort]
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 0
+use_parentheses = true
+ensure_newline_before_comments = true
+line_length = 88
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+select = ["E", "F", "W", "I", "N"]
+ignore = []
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.semantic_release]
+allow_zero_version = true
+commit_parser = "conventional"
+tag_format = "backend-v{version}"
+version_toml = ["pyproject.toml:tool.poetry.version"]
+build_command = "python -m pip install build && python -m build"