# EverydayMMQA: A Multilingual and Multimodal Framework for Culturally Grounded Spoken Visual QA

## Configuration Notes

Before running the scripts, ensure you:

1. Replace `your-gcp-project-id` with your actual Google Cloud Project ID
2. Update environment files with your API keys
3. Modify file paths to match your directory structure

### Resources

This directory contains both codes and a small amount of data.

#### Code

We shared code files along with prompts (if applicable) for reproduciblity as follows:

- [Topic Generation](./bin/generate_topics/generate_topics.py)
- [Query Generation using GPT-4.1, Gemini, Claude](./bin/generate_queries/)
- [Cultural Relevancy of Query](./bin/generate_queries/query_relevancy_GPT_4o.py)
- [Filtering Queries using Relevancy Score](./bin/generate_queries/filter_data_by_rel_score.py)
- [Google Image Search and Downloads](./bin/google-search.py)
- [Downloading Images](./bin/download_images.py)
- [Near Duplicate Image Filtering](./bin/dedup/filter_near_duplicates_flann.py)
- [Image Description Generation](./bin/generate_description/)
- [QA Generation from Images and Parsing](./bin/generate_QA/)
- [Dilectal Translation](./bin/batch_translation/)
- [LLM-based Annotation](./bin/annotation_llm/)

##### Generate Topics

```bash
python bin/generate_topics/generate_topics.py \
    --category_file category_file \
    --country_file list_of_country_text_file \
    --output_file data/queries/all_countries_category_subcategory_topics.json \
    --env_file envs/env.env
```

##### Generate Queries

```bash
python bin/generate_queries/create_queries_gpt_eng.py \
  --topic_file data/queries/category_subcategory_topics.json \
  --output_file data/queries/collection/english/queries_country_gpt.json \
  --cached_dir data/queries/cache_queries_gpt/ \
  --env_file envs/env.env
```

##### Query Relevancy

```bash
python bin/generate_queries/query_relevancy_GPT_4o.py \
  --input_file data/queries/combined_queries_country.jsonl \
  --env_path envs/env.env \
  --output_dir data/queries/cached_dir/query_relevancy_gpt41_country/
```

##### Relevancy Filtering

```bash
python bin/generate_queries/filter_data_by_rel_score.py \
  --input_file data/queries/combined_queries_with_relevancy_country.jsonl \
  --output_file data/queries/combined_queries_with_relevancy_country_rel_80.jsonl \
  --threshold 80
```

##### Google Search

```bash
python bin/google-search.py -e envs/gs_api.env \
  -r data/queries/subcategory_priority.tsv \
  -q data/queries/combined_queries_with_relevancy_country_rel_80.jsonl \
  -o output/ \
  -c [country_name]
```

##### Download images

```bash
python bin/download_images.py --input_dir "data/crawled_images/country/responses/"
  --image_save_dir "data/crawled_images/country/images/" \
  --jsonl_save_path "data/crawled_images/country/country_img_queries.jsonl" \
  --max_workers 15
```

##### Filter duplicate images

```bash
python bin/dedup/filter_near_duplicates_flann.py \
  -i data/crawled_images/country/country_img_queries.jsonl \
  -o data/crawled_images/country/country_dup_image_filtered.jsonl
```

##### Image Description Generation

```bash
python bin/filtering/generate_img_desc_and_categorize_image.py \
  --input_file data/crawled_images/country/country_dup_image_filtered.jsonl \
  --cached_dir cached_dir/img_desc_and_category/GPT-4.1/ \
  --env_path envs/env.env \
  --category "Culture, Arts & Entertainment"
```

##### Generate QA

```bash
python bin/generate_QA/generate_QA_batch_submit.py \
  --input cached_dir/img_desc_and_category/country/country_img_desc_and_category_batch_retrieved.jsonl \
  --env_file envs/env.env \
  --output_dir cached_dir/QA/country/GPT-4.1_batch/ \
  --batch_file cached_dir/QA/country/country_qa_generation_batch.txt
```

##### LLM Annotation

