py-aidol 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

aidol/providers/llm/base.py

@@ -0,0 +1,147 @@
+"""LLM Provider Protocol for AIdol.
+
+This module defines the LLMProvider Protocol for platform-agnostic LLM integration.
+Implementations can use any LLM SDK (LangChain, LiteLLM, direct API calls, etc.).
+Uses LangChain message types for type safety in the interface.
+"""
+
+# pylint: disable=unnecessary-ellipsis,redundant-returns-doc
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol
+
+import litellm
+from langchain_core.messages import BaseMessage
+
+from aidol.schemas import ModelSettings
+
+
+def lookup_context_window(model_name: str) -> int:
+    """Look up the total context window for a given model using LiteLLM's model_cost.
+
+    In LiteLLM's model_cost structure:
+    - 'max_input_tokens': Total context window size (input + output combined)
+    - 'max_tokens'/'max_output_tokens': Maximum output tokens only
+
+    Returns the value of 'max_input_tokens' which represents the total context window.
+    Raises ValueError if not found.
+    """
+    if model_name in litellm.model_cost:
+        model_info = litellm.model_cost[model_name]
+        if "max_input_tokens" in model_info:
+            return model_info["max_input_tokens"]
+    raise ValueError(
+        f"Context window for model '{model_name}' not found in LiteLLM model_cost."
+    )
+
+
+class ProviderConstraints(Protocol):
+    """Protocol for provider constraints used in context building.
+
+    Defines only the constraint properties needed by MessageContextBuilder.
+    This minimal interface allows integrators to pass their existing provider
+    implementations without implementing the full LLMProvider interface.
+    """
+
+    @property
+    def require_first_user_message(self) -> bool:
+        """Whether the provider requires first message to be from user."""
+        ...
+
+    @property
+    def combine_system_messages(self) -> bool:
+        """Whether multiple system messages should be combined into one."""
+        ...
+
+    @property
+    def enforce_alternating_turns(self) -> bool:
+        """Whether messages must alternate between user and assistant."""
+        ...
+
+
+class LLMProvider(ProviderConstraints, Protocol):
+    """Protocol for LLM providers.
+
+    Extends ProviderConstraints with full LLM functionality.
+    Defines the interface for LLM integration in AIdol.
+    Implementations are free to use any underlying SDK.
+
+    Example implementations:
+    - LangChain wrapper (for LangChain-based integrators)
+    - LiteLLM direct calls (for standalone aidol)
+    - Direct API calls (for custom integrations)
+
+    Uses LangChain message types for type safety in the interface.
+    """
+
+    @property
+    def require_first_user_message(self) -> bool:
+        """Whether the provider requires first message to be from user.
+
+        Anthropic: True (Claude requires user message first)
+        OpenAI: False (GPT accepts system-only conversations)
+        """
+        ...
+
+    @property
+    def combine_system_messages(self) -> bool:
+        """Whether multiple system messages should be combined into one.
+
+        Anthropic: True (Claude prefers single system message)
+        OpenAI: False (GPT handles multiple system messages)
+        """
+        ...
+
+    @property
+    def enforce_alternating_turns(self) -> bool:
+        """Whether messages must alternate between user and assistant.
+
+        Anthropic: True (Claude requires strict alternation)
+        OpenAI: False (GPT allows consecutive same-role messages)
+        """
+        ...
+
+    def completion(
+        self,
+        model_settings: ModelSettings,
+        messages: Sequence[BaseMessage],
+        response_format: dict[str, str] | None = None,
+    ) -> str:
+        """Generate completion from messages.
+
+        Args:
+            model_settings: Model configuration (model name, temperature, etc.)
+            messages: LangChain messages (BaseMessage).
+            response_format: Optional response format specification.
+                Example: {"type": "json_object"}
+                Note: Not all providers support this (e.g., Anthropic ignores it).
+
+        Returns:
+            Generated text response.
+
+        Raises:
+            Implementation-specific exceptions propagate to caller.
+        """
+        ...
+
+    def get_context_size(self, model_name: str) -> int:
+        """Get the maximum total context window size for the given model.
+
+        The context window represents the total number of tokens that can be used
+        for both input messages and model output combined in a single API call.
+        This is NOT the maximum output tokens alone.
+
+        This value is used by the application to:
+        1. Check if input messages exceed the available token limit
+        2. Reserve tokens for model output (completion)
+        3. Truncate old messages when the context becomes too large
+
+        Args:
+            model_name: Model identifier (e.g., 'gpt-4o', 'claude-3-opus-20240229')
+
+        Returns:
+            Maximum total context window size in tokens (input + output combined).
+        """
+        ...

