README.md

---

title: Semantic Search Cache API
emoji: 🔎
colorFrom: blue
colorTo: purple
sdk: docker
python_version: "3.10"
app_file: app.py
app_port: 7860
pinned: false
---

# Semantic Search Cache API

This project provides a **semantic search engine with caching and fuzzy clustering**.

It uses:

* Sentence embeddings
* FAISS vector index
* Gaussian Mixture Model clustering
* Semantic caching

The API is built with **FastAPI** and deployed using **Docker** on Hugging Face Spaces.

---

## Features

* Semantic similarity search
* FAISS vector indexing
* Semantic cache for faster repeated queries
* Fuzzy clustering with GMM
* REST API endpoints

---

## API Endpoints

### POST `/query`

Example request:

```json
{
  "query": "space shuttle launch",
  "top_k": 5
}
```

### GET `/cache/stats`

Returns semantic cache statistics.

### DELETE `/cache`

Clears the cache.

---

## Project Structure

```
semantic-search-cache/
│
├── api/
│   └── main.py
│
├── src/
│   ├── query_engine.py
│   ├── semantic_cache.py
│   ├── fuzzy_cluster.py
│
├── models/
│   ├── faiss_index.index
│   ├── documents.pkl
│   └── gmm_model.pkl
│
├── requirements.txt
├── Dockerfile
└── app.py
```

---

## Deployment

This project is deployed using **Docker** on Hugging Face Spaces.

The container exposes port **7860** and runs a FastAPI server using Uvicorn.