```bash
python bin/annotation_llm/run_batch_llm_annotation.py \
  --input-jsonl data/image_desc_qa_splits/country/country_image_desc_qa_dev_100.jsonl \
  --out-dir cached_dir/llm_annotation/country/ \
  --batch-tracking-file cached_dir/llm_annotation/country/batch_tracking.json \
  --project-id google_project_id \
  --location us-central1 \
  --google-application-credentials envs/google_authentication.json \
  --gcs-bucket "google_bucket_name" \
  --gcs-prefix batch_inference_llm_annotation \
  --model gemini-2.5-pro \
  --temperature 0.0 \
  --max-output-tokens 8000 \
  --include-safety-settings


# 2) Fetch + merge
python bin/annotation_llm/fetch_and_merge_batch_results.py \
  --batch-tracking-file cached_dir/llm_annotation/country/batch_tracking.json \
  --input-jsonl data/image_desc_qa_splits/country/country_image_desc_qa_dev_100.jsonl \
  --merged-output-jsonl cached_dir/llm_annotation/country/country_image_desc_qa_dev_items_with_llm_annotations.jsonl \
  --project-id project_id \
  --location us-central1 \
  --google-application-credentials envs/google_authentication.json \
  --save-output-dir results/batch_results \
  --latest-file-only
```

### Data

[Data](./data/) folder contains images, speech, and jsonl files.

The structure of ajson object is as follows:

