GeoSemanticQA
=============

Semantic Parsing and Question Answering for Geographic Questions

This project demonstrates a research-oriented pipeline for geographic question modeling.

Pipeline:
Natural language question
→ semantic representation
→ formal query execution over a geographic knowledge graph
→ answer
→ evaluation and error analysis

Core ideas:
- Explicit semantic representation (not end-to-end black box)
- Rule-based symbolic baseline
- Optional model-assisted baseline
- Gold annotations for evaluation
- Error analysis for research insight

Why this project is relevant:
Geographic questions often involve:
- administrative constraints (e.g. cities in Germany)
- numeric constraints (e.g. population above X)
- relational constraints (e.g. rivers flowing through multiple countries)
- compositional reasoning

This repository focuses on representing and executing such questions explicitly.

Main components:
- Semantic schema for geographic questions
- Rule-based semantic parser
- Optional model-assisted parser
- Knowledge graph construction and query execution
- Evaluation metrics and error categorization

Quick start:
1. Create a virtual environment
2. Install requirements
3. Install the package in editable mode
4. Run demo or evaluation commands

Example question:
Which cities in Germany have a population above 1 million?

Example semantic representation:
intent: select
target_type: City
constraints:
- located_in = Germany
- population > 1000000

Command-line usage:
- geosemanticqa parse --q "your question"
- geosemanticqa answer --q "your question"
- geosemanticqa demo --n 10
- geosemanticqa evaluate

Data:
- data/kg.json: geographic knowledge graph
- data/questions.jsonl: natural language questions
- data/gold.jsonl: gold semantic annotations
- data/annotation_guidelines.md: annotation rules

Outputs:
- results/evaluation_report.json
- results/errors.json
- results/error_analysis.md

License:
MIT License