developmentseed / developmentseed/stac-collection-discovery
Implement LLM-powered query expansion
- Dominant language
- TypeScript
- Stars
- 14
- Forks
- 2
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 3
Description
Implement query expansion using an LLM to generate related search terms, bridging the vocabulary gap between user queries and collection metadata.
### Background
Users often describe phenomena ("coral bleaching") while data is organized by measurements ("sea-surface-temperature"). Query expansion uses an LLM to generate synonyms and related terms, improving recall without requiring changes to upstream STAC APIs.
### Tasks
- [ ] **Task 4.1: Create Query Expansion Prompts**
- File: `src/stac_fastapi/collection_discovery/llm/prompts.py`
- Define `QUERY_EXPANSION_SYSTEM_PROMPT`:
- Context: "You are helping users find geospatial data collections in STAC catalogs"
- Task: "Generate related search terms for the user's query"
- Domain knowledge: Earth observation, remote sensing, satellite imagery terminology
- Define few-shot examples:
- "coral bleaching" → ["coral", "reef", "sea surface temperature", "SST", "ocean heat", "thermal stress"]
- "deforestation" → ["forest", "land cover", "vegetation", "NDVI", "tree cover loss", "biomass"]
- "air pollution" → ["air quality", "NO2", "PM2.5", "aerosol", "ozone", "particulate matter"]
- Output format: JSON array of strings
- [ ] **Task 4.2: Implement Query Expander Service**
- File: `src/stac_fastapi/collection_discovery/llm/expander.py` (new)
- Create `QueryExpander` class:
```python
async def expand(self, query: str) -> QueryExpansionResult:
"""
Returns:
QueryExpansionResult with:
- original_query: str
- expanded_terms: list[str]
- expansion_time_ms: float
"""
```
- Parse LLM JSON response with validation
- Fallback: return `[original_query]` if LLM fails
- [ ] **Task 4.3: Build Expanded Free-Text Query**
- File: `src/stac_fastapi/collection_discovery/llm/expander.py`
- Create function to convert expanded terms to[ STAC free-text](https://github.com/stac-api-extensions/freetext-search) query:
```python
def build_expanded_q(terms: list[str]) -> list[str]:
"""Convert expanded terms to q parameter format."""
# STAC free-text uses OR semantics by default
return terms
```
### Acceptance Criteria
- [ ] `QueryExpander.expand("coral bleaching")` returns SST-related terms
- [ ] Expansion gracefully falls back to original query on LLM failure
- [ ] Prompts produce consistent, domain-appropriate expansions
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with src/stac_fastapi/collection_discovery/llm/prompts.py and then implement the specified service and query builder in src/stac_fastapi/collection_discovery/llm/expander.py. Verify that JSON responses are validated, failures return the original query, and the documented coral bleaching expansion produces STAC free-text terms.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend-api-design, search
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100