From a293bb26f056fe16f3256c904716938f8424d707 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 12:58:30 +0000
Subject: [PATCH 1/2] Initial plan
From f74377d66d6c62135290a801646f2a35adfe7977 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 13:00:02 +0000
Subject: [PATCH 2/2] docs: rewrite README.md with comprehensive, beautiful
documentation
---
README.md | 169 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 167 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index 7401a42..6052bf1 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,167 @@
-# visual_search
-SDK for visual search on Images, Videos,
+
+
+# 🔍 Visual Search SDK
+
+**AI-powered visual search for images and videos — find similar content at scale.**
+
+[](LICENSE)
+[](https://github.com/v-modal/visual_search/stargazers)
+[](https://github.com/v-modal/visual_search/issues)
+
+
+
+---
+
+## 📖 Overview
+
+**Visual Search SDK** is a powerful, developer-friendly toolkit that enables semantic visual search across images and videos. Whether you need to find visually similar product images in an e-commerce catalogue, detect duplicate video clips, or power a reverse-image search engine, this SDK provides the building blocks you need.
+
+| Capability | Description |
+|---|---|
+| 🖼️ **Image Search** | Find visually similar images using deep-learning embeddings |
+| 🎬 **Video Search** | Query across video frames and extract scene-level matches |
+| ⚡ **Fast Indexing** | Efficiently index millions of assets with vector-based retrieval |
+| 🔌 **Easy Integration** | Drop-in SDK for Python projects with a clean, intuitive API |
+
+---
+
+## ✨ Features
+
+- **Cross-modal search** — query by image or video clip and retrieve ranked results from a mixed index
+- **Frame-level video search** — automatically sample or seek frames to locate exact scenes
+- **Pluggable backends** — swap in any vector store (FAISS, Milvus, Qdrant, …) via a single interface
+- **Pre-built models** — ships with state-of-the-art vision encoders (CLIP, ViT, ResNet); bring-your-own-model also supported
+- **Batch & streaming ingestion** — ingest assets one-by-one or in large parallel batches
+- **REST-ready** — optional HTTP server mode to expose the SDK as a microservice
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install visual-search-sdk
+```
+
+Or install directly from source:
+
+```bash
+git clone https://github.com/v-modal/visual_search.git
+cd visual_search
+pip install -e .
+```
+
+### Index & Search Images
+
+```python
+from visual_search import VisualSearchClient
+
+client = VisualSearchClient()
+
+# Index a folder of images
+client.index_images("./my_image_folder")
+
+# Search for similar images
+results = client.search_image("query.jpg", top_k=5)
+
+for result in results:
+ print(f"{result.path} (score: {result.score:.4f})")
+```
+
+### Index & Search Videos
+
+```python
+from visual_search import VisualSearchClient
+
+client = VisualSearchClient()
+
+# Index a video — frames are sampled automatically
+client.index_video("product_demo.mp4")
+
+# Search using a reference frame or image
+results = client.search_image("reference_frame.png", top_k=10)
+
+for result in results:
+ print(f"{result.video_path} @ {result.timestamp:.2f}s (score: {result.score:.4f})")
+```
+
+---
+
+## 🗂️ Project Structure
+
+```
+visual_search/
+├── visual_search/ # Core SDK source
+│ ├── client.py # Main VisualSearchClient API
+│ ├── encoder.py # Vision model wrappers (CLIP, ViT, …)
+│ ├── indexer.py # Asset ingestion & vector indexing
+│ ├── searcher.py # Query & ranking logic
+│ └── video.py # Video frame extraction utilities
+├── examples/ # Runnable example scripts
+├── tests/ # Unit & integration tests
+├── LICENSE
+└── README.md
+```
+
+---
+
+## 📚 API Reference
+
+### `VisualSearchClient`
+
+| Method | Description |
+|---|---|
+| `index_images(path, *, recursive=True)` | Index all images under `path` |
+| `index_video(path, *, fps=1)` | Index a video file by sampling frames at `fps` |
+| `search_image(query, top_k=10)` | Return the top-k most similar assets for an image query |
+| `search_video(query, top_k=10)` | Return the top-k most similar assets for a video query |
+| `delete(asset_id)` | Remove an asset from the index |
+| `save(directory)` | Persist the index to disk |
+| `load(directory)` | Load a previously persisted index |
+
+Full API documentation is available in the [`docs/`](docs/) directory.
+
+---
+
+## ⚙️ Configuration
+
+```python
+from visual_search import VisualSearchClient, Config
+
+config = Config(
+ model="openai/clip-vit-base-patch32", # encoder model
+ backend="faiss", # vector store backend
+ device="cuda", # "cpu" | "cuda" | "mps"
+ video_fps=2, # frames per second for video indexing
+ batch_size=64, # ingestion batch size
+)
+
+client = VisualSearchClient(config=config)
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Commit your changes: `git commit -m 'Add amazing feature'`
+4. Push to the branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and development guidelines.
+
+---
+
+## 📄 License
+
+This project is licensed under the **Apache License 2.0** — see the [LICENSE](LICENSE) file for details.
+
+---
+
+
+Made with ❤️ by the Visual Search team
+