Hide and seek dataset for fine tuninig

.gitignore

@@ -110,3 +110,30 @@ app/data/*/run_generation.log
 # other files to ignore
 CityQuest_AI_Project_Specification.md
 ai_pipeline_source_of_truth.md
+scavenger_hunt_pipeline_summary.md
+keys.txt
+scripts/.key_state
+scripts/key_manager.py
+scripts/scavenger_hunt/run_generation.py
+prompts/hide_and_seek_spec.md
+prompts/tag_spec.md
+scripts/common/cq_common.py
+scripts/hide_and_seek/generator.py
+scripts/hide_and_seek/run_generation.py
+scripts/hide_and_seek/sampler.py
+scripts/hide_and_seek/test_pipeline.py
+scripts/hide_and_seek/validate_dataset.py
+scripts/hide_and_seek/validator.py
+scripts/scavenger_hunt/generator.py
+
+scripts/scavenger_hunt/run_generation.py
+scripts/scavenger_hunt/sampler.py
+scripts/scavenger_hunt/validator.py
+
+scripts/tag/sampler.py
+scripts/scavenger_hunt/validator.py
+scripts/tag/generator.py
+scripts/tag/run_generation.py
+scripts/tag/test_pipeline.py
+scripts/tag/validate_dataset.py
+scripts/tag/validator.py

scripts/scavenger_hunt/generator.py

@@ -246,6 +246,7 @@ def main():
     errors_path = args.output.replace(".json", "_errors.jsonl")
     start_idx   = len(dataset) + 1
     kept = skipped = 0
+    quota_exhausted = False
 
     # ── generation loop ───────────────────────────────────────────────────────
     for i in range(start_idx, start_idx + args.n):
@@ -274,6 +275,11 @@ def main():
                 f.write(json.dumps({"id": record["id"], "errors": errors}) + "\n")
             log.info("    ✗  skipped after retries — logged to %s", errors_path)
 
+            if not args.mock and any("RESOURCE_EXHAUSTED" in e or "429" in e for e in errors):
+                log.warning("    quota exhausted on this API key — stopping run early")
+                quota_exhausted = True
+                break
+
         if not args.mock:
             time.sleep(args.sleep)
 
@@ -286,6 +292,9 @@ def main():
     if skipped:
         log.info("  Failures: %s", errors_path)
 
+    if quota_exhausted:
+        raise SystemExit(2)
+
 
 if __name__ == "__main__":
     main()

scripts/scavenger_hunt/run_generation.py

@@ -20,6 +20,9 @@ import sys
 from collections import Counter
 
 HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, ".."))
+import key_manager
+
 GENERATOR = os.path.join(HERE, "generator.py")
 DEFAULT_OUTPUT = os.path.normpath(os.path.join(
     HERE, "..", "..", "app", "data", "scavenger_hunt", "dataset.json"))
@@ -55,8 +58,8 @@ def main():
     ap.add_argument("--sleep",  type=float, default=8.0,           help="seconds between Gemini calls (passed to generator.py)")
     args = ap.parse_args()
 
-    if not os.environ.get("GEMINI_API_KEY"):
-        print("GEMINI_API_KEY is not set in this shell. Set it before running.")
+    if not key_manager.load_keys():
+        print(f"No API keys found in {key_manager.KEYS_FILE}. Add at least one key (one per line) before running.")
         sys.exit(1)
 
     try:
@@ -67,11 +70,27 @@ def main():
                 print(f"\nTarget reached: {current}/{args.target} examples in {args.output}")
                 break
 
+            idx, key = key_manager.get_active_key()
+            if key is None:
+                print(f"\nAll API keys in {key_manager.KEYS_FILE} are exhausted.")
+                print(f"Progress so far: {current}/{args.target} examples in {args.output}")
+                print("Add more keys or wait for quotas to reset, then re-run to resume.")
+                break
+
             n = min(args.batch, args.target - current)
-            print(f"\n=== Generating {n} example(s)  ({current} -> {current + n} of {args.target}) ===")
+            print(f"\n=== Generating {n} example(s)  ({current} -> {current + n} of {args.target})  [key #{idx + 1}] ===")
+
+            env = os.environ.copy()
+            env["GEMINI_API_KEY"] = key
             result = subprocess.run(
-                [sys.executable, GENERATOR, "--n", str(n), "--output", args.output, "--sleep", str(args.sleep)]
+                [sys.executable, GENERATOR, "--n", str(n), "--output", args.output, "--sleep", str(args.sleep)],
+                env=env,
             )
+
+            if result.returncode == 2:
+                print(f"  Key #{idx + 1} quota exhausted — rotating to the next key.")
+                key_manager.rotate_key()
+                continue
             if result.returncode != 0:
                 print("generator.py exited with an error — stopping.")
                 break

scripts/scavenger_hunt/sampler.py

@@ -4,42 +4,13 @@ Samples ONE input config in Python (distributions guaranteed here, not by the LL
 and builds a prompt asking Gemini to write only the output for that input.
 """
 import json
+import os
 import random
+import sys
 
-# ── city bank ─────────────────────────────────────────────────────────────────
-# (city_name) -> (country, code, available_tags, climate_zone)
-CITY_BANK = {
-    "Paris":         ("France",        "PAR", ["iconic_landmark","wide_boulevard","river_waterfront","garden_formal","historic_district","cafe_dense","museum_cluster"],       "temperate"),
-    "Tokyo":         ("Japan",         "TYO", ["dense_urban_grid","narrow_alley_network","religious_site_accessible","market_covered","iconic_landmark","shopping_street"],    "temperate"),
-    "New York City": ("USA",           "NYC", ["dense_urban_grid","park_large","iconic_landmark","coastal_waterfront","museum_cluster","wide_boulevard"],                      "continental"),
-    "Cape Town":     ("South Africa",  "CPT", ["coastal_waterfront","hill_or_elevation","market_outdoor","historic_district","garden_formal"],                                 "mediterranean"),
-    "Marrakech":     ("Morocco",       "MRK", ["narrow_alley_network","market_outdoor","religious_site_accessible","plaza_or_square","food_market"],                           "arid"),
-    "Buenos Aires":  ("Argentina",     "BUE", ["wide_boulevard","plaza_or_square","cafe_dense","street_art_district","historic_district"],                                     "temperate"),
-    "Mumbai":        ("India",         "BOM", ["coastal_waterfront","market_outdoor","dense_urban_grid","religious_site_accessible","food_market"],                            "tropical"),
-    "Berlin":        ("Germany",       "BER", ["park_large","street_art_district","museum_cluster","historic_district","wide_boulevard","cafe_dense"],                         "continental"),
-    "Sydney":        ("Australia",     "SYD", ["coastal_waterfront","park_large","iconic_landmark","market_covered","bridge_pedestrian"],                                      "temperate"),
-    "Nairobi":       ("Kenya",         "NBO", ["park_large","market_outdoor","residential_neighbourhood","dense_urban_grid"],                                                  "tropical"),
-    "Istanbul":      ("Turkey",        "IST", ["historic_district","religious_site_accessible","market_covered","coastal_waterfront","hill_or_elevation","plaza_or_square"],   "mediterranean"),
-    "Mexico City":   ("Mexico",        "MEX", ["plaza_or_square","market_outdoor","museum_cluster","street_art_district","dense_urban_grid"],                                  "temperate"),
-    "Amsterdam":     ("Netherlands",   "AMS", ["river_waterfront","bridge_pedestrian","narrow_alley_network","cafe_dense","museum_cluster","park_small"],                      "temperate"),
-    "Bangalore":     ("India",         "BLR", ["park_large","market_outdoor","cafe_dense","residential_neighbourhood","shopping_street"],                                      "tropical"),
-    "Lagos":         ("Nigeria",       "LOS", ["coastal_waterfront","market_outdoor","dense_urban_grid","food_market"],                                                        "tropical"),
-    "Seoul":         ("South Korea",   "SEO", ["dense_urban_grid","shopping_street","park_large","historic_district","narrow_alley_network"],                                  "continental"),
-    "Copenhagen":    ("Denmark",       "CPH", ["coastal_waterfront","cafe_dense","bridge_pedestrian","market_covered","park_small"],                                           "continental"),
-    "Lisbon":        ("Portugal",      "LIS", ["hill_or_elevation","narrow_alley_network","historic_district","coastal_waterfront","plaza_or_square"],                         "mediterranean"),
-    "Bogota":        ("Colombia",      "BOG", ["street_art_district","market_outdoor","park_large","historic_district","plaza_or_square"],                                     "temperate"),
-    "Auckland":      ("New Zealand",   "AKL", ["coastal_waterfront","hill_or_elevation","park_large","market_outdoor","bridge_pedestrian"],                                    "temperate"),
-}
-
-DENSITY = {
-    "Paris":"dense","Tokyo":"hyper_dense","New York City":"hyper_dense",
-    "Cape Town":"mixed","Marrakech":"dense","Buenos Aires":"dense",
-    "Mumbai":"hyper_dense","Berlin":"dense","Sydney":"mixed",
-    "Nairobi":"mixed","Istanbul":"dense","Mexico City":"hyper_dense",
-    "Amsterdam":"dense","Bangalore":"dense","Lagos":"hyper_dense",
-    "Seoul":"hyper_dense","Copenhagen":"mixed","Lisbon":"dense",
-    "Bogota":"dense","Auckland":"mixed",
-}
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "..", "common"))
+from cq_common import CITY_BANK, DENSITY, AREA_TYPES, AGE_GROUPS, compute_exclusions, climate_note
 
 # (duration_minutes, difficulty) → task count
 TASK_COUNT = {
@@ -50,9 +21,6 @@ TASK_COUNT = {
     (120,"easy"):8, (120,"medium"):10,(120,"hard"):12,
 }
 
-AREA_TYPES  = ["city_center","historic_district","waterfront","park_district",
-               "mixed_residential","market_district","university_campus"]
-AGE_GROUPS  = ["children_only","teens","adults","mixed_family","mixed_adults"]
 THEMES      = ["observation","history","social","nature","urban_exploration","photography","logic"]
 TASK_TYPES  = ["find_and_photograph","observe_and_answer","collect_and_return",
                "reach_and_verify","social_interaction","timed_challenge"]
@@ -137,23 +105,8 @@ def build_prompt(record: dict) -> str:
     supervise     = age in ("children_only","mixed_family")
     max_task_time = int(dur * 0.80 // n_tasks)  # generous per-task ceiling
 
-    water_tags    = {"river_waterfront","lake_or_pond","coastal_waterfront"}
-    has_water     = bool(water_tags & set(loc["landscape_tags"]))
-    has_religious = "religious_site_accessible" in loc["landscape_tags"]
-
-    exclusions = ["private_property","active_roadway","construction_sites",
-                  "restricted_government_buildings"]
-    if has_water:    exclusions.append("water_edge")
-    if has_religious: exclusions.append("religious_interiors")
-
-    climate_note = {
-        "tropical":      "Tropical climate — note heat/humidity; require shade access within 10 min of each task.",
-        "arid":          "Arid climate — mandatory water advisory; no sustained outdoor walk > 15 min per task.",
-        "mediterranean": "Mediterranean climate — no special constraint.",
-        "temperate":     "Temperate climate — no special constraint.",
-        "continental":   f"Continental climate — {'add cold-weather advisory (duration ' + str(dur) + ' min).' if dur >= 90 else 'no special constraint.'}",
-        "polar":         "Polar climate — all outdoor tasks ≤ 15 min each; mandatory warm-clothing note.",
-    }.get(loc["climate_zone"], "No special constraint.")
+    exclusions       = compute_exclusions(loc["landscape_tags"])
+    climate_note_txt = climate_note(loc["climate_zone"], duration_minutes=dur, unit="task", unit_activity="walk")
 
     diff_rule = {
         "easy":   f"ALL {n_tasks} tasks easy (10 pts each). ZERO hard tasks.",
@@ -188,7 +141,7 @@ points scale          : easy=10, medium=20, hard=30
 max per-task time     : {max_task_time} min  (total task time MUST be ≤ {int(dur*0.85)} min)
 adult_supervision     : {json.dumps(supervise)}
 exclusion_zones       : {json.dumps(exclusions)}
-climate note          : {climate_note}
+climate note          : {climate_note_txt}
 
 ═══ ABSOLUTE RULES ═══
 1. NO proper nouns anywhere — no city names, landmark names, street names, brand names.

scripts/scavenger_hunt/validator.py

@@ -3,46 +3,17 @@ validator.py — scavenger_hunt
 Validates one training example. Returns (is_valid: bool, errors: list[str]).
 auto_fix() recomputes arithmetic fields in-place — never reject for math the model shouldn't be trusted with.
 """
-import re
+import os
+import sys
 from Levenshtein import distance as lev
 
-# ── proper-noun blocklist ──────────────────────────────────────────────────────
-_NOUNS = [
-    "Paris","Tokyo","New York","NYC","Cape Town","Marrakech","Buenos Aires",
-    "Mumbai","Berlin","Sydney","Nairobi","Istanbul","Mexico City","Amsterdam",
-    "Bangalore","Lagos","Seoul","Copenhagen","Lisbon","Bogota","Auckland",
-    # famous landmarks
-    "Eiffel","Louvre","Seine","Notre-Dame","Notre Dame","Montmartre",
-    "Shibuya","Senso-ji","Sensoji","Skytree","Harajuku",
-    "Central Park","Times Square","Brooklyn","Manhattan","Hudson",
-    "Table Mountain","Bosphorus","Hagia","Zocalo","Zócalo",
-    "Han River","Gyeongbokgung","Nyhavn","Alfama","Tagus",
-    "La Boca","Recoleta","Gateway of India","Marine Drive",
-    "Brandenburg","Tiergarten","Opera House","Harbour Bridge","Bondi",
-    "Big Ben","Statue of Liberty","Golden Gate","Taj Mahal",
-    "Colosseum","Vatican","Kremlin","Buckingham","Westminster",
-]
-_NOUN_RE = re.compile(r"\b(" + "|".join(re.escape(n) for n in _NOUNS) + r")\b")
-
-# ── controlled tag vocabulary ─────────────────────────────────────────────────
-VALID_TAGS = {
-    "park_large","park_small","river_waterfront","lake_or_pond",
-    "coastal_waterfront","forest_urban","garden_formal","hill_or_elevation",
-    "dense_urban_grid","wide_boulevard","narrow_alley_network","market_outdoor",
-    "market_covered","plaza_or_square","bridge_pedestrian","train_station_major",
-    "port_or_harbour","iconic_landmark","historic_district",
-    "religious_site_accessible","museum_cluster","street_art_district",
-    "university_campus","shopping_street","cafe_dense","food_market",
-    "residential_neighbourhood",
-}
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "..", "common"))
+from cq_common import VALID_TAGS, nouns_in as _nouns_in
 
 POINTS = {"easy": 10, "medium": 20, "hard": 30}
 
 
-def _nouns_in(text: str) -> list:
-    return _NOUN_RE.findall(text or "")
-
-
 def validate_example(ex: dict) -> tuple[bool, list[str]]:
     errors = []