Add option to return STAC search params only

Will be useful for adding natural language search to external
clients like STAC browser that can query a STAC api on their
own

Author: sunu

stac_search/agents/items_search.py

@@ -17,6 +17,7 @@ class Context:
     query: str
     location: str | None = None
     top_k: int = 5
+    return_search_params_only: bool = False
 
 
 @dataclass
@@ -216,7 +217,8 @@ def get_polygon_from_geodini(location: str):
 
 @dataclass
 class ItemSearchResult:
-    items: List[Dict[str, Any]]
+    items: List[Dict[str, Any]] | None = None
+    search_params: Dict[str, Any] | None = None
     aoi: Dict[str, Any] | None = None
     explanation: str = ""
 
@@ -271,9 +273,12 @@ async def item_search(ctx: Context) -> ItemSearchResult:
 
     # print(f"Searching with params: {params}")
 
-    items = list(client.search(**params).items_as_dicts())
+    if ctx.return_search_params_only:
+        print("Returning STAC query parameters only")
+        return ItemSearchResult(search_params=params, aoi=polygon, explanation=explanation)
 
-    return ItemSearchResult(items=items, aoi=polygon, explanation=explanation)
+    items = list(client.search(**params).items_as_dicts())
+    return ItemSearchResult(items=items, aoi=polygon, explanation=explanation, search_params=params)
 
 
 async def main():

stac_search/api.py

@@ -20,21 +20,27 @@
 # Define request model
 class QueryRequest(BaseModel):
     query: str
-    limit: int = 5
+
+
+class STACItemsRequest(BaseModel):
+    query: str
+    return_search_params_only: bool = False
 
 
 # Define search endpoint
 @app.post("/search")
 async def search(request: QueryRequest):
     """Search for STAC collections using natural language"""
-    results = collection_search(request.query, top_k=request.limit)
+    results = collection_search(request.query)
     return {"results": results}
 
 
 @app.post("/items/search")
-async def search_items(request: QueryRequest):
+async def search_items(request: STACItemsRequest):
     """Search for STAC items using natural language"""
-    ctx = ItemSearchContext(query=request.query, top_k=request.limit)
+    ctx = ItemSearchContext(
+        query=request.query, return_search_params_only=request.return_search_params_only
+    )
     results = await item_search(ctx)
     return {"results": results}