Utilized two models and faliover for retreieving image meta data

AI_USAGE_REPORT.txt

@@ -1,359 +1,136 @@
 ================================================================================
-                        AI USAGE REPORT
+                        AI USAGE REPORT (SUMMARY)
            Cloudzy AI Challenge - Photo Album Management System
 ================================================================================
 
 PROJECT OVERVIEW
 ================
-This project implements an AI-enhanced photo management system that uses machine learning
-models for generating embeddings and AI summaries for photo clusters. The system allows
-users to upload photos, search by similarity, and organize them into meaningful albums
-with AI-generated summaries.
+AI-enhanced photo management system with semantic search, album summarization,
+and image generation capabilities.
 
 ================================================================================
-1. WHERE AND HOW AI WAS USED
+AI MODELS USED
 ================================================================================
 
-A. IMAGE EMBEDDING GENERATION
-Location: cloudzy/ai_utils.py - ImageEmbeddingGenerator class
-Purpose: Convert photo metadata (tags, description, caption) into 1024-dimensional
-         vector embeddings for similarity search
+1. IMAGE EMBEDDING: intfloat/multilingual-e5-large
+   - Location: cloudzy/ai_utils.py (ImageEmbeddingGenerator)
+   - Purpose: Convert photo metadata into 1024-d vectors for similarity search
+   - Used in: Photo upload, semantic search, album clustering
 
-Model Used:
-- Provider: Hugging Face Hub (InferenceClient)
-- Model Name: intfloat/multilingual-e5-large
-- Endpoint: feature_extraction
+2. SUMMARIZATION: facebook/bart-large-cnn
+   - Location: cloudzy/ai_utils.py (TextSummarizer)
+   - Purpose: Generate summaries of photo clusters
+   - Used in: /albums endpoint (creates album descriptions)
 
-How It's Used:
-1. User uploads photo with metadata (tags, caption, description)
-2. metadata is combined into a single text string
-3. Text is sent to HF model via InferenceClient.feature_extraction()
-4. Model returns 1024-d embedding vector
-5. Embedding is stored in FAISS index for similarity search
+3. IMAGE ANALYSIS: Google Gemini 2.0-flash
+   - Location: cloudzy/agents/image_analyzer_2.py (ImageAnalyzerAgent)
+   - Purpose: Analyze images and generate detailed descriptions
+   - Used in: /generate-similar-image endpoint (Step 1)
 
