Update README.md

README.md

@@ -1,20 +1,78 @@
 ---
-title: Cosine Similarity Explainer
-emoji: 🚀
-colorFrom: red
-colorTo: red
-sdk: docker
-app_port: 8501
-tags:
-- streamlit
+title: Semantic Similarity Explainer
+emoji: 🔍
+colorFrom: blue
+colorTo: purple
+sdk: streamlit
+sdk_version: 1.28.0
+app_file: app.py
 pinned: false
-short_description: AI explains sentence similarity.
 license: mit
 ---
 
-# Welcome to Streamlit!
+# 🔍 Semantic Similarity Explainer with AI
 
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
+This Streamlit app calculates the **semantic similarity** between two sentences using transformer-based embeddings (all-MiniLM-L6-v2) and uses AI to explain why that specific score makes sense.
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+## Features
+
+- **Semantic Similarity Calculation**: Uses the `all-MiniLM-L6-v2` transformer model to generate 384-dimensional embeddings
+- **AI-Powered Explanations**: Leverages OpenRouter API to explain similarity scores in detail
+- **Technical Details**: Shows embedding dimensions, cosine similarity calculations, and vector statistics
+- **Interactive Interface**: Easy-to-use Streamlit interface with real-time calculations
+- **History Tracking**: Keeps track of previous calculations during the session
+
+## How It Works
+
+1. **Input**: Enter two sentences you want to compare
+2. **Embedding Generation**: The app uses the `all-MiniLM-L6-v2` model to convert sentences into dense vector representations
+3. **Similarity Calculation**: Computes cosine similarity between the embeddings
+4. **AI Explanation**: Uses GPT-3.5-turbo via OpenRouter to explain the similarity score
+5. **Technical Details**: Shows detailed information about the embeddings and calculations
+
+## Usage
+
+### Without API Key
+- You can use the similarity calculation feature without an API key
+- The app will show similarity scores and technical details
+- AI explanations will be skipped
+
+### With OpenRouter API Key
+- Get your API key from [OpenRouter](https://openrouter.ai/keys)
+- Enter it in the sidebar to enable AI explanations
+- The app will provide detailed explanations of why sentences have specific similarity scores
+
+## Examples
+
+- **High Similarity**: "The car is fast" vs "The automobile is quick" → ~0.90
+- **Moderate Similarity**: "I love dogs" vs "I hate dogs" → ~0.60 (same topic, opposite sentiment)
+- **Low Similarity**: "The cat sat on the mat" vs "Python is a programming language" → ~0.10
+
+## Technical Details
+
+- **Model**: sentence-transformers/all-MiniLM-L6-v2
+- **Embedding Dimensions**: 384
+- **Similarity Metric**: Cosine similarity
+- **AI Model**: GPT-3.5-turbo (via OpenRouter)
+
+## Installation & Local Development
+
+```bash
+# Clone the repository
+git clone <your-repo-url>
+cd semantic-similarity-explainer
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the app
+streamlit run app.py
+```
+
+## Environment Variables
+
+- `OPENROUTER_API_KEY`: Your OpenRouter API key (optional, can also be entered in the UI)
+
+## License
+
+MIT License - see LICENSE file for details.