py-aidol 0.1.0__py3-none-any.whl

aidol/__init__.py

@@ -0,0 +1,7 @@
+"""
+AIdol - Asynchronous chat module for AI idol interaction
+"""
+
+__version__ = "0.1.0"
+
+# No top-level exports - use full paths for clarity

aidol/api/__init__.py

@@ -0,0 +1,13 @@
+"""
+AIdol API routers
+"""
+
+from aidol.api.aidol import AIdolRouter, create_aidol_router
+from aidol.api.companion import CompanionRouter, create_companion_router
+
+__all__ = [
+    "AIdolRouter",
+    "CompanionRouter",
+    "create_aidol_router",
+    "create_companion_router",
+]

aidol/api/aidol.py

@@ -0,0 +1,189 @@
+"""
+AIdol API router
+
+Public endpoints for AIdol group creation and retrieval.
+Public access pattern: no authentication required.
+"""
+
+from aioia_core.auth import UserInfoProvider
+from aioia_core.errors import ErrorResponse
+from aioia_core.fastapi import BaseCrudRouter
+from aioia_core.settings import JWTSettings, OpenAIAPISettings
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel
+from sqlalchemy.orm import sessionmaker
+
+from aidol.protocols import (
+    AIdolRepositoryFactoryProtocol,
+    AIdolRepositoryProtocol,
+    ImageStorageProtocol,
+)
+from aidol.schemas import (
+    AIdol,
+    AIdolCreate,
+    AIdolPublic,
+    AIdolUpdate,
+    ImageGenerationData,
+    ImageGenerationRequest,
+    ImageGenerationResponse,
+)
+from aidol.services import ImageGenerationService
+
+
+class AIdolSingleItemResponse(BaseModel):
+    """Single item response for AIdol (public)."""
+
+    data: AIdolPublic
+
+
+class AIdolRouter(
+    BaseCrudRouter[AIdol, AIdolCreate, AIdolUpdate, AIdolRepositoryProtocol]
+):
+    """
+    AIdol router with public endpoints.
+
+    Public CRUD pattern: no authentication required.
+    Returns AIdolPublic (excludes claim_token) for all responses.
+    """
+
+    def __init__(
+        self,
+        openai_settings: OpenAIAPISettings,
+        image_storage: ImageStorageProtocol,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.openai_settings = openai_settings
+        self.image_storage = image_storage
+
+    def _register_routes(self) -> None:
+        """Register routes (public CRUD + image generation)"""
+        self._register_image_generation_route()
+        self._register_public_create_route()
+        self._register_public_get_route()
+
+    def _register_public_create_route(self) -> None:
+        """POST /{resource_name} - Create an AIdol group (public)"""
+
+        @self.router.post(
+            f"/{self.resource_name}",
+            response_model=AIdolSingleItemResponse,
+            status_code=status.HTTP_201_CREATED,
+            summary="Create AIdol group",
+            description="Create a new AIdol group (public endpoint)",
+        )
+        async def create_aidol(
+            request: AIdolCreate,
+            repository: AIdolRepositoryProtocol = Depends(self.get_repository_dep),
+        ):
+            """Create a new AIdol group."""
+            created = repository.create(request)
+            # Convert to Public schema (exclude claim_token)
+            public_aidol = AIdolPublic(**created.model_dump())
+            return AIdolSingleItemResponse(data=public_aidol)
+
+    def _register_public_get_route(self) -> None:
+        """GET /{resource_name}/{id} - Get an AIdol group (public)"""
+
+        @self.router.get(
+            f"/{self.resource_name}/{{item_id}}",
+            response_model=AIdolSingleItemResponse,
+            status_code=status.HTTP_200_OK,
+            summary="Get AIdol group",
+            description="Get AIdol group by ID (public endpoint)",
+            responses={
+                404: {"model": ErrorResponse, "description": "AIdol group not found"},
+            },
+        )
+        async def get_aidol(
+            item_id: str,
+            repository: AIdolRepositoryProtocol = Depends(self.get_repository_dep),
+        ):
+            """Get AIdol group by ID."""
+            aidol = self._get_item_or_404(repository, item_id)
+            # Convert to Public schema (exclude claim_token)
+            public_aidol = AIdolPublic(**aidol.model_dump())
+            return AIdolSingleItemResponse(data=public_aidol)
+
+    def _register_image_generation_route(self) -> None:
+        """POST /{resource_name}/images - Generate image for AIdol or Companion"""
+
+        @self.router.post(
+            f"/{self.resource_name}/images",
+            response_model=ImageGenerationResponse,
+            status_code=status.HTTP_201_CREATED,
+            summary="Generate image",
+            description="Generate image for AIdol emblem or Companion profile",
+            responses={
+                500: {"model": ErrorResponse, "description": "Image generation failed"},
+            },
+        )
+        async def generate_image(request: ImageGenerationRequest):
+            """Generate image from prompt."""
+            # Generate and download image (TTS pattern: service returns data)
+            service = ImageGenerationService(self.openai_settings)
+            image = service.generate_and_download_image(
+                prompt=request.prompt,
+                size="1024x1024",
+                quality="standard",
+            )
+
+            if image is None:
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Image generation failed",
+                )
+
+            # Upload to permanent storage (TTS pattern: API layer orchestrates)
+            image_url = self.image_storage.upload_image(image)
+
+            return ImageGenerationResponse(
+                data=ImageGenerationData(
+                    image_url=image_url,
+                    width=1024,
+                    height=1024,
+                    format="png",
+                )
+            )
+
+
+def create_aidol_router(
+    openai_settings: OpenAIAPISettings,
+    db_session_factory: sessionmaker,
+    repository_factory: AIdolRepositoryFactoryProtocol,
+    image_storage: ImageStorageProtocol,
+    jwt_settings: JWTSettings | None = None,
+    user_info_provider: UserInfoProvider | None = None,
+    resource_name: str = "aidols",
+    tags: list[str] | None = None,
+) -> APIRouter:
+    """
+    Create AIdol router with dependency injection.
+
+    Args:
+        openai_settings: OpenAI API settings for image generation
+        db_session_factory: Database session factory
+        repository_factory: Factory implementing AIdolRepositoryFactoryProtocol
+        image_storage: Image storage for permanent URLs
+        jwt_settings: Optional JWT settings for authentication
+        user_info_provider: Optional user info provider
+        resource_name: Resource name for routes (default: "aidols")
+        tags: Optional OpenAPI tags
+
+    Returns:
+        FastAPI APIRouter instance
+    """
+    router = AIdolRouter(
+        openai_settings=openai_settings,
+        image_storage=image_storage,
+        model_class=AIdol,
+        create_schema=AIdolCreate,
+        update_schema=AIdolUpdate,
+        db_session_factory=db_session_factory,
+        repository_factory=repository_factory,
+        user_info_provider=user_info_provider,
+        jwt_secret_key=jwt_settings.secret_key if jwt_settings else None,
+        resource_name=resource_name,
+        tags=tags or ["AIdol"],
+    )
+    return router.get_router()