-Integration Points:
-- cloudzy/routes/upload.py: Called during photo upload
-- cloudzy/search_engine.py: Used for vector similarity search
-- Database: Embeddings stored as numpy arrays
-
-B. AI SUMMARY GENERATION
-Location: cloudzy/ai_utils.py - TextSummarizer class
-Purpose: Generate meaningful summaries of photo clusters based on actual photo metadata
-
-Model Used:
-- Provider: Hugging Face Hub (InferenceClient)
-- Model Name: facebook/bart-large-cnn
-- Endpoint: summarization
-
-How It's Used:
-1. User requests /albums endpoint
-2. System retrieves all photo clusters
-3. For each cluster, collects all captions and tags from photos
-4. Combined metadata is sent to BART summarization model
-5. Model generates concise summary (e.g., "A collection of indoor photos featuring...")
-6. Summary replaces placeholder "Cluster of similar photos" in response
-
-Integration Points:
-- cloudzy/routes/photo.py: get_albums() endpoint
-- Response Schema: Pydantic AlbumItem model
-- Fallback: If summarization fails, returns truncated text
-
-================================================================================
-2. PROMPTS AND MODEL INPUTS
-================================================================================
-
-A. IMAGE EMBEDDING INPUTS
-Raw Input Format:
-  tags: List[str] = ["nature", "sunset", "beach"]
-  description: str = "A beautiful sunset at the beach with waves"
-  caption: str = "Sunset beach scene"
-
-Processing:
-  Combined Text = " ".join(tags) + " " + description + " " + caption
-  Example: "nature sunset beach A beautiful sunset at the beach with waves Sunset beach scene"
-
-Model Request (Hugging Face InferenceClient):
-  client.feature_extraction(
-      text=combined_text,
-      model="intfloat/multilingual-e5-large"
-  )
-
-Expected Output:
-  - Type: List of floats (1024 dimensions)
-  - Converted to: numpy.ndarray of shape (1024,)
-  - Data type: float32
-  - Usage: Stored in FAISS index for vector similarity search
-
-B. SUMMARIZATION INPUTS
-Raw Input Format:
-  For each album cluster, combine all photo metadata:
-  texts = []
-  for photo in cluster_photos:
-      texts.append(photo.caption)
-      texts.extend(photo.tags)
-  combined_input = " ".join(texts)
-
-Example Input:
-  "Beach sunset waves ocean Sunset at the ocean view Nature landscape
-   Seascape beautiful A sunset scene with ocean waves A scenic beach view"
-
-Model Request (Hugging Face InferenceClient):
-  client.summarization(
-      text=combined_input,
-      model="facebook/bart-large-cnn"
-  )
-
-Expected Output:
-  - Type: List containing dictionary with 'summary_text' key
-  - Example: "A collection of beach and sunset photographs featuring scenic ocean views"
-  - Processing: Extract summary_text from returned object
-  - Type Conversion: Ensure string type for Pydantic validation
-
-================================================================================
-3. HOW MODEL OUTPUTS WERE REFINED
-================================================================================
-
-A. EMBEDDING OUTPUT REFINEMENT
-Issue Encountered:
-  - Expected shape: (512,) per documentation
-  - Actual shape: (1024,) from model
-  - Initial: Validation checked for 1024 but comment said 512
-
-Resolution:
-  - Updated validation to expect 1024 dimensions (correct model behavior)
-  - Converged to: if embedding.shape[0] != 1024: raise ValueError
-  - Added type casting: np.array(result, dtype=np.float32).reshape(-1)
-  - Reshape(-1) ensures flattening to 1D array
-
-Code Refinement (ai_utils.py, lines 50-62):
-  def _embed_text(self, text: str) -> np.ndarray:
-      result = self.client.feature_extraction(text, model=self.model_name)
-      embedding = np.array(result, dtype=np.float32).reshape(-1)
-      if embedding.shape[0] != 1024:
-          raise ValueError(f"Expected embedding of size 1024, got {embedding.shape[0]}")
-      return embedding
-
-B. SUMMARIZATION OUTPUT REFINEMENT
-Issue Encountered:
-  - Pydantic validation error: "Input should be a valid string"
-  - Received: SummarizationOutput object instead of string
-  - Root Cause: client.summarization() returns structured object, not string
-
-Resolution:
-  - Added type-safe extraction logic
-  - Implemented multiple fallback formats:
-    1. If list: Extract first element's 'summary_text' field
-    2. If dict: Get 'summary_text' field directly
-    3. Fallback: Convert to string
-
-Code Refinement (ai_utils.py, lines 90-100):
-  result = self.client.summarization(text, model=self.model_name)
-  
-  # Extract the summary text from the result object
-  if isinstance(result, list) and len(result) > 0:
-      return result[0].get("summary_text", str(result[0]))
-  elif isinstance(result, dict):
-      return result.get("summary_text", str(result))
-  else:
-      return str(result)
-
-C. ERROR HANDLING AND DEFAULTS
-Embedding Generation:
-  - Validation ensures exact dimension match
-  - Raises clear error if dimension mismatch
-  - Prevents downstream vector search issues
-
-Summarization:
-  - Try-except block with graceful fallback
-  - Fallback: Returns truncated input (first 80 chars)
-  - Empty text handling: Returns default "Album of photos"
-  - Ensures robustness when HF API is unavailable
+4. IMAGE GENERATION: black-forest-labs/FLUX.1-dev
+   - Location: cloudzy/inference_models/text_to_image.py (TextToImageGenerator)
+   - Purpose: Generate high-quality images from text prompts
+   - Used in: /generate-similar-image endpoint (Step 3)
 
 ================================================================================
-4. MANUAL VS AI-GENERATED PARTS
+MANUAL VS AI-GENERATED
 ================================================================================
 
-MANUAL PARTS (100% Developer-Written)
-====================================
-✓ Database schema and models
-  - cloudzy/models.py: SQLAlchemy Photo model
-  - cloudzy/database.py: Database connection and session management
-  
-✓ API Route Handlers
-  - cloudzy/routes/photo.py: All endpoint logic
-  - cloudzy/routes/upload.py: File upload handling
-  - cloudzy/routes/search.py: Search endpoint implementation
-  
-✓ File Management
-  - cloudzy/utils/file_upload_service.py: Upload service
-  - cloudzy/utils/file_utils.py: File utilities
-  
-✓ Data Serialization
-  - cloudzy/schemas.py: Pydantic models and validation
-  
-✓ Search Engine Implementation
-  - cloudzy/search_engine.py: FAISS vector search logic
-  - Distance calculation and result ranking
-  
-✓ Application Configuration
-  - app.py: FastAPI app setup
-  - Dockerfile: Containerization
-  - requirements.txt: Dependencies
+MANUAL WORK (100% Developer-Written):
+✓ Database schema, API routes, file management
+✓ FastAPI application setup and middleware
+✓ Error handling and validation logic
+✓ File upload service and utilities
+✓ FAISS vector search implementation
 
-HYBRID PARTS (Manual Integration + AI Models)
-==============================================
-✓ ImageEmbeddingGenerator Class
-  - Manual: Class structure, API client initialization
-  - Manual: Error handling and validation logic
-  - Manual: Type conversion and reshaping
-  - AI: Feature extraction from HF model
-  - Result: Text → 1024-d vector embeddings
+HYBRID (Manual Integration + AI Models):
+✓ ImageEmbeddingGenerator: Text → 1024-d embeddings (AI model)
+✓ TextSummarizer: Metadata → album summary (AI model)
+✓ ImageAnalyzerAgent: Image → description (AI model)
+✓ TextToImageGenerator: Prompt → generated image (AI model)
 
