https://github.com/usemoss/moss-image-search-demo
https://github.com/usemoss/moss-image-search-demo
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/usemoss/moss-image-search-demo
- Owner: usemoss
- Created: 2025-11-01T16:16:35.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-03-03T07:29:15.000Z (5 months ago)
- Last Synced: 2026-03-03T07:55:09.835Z (5 months ago)
- Language: TypeScript
- Homepage: https://moss-image-search-demo.vercel.app
- Size: 1.78 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# 
Moss Demo Project - Image Search
Moss is a high-performance runtime for real-time semantic search. It delivers sub-10 ms lookups, instant index updates, and zero infra overhead. Moss runs where your agent lives - cloud, in-browser, or on-device - so search feels native and users never wait. You connect your data once; Moss handles indexing, packaging, distribution and updates.
This repo bundles thin, working examples that show how to talk to Moss from Python and JavaScript. Each sample keeps the scaffolding light so you can copy the essentials straight into your own projects.
> **Try out the live deployment of this sample project at https://moss-image-search-demo.vercel.app/**
> 
## Quick Start
**1. Create a single `.env` at the repo root** — copy `.env.example` and fill in your Moss credentials:
```bash
cp .env.example .env
```
All sub-projects read from this one file.
**2. Create the Moss index** (`coco-data-1k.json` is included — no download needed for the 1k tier):
```bash
cd setup-js && npm install && npx tsx createIndex.ts && cd ..
```
> To use 10k, 50k, or 100k tiers, run `npx tsx downloadCoco.ts` first to generate those files.
**3. Start the Python backend** (in one terminal):
```bash
cd backend-py
uv venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
uv sync
uvicorn main:app --reload
```
**4. Start the React app** (in another terminal):
```bash
cd react-app && npm install && npm run dev
```
Open [http://localhost:5173](http://localhost:5173) and start searching.
---
## 1. Go to Moss Portal and Get API Keys
- Visit [usemoss.dev](https://usemoss.dev/) to sign up, create an account, confirm your email, and sign in.
- From the dashboard, open **View secrets** and save the values as `MOSS_PROJECT_ID` and `MOSS_PROJECT_KEY` in the root `.env` file (copy `.env.example` → `.env`).
> 
## 2. Download Dataset
The demo uses COCO Captions images split into tiers (1k, 10k, 50k, 100k).
`coco-data-1k.json` is included in the repo — no download needed for the 1k tier. To use larger tiers (10k, 50k, 100k), run the download script to generate them:
**JavaScript:**
```bash
cd setup-js
npm install
npx tsx downloadCoco.ts
```
**Python:**
```bash
cd setup-py
uv venv && source .venv/bin/activate
uv sync
python download_coco.py
```
This generates `coco-data-10k.json`, `coco-data-50k.json`, and `coco-data-100k.json` in the project root.
## 3. Setup - Upload data and create index
All setup scripts read credentials from the **root `.env`** file (created in step 1). Use either the JS or Python tooling — they produce identical indexes.
### Setup JS
1. Navigate to the `setup-js` folder.
2. Install Node.js and npm.
3. Run `npm install` to install dependencies.
4. `npx tsx createIndex.ts` to create the index for the tier set in the root `.env` (`MOSS_INDEX_TIER`, default `1k`).
5. `npx tsx createAllIndexes.ts` to create indexes for all tiers.
6. `npx tsx query.ts` to load the index and run sample queries.
### Setup Python
1. Navigate to the `setup-py` folder.
2. Install Python 3.10+ and uv.
3. Create and activate a virtual environment:
- `uv venv`
- On Windows: `.\venv\Scripts\activate`
- On macOS/Linux: `source .venv/bin/activate`
4. Run `uv sync` to install dependencies.
5. Run `python create_index.py` to create the index for the tier set in the root `.env` (`MOSS_INDEX_TIER`, default `1k`).
6. Run `python create_all_indexes.py` to create indexes for all tiers.
7. Run `python query.py` to load the index and run sample queries.
## 4. Backend
A FastAPI backend is included in the `backend-py` folder. It proxies queries to Moss, keeping your API keys off the client. It reads credentials from the **root `.env`** file.
All routes are mounted under the `/demo/image-search` prefix:
- `GET /demo/image-search/search` — semantic search endpoint
- `GET /demo/image-search/health` — health check
- `GET /demo/image-search/image-proxy` — secure image proxy (rewrites `http://` COCO URLs to pass through the backend)
**Development server:**
1. Navigate to the `backend-py` folder.
2. Install Python 3.10+ and uv.
3. `uv venv && source .venv/bin/activate`
4. `uv sync` to install dependencies.
5. Run `uvicorn main:app --reload` to start the server.
**Docker:**
```bash
cd backend-py
docker build -t moss-backend .
docker run -p 8080:8080 --env-file ../.env moss-backend
```
## 5. React App powered by Moss
A sample React app is included in the `react-app` folder that demonstrates how to integrate Moss for semantic search. It reads `MOSS_PYTHON_API_URL` from the **root `.env`** file via Vite's env loading.
1. Navigate to the `react-app` folder.
2. Install Node.js and npm.
3. Run `npm install` to install dependencies.
4. Run `npm run dev` to start the development server.