aidol/api/companion.py

@@ -0,0 +1,168 @@
+"""
+Companion API router
+
+Public endpoints for Companion creation and retrieval.
+Public access pattern: no authentication required.
+"""
+
+from aioia_core.auth import UserInfoProvider
+from aioia_core.errors import ErrorResponse
+from aioia_core.fastapi import BaseCrudRouter
+from aioia_core.settings import JWTSettings
+from fastapi import APIRouter, Depends, Query, status
+from pydantic import BaseModel
+from sqlalchemy.orm import sessionmaker
+
+from aidol.protocols import (
+    CompanionRepositoryFactoryProtocol,
+    CompanionRepositoryProtocol,
+)
+from aidol.schemas import Companion, CompanionCreate, CompanionPublic, CompanionUpdate
+
+
+class CompanionSingleItemResponse(BaseModel):
+    """Single item response for Companion (public)."""
+
+    data: CompanionPublic
+
+
+class CompanionPaginatedResponse(BaseModel):
+    """Paginated response for Companion (public)."""
+
+    data: list[CompanionPublic]
+    total: int
+
+
+class CompanionRouter(
+    BaseCrudRouter[
+        Companion, CompanionCreate, CompanionUpdate, CompanionRepositoryProtocol
+    ]
+):
+    """
+    Companion router with public endpoints.
+
+    Public CRUD pattern: no authentication required.
+    Returns CompanionPublic (excludes system_prompt) for all responses.
+    """
+
+    def _register_routes(self) -> None:
+        """Register routes (public CRUD)"""
+        self._register_public_list_route()
+        self._register_public_create_route()
+        self._register_public_get_route()
+
+    def _register_public_list_route(self) -> None:
+        """GET /{resource_name} - List Companions (public)"""
+
+        @self.router.get(
+            f"/{self.resource_name}",
+            response_model=CompanionPaginatedResponse,
+            status_code=status.HTTP_200_OK,
+            summary="List Companions",
+            description="List all Companions with optional filtering (public endpoint)",
+        )
+        async def list_companions(
+            current: int = Query(1, ge=1, description="Current page number"),
+            page_size: int = Query(10, ge=1, le=100, description="Items per page"),
+            sort_param: str | None = Query(
+                None,
+                alias="sort",
+                description='Sorting criteria in JSON format. Example: [["createdAt","desc"]]',
+            ),
+            filters_param: str | None = Query(
+                None,
+                alias="filters",
+                description="Filter conditions (JSON format)",
+            ),
+            repository: CompanionRepositoryProtocol = Depends(self.get_repository_dep),
+        ):
+            """List Companions with pagination, sorting, and filtering."""
+            sort_list, filter_list = self._parse_query_params(sort_param, filters_param)
+            items, total = repository.get_all(
+                current=current,
+                page_size=page_size,
+                sort=sort_list,
+                filters=filter_list,
+            )
+            # Convert to Public schema (exclude system_prompt)
+            public_items = [CompanionPublic(**c.model_dump()) for c in items]
+            return CompanionPaginatedResponse(data=public_items, total=total)
+
+    def _register_public_create_route(self) -> None:
+        """POST /{resource_name} - Create a Companion (public)"""
+
+        @self.router.post(
+            f"/{self.resource_name}",
+            response_model=CompanionSingleItemResponse,
+            status_code=status.HTTP_201_CREATED,
+            summary="Create Companion",
+            description="Create a new Companion (public endpoint)",
+        )
+        async def create_companion(
+            request: CompanionCreate,
+            repository: CompanionRepositoryProtocol = Depends(self.get_repository_dep),
+        ):
+            """Create a new Companion."""
+            created = repository.create(request)
+            # Convert to Public schema (exclude system_prompt)
+            public_companion = CompanionPublic(**created.model_dump())
+            return CompanionSingleItemResponse(data=public_companion)
+
+    def _register_public_get_route(self) -> None:
+        """GET /{resource_name}/{id} - Get a Companion (public)"""
+
+        @self.router.get(
+            f"/{self.resource_name}/{{item_id}}",
+            response_model=CompanionSingleItemResponse,
+            status_code=status.HTTP_200_OK,
+            summary="Get Companion",
+            description="Get Companion by ID (public endpoint)",
+            responses={
+                404: {"model": ErrorResponse, "description": "Companion not found"},
+            },
+        )
+        async def get_companion(
+            item_id: str,
+            repository: CompanionRepositoryProtocol = Depends(self.get_repository_dep),
+        ):
+            """Get Companion by ID."""
+            companion = self._get_item_or_404(repository, item_id)
+            # Convert to Public schema (exclude system_prompt)
+            public_companion = CompanionPublic(**companion.model_dump())
+            return CompanionSingleItemResponse(data=public_companion)
+
+
+def create_companion_router(
+    db_session_factory: sessionmaker,
+    repository_factory: CompanionRepositoryFactoryProtocol,
+    jwt_settings: JWTSettings | None = None,
+    user_info_provider: UserInfoProvider | None = None,
+    resource_name: str = "companions",
+    tags: list[str] | None = None,
+) -> APIRouter:
+    """
+    Create Companion router with dependency injection.
+
+    Args:
+        db_session_factory: Database session factory
+        repository_factory: Factory implementing CompanionRepositoryFactoryProtocol
+        jwt_settings: Optional JWT settings for authentication
+        user_info_provider: Optional user info provider
+        resource_name: Resource name for routes (default: "companions")
+        tags: Optional OpenAPI tags
+
+    Returns:
+        FastAPI APIRouter instance
+    """
+    router = CompanionRouter(
+        model_class=Companion,
+        create_schema=CompanionCreate,
+        update_schema=CompanionUpdate,
+        db_session_factory=db_session_factory,
+        repository_factory=repository_factory,
+        user_info_provider=user_info_provider,
+        jwt_secret_key=jwt_settings.secret_key if jwt_settings else None,
+        resource_name=resource_name,
+        tags=tags or ["Companion"],
+    )
+    return router.get_router()