aidol/providers/llm/openai.py

@@ -0,0 +1,101 @@
+"""OpenAI LLM Provider for AIdol standalone.
+
+Default provider implementation using LangChain ChatOpenAI.
+Uses aioia-core OpenAIAPISettings for configuration.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from aioia_core.settings import OpenAIAPISettings
+from langchain_core.messages import BaseMessage
+from langchain_openai import ChatOpenAI
+
+from aidol.providers.llm.base import lookup_context_window
+from aidol.schemas import ModelSettings
+
+
+class OpenAILLMProvider:
+    """OpenAI LLM Provider using LangChain.
+
+    Default implementation for AIdol standalone apps.
+    Uses aioia-core OpenAIAPISettings for explicit API key injection.
+
+    Constraint properties:
+    - require_first_user_message: False (OpenAI accepts system-only)
+    - combine_system_messages: False (OpenAI handles multiple system messages)
+    - enforce_alternating_turns: False (OpenAI allows consecutive same-role)
+    """
+
+    def __init__(self, settings: OpenAIAPISettings | None = None) -> None:
+        """Initialize with explicit settings injection.
+
+        Args:
+            settings: OpenAI API settings. If None, loads from environment variables.
+        """
+        self._settings = settings or OpenAIAPISettings()
+
+    @property
+    def require_first_user_message(self) -> bool:
+        """OpenAI accepts system-only conversations."""
+        return False
+
+    @property
+    def combine_system_messages(self) -> bool:
+        """OpenAI handles multiple system messages natively."""
+        return False
+
+    @property
+    def enforce_alternating_turns(self) -> bool:
+        """OpenAI allows consecutive messages from same role."""
+        return False
+
+    def completion(
+        self,
+        model_settings: ModelSettings,
+        messages: Sequence[BaseMessage],
+        response_format: dict[str, str] | None = None,
+    ) -> str:
+        """Generate completion using ChatOpenAI.
+
+        Args:
+            model_settings: Model configuration (chat_model, temperature, etc.)
+            messages: LangChain messages (BaseMessage).
+            response_format: Optional response format (e.g., {"type": "json_object"}).
+
+        Returns:
+            Generated text response.
+        """
+        # Build model_kwargs with optional response_format
+        model_kwargs: dict[str, dict[str, str]] = {}
+        if response_format:
+            model_kwargs["response_format"] = response_format
+
+        # Initialize ChatOpenAI with model settings and explicit API key injection
+        chat_model = ChatOpenAI(
+            model=model_settings.chat_model,
+            temperature=model_settings.temperature,
+            seed=model_settings.seed,
+            frequency_penalty=model_settings.frequency_penalty,
+            model_kwargs=model_kwargs,
+            openai_api_key=self._settings.api_key,  # type: ignore[arg-type]
+            openai_organization=self._settings.organization,  # type: ignore[arg-type]
+        )
+
+        # Generate response
+        response = chat_model.generate([list(messages)])
+        return response.generations[0][0].text
+
+    def get_context_size(self, model_name: str) -> int:
+        """Get maximum context window size for OpenAI model.
+
+        Uses LiteLLM's model_cost for dynamic lookup.
+
+        Args:
+            model_name: Model identifier (e.g., 'gpt-4o', 'gpt-4o-mini')
+
+        Returns:
+            Maximum context window size in tokens.
+        """
+        return lookup_context_window(model_name)

aidol/repositories/__init__.py

@@ -4,10 +4,12 @@ AIdol repositories
 
 from aidol.repositories.aidol import AIdolRepository
 from aidol.repositories.aidol_lead import AIdolLeadRepository
+from aidol.repositories.chatroom import ChatroomRepository
 from aidol.repositories.companion import CompanionRepository
 
 __all__ = [
     "AIdolRepository",
     "AIdolLeadRepository",
+    "ChatroomRepository",
     "CompanionRepository",
 ]

aidol/repositories/chatroom.py

@@ -0,0 +1,142 @@
+"""
+AIdol chatroom repository
+
+Implements BaseRepository pattern for BaseCrudRouter compatibility.
+"""
+
+import uuid
+from datetime import datetime, timezone
+
+from aioia_core.repositories import BaseRepository
+from sqlalchemy.orm import Session
+
+from aidol.models import DBChatroom, DBMessage
+from aidol.schemas import (
+    Chatroom,
+    ChatroomCreate,
+    ChatroomUpdate,
+    CompanionMessage,
+    Message,
+    MessageCreate,
+    SenderType,
+)
+
+
+def _convert_db_chatroom_to_model(db_chatroom: DBChatroom) -> Chatroom:
+    """Convert DB chatroom to Pydantic model."""
+    return Chatroom(
+        id=db_chatroom.id,
+        name=db_chatroom.name,
+        language=db_chatroom.language,
+        created_at=db_chatroom.created_at.replace(tzinfo=timezone.utc),
+        updated_at=db_chatroom.updated_at.replace(tzinfo=timezone.utc),
+    )
+
+
+def _convert_chatroom_create_to_db_model(schema: ChatroomCreate) -> dict:
+    """Convert ChatroomCreate schema to DB model data dict."""
+    return schema.model_dump(exclude_unset=True)
+
+
+def _convert_db_message_to_model(db_message: DBMessage) -> Message:
+    """Convert DB message to Pydantic model.
+
+    Returns CompanionMessage if sender_type is COMPANION, else Message.
+    """
+    if db_message.sender_type == SenderType.COMPANION.value:
+        return CompanionMessage(
+            id=db_message.id,
+            sender_type=SenderType.COMPANION,
+            content=db_message.content,
+            created_at=db_message.created_at.replace(tzinfo=timezone.utc),
+        )
+
+    return Message(
+        id=db_message.id,
+        sender_type=SenderType(db_message.sender_type),
+        content=db_message.content,
+        created_at=db_message.created_at.replace(tzinfo=timezone.utc),
+    )
+
+
+class ChatroomRepository(
+    BaseRepository[Chatroom, DBChatroom, ChatroomCreate, ChatroomUpdate]
+):
+    """
+    Database-backed chatroom repository.
+
+    Extends BaseRepository for CRUD operations compatible with BaseCrudRouter.
+    """
+
+    def __init__(self, db_session: Session):
+        super().__init__(
+            db_session=db_session,
+            db_model=DBChatroom,
+            convert_to_model=_convert_db_chatroom_to_model,
+            convert_to_db_model=_convert_chatroom_create_to_db_model,
+        )
+
+    # ========================================
+    # AIdol-specific methods
+    # ========================================
+
+    def add_message_to_chatroom(
+        self, chatroom_id: str, message: MessageCreate
+    ) -> Message:
+        """
+        Add message to chatroom.
+
+        Follows aioia-core pattern: CreateSchema (no id) → Model (with id).
+        Returned Message always has id set (generated by repository).
+
+        Args:
+            chatroom_id: Chatroom ID
+            message: MessageCreate or CompanionMessageCreate schema (no id)
+
+        Returns:
+            Message or CompanionMessage with id guaranteed to be set
+        """
+        # sender_type.value is guaranteed by Pydantic validation
+        sender_type_value = message.sender_type.value
+
+        # Get companion_id if available (CompanionMessageCreate has it)
+        companion_id = getattr(message, "companion_id", None)
+
+        db_message = DBMessage(
+            id=str(uuid.uuid4()),
+            chatroom_id=chatroom_id,
+            sender_type=sender_type_value,
+            content=message.content,
+            claim_token=message.claim_token,
+            companion_id=companion_id,
+            created_at=datetime.now(timezone.utc),
+            updated_at=datetime.now(timezone.utc),
+        )
+        self.db_session.add(db_message)
+        self.db_session.commit()
+        self.db_session.refresh(db_message)
+        return _convert_db_message_to_model(db_message)
+
+    def get_messages_by_chatroom_id(
+        self, chatroom_id: str, limit: int, offset: int
+    ) -> list[Message]:
+        """
+        Get messages in chatroom with pagination.
+
+        Args:
+            chatroom_id: Chatroom ID
+            limit: Maximum number of messages
+            offset: Number of messages to skip
+
+        Returns:
+            List of messages ordered by created_at (descending, newest first)
+        """
+        db_messages = (
+            self.db_session.query(DBMessage)
+            .filter(DBMessage.chatroom_id == chatroom_id)
+            .order_by(DBMessage.created_at.desc())
+            .offset(offset)
+            .limit(limit)
+            .all()
+        )
+        return [_convert_db_message_to_model(msg) for msg in db_messages]

aidol/schemas/__init__.py

@@ -13,6 +13,19 @@ from aidol.schemas.aidol import (
     ImageGenerationResponse,
 )
 from aidol.schemas.aidol_lead import AIdolLead, AIdolLeadBase, AIdolLeadCreate
+from aidol.schemas.chatroom import (
+    AudioFormat,
+    Chatroom,
+    ChatroomBase,
+    ChatroomCreate,
+    ChatroomUpdate,
+    CompanionMessage,
+    CompanionMessageCreate,
+    Message,
+    MessageBase,
+    MessageCreate,
+    SenderType,
+)
 from aidol.schemas.companion import (
     Companion,
     CompanionBase,
@@ -24,8 +37,11 @@ from aidol.schemas.companion import (
     Grade,
     Position,
 )
+from aidol.schemas.model_settings import ModelSettings, ModelSettingsBase
+from aidol.schemas.persona import Persona
 
 __all__ = [
+    # AIdol
     "AIdol",
     "AIdolBase",
     "AIdolCreate",
@@ -34,9 +50,23 @@ __all__ = [
     "ImageGenerationData",
     "ImageGenerationRequest",
     "ImageGenerationResponse",
+    # AIdolLead
     "AIdolLead",
     "AIdolLeadBase",
     "AIdolLeadCreate",
+    # Chatroom
+    "AudioFormat",
+    "Chatroom",
+    "ChatroomBase",
+    "ChatroomCreate",
+    "ChatroomUpdate",
+    "CompanionMessage",
+    "CompanionMessageCreate",
+    "Message",
+    "MessageBase",
+    "MessageCreate",
+    "SenderType",
+    # Companion
     "Companion",
     "CompanionBase",
     "CompanionCreate",
@@ -46,4 +76,9 @@ __all__ = [
     "Gender",
     "Grade",
     "Position",
+    # Model Settings
+    "ModelSettings",
+    "ModelSettingsBase",
+    # Persona
+    "Persona",
 ]

aidol/schemas/chatroom.py

@@ -0,0 +1,147 @@
+"""
+AIdol chatroom, message, and related schemas
+"""
+
+from datetime import datetime, timezone
+from enum import Enum, unique
+
+from humps import camelize
+from pydantic import BaseModel, ConfigDict, Field
+
+# =============================================================================
+# Enums
+# =============================================================================
+
+
+@unique
+class SenderType(str, Enum):
+    """
+    Sender types for chat messages.
+
+    Core types for AIdol standalone. Platform-specific integrators
+    may define their own extended SenderType with additional values.
+    """
+
+    USER = "user"
+    COMPANION = "companion"
+
+
+@unique
+class AudioFormat(str, Enum):
+    """Audio format types."""
+
+    MP3 = "mp3"
+    WAV = "wav"
+    OGG = "ogg"
+
+
+# =============================================================================
+# Message Schemas
+# =============================================================================
+
+
+class MessageBase(BaseModel):
+    """Base message model with common fields."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    content: str = Field(..., description="Message content")
+    sender_type: SenderType = Field(
+        default=SenderType.USER, description="Type of the sender"
+    )
+
+
+class Message(MessageBase):
+    """Message response schema with id and timestamp."""
+
+    model_config = ConfigDict(
+        frozen=True, populate_by_name=True, alias_generator=camelize
+    )
+
+    id: str = Field(..., description="Unique message identifier")
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Message creation timestamp",
+    )
+
+    def is_user(self) -> bool:
+        """Check if message is from user"""
+        return self.sender_type == SenderType.USER
+
+    def is_companion(self) -> bool:
+        """Check if message is from companion (AI)"""
+        return self.sender_type == SenderType.COMPANION
+
+
+class CompanionMessage(Message):
+    """Companion message response schema."""
+
+    sender_type: SenderType = Field(
+        default=SenderType.COMPANION, description="Type of the sender"
+    )
+
+
+class MessageCreate(MessageBase):
+    """Schema for creating a message (no id, no timestamp).
+
+    claim_token is used for anonymous user identification and DAU/MAU analytics.
+    It's a UUID stored in localStorage, identifying users without authentication.
+    """
+
+    claim_token: str | None = Field(
+        default=None, description="Anonymous user identifier for analytics"
+    )
+
+
+class CompanionMessageCreate(MessageCreate):
+    """Schema for creating a companion message.
+
+    companion_id is optional for aidol standalone but may be required for platform integration.
+    When provided, it's used to identify the companion in the platform's companion system.
+    """
+
+    sender_type: SenderType = Field(
+        default=SenderType.COMPANION, description="Type of the sender"
+    )
+    companion_id: str | None = Field(
+        default=None, description="Companion ID for platform integration"
+    )
+
+
+# =============================================================================
+# Chatroom Schemas
+# =============================================================================
+
+
+class ChatroomBase(BaseModel):
+    """Base chatroom model with common fields."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    name: str = Field(..., description="Chatroom name")
+    language: str = Field(default="en", description="Chatroom language")
+
+
+class Chatroom(ChatroomBase):
+    """Chatroom response schema with id and timestamps."""
+
+    model_config = ConfigDict(
+        populate_by_name=True, from_attributes=True, alias_generator=camelize
+    )
+
+    id: str = Field(..., description="Chatroom ID")
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+
+class ChatroomCreate(ChatroomBase):
+    """Schema for creating a chatroom (no id)."""
+
+
+class ChatroomUpdate(BaseModel):
+    """Schema for updating a chatroom (all fields optional)."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    name: str | None = Field(default=None, description="Chatroom name")
+    language: str | None = Field(default=None, description="Chatroom language")

