---
title: HackathonSpaceRecommender
emoji: 🤗
colorFrom: yellow
colorTo: red
sdk: gradio
sdk_version: 6.19.0
python_version: '3.13'
app_file: app.py
pinned: true
short_description: Discover Hackathon Spaces with natural language
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/683d69c43015d6c975e276c1/6YD-6mwx3_JX7idRJiX8d.png
---

Discover Build Small Hackathon Spaces through a cached, README-aware recommender.

## Features

- Live Hugging Face Spaces listing with local cache fallback
- README fetching, cleaning, and deterministic summarization
- Rule-based taxonomy and track detection
- Keyword plus TF-IDF searchable index
- Natural-language recommendations with concise reasons built from semantic profiles and README evidence
- Local-only query profiling and reranking
- Browse-by-category view, index refresh, and shared comments modal
- Shared notes and Space likes saved in the bucket-mounted SQLite database

## Persistence

- Index snapshot: `data/spaces_index.json`
- Local fallback cache: `data/spaces_cache.json`
- Sample fallback: `data/sample_spaces.json`
- Shared database: `/data/hackathon-space-recommender/build_small_quest_finder.sqlite3` on the mounted Hugging Face bucket volume
- Optional storage override: `BSQF_STORAGE_DIR` (must point inside `/data/` to stay bucket-backed)
- Environment override: `BSQF_ORG_NAME`

## Local development

```bash
pip install -r requirements.txt
python app.py
```

## Cache refresh

```bash
python scripts/update_spaces_cache.py
```

## Recommendation pipeline

Recommendations are generated locally from cached README data, semantic profiles, evidence snippets, and bucket-backed likes stored in SQLite. No external LLM API key is required for the core experience.