aidol/factories.py

@@ -0,0 +1,24 @@
+"""
+AIdol repository factories
+
+Uses BaseRepositoryFactory for BaseCrudRouter compatibility.
+"""
+
+from aioia_core.factories import BaseRepositoryFactory
+
+from aidol.repositories.aidol import AIdolRepository
+from aidol.repositories.companion import CompanionRepository
+
+
+class AIdolRepositoryFactory(BaseRepositoryFactory[AIdolRepository]):
+    """Factory for creating AIdol repositories."""
+
+    def __init__(self):
+        super().__init__(repository_class=AIdolRepository)
+
+
+class CompanionRepositoryFactory(BaseRepositoryFactory[CompanionRepository]):
+    """Factory for creating Companion repositories."""
+
+    def __init__(self):
+        super().__init__(repository_class=CompanionRepository)

aidol/models/__init__.py

@@ -0,0 +1,8 @@
+"""
+AIdol database models
+"""
+
+from aidol.models.aidol import DBAIdol
+from aidol.models.companion import DBCompanion
+
+__all__ = ["DBAIdol", "DBCompanion"]

aidol/models/aidol.py

@@ -0,0 +1,24 @@
+"""
+AIdol database model
+
+Uses aioia_core.models.BaseModel which provides:
+- id: Mapped[str] (primary key, UUID default)
+- created_at: Mapped[datetime]
+- updated_at: Mapped[datetime]
+"""
+
+from aioia_core.models import BaseModel
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class DBAIdol(BaseModel):
+    """AIdol (group) database model"""
+
+    __tablename__ = "aidols"
+
+    # id, created_at, updated_at inherited from BaseModel
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    concept: Mapped[str | None] = mapped_column(String, nullable=True)
+    profile_image_url: Mapped[str] = mapped_column(String, nullable=False)
+    claim_token: Mapped[str | None] = mapped_column(String(36), nullable=True)

aidol/models/companion.py

