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

aidol/api/aidol.py

@@ -1,3 +1,4 @@
+# pylint: disable=duplicate-code
 """
 AIdol API router
 
@@ -8,32 +9,25 @@ 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 aioia_core.settings import JWTSettings
+from fastapi import APIRouter, Depends, HTTPException, Response, status
 from pydantic import BaseModel
 from sqlalchemy.orm import sessionmaker
 
+from aidol.api.common import register_image_generation_route
 from aidol.protocols import (
     AIdolRepositoryFactoryProtocol,
     AIdolRepositoryProtocol,
     ImageStorageProtocol,
 )
-from aidol.schemas import (
-    AIdol,
-    AIdolCreate,
-    AIdolPublic,
-    AIdolUpdate,
-    ImageGenerationData,
-    ImageGenerationRequest,
-    ImageGenerationResponse,
-)
-from aidol.services import ImageGenerationService
+from aidol.schemas import AIdol, AIdolCreate, AIdolPublic, AIdolUpdate
+from aidol.settings import GoogleGenAISettings
 
 
-class AIdolSingleItemResponse(BaseModel):
-    """Single item response for AIdol (public)."""
+class AIdolCreateResponse(BaseModel):
+    """Response for AIdol creation (only id)."""
 
-    data: AIdolPublic
+    id: str
 
 
 class AIdolRouter(
@@ -48,49 +42,92 @@ class AIdolRouter(
 
     def __init__(
         self,
-        openai_settings: OpenAIAPISettings,
+        google_settings: GoogleGenAISettings | None,
         image_storage: ImageStorageProtocol,
         **kwargs,
     ):
-        super().__init__(**kwargs)
-        self.openai_settings = openai_settings
+        self.google_settings = google_settings
         self.image_storage = image_storage
+        super().__init__(**kwargs)
 
     def _register_routes(self) -> None:
         """Register routes (public CRUD + image generation)"""
-        self._register_image_generation_route()
+        # Register shared image generation route
+        register_image_generation_route(
+            router=self.router,
+            resource_name=self.resource_name,
+            google_settings=self.google_settings,
+            image_storage=self.image_storage,
+        )
+
         self._register_public_create_route()
         self._register_public_get_route()
+        self._register_public_update_route()
+
+    def _register_public_update_route(self) -> None:
+        """PATCH /{resource_name}/{id} - Update AIdol group (public)"""
+
+        @self.router.patch(
+            f"/{self.resource_name}/{{item_id}}",
+            response_model=AIdolPublic,
+            status_code=status.HTTP_200_OK,
+            summary="Update AIdol group",
+            description="Update AIdol group by ID (public endpoint). Returns updated AIdol data directly.",
+            responses={
+                404: {"model": ErrorResponse, "description": "AIdol group not found"},
+            },
+        )
+        async def update_aidol(
+            item_id: str,
+            data: AIdolUpdate,
+            repository: AIdolRepositoryProtocol = Depends(self.get_repository_dep),
+        ):
+            """Update AIdol group."""
+            # TODO: Verify ClaimToken if strict ownership is required (Sprint 1)
+            updated = repository.update(item_id, data)
+            if not updated:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail="AIdol group not found",
+                )
+
+            # Return updated AIdol as public schema
+            return AIdolPublic(**updated.model_dump())
 
     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,
+            response_model=AIdolCreateResponse,
             status_code=status.HTTP_201_CREATED,
             summary="Create AIdol group",
-            description="Create a new AIdol group (public endpoint)",
+            description="Create a new AIdol group (public endpoint). Returns only the created id.",
         )
         async def create_aidol(
             request: AIdolCreate,
+            response: Response,
             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)
+
+            # Set ClaimToken header
+            if created.claim_token:
+                response.headers["ClaimToken"] = created.claim_token
+
+            # Return only id
+            return AIdolCreateResponse(id=created.id)
 
     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,
+            response_model=AIdolPublic,
             status_code=status.HTTP_200_OK,
             summary="Get AIdol group",
-            description="Get AIdol group by ID (public endpoint)",
+            description="Get AIdol group by ID (public endpoint). Returns AIdol data directly.",
             responses={
                 404: {"model": ErrorResponse, "description": "AIdol group not found"},
             },
@@ -101,54 +138,12 @@ class AIdolRouter(
         ):
             """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",