-✓ TextSummarizer Class
-  - Manual: Class structure, API client initialization
-  - Manual: Output parsing and extraction logic
-  - Manual: Error handling and fallbacks
-  - Manual: Empty text handling
-  - AI: Summary generation from combined text
-  - Result: Multi-sentence text → concise summary
-
-✓ Album Summary Integration (photo.py)
-  - Manual: Cluster iteration and photo data collection
-  - Manual: Text concatenation logic
-  - Manual: Response structure and schema mapping
-  - AI: Summary generation
-  - Result: Photo cluster → meaningful album summary
-
-AI-GENERATED PARTS
-==================
-✓ Embedding vectors
-  - Generated by: intfloat/multilingual-e5-large
-  - Content: Semantic representation of photo metadata
-  - Used for: Similarity search and clustering
-
-✓ Album summaries
-  - Generated by: facebook/bart-large-cnn
-  - Content: Concise description of photo cluster themes
-  - Used for: Album display and description
-
-✓ Model-specific responses
-  - Output format: Determined by HF models
-  - Processing: Handled by manual extraction code
+AI-GENERATED CONTENT:
+✓ Embedding vectors (semantic representations)
+✓ Album summaries (cluster descriptions)
+✓ Image descriptions (visual analysis)
+✓ Generated images (from text prompts)
 
 ================================================================================
-5. DEVELOPMENT PROCESS AND DECISIONS
+NEW ENDPOINT: /generate-similar-image
 ================================================================================
 
-DECISION 1: Model Selection
-Manual Decision: Why facebook/bart-large-cnn?
-- Reasons:
-  * Pre-trained on CNN/DailyMail summarization corpus
-  * Optimized for multi-sentence summarization
-  * Fast inference through Hugging Face API
-  * Produces concise, extractive summaries
-  
-Alternative considered: facebook/bart-base (smaller, faster but lower quality)
+Endpoint: POST /generate-similar-image
+Location: cloudzy/routes/generate.py
 
-DECISION 2: Embedding Dimension Resolution
-Manual Decision: Accept 1024-d embeddings (not 512-d)
-- Reason:
-  * intfloat/multilingual-e5-large actually produces 1024 dimensions
-  * Better semantic representation than 512-d
-  * FAISS index configured for 1024-d vectors
-  * Updated validation to reflect actual model output
+Workflow:
+1. User uploads an image
+2. ImageAnalyzerAgent analyzes it → gets description
+3. TextToImageGenerator creates new image from description
+4. Returns generated image URL + description
 
-DECISION 3: Error Handling Strategy
-Manual Decision: Graceful degradation with fallbacks
-- Implementation:
-  * Try summarization first
-  * If fails, return truncated text
-  * If text is empty, return default message
-  * Ensures endpoint never fails due to AI API issues
+Response:
+{
+  "description": "Detailed image analysis from Gemini",
+  "generated_image_url": "http://127.0.0.1:8000/uploads/generated_20241025_123456_789.png",
+  "message": "Similar image generated successfully"
+}
 
-DECISION 4: Output Extraction
-Manual Decision: Flexible type handling for model output
-- Implementation:
-  * Handle both list and dict return formats
-  * Extract 'summary_text' field when available
-  * Fallback to string conversion
-  * Ensures compatibility with different API versions
+Performance: ~40-75 seconds per request
+- Image analysis: ~5-10s (Gemini)
+- Image generation: ~30-60s (FLUX.1-dev)
 
 ================================================================================
-6. TESTING AND VALIDATION
+PROMPTS USED IN PROJECT
 ================================================================================
 
-Validation Points:
-✓ Embedding shape validation (must be 1024-d)
-✓ Type conversion to float32
-✓ Summary extraction and string conversion
-✓ Pydantic schema validation (AlbumItem requires string album_summary)
-✓ Error handling and fallbacks
+1. IMAGE ANALYSIS PROMPT (ImageAnalyzerAgent - Gemini):
+   Location: cloudzy/agents/image_analyzer_2.py
+   
+   "Describe this image in a way that could be used as a prompt for generating 
+   a new image inspired by it. Focus on the main subjects, composition, style, 
+   mood, and colors. Avoid mentioning specific names or exact details — instead, 
+   describe the overall aesthetic and atmosphere so the result feels similar but 
+   not identical."
 
-Testing Done:
-✓ Manual endpoint testing with sample photos
-✓ Verified embedding shape and type
-✓ Tested summarization with various input lengths
-✓ Validated API error handling
-✓ Checked Pydantic schema compliance
+2. IMAGE GENERATION PROMPT:
+   - Input: Description from ImageAnalyzerAgent (above)
+   - Model: FLUX.1-dev (black-forest-labs/FLUX.1-dev)
+   - Location: cloudzy/inference_models/text_to_image.py
+   - Strategy: Direct prompt passing to image generation model
 
 ================================================================================
-7. ENVIRONMENT CONFIGURATION
+ENVIRONMENT VARIABLES
 ================================================================================
 