@@ -0,0 +1,27 @@
+"""
+Companion database model
+
+Uses aioia_core.models.BaseModel which provides:
+- id: Mapped[str] (primary key, UUID default)
+- created_at: Mapped[datetime]
+- updated_at: Mapped[datetime]
+"""
+
+from aioia_core.models import BaseModel
+from sqlalchemy import ForeignKey, Index, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class DBCompanion(BaseModel):
+    """Companion (member) database model"""
+
+    __tablename__ = "companions"
+
+    # id, created_at, updated_at inherited from BaseModel
+    aidol_id: Mapped[str | None] = mapped_column(ForeignKey("aidols.id"), nullable=True)
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    biography: Mapped[str | None] = mapped_column(Text, nullable=True)
+    profile_picture_url: Mapped[str | None] = mapped_column(String, nullable=True)
+    system_prompt: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    __table_args__ = (Index("ix_companions_aidol_id", "aidol_id"),)

aidol/protocols.py

@@ -0,0 +1,100 @@
+"""
+AIdol repository protocols for type-safe dependency injection.
+
+Defines the interface that AIdol Router expects from repositories.
+Platform-specific integrators implement these protocols via adapters.
+"""
+
+# pylint: disable=unnecessary-ellipsis
+
+from typing import Protocol
+
+import PIL.Image
+from aioia_core import CrudRepositoryProtocol
+from sqlalchemy.orm import Session
+
+from aidol.schemas import (
+    AIdol,
+    AIdolCreate,
+    AIdolUpdate,
+    Companion,
+    CompanionCreate,
+    CompanionUpdate,
+)
+
+
+class AIdolRepositoryProtocol(
+    CrudRepositoryProtocol[AIdol, AIdolCreate, AIdolUpdate], Protocol
+):
+    """Protocol defining AIdol repository expectations.
+
+    This protocol enables type-safe dependency injection by defining
+    the exact interface that AIdolRouter uses. Inherits CRUD operations
+    from CrudRepositoryProtocol.
+    """
+
+
+class AIdolRepositoryFactoryProtocol(Protocol):
+    """Protocol for factory that creates AIdolRepositoryProtocol instances.
+
+    Implementations:
+        - aidol.factories.AIdolRepositoryFactory (standalone)
+    """
+
+    def create_repository(
+        self, db_session: Session | None = None
+    ) -> AIdolRepositoryProtocol:
+        """Create a repository instance.
+
+        Args:
+            db_session: Optional database session.
+        """
+        ...
+
+
+class CompanionRepositoryProtocol(
+    CrudRepositoryProtocol[Companion, CompanionCreate, CompanionUpdate], Protocol
+):
+    """Protocol defining Companion repository expectations.
+
+    This protocol enables type-safe dependency injection by defining
+    the exact interface that CompanionRouter uses. Inherits CRUD operations
+    from CrudRepositoryProtocol.
+    """
+
+
+class CompanionRepositoryFactoryProtocol(Protocol):
+    """Protocol for factory that creates CompanionRepositoryProtocol instances.
+
+    Implementations:
+        - aidol.factories.CompanionRepositoryFactory (standalone)
+    """
+
+    def create_repository(
+        self, db_session: Session | None = None
+    ) -> CompanionRepositoryProtocol:
+        """Create a repository instance.
+
+        Args:
+            db_session: Optional database session.
+        """
+        ...
+
+
+class ImageStorageProtocol(Protocol):
+    """Protocol for image storage operations.
+
+    Enables dependency injection of storage implementations.
+    Platform-specific adapters implement this protocol.
+
+    Implementations:
+        - ImageStorageAdapter (platform integration via StorageService)
+    """
+
+    def upload_image(self, image: PIL.Image.Image) -> str:
+        """Upload an image and return the permanent URL.
+
+        Args:
+            image: PIL Image object to upload.
+        """
+        ...

aidol/repositories/__init__.py

@@ -0,0 +1,11 @@
+"""
+AIdol repositories
+"""
+
+from aidol.repositories.aidol import AIdolRepository
+from aidol.repositories.companion import CompanionRepository
+
+__all__ = [
+    "AIdolRepository",
+    "CompanionRepository",
+]

aidol/repositories/aidol.py

