Delete README.md

README.md

@@ -1,371 +0,0 @@
----
-title: Visual Search System
-emoji: 🔍
-colorFrom: blue
-colorTo: green
-sdk: streamlit
-sdk_version: "1.37.0"
-app_file: app.py
-pinned: false
-license: mit
----
-
-
-
-
-# Modern Visual Search System (CLIP-based)
-
-## Overview
-
-This project implements a modern, scalable visual search system using OpenAI's CLIP model. It provides both a REST API (FastAPI) and a web interface (Streamlit) for searching large image datasets using natural language queries and image queries, returning the top 5 most visually relevant images.
-
-## Features
-
-- **REST API**: FastAPI backend with comprehensive endpoints
-- **Web Interface**: Streamlit frontend with intuitive UI
-- **Text Search**: Search images using natural language descriptions
-- **Image Search**: Find similar images by providing an image as query
-- **Image Upload**: Upload images to find similar images in the dataset
-- **Top 5 Results**: Always returns the 5 most similar images
-- **Fast Search**: Uses precomputed embeddings for optimal performance
-- **GPU Acceleration**: Automatic GPU detection and utilization
-- **API Documentation**: Auto-generated Swagger/OpenAPI docs
-
-## Architecture
-
-```
-┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
-│   Streamlit     │    │   FastAPI       │    │   CLIP Model    │
-│   Frontend      │◄──►│   Backend       │◄──►│   (Encoder)     │
-│   (Port 8501)   │    │   (Port 8000)   │    │                 │
-└─────────────────┘    └─────────────────┘    └─────────────────┘
-                              │
-                              ▼
-                       ┌─────────────────┐
-                       │   Image         │
-                       │   Database      │
-                       │   (images/)     │
-                       └─────────────────┘
-```
-
-## Technical Details
-
-- **Image & Text Features**: CLIP (ViT-B-32, openai weights)
-- **Search Algorithm**: Cosine similarity in CLIP embedding space
-- **Embedding Dimension**: 512 (default for ViT-B-32)
-- **Performance**: Fast, GPU-accelerated if available
-- **Dependencies**: `open-clip-torch`, `torch`, `fastapi`, `streamlit`, `Pillow`, `numpy`
-
-## Quick Start
-
-### 1. Install Dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-### 2. Prepare Your Images
-
-The application will automatically check and download images for you:
-
-```bash
-# Check image status
-python start_app.py --check-only
-
-# Download missing images (if any)
-python start_app.py --download-images
-
-# Or let the app handle everything automatically
-python start_app.py
-```
-
-**Automatic Features:**
-- ✅ Checks if images are already downloaded
-- ✅ Downloads missing images in parallel (up to 20 workers)
-- ✅ Skips existing images to save time
-- ✅ Shows progress and statistics
-- ✅ Handles errors gracefully
-- ✅ **Smart startup**: Allows application to start with sufficient images (default: 1000+)
-- ✅ **Flexible requirements**: Can adjust minimum image requirements
-- ✅ **Graceful degradation**: Works even with partial image database
-
-### 3. Start the Application
-
-#### Option A: Start Both Services (Recommended)
-```bash
-python start_app.py
-```
-
-This will:
-1. Check dependencies
-2. Verify/download images automatically
-3. Start both the FastAPI backend and Streamlit frontend
-
-#### Command Line Options
-
-```bash
-# Basic startup (recommended)
-python start_app.py
-
-# Skip automatic image download
-python start_app.py --skip-download
-
-# Force download images even if some exist
-python start_app.py --download-images
-
-# Use custom number of parallel workers
-python start_app.py --max-workers 10
-
-# Use custom images directory
-python start_app.py --images-dir my_images
-
-# Set custom minimum image requirement
-python start_app.py --min-images 500
-
-# Only check image status, don't start services
-python start_app.py --check-only
-```
-
-#### Option B: Start Services Separately
-
-**Start FastAPI Backend:**
-```bash
-cd api && python main.py
-```
-
-**Start Streamlit Frontend (in another terminal):**
-```bash
-streamlit run streamlit_app.py
-```
-
-#### Option C: Download Images Only
-
-```bash
-# Download all images
-python download_images.py
-
-# Download with custom settings
-python download_images.py --max-workers 15 --output-dir images
-
-# Check status only
-python download_images.py --check-only
-```
-
-### 4. Access the Application
-
-- **Web Interface**: http://localhost:8501
-- **API Documentation**: http://localhost:8000/docs
-- **API Health Check**: http://localhost:8000/api/health
-
-## API Endpoints
-
-### Core Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/` | GET | Root endpoint with API info |
-| `/api/health` | GET | Health check |
-| `/api/info` | GET | System information |
-| `/api/images` | GET | List available images |
-
-### Search Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/search/text` | POST | Text-based search |
-| `/api/search/image` | POST | Image-based search |
-| `/api/search/image/upload` | POST | Upload image for search |
-
-### Example API Usage
-
-#### Text Search
-```bash
-curl -X POST "http://localhost:8000/api/search/text" \
-     -H "Content-Type: application/json" \
-     -d '{"query": "red car", "top_k": 5}'
-```
-
-#### Image Search
-```bash
-curl -X POST "http://localhost:8000/api/search/image" \
-     -H "Content-Type: application/json" \
-     -d '{"image_path": "images/0001.jpg", "top_k": 5}'
-```
-
-#### Image Upload Search
-```bash
-curl -X POST "http://localhost:8000/api/search/image/upload" \
-     -F "file=@your_image.jpg" \
-     -F "top_k=5"
-```
-
-## Web Interface Features
-
-### Text Search
-- Enter natural language descriptions
-- Examples: "a cat sitting", "red car", "person walking", "building with windows"
-- Returns images that best match the text description
-
-### Image Search
-- Select an image from your dataset
-- Finds images visually similar to the selected image
-- Excludes the query image from results
-
-### Image Upload Search
-- Upload any image file (JPG, PNG, BMP, TIFF)
-- Find similar images in your dataset
-- Real-time processing and results
-
-### Results Display
-- **Ranking**: 1-5 (top 5 results)
-- **Filename**: Name of the image file
-- **Path**: Full path to the image
-- **Similarity Score**: Percentage indicating how well the image matches the query
-- **Image Preview**: Visual display of results
-
-## Testing
-
-### Test the API
-```bash
-python test_api.py
-```
-
-### Test the CLI (Legacy)
-```bash
-python test_search.py
-```
-
-### Run Demo
-```bash
-python demo_search.py
-```
-
-## Development
-
-### Project Structure
-```
-visual-search-system/
-├── api/
-│   └── main.py              # FastAPI backend
-├── src/
-│   └── models/
-│       └── multimodal_encoder.py  # CLIP encoder
-├── images/                   # Image database
-├── models/
-│   └── clip_index/          # Precomputed embeddings
-├── streamlit_app.py         # Streamlit frontend
-├── start_app.py             # Startup script
-├── test_api.py              # API tests
-├── run_search.py            # CLI interface (legacy)
-└── requirements.txt         # Dependencies
-```
-
-### Adding New Features
-
-1. **New API Endpoints**: Add to `api/main.py`
-2. **New UI Components**: Add to `streamlit_app.py`
-3. **New Search Methods**: Extend `src/models/multimodal_encoder.py`
-
-## Performance
-
-- **Precomputed Embeddings**: Uses existing embeddings in `models/clip_index/` for faster search
-- **Real-time Fallback**: Falls back to real-time encoding if precomputed embeddings aren't available
-- **GPU Acceleration**: Automatically uses GPU if available for faster processing
-- **Memory Efficient**: Processes images in batches to manage memory usage
-- **Async Processing**: FastAPI handles concurrent requests efficiently
-
-## Deployment
-
-### Hugging Face Spaces (Recommended)
-
-This application is designed to work seamlessly on Hugging Face Spaces:
-
-1. **Fork this repository** to your Hugging Face account
-2. **Create a new Space** on Hugging Face Spaces
-3. **Connect your forked repository** to the Space
-4. **The application will automatically**:
-   - Check for downloaded images
-   - Download missing images in parallel
-   - Start the Streamlit interface
-   - Handle all dependencies automatically
-
-**Features for Hugging Face Spaces:**
-- ✅ Automatic image downloading with progress tracking
-- ✅ Optimized for Spaces environment (reduced parallel workers)
-- ✅ Built-in error handling and recovery
-- ✅ No manual setup required
-- ✅ Works with the provided `photos_url.csv` dataset
-
-**Space Configuration:**
-- **SDK**: Streamlit
-- **Hardware**: CPU Basic (free tier) or GPU for faster processing
-- **App File**: `app.py`
-
-### Docker Deployment
-
-Create a `Dockerfile`:
-
-```Dockerfile
-FROM python:3.9-slim
-
-WORKDIR /app
-
-# Install system dependencies
-RUN apt-get update && apt-get install -y \
-    libgl1-mesa-glx \
-    libglib2.0-0 \
-    && rm -rf /var/lib/apt/lists/*
-
-# Copy requirements and install Python dependencies
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Copy application code
-COPY . .
-
-# Expose ports
-EXPOSE 8000 8501
-
-# Start the application
-CMD ["python", "start_app.py"]
-```
-
-Build and run:
-```bash
-docker build -t visual-search .
-docker run -p 8000:8000 -p 8501:8501 -v $(pwd)/images:/app/images visual-search
-```
-
-### Production Deployment
-
-For production, consider:
-- Using a production ASGI server like Gunicorn
-- Setting up proper CORS configuration
-- Implementing authentication
-- Using a reverse proxy (nginx)
-- Setting up monitoring and logging
-
-## Troubleshooting
-
-### Common Issues
-
-- **API Connection Failed**: Make sure the FastAPI server is running on port 8000
-- **No images found**: Ensure images are in the `images/` directory with `.jpg` extension
-- **Model loading errors**: Check that all dependencies are installed correctly
-- **GPU issues**: Install appropriate CUDA version for your GPU
-- **Memory errors**: Reduce batch size or use CPU-only mode
-- **Port conflicts**: Change ports in `start_app.py` if needed
-
-### Debug Mode
-
-Run with debug information:
-```bash
-# API with debug logging
-cd api && uvicorn main:app --reload --log-level debug
-
-# Streamlit with debug
-streamlit run streamlit_app.py --logger.level debug
-```
-
-## License
-MIT