-Required Environment Variables:
-- HF_TOKEN: Hugging Face API token (for authentication)
-  Location: Set in .env file
-  Usage: InferenceClient initialization
-  Scope: Both ImageEmbeddingGenerator and TextSummarizer
-
-API Access:
-- Provider: Hugging Face Inference API
-- Authentication: Token-based via HF_TOKEN
-- Rate Limiting: Subject to HF plan limits
-- Fallback: When unavailable, gracefully returns truncated text
+Required:
+- HF_TOKEN: Hugging Face API key (embeddings, summarization)
+- GEMINI_API_KEY: Google Gemini API key (image analysis)
+- HF_TOKEN_1: Alternative HF token (image generation)
+- APP_DOMAIN: App URL (default: http://127.0.0.1:8000/)
 
 ================================================================================
-8. PERFORMANCE CONSIDERATIONS
+KEY DECISIONS
 ================================================================================
 
-Current Implementation:
-- Summarization called per album cluster (on-demand)
-- Embedding generation per photo upload
-- FAISS vector search (fast, local)
-
-Potential Optimizations:
-✓ Cache summaries in database (reduce API calls)
-✓ Batch embedding generation for multiple uploads
-✓ Implement summary caching with TTL
-✓ Consider async processing for large clusters
-
-Current Trade-offs:
-- Speed vs Freshness: Summaries generated on-demand (fresh, slower)
-- Accuracy vs Cost: Full text summarization vs cached summaries
+1. Used FLUX.1-dev for high-quality image generation (vs Stable Diffusion)
+2. Composable pipeline: ImageAnalyzer → TextToImageGenerator (reusable components)
+3. Graceful error handling with fallbacks when APIs unavailable
+4. Temporary file handling: saves uploads locally for Gemini analysis
 
 ================================================================================
 SUMMARY
 ================================================================================
 
-This project demonstrates responsible AI integration:
-
-1. Clear Separation: Manual development (infrastructure, logic) vs AI (models)
-2. Error Handling: Graceful degradation when AI services unavailable
-3. Transparency: Documented model choices and output processing
-4. Flexibility: Handle various model output formats
-5. Validation: Schema validation ensures data integrity
-6. Integration: AI models complement, not replace, core functionality
+This project integrates 4 AI models responsibly:
+- Embeddings for semantic search
+- Summarization for album descriptions
+- Vision AI for image analysis
+- Generative AI for image creation
 
-AI Value Added:
-- Semantic search capabilities (embeddings)
-- Automated summary generation (reduces manual effort)
-- Better user experience (meaningful album descriptions)
+All manual work handles infrastructure, logic, validation, and error handling.
+AI models are called for their specialized tasks only.
 
-Human Involvement:
-- System design and architecture
-- Error handling and edge cases
-- API integration and data processing
-- Schema definition and validation
-- Deployment and configuration
+New capability: Generate creative image variations from uploaded photos using
+intelligent analysis + high-quality generation pipeline.
 
 ================================================================================

app.py

@@ -6,7 +6,7 @@ from fastapi.staticfiles import StaticFiles
 from dotenv import load_dotenv
 
 from cloudzy.database import create_db_and_tables
-from cloudzy.routes import upload, photo, search
+from cloudzy.routes import upload, photo, search, generate
 from cloudzy.search_engine import SearchEngine
 import os
 
@@ -55,6 +55,7 @@ app.add_middleware(
 app.include_router(upload.router)
 app.include_router(photo.router)
 app.include_router(search.router)
+app.include_router(generate.router)
 
 UPLOAD_DIR = os.path.join(os.getcwd(), "uploads")
 os.makedirs(UPLOAD_DIR, exist_ok=True)
@@ -76,6 +77,7 @@ async def root():
             "list_photos": "GET /photos - List all photos",
             "search": "GET /search?q=... - Semantic search",
             "image_to_image": "POST /search/image-to-image - Similar images",
+            "generate_similar": "POST /generate-similar-image - Generate image from description",
             "docs": "/docs - Interactive API documentation",
         }
     }

cloudzy/agents/{similar_image_retriever.py → image_analyzer_2.py}

@@ -3,12 +3,14 @@ from pathlib import Path
 from PIL import Image
 from dotenv import load_dotenv
 import os
+import json
+import re
 
 load_dotenv()
 
 
 class ImageAnalyzerAgent:
-    """Agent for analyzing images using Gemini with smolagents"""
+    """Agent for describing images using Gemini with smolagents"""
     
     def __init__(self):
         """Initialize the agent with Gemini configuration"""
@@ -28,42 +30,93 @@ class ImageAnalyzerAgent:
         self.agent = CodeAgent(
             tools=[],
             model=self.model,
-            max_steps=20,
-            verbosity_level=2
+            max_steps=5,
+            verbosity_level=1
         )
     
-    def analyze_images(self, image_paths):
+    def retrieve_similar_images(self, image_path):
         """
-        Load images from file paths and analyze them using the agent.
+        Describe a given image.
         
         Args:
-            image_paths: List of Path objects or strings pointing to image files
+            image_path: Path object or string pointing to an image file
             
         Returns:
-            Agent response with image descriptions
+            Description text of the image
         """
-        # Convert strings to Path objects if needed
-        image_paths = [Path(path) if isinstance(path, str) else path for path in image_paths]
+        image_path = Path(image_path) if isinstance(image_path, str) else image_path
         