@@ -0,0 +1,57 @@
+# pylint: disable=duplicate-code
+# TODO: Extract common AIdol converters to shared module
+#       (duplicated in managers/database_aidol_manager.py)
+"""
+AIdol repository
+
+Implements BaseRepository pattern for BaseCrudRouter compatibility.
+"""
+
+from datetime import timezone
+
+from aioia_core.repositories import BaseRepository
+from sqlalchemy.orm import Session
+
+from aidol.models import DBAIdol
+from aidol.schemas import AIdol, AIdolCreate, AIdolUpdate
+
+
+def _convert_db_aidol_to_model(db_aidol: DBAIdol) -> AIdol:
+    """Convert DB AIdol to Pydantic model.
+
+    Includes claim_token for internal use (Service layer).
+    Router should convert to AIdolPublic for API responses.
+    """
+    return AIdol(
+        id=db_aidol.id,
+        name=db_aidol.name,
+        concept=db_aidol.concept,
+        profile_image_url=db_aidol.profile_image_url,
+        claim_token=db_aidol.claim_token,
+        created_at=db_aidol.created_at.replace(tzinfo=timezone.utc),
+        updated_at=db_aidol.updated_at.replace(tzinfo=timezone.utc),
+    )
+
+
+def _convert_aidol_create_to_db(schema: AIdolCreate) -> dict:
+    """Convert AIdolCreate schema to DB model data dict.
+
+    Includes claim_token for ownership verification.
+    """
+    return schema.model_dump(exclude_unset=True)
+
+
+class AIdolRepository(BaseRepository[AIdol, DBAIdol, AIdolCreate, AIdolUpdate]):
+    """
+    Database-backed AIdol repository.
+
+    Extends BaseRepository for CRUD operations compatible with BaseCrudRouter.
+    """
+
+    def __init__(self, db_session: Session):
+        super().__init__(
+            db_session=db_session,
+            db_model=DBAIdol,
+            convert_to_model=_convert_db_aidol_to_model,
+            convert_to_db_model=_convert_aidol_create_to_db,
+        )

aidol/repositories/companion.py

@@ -0,0 +1,57 @@
+"""
+Companion repository
+
+Implements BaseRepository pattern for BaseCrudRouter compatibility.
+"""
+
+from datetime import timezone
+
+from aioia_core.repositories import BaseRepository
+from sqlalchemy.orm import Session
+
+from aidol.models import DBCompanion
+from aidol.schemas import Companion, CompanionCreate, CompanionUpdate
+
+
+def _convert_db_companion_to_model(db_companion: DBCompanion) -> Companion:
+    """Convert DB Companion to Pydantic model.
+
+    Includes system_prompt for internal use (Service layer).
+    Router should convert to CompanionPublic for API responses.
+    """
+    return Companion(
+        id=db_companion.id,
+        aidol_id=db_companion.aidol_id,
+        name=db_companion.name,
+        biography=db_companion.biography,
+        profile_picture_url=db_companion.profile_picture_url,
+        system_prompt=db_companion.system_prompt,
+        created_at=db_companion.created_at.replace(tzinfo=timezone.utc),
+        updated_at=db_companion.updated_at.replace(tzinfo=timezone.utc),
+    )
+
+
+def _convert_companion_create_to_db(schema: CompanionCreate) -> dict:
+    """Convert CompanionCreate schema to DB model data dict.
+
+    Includes system_prompt for AI configuration.
+    """
+    return schema.model_dump(exclude_unset=True)
+
+
+class CompanionRepository(
+    BaseRepository[Companion, DBCompanion, CompanionCreate, CompanionUpdate]
+):
+    """
+    Database-backed Companion repository.
+
+    Extends BaseRepository for CRUD operations compatible with BaseCrudRouter.
+    """
+
+    def __init__(self, db_session: Session):
+        super().__init__(
+            db_session=db_session,
+            db_model=DBCompanion,
+            convert_to_model=_convert_db_companion_to_model,
+            convert_to_db_model=_convert_companion_create_to_db,
+        )

aidol/schemas/__init__.py

@@ -0,0 +1,37 @@
+"""
+AIdol Pydantic schemas
+"""
+
+from aidol.schemas.aidol import (
+    AIdol,
+    AIdolBase,
+    AIdolCreate,
+    AIdolPublic,
+    AIdolUpdate,
+    ImageGenerationData,
+    ImageGenerationRequest,
+    ImageGenerationResponse,
+)
+from aidol.schemas.companion import (
+    Companion,
+    CompanionBase,
+    CompanionCreate,
+    CompanionPublic,
+    CompanionUpdate,
+)
+
+__all__ = [
+    "AIdol",
+    "AIdolBase",
+    "AIdolCreate",
+    "AIdolPublic",
+    "AIdolUpdate",
+    "ImageGenerationData",
+    "ImageGenerationRequest",
+    "ImageGenerationResponse",
+    "Companion",
+    "CompanionBase",
+    "CompanionCreate",
+    "CompanionPublic",
+    "CompanionUpdate",
+]

aidol/schemas/aidol.py

