---
title: Semantic Similarity Explainer
emoji: 🚀
colorFrom: blue
colorTo: red
sdk: streamlit
sdk_version: 1.28.0
app_file: app.py
pinned: false
license: mit
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/688dfa71393005de0077ca78/EUX1LCDAD4tnusOBUEqz4.jpeg
short_description: See how AI understands language with live examples.
---

# 🔍 Semantic Similarity Explainer with AI

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.

## 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 https://github.com/Umer-K/semantic-similarity-explainer.git
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.