-                )
-            )
+            # Return AIdol as public schema
+            return AIdolPublic(**aidol.model_dump())
 
 
 def create_aidol_router(
-    openai_settings: OpenAIAPISettings,
+    google_settings: GoogleGenAISettings | None,
     db_session_factory: sessionmaker,
     repository_factory: AIdolRepositoryFactoryProtocol,
     image_storage: ImageStorageProtocol,
@@ -161,7 +156,7 @@ def create_aidol_router(
     Create AIdol router with dependency injection.
 
     Args:
-        openai_settings: OpenAI API settings for image generation
+        google_settings: Google API settings (uses ADC if api_key is None)
         db_session_factory: Database session factory
         repository_factory: Factory implementing AIdolRepositoryFactoryProtocol
         image_storage: Image storage for permanent URLs
@@ -174,7 +169,7 @@ def create_aidol_router(
         FastAPI APIRouter instance
     """
     router = AIdolRouter(
-        openai_settings=openai_settings,
+        google_settings=google_settings,
         image_storage=image_storage,
         model_class=AIdol,
         create_schema=AIdolCreate,

aidol/api/common.py

@@ -0,0 +1,72 @@
+"""
+Common API utilities.
+
+Shared functions for registering common routes across different routers.
+"""
+
+from aioia_core.errors import ErrorResponse
+from fastapi import APIRouter, HTTPException, status
+
+from aidol.protocols import ImageStorageProtocol
+from aidol.schemas import (
+    ImageGenerationData,
+    ImageGenerationRequest,
+    ImageGenerationResponse,
+)
+from aidol.services import ImageGenerationService
+from aidol.settings import GoogleGenAISettings
+
+
+def register_image_generation_route(
+    router: APIRouter,
+    resource_name: str,
+    google_settings: GoogleGenAISettings | None,
+    image_storage: ImageStorageProtocol,
+) -> None:
+    """
+    Register image generation route to the given router.
+
+    Args:
+        router: FastAPI APIRouter instance
+        resource_name: Resource name for the route path
+        google_settings: Google API settings (API Key or Vertex AI with ADC)
+        image_storage: Image Storage instance
+    """
+
+    @router.post(
+        f"/{resource_name}/images",
+        response_model=ImageGenerationResponse,
+        status_code=status.HTTP_201_CREATED,
+        summary="Generate image",
+        description=f"Generate image for {resource_name}",
+        responses={
+            500: {"model": ErrorResponse, "description": "Image generation failed"},
+        },
+    )
+    async def generate_image(request: ImageGenerationRequest):
+        """Generate image from prompt."""
+        # Generate and download image
+        service = ImageGenerationService(settings=google_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
+        image_url = image_storage.upload_image(image)
+
+        return ImageGenerationResponse(
+            data=ImageGenerationData(
+                image_url=image_url,
+                width=1024,
+                height=1024,
+                format="png",
+            )
+        )

aidol/api/companion.py

@@ -1,3 +1,4 @@
+# pylint: disable=duplicate-code
 """
 Companion API router
 
@@ -9,21 +10,25 @@ 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 fastapi import APIRouter, Depends, HTTPException, Query, status
 from pydantic import BaseModel
 from sqlalchemy.orm import sessionmaker
 
+from aidol.api.common import register_image_generation_route
 from aidol.protocols import (
     CompanionRepositoryFactoryProtocol,
     CompanionRepositoryProtocol,
+    ImageStorageProtocol,
 )
-from aidol.schemas import Companion, CompanionCreate, CompanionPublic, CompanionUpdate
-
-
-class CompanionSingleItemResponse(BaseModel):
-    """Single item response for Companion (public)."""
-
-    data: CompanionPublic
+from aidol.schemas import (
+    Companion,
+    CompanionCreate,
+    CompanionPublic,
+    CompanionUpdate,
+    Gender,
+)
+from aidol.services.companion_service import to_companion_public
+from aidol.settings import GoogleGenAISettings
 
 
 class CompanionPaginatedResponse(BaseModel):
@@ -45,11 +50,31 @@ class CompanionRouter(
     Returns CompanionPublic (excludes system_prompt) for all responses.
     """
 
+    def __init__(
+        self,
+        google_settings: GoogleGenAISettings | None,
+        image_storage: ImageStorageProtocol,
+        **kwargs,
+    ):
+        self.google_settings = google_settings
+        self.image_storage = image_storage
+        super().__init__(**kwargs)
+
     def _register_routes(self) -> None:
-        """Register routes (public CRUD)"""
+        """Register routes (public CRUD + image generation)"""
+        # Register shared image generation route
+        register_image_generation_route(
+            router=self.router,
+            resource_name=self.resource_name,
+            google_settings=self.google_settings,
+            image_storage=self.image_storage,
+        )
+
         self._register_public_list_route()
         self._register_public_create_route()
         self._register_public_get_route()
+        self._register_public_update_route()
+        self._register_public_delete_route()
 
     def _register_public_list_route(self) -> None:
         """GET /{resource_name} - List Companions (public)"""
@@ -59,33 +84,48 @@ class CompanionRouter(
             response_model=CompanionPaginatedResponse,
             status_code=status.HTTP_200_OK,
             summary="List Companions",
-            description="List all Companions with optional filtering (public endpoint)",
+            description="List all Companions with optional filtering by gender and cast status",
         )
         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)",
+            gender: Gender | None = Query(None, description="Filter by gender"),
+            is_cast: bool | None = Query(
+                None, alias="isCast", description="Filter by cast status"
             ),
+            aidol_id: str | None = Query(None, description="Filter by AIdol Group ID"),
             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)
+            """List Companions with optional gender and isCast filters."""
+            filter_list: list[dict] = []
+
+            # Add filters only if provided
+            if gender is not None:
+                filter_list.append(
+                    {"field": "gender", "operator": "eq", "value": gender.value}
+                )
+
+            # Filter by aidol_id if provided
+            if aidol_id is not None:
+                filter_list.append(
+                    {"field": "aidol_id", "operator": "eq", "value": aidol_id}
+                )
+
+            # isCast is derived from aidol_id presence
+            # isCast=true → aidol_id is not null (belongs to a group)
+            # isCast=false → aidol_id is null (not in a group)
+            if is_cast is True:
+                filter_list.append(
+                    {"field": "aidol_id", "operator": "ne", "value": None}
+                )
+            elif is_cast is False:
+                filter_list.append(
+                    {"field": "aidol_id", "operator": "eq", "value": None}
+                )
+
             items, total = repository.get_all(
-                current=current,
-                page_size=page_size,
-                sort=sort_list,
-                filters=filter_list,
+                filters=filter_list if filter_list else None,
             )
             # Convert to Public schema (exclude system_prompt)
-            public_items = [CompanionPublic(**c.model_dump()) for c in items]
+            public_items = [to_companion_public(c) for c in items]
             return CompanionPaginatedResponse(data=public_items, total=total)
 
     def _register_public_create_route(self) -> None:
@@ -93,30 +133,33 @@ class CompanionRouter(
 
         @self.router.post(
             f"/{self.resource_name}",
-            response_model=CompanionSingleItemResponse,
+            response_model=CompanionPublic,
             status_code=status.HTTP_201_CREATED,
             summary="Create Companion",
-            description="Create a new Companion (public endpoint)",
+            description="Create a new Companion. Returns the created companion data.",
         )
         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)
+            # Exclude system_prompt from request - should not be set via API
+            sanitized_data = request.model_dump(exclude={"system_prompt"})
+            sanitized_request = CompanionCreate(**sanitized_data)
+
+            created = repository.create(sanitized_request)
+            # Return created companion as public schema
+            return to_companion_public(created)
 
     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,
+            response_model=CompanionPublic,
             status_code=status.HTTP_200_OK,
             summary="Get Companion",
-            description="Get Companion by ID (public endpoint)",
+            description="Get Companion by ID (public endpoint). Returns companion data directly.",
             responses={
                 404: {"model": ErrorResponse, "description": "Companion not found"},
             },
@@ -127,14 +170,85 @@ class CompanionRouter(
         ):
             """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)
+            # Return companion as public schema
+            return to_companion_public(companion)
+
+    def _register_public_update_route(self) -> None:
+        """PATCH /{resource_name}/{id} - Update Companion (public)"""
+
+        @self.router.patch(
+            f"/{self.resource_name}/{{item_id}}",
+            response_model=CompanionPublic,
+            status_code=status.HTTP_200_OK,
+            summary="Update Companion",
+            description="Update Companion by ID (public endpoint). Returns updated companion data directly.",
+            responses={
+                404: {"model": ErrorResponse, "description": "Companion not found"},
+            },
+        )
+        async def update_companion(
+            item_id: str,
+            data: CompanionUpdate,
+            repository: CompanionRepositoryProtocol = Depends(self.get_repository_dep),
+        ):
+            """Update Companion."""
+            # Exclude system_prompt from request - should not be set via API
+            sanitized_data = data.model_dump(
+                exclude={"system_prompt"}, exclude_unset=True
+            )
+            sanitized_request = CompanionUpdate(**sanitized_data)
+
+            updated = repository.update(item_id, sanitized_request)
+            if not updated:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail="Companion not found",
+                )
+
+            # Return updated companion as public schema
+            return to_companion_public(updated)
+
+    def _register_public_delete_route(self) -> None:
+        """DELETE /{resource_name}/{id} - Remove Companion from Group (public)"""
+
+        @self.router.delete(
+            f"/{self.resource_name}/{{item_id}}",
+            response_model=CompanionPublic,
+            status_code=status.HTTP_200_OK,
+            summary="Remove Companion from Group",
+            description="Remove Companion from AIdol group (unassign aidol_id). Does not delete the record.",
+            responses={
+                404: {"model": ErrorResponse, "description": "Companion not found"},
+            },
+        )
+        async def delete_companion(
+            item_id: str,
+            repository: CompanionRepositoryProtocol = Depends(self.get_repository_dep),
+        ):
+            """Remove Companion from Group (Unassign)."""
+            # Get item first
+            self._get_item_or_404(repository, item_id)
+
+            # Update aidol_id to None (remove from group)
+            update_data = CompanionUpdate(aidol_id=None)
+
+            updated = repository.update(item_id, update_data)
+
+            if not updated:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail="Companion not found",
+                )
+
+            # Return updated companion as public schema
+            return to_companion_public(updated)
 
 
 def create_companion_router(
+    google_settings: GoogleGenAISettings | None,
     db_session_factory: sessionmaker,
     repository_factory: CompanionRepositoryFactoryProtocol,
+    image_storage: ImageStorageProtocol,
     jwt_settings: JWTSettings | None = None,
     user_info_provider: UserInfoProvider | None = None,
     resource_name: str = "companions",
@@ -144,8 +258,10 @@ def create_companion_router(
     Create Companion router with dependency injection.
 
     Args:
+        google_settings: Google API settings (uses ADC if api_key is None)
         db_session_factory: Database session factory
         repository_factory: Factory implementing CompanionRepositoryFactoryProtocol
+        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: "companions")
@@ -155,6 +271,8 @@ def create_companion_router(
         FastAPI APIRouter instance
     """
     router = CompanionRouter(
+        google_settings=google_settings,
+        image_storage=image_storage,
         model_class=Companion,
         create_schema=CompanionCreate,
         update_schema=CompanionUpdate,

aidol/api/lead.py

@@ -0,0 +1,123 @@
+"""
+Lead API router
+
+Public endpoints for collecting leads (emails).
+"""
+
+from typing import Annotated
+
+from aioia_core.fastapi import BaseCrudRouter
+from aioia_core.settings import JWTSettings
+from fastapi import APIRouter, Depends, Header, status
+from pydantic import BaseModel
+from sqlalchemy.orm import Session, sessionmaker
+
+from aidol.protocols import (
+    AIdolLeadRepositoryFactoryProtocol,
+    AIdolLeadRepositoryProtocol,
+    AIdolRepositoryFactoryProtocol,
+    NoUpdate,
+)
+from aidol.schemas import AIdolLead, AIdolLeadCreate, AIdolUpdate
+
+
+class LeadResponse(BaseModel):
+    """Response for lead creation."""
+
+    email: str
+
+
+class LeadRouter(
+    BaseCrudRouter[AIdolLead, AIdolLeadCreate, NoUpdate, AIdolLeadRepositoryProtocol]
+):
+    """
+    Lead router.
+
+    Handles email collection.
+    """
+
+    def __init__(
+        self,
+        aidol_repository_factory: AIdolRepositoryFactoryProtocol,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.aidol_repository_factory = aidol_repository_factory
+
+    def _register_routes(self) -> None:
+        """Register routes."""
+        self._register_create_lead_route()
+
+    def _register_create_lead_route(self) -> None:
+        """POST /leads - Collect email"""
+
+        @self.router.post(
+            f"/{self.resource_name}",
+            response_model=LeadResponse,
+            status_code=status.HTTP_201_CREATED,
+            summary="Collect Lead",
+            description="Collect email. Associates with AIdol if ClaimToken is valid.",
+        )
+        async def create_lead(
+            request: AIdolLeadCreate,
+            claim_token: Annotated[str | None, Header(alias="ClaimToken")] = None,
+            db_session: Session = Depends(self.get_db_dep),
+            lead_repository: AIdolLeadRepositoryProtocol = Depends(
+                self.get_repository_dep
+            ),
+        ):
+            """Collect email."""
+            email_saved = False
+
+            # 1. Try to associate with AIdol if token is present
+            if claim_token:
+                # Reuse session from dependency
+                aidol_repo = self.aidol_repository_factory.create_repository(db_session)
+
+                # Find AIdol by claim_token
+                # Assuming get_all supports filters
+                items, _ = aidol_repo.get_all(
+                    filters=[
+                        {
+                            "field": "claim_token",
+                            "operator": "eq",
+                            "value": claim_token,
+                        }
+                    ]
+                )
+
+                if items:
+                    aidol = items[0]
+                    # Update AIdol email
+                    aidol_repo.update(aidol.id, AIdolUpdate(email=request.email))
+                    email_saved = True
+
+            # 2. If not saved as AIdol email, create Lead
+            if not email_saved:
+                lead_repository.create(request)
+
+            return LeadResponse(email=request.email)
+
+
+def create_lead_router(
+    db_session_factory: sessionmaker,
+    aidol_repository_factory: AIdolRepositoryFactoryProtocol,
+    lead_repository_factory: AIdolLeadRepositoryFactoryProtocol,
+    jwt_settings: JWTSettings | None = None,
+    resource_name: str = "leads",
+    tags: list[str] | None = None,
+) -> APIRouter:
+    """Create Lead router."""
+    router = LeadRouter(
+        model_class=AIdolLead,
+        create_schema=AIdolLeadCreate,
+        update_schema=NoUpdate,  # Update not supported
+        db_session_factory=db_session_factory,
+        repository_factory=lead_repository_factory,
+        aidol_repository_factory=aidol_repository_factory,
+        user_info_provider=None,  # No auth required for lead collection
+        jwt_secret_key=jwt_settings.secret_key if jwt_settings else None,
+        resource_name=resource_name,
+        tags=tags or ["Lead"],
+    )
+    return router.get_router()

aidol/factories.py

@@ -7,6 +7,7 @@ Uses BaseRepositoryFactory for BaseCrudRouter compatibility.
 from aioia_core.factories import BaseRepositoryFactory
 
 from aidol.repositories.aidol import AIdolRepository
+from aidol.repositories.aidol_lead import AIdolLeadRepository
 from aidol.repositories.companion import CompanionRepository
 
 
@@ -22,3 +23,10 @@ class CompanionRepositoryFactory(BaseRepositoryFactory[CompanionRepository]):
 
     def __init__(self):
         super().__init__(repository_class=CompanionRepository)
+
+
+class AIdolLeadRepositoryFactory(BaseRepositoryFactory[AIdolLeadRepository]):
+    """Factory for creating AIdolLead repositories."""
+
+    def __init__(self):
+        super().__init__(repository_class=AIdolLeadRepository)

aidol/protocols.py

@@ -11,11 +11,14 @@ from typing import Protocol
 
 import PIL.Image
 from aioia_core import CrudRepositoryProtocol
+from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
 from aidol.schemas import (
     AIdol,
     AIdolCreate,
+    AIdolLead,
+    AIdolLeadCreate,
     AIdolUpdate,
     Companion,
     CompanionCreate,
@@ -23,6 +26,10 @@ from aidol.schemas import (
 )
 
 
+class NoUpdate(BaseModel):
+    """Placeholder for repositories without update support."""
+
+
 class AIdolRepositoryProtocol(
     CrudRepositoryProtocol[AIdol, AIdolCreate, AIdolUpdate], Protocol
 ):
@@ -98,3 +105,22 @@ class ImageStorageProtocol(Protocol):
             image: PIL Image object to upload.
         """
         ...
+
+
+class AIdolLeadRepositoryProtocol(
+    CrudRepositoryProtocol[AIdolLead, AIdolLeadCreate, NoUpdate], Protocol
+):
+    """Protocol defining AIdolLead repository expectations.
+
+    Inherits CRUD operations from CrudRepositoryProtocol.
+    """
+
+
+class AIdolLeadRepositoryFactoryProtocol(Protocol):
+    """Protocol for factory that creates AIdolLeadRepositoryProtocol instances."""
+
+    def create_repository(
+        self, db_session: Session | None = None
+    ) -> AIdolLeadRepositoryProtocol:
+        """Create a repository instance."""
+        ...

aidol/repositories/aidol_lead.py

@@ -7,17 +7,13 @@ Implements BaseRepository pattern for BaseCrudRouter compatibility.
 from datetime import timezone
 
 from aioia_core.repositories import BaseRepository
-from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
 from aidol.models import DBAIdolLead
+from aidol.protocols import AIdolLeadRepositoryProtocol, NoUpdate
 from aidol.schemas import AIdolLead, AIdolLeadCreate
 
 
-class _AIdolLeadUpdate(BaseModel):
-    """Placeholder for update schema (not used)."""
-
-
 def _convert_db_aidol_lead_to_model(db_lead: DBAIdolLead) -> AIdolLead:
     """Convert DB AIdolLead to Pydantic model."""
     return AIdolLead(
@@ -35,7 +31,8 @@ def _convert_aidol_lead_create_to_db(schema: AIdolLeadCreate) -> dict:
 
 
 class AIdolLeadRepository(
-    BaseRepository[AIdolLead, DBAIdolLead, AIdolLeadCreate, _AIdolLeadUpdate]
+    BaseRepository[AIdolLead, DBAIdolLead, AIdolLeadCreate, NoUpdate],
+    AIdolLeadRepositoryProtocol,
 ):
     """
     Database-backed AIdolLead repository.

aidol/services/companion_service.py

@@ -0,0 +1,96 @@
+"""
+Companion service
+
+Business logic for Companion operations including grade and MBTI calculation.
+"""
+
+from aidol.schemas.companion import Companion, CompanionPublic, CompanionStats, Grade
+
+
+def calculate_grade(stats: CompanionStats) -> Grade:
+    """Calculate grade based on stats average.
+
+    - A: 80-100
+    - B: 60-79
+    - C: 40-59
+    - F: 0-39
+    """
+    avg = (
+        (stats.vocal or 0)
+        + (stats.dance or 0)
+        + (stats.rap or 0)
+        + (stats.visual or 0)
+        + (stats.stamina or 0)
+        + (stats.charm or 0)
+    ) / 6
+    if avg >= 80:
+        return Grade.A
+    if avg >= 60:
+        return Grade.B
+    if avg >= 40:
+        return Grade.C
+    return Grade.F
+
+
+def calculate_mbti(
+    energy: int | None,
+    perception: int | None,
+    judgment: int | None,
+    lifestyle: int | None,
+) -> str | None:
+    """Calculate MBTI string from 4 dimension scores.
+
+    Each score is 1-10:
+    - energy: 1-5 = E, 6-10 = I
+    - perception: 1-5 = N, 6-10 = S
+    - judgment: 1-5 = T, 6-10 = F
+    - lifestyle: 1-5 = P, 6-10 = J
+
+    Returns None if any dimension is missing.
+    """
+    if any(v is None for v in (energy, perception, judgment, lifestyle)):
+        return None
+
+    assert energy is not None
+    assert perception is not None
+    assert judgment is not None
+    assert lifestyle is not None
+
+    e_i = "E" if energy <= 5 else "I"
+    n_s = "N" if perception <= 5 else "S"
+    t_f = "T" if judgment <= 5 else "F"
+    p_j = "P" if lifestyle <= 5 else "J"
+
+    return f"{e_i}{n_s}{t_f}{p_j}"
+
+
+def to_companion_public(companion: Companion) -> CompanionPublic:
+    """Convert Companion to CompanionPublic with calculated grade and mbti."""
+    # Build stats object
+    stats = companion.stats if companion.stats else CompanionStats()
+
+    # Calculate grade from stats
+    grade = calculate_grade(stats)
+
+    # Calculate MBTI from 4 dimensions
+    mbti = calculate_mbti(
+        companion.mbti_energy,
+        companion.mbti_perception,
+        companion.mbti_judgment,
+        companion.mbti_lifestyle,
+    )
+
+    return CompanionPublic(
+        id=companion.id,
+        aidol_id=companion.aidol_id,
+        name=companion.name,
+        gender=companion.gender,
+        grade=grade,
+        biography=companion.biography,
+        profile_picture_url=companion.profile_picture_url,
+        position=companion.position,
+        mbti=mbti,
+        stats=stats,
+        created_at=companion.created_at,
+        updated_at=companion.updated_at,
+    )

aidol/services/image_generation_service.py

@@ -1,145 +1,112 @@
 """
-Image generation service for AIdol
+Image generation service for AIdol.
 
-Generates images using OpenAI DALL-E 3 for AIdol emblems and Companion profiles.
+Generates images using Google Gemini for AIdol emblems and Companion profiles.
 """
 
+from __future__ import annotations
+
 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
+from google import genai
+from google.genai import errors as genai_errors
+
+from aidol.settings import GoogleGenAISettings
 
 logger = logging.getLogger(__name__)
 
 
 @dataclass
 class ImageGenerationResponse:
-    """Structured response from the Image Generation service"""
+    """Structured response for compatibility (legacy)"""
 
-    url: str
-    revised_prompt: str | None
+    url: str | None = None
+    revised_prompt: str | None = None
 
 
 class ImageGenerationService:
-    """Service for generating images using OpenAI DALL-E 3"""
+    """Service for generating images using Google Gemini 3 (Imagen)."""
 
-    def __init__(self, openai_settings: OpenAIAPISettings):
-        """
-        Initialize the Image Generation service with OpenAI settings.
+    client: "genai.Client | None" = None
 
-        Args:
-            openai_settings: OpenAI settings containing required API key
+    def __init__(self, settings: GoogleGenAISettings | None = None):
         """
-        self.settings = openai_settings
-        self.client = openai.OpenAI(api_key=self.settings.api_key)
+        Initialize the Image Generation service.
 
-    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.
+        Supports two authentication methods:
+        1. Google AI API: settings.api_key
+        2. Vertex AI API (ADC): settings.cloud_project (location=global hardcoded)
 
         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.
+            settings: GoogleGenAISettings for configuration.
         """
-        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,
+        # Priority 1: Settings with api_key (Google AI API)
+        if settings and settings.api_key:
+            self.client = genai.Client(api_key=settings.api_key)
+        # Priority 2: Settings with cloud_project (Vertex AI, location=global)
+        elif settings and settings.cloud_project:
+            self.client = genai.Client(
+                vertexai=True,
+                project=settings.cloud_project,
+                location="global",
             )
-
-            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,
+        else:
+            logger.error(
+                "No authentication configured. "
+                "Set GOOGLE_API_KEY or GOOGLE_CLOUD_PROJECT"
             )
-
-        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))
+            self.client = None
 
     def generate_and_download_image(
         self,
         prompt: str,
-        size: Literal[
-            "1024x1024",
-            "1792x1024",
-            "1024x1792",
-        ] = "1024x1024",
-        quality: Literal["standard", "hd"] = "standard",
+        size: Literal["1024x1024"] = "1024x1024",  # pylint: disable=unused-argument
+        quality: Literal["standard"] = "standard",  # pylint: disable=unused-argument
     ) -> 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.
+        """
+        Generate an image using Gemini 3 and return as PIL Image.
 
         Args:
-            prompt: Text description of the image to generate.
-            size: Image size (default: "1024x1024").
-            quality: Image quality "standard" or "hd" (default: "standard").
+            prompt: Text description.
+            size: Ignored (Gemini specific).
+            quality: Ignored (Gemini specific).
 
         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:
+        if not self.client:
+            logger.error("Gemini client not initialized")
+            return None
+
+        try:
+            logger.info("Generating image with Gemini 3 (prompt: %s)...", prompt[:50])
+
+            response = self.client.models.generate_content(
+                model="gemini-3-pro-image-preview",
+                contents=[prompt],  # type: ignore[arg-type]
+            )
+
+            # Iterate parts to find the image
+            if response.parts:
+                for part in response.parts:
+                    if part.inline_data and part.inline_data.data:
+                        logger.info("Successfully generated image via Gemini.")
+                        # Manually convert bytes to PIL Image to ensure it's a standard PIL object
+                        # compatible with main.py's save(format="PNG") call.
+                        return PIL.Image.open(BytesIO(part.inline_data.data))
+
+            logger.warning("No image data found in Gemini response.")
+            return None
+
+        except genai_errors.APIError as e:
+            logger.error("Gemini API error: code=%s, message=%s", e.code, e.message)
             return None
 
-        logger.info("Downloading image from DALL-E temporary URL...")
-        return self._download_image(result.url)
+    # Legacy methods for compatibility if needed (can be removed or shimmed)
+    def generate_image(self, *args, **kwargs):  # pylint: disable=unused-argument
+        """Deprecated: Use generate_and_download_image instead."""
+        logger.warning("generate_image is deprecated for Gemini service.")

aidol/settings.py

@@ -0,0 +1,37 @@
+"""
+Environment settings for aidol module.
+
+Provides GoogleGenAISettings for image generation with Google Gemini.
+"""
+
+from pydantic_settings import BaseSettings
+
+
+class GoogleGenAISettings(BaseSettings):
+    """
+    Google Gen AI SDK settings for Gemini image generation.
+
+    Supports two authentication methods:
+    1. Google AI API: GOOGLE_API_KEY
+    2. Vertex AI API (ADC): GOOGLE_CLOUD_PROJECT
+
+    For Google AI API:
+        export GOOGLE_API_KEY=your-api-key
+
+    For Vertex AI with ADC:
+        export GOOGLE_CLOUD_PROJECT=your-project-id
+        gcloud auth application-default login
+
+    Note: Vertex AI uses location="global" (hardcoded) because
+    Gemini image generation models only support the global endpoint.
+
+    Environment variables:
+        GOOGLE_API_KEY: Google API key (optional)
+        GOOGLE_CLOUD_PROJECT: GCP project ID for Vertex AI (optional)
+    """
+
+    api_key: str | None = None
+    cloud_project: str | None = None
+
+    class Config:
+        env_prefix = "GOOGLE_"

{py_aidol-0.2.0.dist-info → py_aidol-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-aidol
-Version: 0.2.0
+Version: 0.4.0
 Summary: Create and chat with your own AI idol group
 License: Apache-2.0
 Keywords: kpop,idol,aidol,ai-companion,chatbot,image-generation
@@ -14,6 +14,7 @@ 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: google-genai (>=1.60.0,<2.0.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)
@@ -33,7 +34,7 @@ AI 아이돌 그룹 생성 및 채팅 Python 패키지
 ## 주요 기능
 
 - AI 아이돌 그룹/멤버 CRUD
-- DALL-E 3 이미지 생성 (엠블럼, 프로필)
+- Google Gemini 이미지 생성 (엠블럼, 프로필)
 - 텍스트 채팅 (페르소나 기반 응답)
 - Buppy 통합 Adapter 패턴
 
@@ -61,7 +62,7 @@ from aidol.factories import AIdolRepositoryFactory, CompanionRepositoryFactory
 # AIdol 라우터
 aidol_router = AIdolRouter(
     repository_factory=AIdolRepositoryFactory(),
-    openai_settings=openai_settings,
+    google_settings=google_settings,
     image_storage=image_storage,
 )
 
@@ -86,11 +87,27 @@ make format
 
 ## 환경 변수
 
-### 필수 (이미지 생성 시)
+### 이미지 생성 인증 (선택, ADC 지원)
 
 | 변수 | 설명 |
 |------|------|
-| `OPENAI_API_KEY` | OpenAI API 키 |
+| `GOOGLE_API_KEY` | Google API 키 (Google AI API) |
+| `GOOGLE_CLOUD_PROJECT` | GCP 프로젝트 ID (Vertex AI) |
+
+**인증 방법:**
+
+**Option 1: Google AI API (API Key)**
+```bash
+export GOOGLE_API_KEY=your-api-key
+```
+
+**Option 2: Vertex AI (ADC)**
+```bash
+export GOOGLE_CLOUD_PROJECT=your-project-id
+gcloud auth application-default login  # 로컬 개발
+```
+
+> **참고**: Vertex AI 사용 시 `location=global`이 하드코딩되어 있습니다 (Gemini 이미지 생성 모델 요구사항).
 
 ### 선택
 
@@ -105,7 +122,8 @@ make format
 
 - aioia-core (공통 인프라)
 - FastAPI, SQLAlchemy, Pydantic
-- OpenAI (이미지 생성, 채팅)
+- Google Generative AI (이미지 생성)
+- OpenAI (채팅)
 - Pillow (이미지 처리)
 
 ## 라이선스

{py_aidol-0.2.0.dist-info → py_aidol-0.4.0.dist-info}/RECORD

@@ -1,24 +1,28 @@
 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/api/aidol.py,sha256=AIpDMTTOxht1eEVk4YITvmJzvklpYlDTpQVrIuSjeUw,6588
+aidol/api/common.py,sha256=w8ERo96t9tat4HPs1qw9JhyoJ8cj5crHCe92Hp3Usug,2198
+aidol/api/companion.py,sha256=Nlx4QHqoi0y_CMczEh75n8C4xJTWp8eV1BqHjEzkOFw,10840
+aidol/api/lead.py,sha256=RSf3GcIUVJu752rU9HG7Wy22UmnrRZnN_NGWkpTRDfE,3921
+aidol/factories.py,sha256=5VhEbUVQEo-WruOdDauOi9xGgMxrgT339glocC1ua4o,983
 aidol/models/__init__.py,sha256=AljQMgSE9vHx203NFQZMknKpzHIfyFLLcOMnFpMOLAs,218
 aidol/models/aidol.py,sha256=By82BqiAasLNy8ZCNON2m46BnSCfL2J_ZFLO6_MMFO0,903
 aidol/models/aidol_lead.py,sha256=xCa1AqJdBBeW2Edcj1pK-cXbX5oatxzCOkPyqEGBXVw,619
 aidol/models/companion.py,sha256=fom58GXjGvAxxndS4X4MrT1HWNw8Ps99BNEyPd5JhW0,1974
-aidol/protocols.py,sha256=Zc9LWUcdHJlerI649v3maXbgXARiXrBiRd2cxNLnSDE,2667
+aidol/protocols.py,sha256=8-7iwbtMv5vQUAYGRbbKvm6YfYZZ1VZz6dufse_DYp4,3375
 aidol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 aidol/repositories/__init__.py,sha256=4kE68a-eRhXt9z5a2XCn1_2s-p3VMpQIdL3oRDb1Ns0,296
 aidol/repositories/aidol.py,sha256=-hf7WW_sDx4vE9bHzKQnzfkgu-on7sqOem9gFO8x0EE,1810
-aidol/repositories/aidol_lead.py,sha256=g15VJwOI-w_a1fe0OzSUUC0zdfqKSR2JHqywdcOvTfU,1516
+aidol/repositories/aidol_lead.py,sha256=vmCHXdTtxDSiRpd_n7DuyecZDPLls56r0N5vyT_v9zI,1488
 aidol/repositories/companion.py,sha256=dUkJA0me2kmxqk3B4L0w4ENcHeAQFw5ki6RvZ5eLHDg,2877
 aidol/schemas/__init__.py,sha256=sNurP-s24PgS4ZJ7xusZ7Z7wXtl1rdsnAxxdeubRXHE,923
 aidol/schemas/aidol.py,sha256=wOfHaLu4I56elLLj6A3CGriPZE4Pz4fFAyC3emtvaCE,4135
 aidol/schemas/aidol_lead.py,sha256=JS8U-ep0Ga6x0PdwXhJfTrcOCKgG0wfFW8pN5X35GUM,1070
 aidol/schemas/companion.py,sha256=I4hi4LT-S9AC7lqt1jyYfd0vSqYmxYNm2k9EsZdyNyM,7584
 aidol/services/__init__.py,sha256=3vdT_CtUfeDWbsPn7Xnp41sajovcl2nCvpZ8KNFPHYM,144
-aidol/services/image_generation_service.py,sha256=naqOxe5jsSTs9__Nj3gwBtOQPkfWvgqVV4z6XkA6DGM,4359
-py_aidol-0.2.0.dist-info/METADATA,sha256=oVVlTXIUXp2BPT61cQnQLav5lozJwul0H0SOOWJdrpc,2880
-py_aidol-0.2.0.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
-py_aidol-0.2.0.dist-info/RECORD,,
+aidol/services/companion_service.py,sha256=tNNWiIFmJQ-I3UBW06baOANXhBx5oTKoT6nkqfnDisA,2490
+aidol/services/image_generation_service.py,sha256=zDs9HP_JckHFJJZUIo2ADSsHGppat-8V-ttu8DlN-BU,3862
+aidol/settings.py,sha256=7oI3Vn1iGXvLRRahJ1ygD6qIu-BvZmlVvvMQxnsq1kc,1003
+py_aidol-0.4.0.dist-info/METADATA,sha256=FI4-Xdaxi36hwykQQGgmttCOlsFOlSh_NzCluamZIvA,3431
+py_aidol-0.4.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+py_aidol-0.4.0.dist-info/RECORD,,

{py_aidol-0.2.0.dist-info → py_aidol-0.4.0.dist-info}/WHEEL

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