aidol/schemas/model_settings.py

@@ -0,0 +1,35 @@
+"""
+AIdol LLM model settings schemas
+"""
+
+from humps import camelize
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelSettingsBase(BaseModel):
+    """Base settings for LLM model configuration, excluding the model name.
+
+    Contains common parameters used across all model settings.
+    Platform-specific extensions can inherit from this class.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    temperature: float = Field(
+        default=0.0, description="Sampling temperature (0.0-2.0)"
+    )
+    seed: int | None = Field(
+        default=None, description="Random seed for reproducibility"
+    )
+    frequency_penalty: float = Field(
+        default=0.0, description="Frequency penalty (-2.0-2.0)"
+    )
+
+
+class ModelSettings(ModelSettingsBase):
+    """Settings for LLM model configuration, including the model name.
+
+    Used by LLMProvider.completion() to configure model behavior.
+    """
+
+    chat_model: str = Field(..., description="The model name (e.g., 'gpt-4o')")

aidol/schemas/persona.py

@@ -0,0 +1,20 @@
+"""
+AIdol persona schema
+"""
+
+from humps import camelize
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Persona(BaseModel):
+    """Chat agent persona"""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    name: str | None = Field(default=None, description="Agent name")
+    system_prompt: str | None = Field(
+        default=None, description="System prompt for the agent"
+    )
+    timezone_name: str = Field(
+        default="UTC", description="Timezone for real-time context (e.g., 'Asia/Seoul')"
+    )

aidol/services/__init__.py

@@ -3,7 +3,9 @@ AIdol services
 """
 
 from aidol.services.image_generation_service import ImageGenerationService
+from aidol.services.response_generation_service import ResponseGenerationService
 
 __all__ = [
     "ImageGenerationService",
+    "ResponseGenerationService",
 ]