-        # Open and load images
-        images = [Image.open(img_path) for img_path in image_paths if img_path.exists()]
+        if not image_path.exists():
+            raise FileNotFoundError(f"Image not found at {image_path}")
         
-        print(f"Loaded {len(images)} images from provided paths")
-        
-        if not images:
-            print("No images found. Please provide valid image paths.")
-            return None
+        image = Image.open(image_path)
+        print(f"Loaded image: {image_path.name}\n")
         
         response = self.agent.run(
             """
-            Describe these images to me:
+            Describe this image in a way that could be used as a prompt for generating a new image inspired by it.
+Focus on the main subjects, composition, style, mood, and colors.
+Avoid mentioning specific names or exact details — instead, describe the overall aesthetic and atmosphere so the result feels similar but not identical.
             """,
-            images=images
+            images=[image]
         )
         
-        print("\n=== Agent Response ===")
-        print(response)
         return response
+    
+    def analyze_image_metadata(self, image_path):
+        """
+        Analyze an image and extract structured metadata (tags, description, caption).
+        
+        Args:
+            image_path: Path object or string pointing to an image file
+            
+        Returns:
+            Dictionary with keys: tags (list), description (str), caption (str)
+            
+        Raises:
+            FileNotFoundError: If image file doesn't exist
+            ValueError: If response cannot be parsed into valid JSON
+        """
+        image_path = Path(image_path) if isinstance(image_path, str) else image_path
+        
+        if not image_path.exists():
+            raise FileNotFoundError(f"Image not found at {image_path}")
+        
+        image = Image.open(image_path)
+        print(f"Loaded image: {image_path.name}\n")
+        
+        prompt = """
+Describe this image in the following exact format:
+
+result: {
+  "tags": [list of tags related to the image],
+  "description": "a 5-line descriptive description for the image",
+  "caption": "a short description for the image"
+}
+        """
+        
+        response = self.agent.run(prompt, images=[image])
+        
+        # Handle both dict and string responses
+        if isinstance(response, dict):
+            # Response is already a dictionary
+            return response
+        
+        # If response is a string, extract JSON part
+        # Look for the pattern: result: { ... }
+        match = re.search(r'result:\s*(\{[\s\S]*\})', response)
+        
+        if not match:
+            raise ValueError(f"Could not find JSON in response: {response}")
+        
+        json_str = match.group(1)
+        
+        try:
+            # Parse the JSON string into a dictionary
+            result_dict = json.loads(json_str)
+            return result_dict
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Failed to parse JSON from response: {json_str}\nError: {str(e)}")
 
 
 # Test with sample images
@@ -76,4 +129,9 @@ if __name__ == "__main__":
     ]
     
     agent = ImageAnalyzerAgent()
-    agent.analyze_images(sample_image_paths)
+    
+    # Test with first sample image
+    result = agent.analyze_image_metadata(sample_image_paths[0])
+    print(f"\n=== Results ===")
+    print(f"Description: {result}")
+    # print(f"Similar images found: {len(result['similar_images'])}")

cloudzy/inference_models/text_to_image.py

@@ -0,0 +1,78 @@
+import os
+from datetime import datetime
+from pathlib import Path
+from huggingface_hub import InferenceClient
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class TextToImageGenerator:
+    """Class for generating images from text prompts using HuggingFace models"""
+    
+    def __init__(self, model_id: str = "black-forest-labs/FLUX.1-dev", provider: str = "nebius"):
+        """
+        Initialize the text-to-image generator.
+        
+        Args:
+            model_id: HuggingFace model ID (default: FLUX.1-dev for high quality)
+            provider: API provider (default: nebius)
+        """
+        api_key = os.getenv("HF_TOKEN_1")
+        if not api_key:
+            raise ValueError("HF_TOKEN_1 not found in environment variables")
+        
+        self.client = InferenceClient(
+            provider=provider,
+            api_key=api_key,
+        )
+        self.model_id = model_id
+        self.uploads_dir = Path(__file__).parent.parent.parent / "uploads"
+        self.uploads_dir.mkdir(exist_ok=True)
+        
+        self.app_domain = os.getenv("APP_DOMAIN", "http://127.0.0.1:8000/")
+    
+    def generate(self, prompt: str) -> str:
+        """
+        Generate an image from a text prompt and save it to the uploads folder.
+        
+        Args:
+            prompt: Text description of the image to generate
+            
+        Returns:
+            URL of the generated image in format: {APP_DOMAIN}uploads/{filename}
+        """
+        if not prompt or not prompt.strip():
+            raise ValueError("Prompt cannot be empty")
+        
+        try:
+            # Generate image using HuggingFace inference
+            image = self.client.text_to_image(
+                prompt,
+                model=self.model_id,
+            )
+            
+            # Create filename with timestamp
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")[:-3]
+            filename = f"generated_{timestamp}.png"
+            filepath = self.uploads_dir / filename
+            
+            # Save image
+            image.save(filepath)
+            
+            # Return URL in the required format
+            image_url = f"{self.app_domain}uploads/{filename}"
+            return image_url
+            
+        except Exception as e:
+            raise RuntimeError(f"Failed to generate image: {str(e)}") from e
+
+
+# Test with sample prompt
+if __name__ == "__main__":
+    generator = TextToImageGenerator()
+    
+    # Test with a sample prompt
+    prompt = "A beautiful sunset over mountains with birds flying"
+    url = generator.generate(prompt)
+    print(f"Generated image URL: {url}")

