SPECTRA

// A minimal STAC Item — the atomic unit of the catalog
{
  "type": "Feature",
  "id": "8d09ed33ab1fb1c6",
  "geometry": { "type": "Point", "coordinates": [-77.361, 38.615] },
  "properties": {
    "datetime": "2026-03-29T15:03:14Z",
    "gsd": 0.03               // 3 cm/pixel ground resolution
  },
  "assets": {
    "visual": { "href": "./8d09ed33_ortho.tif", "type": "image/tiff; cloud-optimized=true" },
    "thumbnail": { "href": "./8d09ed33_thumb.jpg", "type": "image/jpeg" }
  }
}

import pystac, rasterio
from ultralytics import YOLO

model   = YOLO("yolo11n.pt")
catalog = pystac.read_file("https://drone-catalog.shadyknollcave.io/catalog.json")

for item in catalog.get_all_items():
    cog_url = item.assets["visual"].href          # from the STAC Item ↑
    with rasterio.open(cog_url) as ds:
        chip      = ds.read([1,2,3]).transpose(1,2,0)
        transform = ds.transform                      # pixel → world coords

    for box in model(chip)[0].boxes.xyxy.tolist():
        x0, y0, x1, y1 = box
        lon0, lat0 = rasterio.transform.xy(transform, y0, x0)  # pixels → lon/lat
        print(f"detection at ({lon0:.6f}, {lat0:.6f})")

# CV output: {"cars": 21, "trucks": 4}
# LLM reads that context and produces:
{
  "spectra:ai.scene_type":      "commercial_parking",
  "spectra:ai.activity_level":  "high",
  "spectra:ai.description":     "Dense commercial parking lot, high vehicle turnover",
  "spectra:ai.features":        ["vehicles", "parking_lot", "paved_surface"]
}
# ↑ written back into the STAC Item and indexed by stac-fastapi

# 1. Concatenate enriched text fields into embedding document
embed_doc = f"{item['properties']['spectra:ai.description']} {item['properties']['spectra:ai.search_text']}"

# 2. Embed → 768-dim vector  (Ollama primary, sentence-transformers fallback)
vector = embedder.embed(embed_doc)  # [0.021, -0.147, …] × 768, Cosine metric

# 3. Upsert into Qdrant with filterable payload (idempotent UUID5 IDs)
qdrant.upsert(
  collection_name="spectra-stac",
  points=[PointStruct(
    id=uuid5(NAMESPACE_URL, item["id"]),
    vector=vector,
    payload={
      "item_id":        item["id"],
      "scene_type":     item["properties"]["spectra:ai.scene_type"],
      "activity_level": item["properties"]["spectra:ai.activity_level"],
      "bbox":           item["bbox"],
    }
  )]
)

# Two legs run in parallel
semantic_hits   = qdrant_search(embed(query), filters=payload_filter)  # vector proximity
structural_hits = stac_api_search(cql2_filter, datetime_range, bbox)    # exact metadata

# Reciprocal Rank Fusion  (k=60, Cormack et al. 2009)
for item_id, sem_rank, str_rank in merged_ranks(semantic_hits, structural_hits):
    rrf_score = (0.6 / (60 + sem_rank + 1)   # 60 % semantic weight
               + 0.4 / (60 + str_rank + 1))  # 40 % structural weight

# Returns: GeoJSON FeatureCollection — each feature carries:
#   _rrf_score · _semantic_score · _semantic_rank · _structural_rank
# Graceful degradation: Qdrant unreachable → structural-only results

{
  "collections": ["drone-imagery"],
  "datetime": "2026-03-01T00:00:00Z/..",
  "filter-lang": "cql2-json",
  "filter": {
    "op": "and", "args": [
      { "op": "=",          "args": [{ "property": "spectra:ai.activity_level" }, "high"] },
      { "op": "a_contains", "args": [{ "property": "spectra:ai.features" }, ["parking_lot"]] }
    ]
  }
}
// → GeoJSON FeatureCollection with matching STAC Items

# Tools the LLM sees (not HTTP endpoints — just function signatures)
list_collections()
  → ["drone-imagery"]

get_collection_info(collection_id="drone-imagery")
  → { title, description, queryable_fields, item_count }

search_stac(
  collection="drone-imagery",
  scene_type="commercial_parking",      # from LLM enrichment ↑
  activity_level="high",
  bbox=[-77.4, 38.5, -77.3, 38.7],
  limit=10
)
  → [{ id, geometry, assets, properties }]  # normalized STAC Items

# User types: "high-activity parking lots, March 2026"
# Agent loop resolves it step by step:

# 1. model chooses tool → search_stac()
search_stac(filter={
  "op": "and", "args": [
    { "op": "=", "args": ["spectra:ai.activity_level", "high"] },
    { "op": "a_contains", "args": ["spectra:ai.features", ["parking_lot"]] }
  ]
}, datetime="2026-03-01T00:00:00Z/..")

# 2. STAC API returns items with geometry + enriched properties ↑
# 3. agent returns GeoJSON → frontend renders polygons on map
# 4. user clicks footprint → TiTiler serves COG preview tile