zzstoatzz.io
semantic bufo search
find-bufo.com
bufo
1# find-bufo
2
3semantic search for the bufo zone
4
5**live at: [find-bufo.fly.dev](https://find-bufo.fly.dev/)**
6
7## overview
8
9a one-page application for searching through all the bufos from [bufo.zone](https://bufo.zone/) using multi-modal embeddings and vector search.
10
11## architecture
12
13- **backend**: rust (actix-web)
14- **frontend**: vanilla html/css/js
15- **embeddings**: voyage ai voyage-multimodal-3
16- **vector store**: turbopuffer
17- **deployment**: fly.io
18
19## setup
20
211. install dependencies:
22 - rust toolchain
23 - python 3.11+ with uv
24
252. copy environment variables:
26 ```bash
27 cp .env.example .env
28 ```
29
303. set your api keys in `.env`:
31 - `VOYAGE_API_TOKEN` - for generating embeddings
32 - `TURBOPUFFER_API_KEY` - for vector storage
33
34## ingestion
35
36to populate the vector store with bufos:
37
38```bash
39uvx scripts/ingest_bufos.py
40```
41
42this will:
431. scrape all bufos from bufo.zone
442. download them to `data/bufos/`
453. generate embeddings for each image
464. upload to turbopuffer
47
48## development
49
50run the server locally:
51
52```bash
53cargo run
54```
55
56the app will be available at `http://localhost:8080`
57
58## deployment
59
60deploy to fly.io:
61
62```bash
63fly launch # first time
64fly secrets set VOYAGE_API_TOKEN=your_token
65fly secrets set TURBOPUFFER_API_KEY=your_key
66fly deploy
67```
68
69## usage
70
711. open the app
722. enter a search query describing the bufo you want
733. see the top matching bufos with similarity scores
744. click any bufo to open it in a new tab
75
76## how it works
77
781. **ingestion**: all bufo images are embedded using voyage ai's multimodal model
792. **search**: user queries are embedded with the same model
803. **retrieval**: turbopuffer finds the most similar bufos using cosine distance
814. **display**: results are shown with similarity scores