cloudzy/routes/generate.py

@@ -0,0 +1,88 @@
+"""Generate endpoint for creating similar images"""
+from fastapi import APIRouter, UploadFile, File, HTTPException
+from pathlib import Path
+import os
+
+from cloudzy.agents.image_analyzer_2 import ImageAnalyzerAgent
+from cloudzy.inference_models.text_to_image import TextToImageGenerator
+from cloudzy.utils.file_utils import save_uploaded_file
+from cloudzy.schemas import GenerateImageResponse
+
+router = APIRouter(tags=["generate"])
+
+# Allowed image extensions
+ALLOWED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
+
+
+def validate_image_file(filename: str) -> bool:
+    """Check if file has valid image extension"""
+    return Path(filename).suffix.lower() in ALLOWED_EXTENSIONS
+
+
+@router.post("/generate-similar-image", response_model=GenerateImageResponse)
+async def generate_similar_image(
+    file: UploadFile = File(...),
+):
+    """
+    Generate a similar image from an input image.
+    
+    This endpoint:
+    1. Takes an image as input
+    2. Analyzes the image to get a description using ImageAnalyzerAgent
+    3. Uses the description to generate a new image via TextToImageGenerator
+    4. Returns the URL of the generated image
+    
+    Args:
+        file: The input image file
+        
+    Returns:
+        GenerateImageResponse with the generated image URL and description
+    """
+    # --- Validate file ---
+    if not file.filename:
+        raise HTTPException(status_code=400, detail="No filename provided")
+    
+    if not validate_image_file(file.filename):
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid file type. Allowed: {', '.join(ALLOWED_EXTENSIONS)}"
+        )
+    
+    content = await file.read()
+    if not content:
+        raise HTTPException(status_code=400, detail="Empty file")
+    
+    # --- Save uploaded file temporarily ---
+    try:
+        saved_filename = save_uploaded_file(content, file.filename)
+        filepath = Path(__file__).parent.parent.parent / "uploads" / saved_filename
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to save file: {str(e)}")
+    
+    # --- Step 1: Analyze image and get description ---
+    try:
+        analyzer = ImageAnalyzerAgent()
+        description = analyzer.retrieve_similar_images(filepath)
+        print(f"Generated description: {description}")
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, 
+            detail=f"Failed to analyze image: {str(e)}"
+        )
+    
+    # --- Step 2: Generate image from description ---
+    try:
+        generator = TextToImageGenerator()
+        generated_image_url = generator.generate(description)
+        print(f"Generated image URL: {generated_image_url}")
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, 
+            detail=f"Failed to generate image: {str(e)}"
+        )
+    
+    return GenerateImageResponse(
+        description=description,
+        generated_image_url=generated_image_url,
+        message="Similar image generated successfully"
+    )

cloudzy/routes/photo.py