@@ -0,0 +1,119 @@
+"""
+AIdol (group) schemas
+
+Schema hierarchy:
+- AIdolBase: Mutable fields (used in Create/Update)
+- AIdolCreate: Base + optional claim_token
+- AIdolUpdate: Base fields only
+- AIdol: Response with all fields including claim_token (internal use)
+- AIdolPublic: Response without sensitive fields (API use)
+"""
+
+from datetime import datetime
+
+from humps import camelize
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AIdolBase(BaseModel):
+    """Base AIdol model with mutable fields.
+
+    Contains only fields that can be modified after creation.
+    Excludes claim_token (immutable, set at creation only).
+    """
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    name: str = Field(..., description="AIdol group name")
+    concept: str | None = Field(default=None, description="Group concept or theme")
+    profile_image_url: str = Field(..., description="Profile image URL")
+
+
+class AIdolCreate(AIdolBase):
+    """Schema for creating an AIdol group (no id).
+
+    claim_token is optional for anonymous ownership verification.
+    """
+
+    claim_token: str | None = Field(
+        default=None,
+        description="Optional client-generated UUID for ownership verification",
+    )
+
+
+class AIdolUpdate(BaseModel):
+    """Schema for updating an AIdol group (all fields optional)."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    name: str | None = Field(default=None, description="AIdol group name")
+    concept: str | None = Field(default=None, description="Group concept or theme")
+    profile_image_url: str | None = Field(default=None, description="Profile image URL")
+
+
+class AIdol(AIdolBase):
+    """AIdol response schema with id and timestamps.
+
+    Includes optional claim_token for ownership verification.
+    Use AIdolPublic for API responses to exclude sensitive fields.
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True, from_attributes=True, alias_generator=camelize
+    )
+
+    id: str = Field(..., description="AIdol group ID")
+    claim_token: str | None = Field(
+        default=None, description="Optional ownership token (sensitive, internal use)"
+    )
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+
+class AIdolPublic(AIdolBase):
+    """Public AIdol response schema without sensitive fields.
+
+    Excludes claim_token for API responses.
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True, from_attributes=True, alias_generator=camelize
+    )
+
+    id: str = Field(..., description="AIdol group ID")
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+
+# ---------------------------------------------------------------------------
+# Image Generation
+# ---------------------------------------------------------------------------
+
+
+class ImageGenerationRequest(BaseModel):
+    """Request schema for image generation."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    prompt: str = Field(
+        ...,
+        max_length=200,
+        description="Text description for image generation (max 200 chars)",
+    )
+
+
+class ImageGenerationData(BaseModel):
+    """Image generation result data."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    image_url: str = Field(..., description="Generated image URL")
+    width: int = Field(..., description="Image width in pixels")
+    height: int = Field(..., description="Image height in pixels")
+    format: str = Field(..., description="Image format (e.g., png, jpg)")
+
+
+class ImageGenerationResponse(BaseModel):
+    """Response schema for image generation."""
+
+    data: ImageGenerationData

aidol/schemas/companion.py

@@ -0,0 +1,93 @@
+"""
+Companion (member) schemas
+
+Schema hierarchy:
+- CompanionBase: Mutable fields (used in Create/Update)
+- CompanionCreate: Base + system_prompt (mutable, but sensitive)
+- CompanionUpdate: Base + system_prompt (mutable, but sensitive)
+- Companion: Response with all fields including system_prompt (internal use)
+- CompanionPublic: Response without sensitive fields (API use)
+"""
+
+from datetime import datetime
+
+from humps import camelize
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CompanionBase(BaseModel):
+    """Base companion model with common mutable fields.
+
+    Contains fields that can be modified after creation.
+    Excludes system_prompt (sensitive, requires explicit inclusion).
+    """
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    aidol_id: str | None = Field(default=None, description="AIdol group ID")
+    name: str = Field(..., description="Companion name")
+    biography: str | None = Field(default=None, description="Companion biography")
+    profile_picture_url: str | None = Field(
+        default=None, description="Profile picture URL"
+    )
+
+
+class CompanionCreate(CompanionBase):
+    """Schema for creating a companion (no id).
+
+    Includes system_prompt for creation (excluded from response for security).
+    """
+
+    system_prompt: str | None = Field(
+        default=None, description="AI system prompt (not exposed in responses)"
+    )
+
+
+class CompanionUpdate(BaseModel):
+    """Schema for updating a companion (all fields optional)."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=camelize)
+
+    aidol_id: str | None = Field(default=None, description="AIdol group ID")
+    name: str | None = Field(default=None, description="Companion name")
+    biography: str | None = Field(default=None, description="Companion biography")
+    profile_picture_url: str | None = Field(
+        default=None, description="Profile picture URL"
+    )
+    system_prompt: str | None = Field(
+        default=None, description="AI system prompt (not exposed in responses)"
+    )
+
+
+class Companion(CompanionBase):
+    """Companion response schema with id and timestamps.
+
+    Includes system_prompt for internal use (Service layer).
+    Use CompanionPublic for API responses to exclude sensitive fields.
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True, from_attributes=True, alias_generator=camelize
+    )
+
+    id: str = Field(..., description="Companion ID")
+    system_prompt: str | None = Field(
+        default=None, description="AI system prompt (sensitive, internal use only)"
+    )
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+
+class CompanionPublic(CompanionBase):
+    """Public companion response schema without sensitive fields.
+
+    Excludes system_prompt for API responses.
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True, from_attributes=True, alias_generator=camelize
+    )
+
+    id: str = Field(..., description="Companion ID")
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")

aidol/services/__init__.py

@@ -0,0 +1,9 @@
+"""
+AIdol services
+"""
+
+from aidol.services.image_generation_service import ImageGenerationService
+
+__all__ = [
+    "ImageGenerationService",
+]

aidol/services/image_generation_service.py

