developmentseed / developmentseed/stac-collection-discovery

Implement LLM-powered query expansion

Open
#239 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.