README.md

metadata

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

pip install -r requirements.txt
python app.py

Cache refresh

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.