Initial commit

2025-07-19 11:55:09 +01:00
commit 49c82456c9
19 changed files with 36092 additions and 0 deletions
@@ -0,0 +1,68 @@
+# API Documentation
+
+## POST /get_tag
+
+Identify a clothing tag and find similar tags/images using computer vision, text similarity, and (optionally) LLM-based filtering.
+
+### Request
+- **Content-Type:** application/json
+- **Body:**
+  ```json
+  {
+    "image_url": "<image-url>",
+    "use_llm": true  // Optional, default: false
+  }
+  ```
+  - `image_url` (string, required): URL of the tag image to scan
+  - `use_llm` (boolean, optional): If true, use LLM-based similarity filtering
+
+### Response
+- **Content-Type:** application/json
+- **Body:**
+  ```json
+  {
+    "results": [
+      {
+        "tag": "Jerzees T-Shirt Tags",
+        "similar_images": [
+          "https://.../tag1.jpg",
+          "https://.../tag2.jpg"
+        ],
+        "appraisal_value": [150.0, 75.0],
+        "years": ["1998", "1997"],
+        "status": ["public", "private"]
+      }
+    ]
+  }
+  ```
+
+### Example Request
+```bash
+curl -X POST http://localhost:8000/get_tag \
+  -H "Content-Type: application/json" \
+  -d '{"image_url": "https://example.com/tag_image.jpg", "use_llm": true}'
+```
+
+### Example Response
+```json
+{
+  "results": [
+    {
+      "tag": "Jerzees T-Shirt Tags",
+      "similar_images": [
+        "https://.../tag1.jpg",
+        "https://.../tag2.jpg"
+      ],
+      "appraisal_value": [150.0, 75.0],
+      "years": ["1998", "1997"],
+      "status": ["public", "private"]
+    }
+  ]
+}
+```
+
+### Notes
+- If `use_llm` is true, the system will use an LLM (OpenAI) to further filter and rank similar images.
+- If no tag is identified, or no similar images are found, the response will indicate this.
+- The endpoint is designed for use with the provided frontend, but can be called directly from any HTTP client.
+- Requires a valid OpenAI API key if using LLM. 
@@ -0,0 +1,65 @@
+# Tag Scan Mini App
+
+## Overview
+
+This project is an AI-powered clothing tag identification and similarity search system. It analyzes clothing tag images, identifies brands using computer vision, and finds similar tags from a database. The system uses advanced AI techniques including image embeddings, text similarity, and (optionally) LLM-based filtering to provide accurate tag matching and recommendations.
+
+## Features
+- **Tag Identification:** Uses computer vision to identify clothing tag brands from images
+- **Text-Based Matching:** Implements TF-IDF and cosine similarity for tag name matching
+- **Image Similarity Search:** Uses CLIP embeddings and FAISS for visually similar tag images
+- **LLM Enhancement:** Optional LLM analysis for improved similarity filtering
+- **Metadata Extraction:** Provides appraisal values, years, and status information for similar tags
+- **Simple Frontend:** Web UI to upload image URL, toggle LLM, and view results visually
+
+## Tech Stack
+- Python, Flask
+- CLIP (Hugging Face), FAISS, scikit-learn, pandas, numpy
+- OpenAI (optional, for LLM)
+- HTML/CSS/JS frontend (Flask template)
+
+## Setup & Installation
+
+1. **Clone the Repository**
+   ```bash
+   git clone <repository-url>
+   cd ds_task_tag_scan_project/ds_task/backend
+   ```
+2. **Create and Activate Virtual Environment**
+   ```bash
+   python3 -m venv ../venv
+   source ../venv/bin/activate
+   ```
+3. **Install Requirements**
+   ```bash
+   pip install -r requirements.txt
+   ```
+4. **Set Environment Variables** (if using LLM)
+   ```bash
+   export OPENAI_API_KEY=your-openai-key
+   ```
+5. **Run the App**
+   ```bash
+   python app.py
+   ```
+   (For production, use Docker or a Linux server for stability.)
+
+## Usage
+- Go to [http://localhost:8000/](http://localhost:8000/) in your browser
+- Enter a tag image URL
+- Toggle "Use LLM Similarity" if desired
+- Click "Scan Tag" to see results (tag info, similar images, metadata)
+
+## File Structure
+- `backend/` - Flask app, ML/DS logic, templates
+- `data/` - Tag guides, expert and community CSVs
+- `docs/` - Documentation (this file, API doc)
+
+## Notes
+- For best stability, run in a Linux environment or Docker.
+- On Mac, the app is configured to use only one thread for all ML/numerical libraries.
+- LLM similarity requires a valid OpenAI API key.
+
+---
+
+See `API_Documentation.md` for API details.