@@ -81,7 +81,7 @@ async def list_photos(
 
 @router.get("/albums", response_model=AlbumsResponse)
 async def get_albums(
-    top_k: int = Query(5, ge=2, le=50),
+    top_k: int = Query(5, ge=1, le=5),
     session: Session = Depends(get_session),
 ):
     """

cloudzy/routes/search.py

@@ -78,59 +78,59 @@ async def search_photos(
     )
 
 
-@router.post("/search/image-to-image")
-async def image_to_image_search(
-    reference_photo_id: int = Query(..., description="Reference photo ID"),
-    top_k: int = Query(5, ge=1, le=50),
-    session: Session = Depends(get_session),
-):
-    """
-    Find similar images to a reference photo (image-to-image search).
-    
-    Args:
-        reference_photo_id: ID of the reference photo
-        top_k: Number of similar results
-    
-    Returns: Similar photos
-    """
-    # Get reference photo
-    statement = select(Photo).where(Photo.id == reference_photo_id)
-    reference_photo = session.exec(statement).first()
-    
-    if not reference_photo:
-        raise HTTPException(status_code=404, detail=f"Photo {reference_photo_id} not found")
-    
-    # Get reference embedding
-    reference_embedding = reference_photo.get_embedding()
-    if not reference_embedding:
-        raise HTTPException(status_code=400, detail="Photo has no embedding")
-    
-    # Search in FAISS
-    search_engine = SearchEngine()
-    search_results = search_engine.search(
-        np.array(reference_embedding, dtype=np.float32),
-        top_k=top_k + 1  # +1 to skip the reference photo itself
-    )
-    
-    # Build results (skip first result which is the reference photo itself)
-    result_objects = []
-    for photo_id, distance in search_results[1:]:  # Skip first result
-        statement = select(Photo).where(Photo.id == photo_id)
-        photo = session.exec(statement).first()
+# @router.post("/search/image-to-image")
+# async def image_to_image_search(
+#     reference_photo_id: int = Query(..., description="Reference photo ID"),
+#     top_k: int = Query(5, ge=1, le=50),
+#     session: Session = Depends(get_session),
+# ):
+#     """
+#     Find similar images to a reference photo (image-to-image search).
+    
+#     Args:
+#         reference_photo_id: ID of the reference photo
+#         top_k: Number of similar results
+    
+#     Returns: Similar photos
+#     """
+#     # Get reference photo
+#     statement = select(Photo).where(Photo.id == reference_photo_id)
+#     reference_photo = session.exec(statement).first()
+    
+#     if not reference_photo:
+#         raise HTTPException(status_code=404, detail=f"Photo {reference_photo_id} not found")
+    
+#     # Get reference embedding
+#     reference_embedding = reference_photo.get_embedding()
+#     if not reference_embedding:
+#         raise HTTPException(status_code=400, detail="Photo has no embedding")
+    
+#     # Search in FAISS
+#     search_engine = SearchEngine()
+#     search_results = search_engine.search(
+#         np.array(reference_embedding, dtype=np.float32),
+#         top_k=top_k + 1  # +1 to skip the reference photo itself
+#     )
+    
+#     # Build results (skip first result which is the reference photo itself)
+#     result_objects = []
+#     for photo_id, distance in search_results[1:]:  # Skip first result
+#         statement = select(Photo).where(Photo.id == photo_id)
+#         photo = session.exec(statement).first()
         
-        if photo:
-            result_objects.append(
-                SearchResult(
-                    photo_id=photo.id,
-                    filename=photo.filename,
-                    tags=photo.get_tags(),
-                    caption=photo.caption,
-                    distance=distance,
-                )
-            )
-    
-    return SearchResponse(
-        query=f"Similar to photo {reference_photo_id}",
-        results=result_objects[:top_k],
-        total_results=len(result_objects),
-    )
+#         if photo:
+#             result_objects.append(
+#                 SearchResult(
+#                     photo_id=photo.id,
+#                     filename=photo.filename,
+#                     tags=photo.get_tags(),
+#                     caption=photo.caption,
+#                     distance=distance,
+#                 )
+#             )
+    
+#     return SearchResponse(
+#         query=f"Similar to photo {reference_photo_id}",
+#         results=result_objects[:top_k],
+#         total_results=len(result_objects),
+#     )

cloudzy/routes/upload.py

@@ -12,6 +12,7 @@ from cloudzy.ai_utils import  ImageEmbeddingGenerator
 from cloudzy.search_engine import SearchEngine
 
 from cloudzy.agents.image_analyzer import ImageDescriber
+from cloudzy.agents.image_analyzer_2 import ImageAnalyzerAgent
 from cloudzy.utils.file_upload_service import ImgBBUploader
 
 
@@ -62,10 +63,11 @@ def validate_image_file(filename: str) -> bool:
     """Check if file has valid image extension"""
     return Path(filename).suffix.lower() in ALLOWED_EXTENSIONS
 
-def process_image_in_background(photo_id: int, filepath: str, image_url: str):
+def process_image_in_background(photo_id: int, filepath: str):
     """
     Background task to:
-    - Describe the image
+    - Analyze image metadata (primary method using local file)
+    - Fallback to ImgBB upload + ImageDescriber if metadata analysis fails
     - Generate embedding
     - Update database record
     - Index embedding in FAISS
@@ -74,9 +76,30 @@ def process_image_in_background(photo_id: int, filepath: str, image_url: str):
     from sqlmodel import select
     
     try:
-        describer = ImageDescriber()
-        print(f"[Background] Processing image {photo_id}...")
-        result = describer.describe_image(image_url)
+        result = None
+        
+        # --- Primary method: Analyze metadata from local filepath ---
+        try:
+            print(f"[Background] Analyzing image metadata locally for photo {photo_id}...")
+            analyzer = ImageAnalyzerAgent()
+            result = analyzer.analyze_image_metadata(filepath)
+            print(f"[Background] Successfully extracted metadata for photo {photo_id}")
+        except Exception as metadata_error:
+            print(f"[Background] Metadata analysis failed for photo {photo_id}: {metadata_error}")
+            print(f"[Background] Falling back to ImgBB upload + ImageDescriber...")
+            
+            # --- Fallback method: Upload to ImgBB and use ImageDescriber ---
+            try:
+                uploader = ImgBBUploader(expiration=600)
+                image_url = uploader.upload(filepath)
+                print(f"[Background] Image {photo_id} uploaded to ImgBB: {image_url}")
+                
+                describer = ImageDescriber()
+                print(f"[Background] Processing image {photo_id} with ImageDescriber...")
+                result = describer.describe_image(image_url)
+                print(f"[Background] Successfully described image using ImageDescriber")
+            except Exception as fallback_error:
+                raise Exception(f"Both metadata analysis and ImageDescriber failed - Primary: {str(metadata_error)}, Fallback: {str(fallback_error)}")
 
         tags = result.get("tags", [])
         caption = result.get("caption", "")
@@ -135,12 +158,6 @@ async def upload_photo(
     saved_filename = save_uploaded_file(content, file.filename)
     filepath = f"uploads/{saved_filename}"
 
-    try:
-        uploader = ImgBBUploader(expiration=600)
-        image_url = uploader.upload(filepath)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Image upload failed: {str(e)}")
-
     APP_DOMAIN = os.getenv("APP_DOMAIN")
     image_local_url = f"{APP_DOMAIN}uploads/{saved_filename}"
 
@@ -154,13 +171,12 @@ async def upload_photo(
     session.commit()
     session.refresh(photo)
 
-    # --- Schedule background task ---
+    # --- Schedule background task (includes ImgBB upload) ---
     if background_tasks:
         background_tasks.add_task(
             process_image_in_background,
             photo_id=photo.id,
-            filepath=filepath,
-            image_url=image_url
+            filepath=filepath
         )
 
     return UploadResponse(

cloudzy/schemas.py

@@ -65,4 +65,11 @@ class AlbumItem(BaseModel):
     album_summary: str
     album: List[PhotoItem]
 
-AlbumsResponse = List[AlbumItem]
+AlbumsResponse = List[AlbumItem]
+
+
+class GenerateImageResponse(BaseModel):
+    """Response for generating a similar image"""
+    description: str
+    generated_image_url: str
+    message: str

cloudzy/search_engine.py

@@ -3,6 +3,7 @@ import faiss
 import numpy as np
 from typing import List, Tuple
 import os
+import random
 
 
 class SearchEngine:
@@ -19,20 +20,21 @@ class SearchEngine:
             base_index = faiss.IndexFlatL2(dim)
             self.index = faiss.IndexIDMap(base_index)
 
-    def create_albums(self, top_k: int = 5, distance_threshold: float = 0.3) -> List[List[int]]:
+    def create_albums(self, top_k: int = 5, distance_threshold: float = 0.3, album_size: int = 5) -> List[List[int]]:
         """
         Group similar images into albums (clusters).
         
-        For each unvisited photo, finds its top_k most similar photos and creates an album.
+        Returns exactly top_k albums, each containing up to album_size similar photos.
         Photos are marked as visited to avoid duplicate albums.
         Only includes photos within the distance threshold.
         
         Args:
-            top_k: Number of similar images to find for each album
-            distance_threshold: Maximum distance to consider photos as similar (default 0.5)
+            top_k: Number of albums to return
+            distance_threshold: Maximum distance to consider photos as similar (default 0.3)
+            album_size: How many similar photos to search for per album (default 5)
             
         Returns:
-            List of albums, each album is a list of photo_ids
+            List of top_k albums, each album is a list of photo_ids (randomized order each call)
         """
         from cloudzy.database import SessionLocal
         from cloudzy.models import Photo
@@ -45,11 +47,18 @@ class SearchEngine:
         # Get all photo IDs from FAISS index
         id_map = self.index.id_map
         all_ids = [id_map.at(i) for i in range(id_map.size())]
+        
+        # Shuffle for randomization - different albums each call
+        random.shuffle(all_ids)
 
         visited = set()
         albums = []
 
         for photo_id in all_ids:
+            # Stop if we have enough albums
+            if len(albums) >= top_k:
+                break
+            
             # Skip if already in an album
             if photo_id in visited:
                 continue
@@ -67,7 +76,7 @@ class SearchEngine:
                 
                 # Search for similar images
                 query_embedding = np.array(embedding).reshape(1, -1).astype(np.float32)
-                distances, ids = self.index.search(query_embedding, top_k)
+                distances, ids = self.index.search(query_embedding, album_size)
                 
                 # Build album: collect similar photos that haven't been visited and are within threshold
                 album = []
@@ -153,3 +162,42 @@ class SearchEngine:
             "dimension": self.dim,
             "index_type": type(self.index).__name__,
         }
+
+    def debug_distances(self, sample_size: int = 3) -> dict:
+        """Debug distances between photos to understand why albums aren't grouping"""
+        from cloudzy.database import SessionLocal
+        from cloudzy.models import Photo
+        from sqlmodel import select
+        
+        self.load()
+        if self.index.ntotal == 0:
+            return {"error": "No embeddings in index"}
+        
+        id_map = self.index.id_map
+        all_ids = [id_map.at(i) for i in range(min(id_map.size(), sample_size))]
+        
+        debug_info = {}
+        session = SessionLocal()
+        try:
+            for photo_id in all_ids:
+                photo = session.exec(select(Photo).where(Photo.id == photo_id)).first()
+                if not photo:
+                    continue
+                
+                embedding = photo.get_embedding()
+                if not embedding:
+                    continue
+                
+                query_embedding = np.array(embedding).reshape(1, -1).astype(np.float32)
+                distances, ids = self.index.search(query_embedding, 5)
+                
+                debug_info[photo_id] = {
+                    "top_5_results": [
+                        {"id": int(pid), "distance": float(d)} 
+                        for pid, d in zip(ids[0], distances[0]) if pid != -1
+                    ]
+                }
+        finally:
+            session.close()
+        
+        return debug_info