@@ -0,0 +1,145 @@
+"""
+Image generation service for AIdol
+
+Generates images using OpenAI DALL-E 3 for AIdol emblems and Companion profiles.
+"""
+
+import logging
+from dataclasses import dataclass
+from io import BytesIO
+from typing import Literal
+
+import httpx
+import openai
+import PIL.Image
+from aioia_core.settings import OpenAIAPISettings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ImageGenerationResponse:
+    """Structured response from the Image Generation service"""
+
+    url: str
+    revised_prompt: str | None
+
+
+class ImageGenerationService:
+    """Service for generating images using OpenAI DALL-E 3"""
+
+    def __init__(self, openai_settings: OpenAIAPISettings):
+        """
+        Initialize the Image Generation service with OpenAI settings.
+
+        Args:
+            openai_settings: OpenAI settings containing required API key
+        """
+        self.settings = openai_settings
+        self.client = openai.OpenAI(api_key=self.settings.api_key)
+
+    def generate_image(
+        self,
+        prompt: str,
+        size: Literal[
+            "1024x1024",
+            "1792x1024",
+            "1024x1792",
+        ] = "1024x1024",
+        quality: Literal["standard", "hd"] = "standard",
+    ) -> ImageGenerationResponse | None:
+        """
+        Generate an image from a text prompt using OpenAI DALL-E 3.
+
+        Args:
+            prompt: Text description of the image to generate
+            size: Image size (default: "1024x1024")
+            quality: Image quality "standard" or "hd" (default: "standard")
+
+        Returns:
+            An ImageGenerationResponse object containing the image URL and revised prompt,
+            or None if generation fails.
+
+        Raises:
+            openai.OpenAIError: If OpenAI API call fails.
+        """
+        try:
+            logger.info("Generating image with OpenAI DALL-E 3...")
+            response = self.client.images.generate(
+                model="dall-e-3",
+                prompt=prompt,
+                size=size,
+                quality=quality,
+                n=1,
+            )
+
+            if not response.data or len(response.data) == 0:
+                logger.error("No image data returned from OpenAI")
+                return None
+
+            image_data = response.data[0]
+            url = image_data.url
+
+            if not url:
+                logger.error("No URL found in image response")
+                return None
+
+            revised_prompt = image_data.revised_prompt
+
+            logger.info("Successfully generated image: %s", url[:100])
+            return ImageGenerationResponse(
+                url=url,
+                revised_prompt=revised_prompt,
+            )
+
+        except openai.OpenAIError as e:
+            logger.error("OpenAI API error: %s", e)
+            raise
+
+    def _download_image(self, url: str) -> PIL.Image.Image:
+        """Download image from URL and return as PIL Image.
+
+        Args:
+            url: URL of the image to download.
+
+        Raises:
+            httpx.HTTPError: If download fails.
+        """
+        with httpx.Client(timeout=30.0) as client:
+            response = client.get(url)
+            response.raise_for_status()
+            return PIL.Image.open(BytesIO(response.content))
+
+    def generate_and_download_image(
+        self,
+        prompt: str,
+        size: Literal[
+            "1024x1024",
+            "1792x1024",
+            "1024x1792",
+        ] = "1024x1024",
+        quality: Literal["standard", "hd"] = "standard",
+    ) -> PIL.Image.Image | None:
+        """Generate an image and download as PIL Image.
+
+        DALL-E returns temporary URLs that expire in 1-2 hours.
+        Use this method to download the image immediately after generation.
+
+        Args:
+            prompt: Text description of the image to generate.
+            size: Image size (default: "1024x1024").
+            quality: Image quality "standard" or "hd" (default: "standard").
+
+        Returns:
+            PIL Image object, or None if generation fails.
+
+        Raises:
+            openai.OpenAIError: If OpenAI API call fails.
+            httpx.HTTPError: If image download fails.
+        """
+        result = self.generate_image(prompt, size, quality)
+        if result is None:
+            return None
+
+        logger.info("Downloading image from DALL-E temporary URL...")
+        return self._download_image(result.url)

