hash066/mvj-vectorsearch

Lost & Found Vector Search API

A FastAPI backend for lost and found item vector search using embeddings, vector databases, and reranking.

Features

• —Ingest Items: Embed and store lost/found items with metadata.
• —Vector Search: Search for similar items using images, text, or features.
• —Reranking: Score results based on similarity, geo-distance, time, and metadata matches.
• —Feedback: Log user feedback for later improvement.
• —Support Multiple Embedding Backends: Google Gemini, OpenCLIP, sentence-transformers.
• —Vector DB Options: Pinecone (preferred), Qdrant, or local FAISS.
• —Metadata Storage: SQLite for structured data.

Endpoints

• —POST /lostfound/ingest - Ingest a new item
• —POST /lostfound/search - Search for matching items
• —POST /lostfound/feedback - Submit feedback on search results
• —GET /lostfound/item/{id} - Retrieve item details
• —GET /health - Health check

Setup

Local Development

1. 1.Clone the repo.
2. 2.Install Python 3.11.
3. 3.Install dependencies:

   pip install -r requirements.txt

1. 1.Set environment variables (see below).
2. 2.Run the server:

   uvicorn main:app --reload

1. 1.API will be at http://localhost:8000.

Docker

1. 1.Build and run with docker-compose:

   cd docker
   docker-compose up --build

1. 1.API at http://localhost:8000.

Hugging Face Spaces

1. 1.Fork this repo to Hugging Face Spaces.
2. 2.Add secrets for API keys.
3. 3.Deploy as is.

Environment Variables

• —GOOGLE_API_KEY: For Gemini embeddings. If not set, falls back to OpenCLIP/sentence-transformers.
• —PINECONE_API_KEY: Pinecone API key.
• —PINECONE_INDEX: Pinecone index name (default: "lostfound").
• —PINECONE_ENV: Pinecone environment (default: "us-east-1").
• —QDRANT_URL: Qdrant server URL (default: "http://localhost:6333").
• —QDRANT_COLLECTION: Qdrant collection name (default: "lostfound").
• —THUMBNAIL_BASE_URL: Base URL for fallback thumbnail images (default: "http://your-storage.com/thumbs").

If Pinecone keys not provided, tries Qdrant, else FAISS (local).

Usage Examples

Ingest Item

curl -X POST http://localhost:8000/lostfound/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "type": "found",
    "timestamp": "2025-11-17T12:00:00Z",
    "source": "user",
    "location": [12.9715987, 77.594566],
    "metadata": {"color": "black", "category": "bag"}
  }'

Search Items

curl -X POST http://localhost:8000/lostfound/search \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req-123",
    "timestamp": "2025-11-17T12:00:00Z",
    "source": "ui",
    "location": [12.9716, 77.5946],
    "radius_m": 1000,
    "payload": {"mode": "features", "features": {"color": "black", "category": "bag"}},
    "k": 10
  }'

Feedback

curl -X POST http://localhost:8000/lostfound/feedback \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req-123",
    "item_id": "uuid-1",
    "candidate_id": "uuid-2",
    "label": "match"
  }'

Health

curl http://localhost:8000/health

Testing

Run tests:

python tests/test_api.py

Sample Scripts

• —scripts/ingest_sample.py: Sample ingest request.
• —scripts/query_example.py: Sample search request.

Run with:

python scripts/ingest_sample.py

Reranking Formula

Final score = sigmoid(wsim * sim + wgeo geo_score - w_time timedeltanorm + wmeta * metascore)

• —wsim=0.7, wgeo=0.15, wtime=0.1, wmeta=0.05

Deployment

For Hugging Face Spaces:

• —Add app/ as root if needed.
• —Set env vars in secrets.