```json
msa_description": "\u062a\u064f\u0638\u0647\u0631 \u0627{
  "image_id": "f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6",
  "country": "Qatar",
  "category": "History, Geography & National Identity",
  "subcategory": "Geography & Cultural Regions",
  "image_url": "https://st5.depositphotos.com/19085394/64931/i/1600/depositphotos_649311054-stock-photo-skyline-doha-capital-qatar.jpg",
  "image_path": "./data/crawled_images/Qatar/images/history_geography_and_national_identity/geography_and_cultural_regions/f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6.jpg",
  "image_desc_meta": {
    "en_description": "A photograph showing a skyline of modern high-rise buildings along a waterfront, with clear blue skies and water in the foreground. The architecture includes unique and varied designs, some under construction.",
    "image_category": "Photograph",
    "msa_description": "صورة تظهر أفق المباني الشاهقة الحديثة على طول الواجهة البحرية، مع سماء زرقاء صافية والمياه في المقدمة. وتشمل الهندسة المعمارية تصاميم فريدة ومتنوعة، وبعضها قيد الإنشاء.",
    "ajp_description": "صورة بتفرجي أفق من مباني عالية حديثة عالواجهة البحرية، والسماء صافية زرقا والمَيّ قدام. العمارة فيها تصاميم مميزة ومختلفة، وفيه بعضها لسه تحت الإنشاء.",
    "arz_description": "صورة بتبين أفق المدينة مليان عمارات عالية وحديثة على البحر، والسماء صافية والمية قدام الصورة. المباني ليها تصاميم مختلفة ومميزة، وفيه شوية مباني لسه تحت الإنشاء."
  },
  "QA_meta": {
    "open-ended": [
      {
        "en_question": "What city is depicted in the image, known for its modern skyline and unique architectural designs along the waterfront?",
        "en_answer": "The image depicts Doha, the capital city of Qatar.",
        "en_rationale": "The skyline and waterfront, along with the modern and varied architectural designs, are characteristic of Doha, a major city in the Middle East.",
        "msa_question": "ما هي المدينة التي تظهر في الصورة، والمعروفة بأفقها الحديث وتصميماتها المعمارية الفريدة على طول الواجهة البحرية؟",
        "msa_answer": "الصورة تصور الدوحة، عاصمة قطر.",
        "msa_rationale": "تتميز الدوحة، وهي مدينة رئيسية في الشرق الأوسط، بأفقها وواجهتها البحرية، إلى جانب التصاميم المعمارية الحديثة والمتنوعة.",
        "ajp_question": "أي مدينة مبينة بالصورة، والمعروفة بأفقها العصري وتصاميمها المعمارية المميزة على الواجهة البحرية؟",
        "ajp_answer": "الصورة بتبين الدوحة، عاصمة قطر.",
        "ajp_rationale": "الأفق والكورنيش، مع التصاميم المعمارية الحديثة والمتنوعة، هني من ميزات الدوحة، وهي مدينة كبيرة بالشرق الأوسط.",
        "arz_question": "إيه المدينة اللي في الصورة، المشهورة بأبراجها الحديثة وتصميماتها المعمارية المميزة على الكورنيش؟",
        "arz_answer": "الصورة بتورّي الدوحة، عاصمة قطر.",
        "arz_rationale": "الأفق والكورنيش، مع التصاميم المعمارية الحديثة والمتنوعة، هما من الحاجات اللي بتميز الدوحة، واحدة من أكبر المدن في الشرق الأوسط.",
        "en_audio_file_gen": "./data/speech/xtts_v2_wav_en/qatar/wav/Qatar/geography_and_cultural_regions/0_f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_open-ended_1089.wav",
        "msa_audio_file_gen": "./data/speech/xtts_v2_wav_msa_v2/qatar/test/wav/geography_and_cultural_regions/f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_open-ended_0_0.wav",
        "en_human_audio_file_gen": [
          "./data/speech/recordings/english/qatar/wav/qatar/history_geography_and_national_identity/geography_and_cultural_regions/f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_open_q_269.wav"
        ],
        "en_human_answer": "The image depicts Doha, the capital city of Qatar.",
        "en_trans_original_question": "The city is depicted in the image known for its modern skyline and unique architectural designs along the waterfront.",
        "en_trans_original_answer": "The image depicts Doha, the capital city of Qatar."
      }
    ],
    "multiple-choice": [
      {
        "en_question": "Which city is famous for the skyline shown in the image, featuring modern high-rise buildings along a waterfront?",
        "en_answer": "Doha, Qatar",
        "en_rationale": "Doha's skyline is distinct for its waterfront location and varied architectural designs, distinguishing it from other cities like Dubai or Manama.",
        "en_options": [
          "Doha, Qatar",
          "Dubai, UAE",
          "Manama, Bahrain"
        ],
        "msa_question": "أي مدينة هي المشهورة بالأفق المبين في الصورة، والتي تضم المباني الشاهقة الحديثة على طول الواجهة البحرية؟",
        "msa_answer": "الدوحة، قطر",
        "msa_rationale": "أفق الدوحة متميز بموقعه على الواجهة البحرية والتصاميم المعمارية المتنوعة، وتمييزه عن غيره من المدن مثل دبي أو المنامة.",
        "msa_options": [
          "الدوحة، قطر",
          "دبي، الإمارات العربية المتحدة",
          "المنامة، البحرين"
        ],
        "ajp_question": "أي مدينة مشهورة بالأفق اللي مبين بالصورة، واللي فيه مباني عالية حديثة على الواجهة البحرية؟",
        "ajp_answer": "الدوحة، قطر",
        "ajp_rationale": "أفق الدوحة مميز بموقعه عالبحر وتصاميمه المعمارية المتنوعة، وهاد الشي بفرّقه عن مدن تانية مثل دبي أو المنامة.",
        "ajp_options": [
          "الدوحة، قطر",
          "دبي، الإمارات",
          "المنامة، البحرين"
        ],
        "arz_question": "أنهي مدينة مشهورة بالمنظر اللي في الصورة، اللي فيه أبراج عالية حديثة جنب البحر؟",
        "arz_answer": "الدوحة، قطر",
        "arz_rationale": "أفق الدوحة مميز عشان موقعه على البحر وتصميماته المعمارية المختلفة، وده اللي بيخليه مختلف عن مدن تانية زي دبي أو المنامة.",
        "arz_options": [
          "الدوحة، قطر",
          "دبي، الإمارات",
          "المنامة، البحرين"
        ],
        "en_audio_file_gen": "./data/speech/xtts_v2_wav_en/qatar/wav/Qatar/geography_and_cultural_regions/0_f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_multiple-choice_4077.wav",
        "msa_audio_file_gen": "./data/speech/xtts_v2_wav_msa_v2/qatar/test/wav/geography_and_cultural_regions/f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_multiple-choice_0_0.wav",
        "en_human_audio_file_gen": [
          "./data/speech/recordings/english/qatar/wav/qatar/history_geography_and_national_identity/geography_and_cultural_regions/f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_mcq_269.wav"
        ],
        "en_human_answer": "Doha, Qatar",
        "en_trans_original_question": "The city is depicted in the image known for its modern skyline and unique architectural designs along the waterfront.",
        "en_trans_original_answer": "Doha, Qatar"
      }
    ],
    "true_false": [
      {
        "en_question": "The image shows a skyline located in the Middle East.",
        "en_answer": "True",
        "en_rationale": "Doha, the capital of Qatar, is in the Middle East, and the skyline reflects its modern urban development.",
        "msa_question": "تظهر الصورة أفق يقع في الشرق الأوسط.",
        "msa_answer": "صحيح",
        "msa_rationale": "تقع الدوحة، عاصمة قطر، في الشرق الأوسط، ويعكس أفقها التطور الحضري الحديث.",
        "ajp_question": "الصورة بتبين أفق مدينة موجودة بالشرق الأوسط.",
        "ajp_answer": "صحيح",
        "ajp_rationale": "الدوحة، عاصمة قطر، موجودة بالشرق الأوسط، وأفق المدينة بيعكس تطورها العمراني الحديث.",
        "arz_question": "الصورة بتورّي منظر للمدينة في الشرق الأوسط.",
        "arz_answer": "صحيح",
        "arz_rationale": "الدوحة، عاصمة قطر، في الشرق الأوسط، والمنظر بتاع الأبراج فيها بيبين قد إيه المدينة متطورة وحديثة.",
        "en_audio_file_gen": "./data/speech/xtts_v2_wav_en/qatar/wav/Qatar/geography_and_cultural_regions/0_f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_true_false_0_7127.wav",
        "msa_audio_file_gen": "./data/speech/xtts_v2_wav_msa_v2/qatar/test/wav/geography_and_cultural_regions/f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_true_false_0_0.wav",
        "en_human_audio_file_gen": [
          "./data/speech/recordings/english/qatar/wav/qatar/history_geography_and_national_identity/geography_and_cultural_regions/f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_tf1_269.wav"
        ],
        "en_human_answer": "True",
        "en_trans_original_question": "The initial skyline located in the Middle East.",
        "en_trans_original_answer": "True"
      },
      {
        "en_question": "The buildings in the image are part of the skyline of New York City.",
        "en_answer": "False",
        "en_rationale": "The skyline shown is in Doha, Qatar, not New York City, as evidenced by the architectural style and waterfront location.",
        "msa_question": "المباني في الصورة هي جزء من أفق مدينة نيويورك.",
        "msa_answer": "خطأ",
        "msa_rationale": "الأفق الظاهر في الصورة هو في الدوحة، قطر، وليس مدينة نيويورك، كما يتضح من النمط المعماري وموقع الواجهة البحرية.",
        "ajp_question": "البنايات اللي بالصورة هني جزء من أفق نيويورك سيتي.",
        "ajp_answer": "غير صحيح",
        "ajp_rationale": "الأفق اللي مبين بالصورة هو في الدوحة، قطر، مش نيويورك، والدليل على هالشي هو أسلوب العمارة والموقع عالبحر.",
        "arz_question": "المباني اللي في الصورة دي جزء من منظر نيويورك.",
        "arz_answer": "غير صحيح",
        "arz_rationale": "المنظر اللي باين ده في الدوحة، قطر، مش نيويورك، وده باين من شكل العمارات والمكان اللي على البحر.",
        "en_audio_file_gen": "./data/speech/xtts_v2_wav_en/qatar/wav/Qatar/geography_and_cultural_regions/0_f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_true_false_1_4992.wav",
        "msa_audio_file_gen": "./data/speech/xtts_v2_wav_msa_v2/qatar/test/wav/geography_and_cultural_regions/f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_true_false_1_0.wav",
        "en_human_audio_file_gen": [
          "./data/speech/recordings/english/qatar/wav/qatar/history_geography_and_national_identity/geography_and_cultural_regions/f0729466f1ca36841f0d32c36cbfd0c8b30da71add8450a6af59fac422b4c0e6_tf2_271.wav"
        ],
        "en_human_answer": "False",
        "en_trans_original_question": "They will link in the image or part of a skyline in New York.",
        "en_trans_original_answer": "False"
      }
    ]
  }
}
```

## Data Release:

Will be made available under license CC BY-NC-SA 4.0 (https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en).
