We used a Sentence Transformer model to create embeddings for charity descriptions and save these in a FAISS Index for quick retrieval, enabling natural language search for charities.

Go to https://recommender-fast-api-production.up.railway.app/docs to see the Swagger docs for the Cloud API. Swagger also allows you to 'Try It Out' from the UI.

Alternatively run the following curl command (replace the query string as desired):

curl -X 'POST' \
  'https://recommender-fast-api-production.up.railway.app/recommend' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "helping homeless"
}'

1. Create conda environment:

conda env create -f environment.yml
conda activate faiss-env

2. Run python build_faiss_index.py OR ask one of the contributors for the charity_faiss.index and charity_faiss_mapping.json files. (build_faiss_index.py takes ~40 min to run on a CPU)

Ensure conda environment is activated. If not, run conda activate faiss-env.

1. Run uvicorn api:app --reload to start the local API server
2. Go to "http://127.0.0.1:8000/docs" to view the Swagger docs and try out the API. Alternatively, run the following from the terminal:

curl -X 'POST' \
  'http://localhost:8000/recommend' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "helping homeless"
}'

Minimal instructions for downloading FAISS assets at container start (avoids Railway build-time timeout)

1. Set environment variables:

• FAISS_INDEX_URL: URL to download charity_faiss.index
• FAISS_JSON_URL: URL to download charity_faiss_mapping.json

2. Build the Docker image locally:

docker build -t donation-downloader:local .

3. Run container (downloads at start):

docker run --rm -e FAISS_INDEX_URL="https://example.com/charity_faiss.index" \
  -e FAISS_JSON_URL="https://example.com/charity_faiss_mapping.json" \
  donation-downloader:local

4. To run your app after downloads, provide the command as arguments to the container. Example (replace with your start command):

docker run --rm -e FAISS_INDEX_URL=... -e FAISS_JSON_URL=... donation-downloader:local yarn start

Notes:

• The downloader retries and streams the download to avoid large memory use.
• We intentionally download at container start (not during build) so Railway's build-time network timeout won't affect fetching large files.