py_aidol-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: py-aidol
+Version: 0.1.0
+Summary: Create and chat with your own AI idol group
+License: Apache-2.0
+Keywords: kpop,idol,aidol,ai-companion,chatbot,image-generation
+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.2.0,<3.0.0)
+Requires-Dist: fastapi (>=0.115.12,<0.116.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: openai (>=1.0.0)
+Requires-Dist: pillow (>=10.0.0,<11.0.0)
+Requires-Dist: psycopg2-binary (>=2.9.9,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.1.0,<3.0.0)
+Requires-Dist: pydantic[email] (>=2.5.3,<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.25,<3.0.0)
+Requires-Dist: sqlalchemy-mixins (>=2.0.5,<3.0.0)
+Description-Content-Type: text/markdown
+
+# AIdol Backend
+
+AI 아이돌 그룹 생성 및 채팅 Python 패키지
+
+## 주요 기능
+
+- AI 아이돌 그룹/멤버 CRUD
+- DALL-E 3 이미지 생성 (엠블럼, 프로필)
+- 텍스트 채팅 (페르소나 기반 응답)
+- Buppy 통합 Adapter 패턴
+
+## 설치
+
+```bash
+cd backend
+poetry install
+poetry run uvicorn main:app --reload
+```
+
+API 문서:
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+## 사용법
+
+### FastAPI 통합
+
+```python
+from aidol.api.aidol import AIdolRouter
+from aidol.api.companion import CompanionRouter
+from aidol.factories import AIdolRepositoryFactory, CompanionRepositoryFactory
+
+# AIdol 라우터
+aidol_router = AIdolRouter(
+    repository_factory=AIdolRepositoryFactory(),
+    openai_settings=openai_settings,
+    image_storage=image_storage,
+)
+
+# Companion 라우터
+companion_router = CompanionRouter(
+    repository_factory=CompanionRepositoryFactory(),
+)
+
+app.include_router(aidol_router.router, prefix="/api/aidol")
+app.include_router(companion_router.router, prefix="/api/aidol")
+```
+
+## 개발
+
+```bash
+poetry install
+make lint
+make type-check
+make unit-test
+make format
+```
+
+## 환경 변수
+
+### 필수 (이미지 생성 시)
+
+| 변수 | 설명 |
+|------|------|
+| `OPENAI_API_KEY` | OpenAI API 키 |
+
+### 선택
+
+| 변수 | 기본값 | 설명 |
+|------|--------|------|
+| `AIDOL_OPENAI_MODEL` | `gpt-4o-mini` | 채팅 응답 LLM 모델 |
+
+> **참고**: 데이터베이스, 모델 등 추가 설정은 기본값으로 로컬 개발 가능합니다.
+> 변경이 필요한 경우 `aidol/` 내 Settings 클래스를 참고하세요.
+
+## 의존성
+
+- aioia-core (공통 인프라)
+- FastAPI, SQLAlchemy, Pydantic
+- OpenAI (이미지 생성, 채팅)
+- Pillow (이미지 처리)
+
+## 라이선스
+
+Apache 2.0
+

py_aidol-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+aidol/__init__.py,sha256=iMN-aij1k6vElJt0sZQT4QYJjvoD27Q9vtZkQA0TY9c,141
+aidol/api/__init__.py,sha256=skD_w82nT0v1hdKK9BBOycNERexIr8F1BmSmSono4Jk,276
+aidol/api/aidol.py,sha256=DQzwF41bnfw8JpcrZlV3XDkvuH5AszyYCJwOmcRxTKg,6684
+aidol/api/companion.py,sha256=QBsPgSjBp1USunB6Jth6fdWLwBzsI6KIq6XQZu9OifQ,6287
+aidol/factories.py,sha256=HYkJN9qu1fZOgLW6hk3t0Ixh41mVB4tzzmOQQcso9tA,698
+aidol/models/__init__.py,sha256=nlmLezsKx1xGdJkKANkOj3QCZQVPniXkYwQBsj8Ockk,155
+aidol/models/aidol.py,sha256=0t1OJiJBnmhpRCYczmsr1aYD8pMZqE3wKaUWIQiymKM,750
+aidol/models/companion.py,sha256=F64BejN3ZWP4EyNDBiV0s63dofsAgMVZJi55JV0b5gk,954
+aidol/protocols.py,sha256=Zc9LWUcdHJlerI649v3maXbgXARiXrBiRd2cxNLnSDE,2667
+aidol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aidol/repositories/__init__.py,sha256=hJbn-Pw0iGMMIYkUbEqLOy-gK_0LqCJLBba21pmZ0Pw,207
+aidol/repositories/aidol.py,sha256=zwgXB823EZsrYYoJn2S05VD1bcuhSlcwnlVCJoD09p0,1744
+aidol/repositories/companion.py,sha256=xzAHrdCexT4cXFPTg3yCmWoqou8edeZO0A22ozMieFg,1775
+aidol/schemas/__init__.py,sha256=dakC_xvl4akjGRSOJdFnB1k6_RbNplGnPzEwI_7wwKA,661
+aidol/schemas/aidol.py,sha256=aTS7hx4BGUvLDMgqo3CGVY_867GO0vnAeJhRFntGG1g,3834
+aidol/schemas/companion.py,sha256=SCjvNETAZII256o0myCp6q1wzp999JIO99q8cKf8Yo0,3224
+aidol/services/__init__.py,sha256=3vdT_CtUfeDWbsPn7Xnp41sajovcl2nCvpZ8KNFPHYM,144
+aidol/services/image_generation_service.py,sha256=naqOxe5jsSTs9__Nj3gwBtOQPkfWvgqVV4z6XkA6DGM,4359
+py_aidol-0.1.0.dist-info/METADATA,sha256=_c0y1xNNGOGHmKIeSfvCqWmYLPuGfDypFHg7jn8uVoM,2880
+py_aidol-0.1.0.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+py_aidol-0.1.0.dist-info/RECORD,,

py_aidol-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.0
+Root-Is-Purelib: true
+Tag: py3-none-any