agentic-site-selection

agentic-site-selection asks, in plain English, "Where in Houston should an independent coffee shop open next?" A manager agent plans the work and hands it to small subagents, which call a local Model Context Protocol server. The server does the spatial math with ArcGIS Pro and numpy over a prepared hex table. A summary agent then writes a ranked answer with its reasons, says whether the two methods agree, and adds a confidence and caveats block. The two methods are an expert-weighted overlay and Esri's USA Geodemographic Embeddings with Find Similar Features Using Embeddings. Both are scored against coffee shops that were hidden from them.

flowchart TB
    Q["User question<br/>(plain English)"] --> M["Manager agent<br/>Sonnet 5.5: plans, delegates,<br/>never sees raw data"]
    M --> G["Geocode agent<br/>Haiku 5.5"]
    M --> D["Data agent<br/>Haiku 5.5"]
    M --> A["Analysis agent<br/>Sonnet 5.5"]
    M --> V["Validation agent<br/>Haiku 5.5"]
    G & D & A & V <-- "MCP over stdio" --> S["Local MCP server<br/>geocode, hex_profile, overlay_suitability,<br/>find_similar, hot_spots, validate<br/>(sources, checks, caveats in every result)"]
    S <--> T["Prepared tables<br/>880 H3 r7 hexes: ACS, coffee shops,<br/>scores, validation"]
    S <-. "subprocess (optional)" .-> P["ArcGIS Pro 3.7 / ArcPy<br/>FindSimilarFeaturesUsingEmbeddings,<br/>HotSpots"]
    S <-- "HTTPS" --> C["U.S. Census Geocoder"]
    M --> W["Summary agent<br/>Sonnet 5.5: ranked sites, reasons,<br/>method agreement, confidence + caveats"]

Results (Harris County, Texas; built 22 Oct 2026)

Study area. Harris County is covered by 880 H3 resolution-7 hexes (about 5.2 km² each). Overture Places lists 1,217 coffee shops in them after cleaning. 509 of these are chains and 708 are independents, and the independents sit in 253 hexes. Population is the ACS 2020-2024 count, 4,838,303, allocated from 1,115 tracts to hexes by 2020 block populations. Esri's own hex population field gives 4,973,340, and the two agree with Pearson r = 0.971 per hex.

Validation: spatially blocked hold-out. The hexes were split into 5 blocks (k-means on hex centroids). For each block, all of its shops were hidden. The embedding query was rebuilt from the independent-shop hexes in the other four blocks, and the overlay's competition term was recomputed without the hidden shops. Each method was then scored on how highly it ranks the block's real independent-shop hexes. Values are means across blocks with the min-max range in brackets (results/validation.json, per block in results/validation_blocks.csv):

Method	AUC (shop vs non-shop hexes)	P@k (k = held-out shop hexes)	P@10
Overlay, expert weights	0.708 (0.550-0.810)	0.427 (0.273-0.703)	0.40 (0.10-1.00)
Overlay, demand only (competition weight 0)	0.707 (0.549-0.812)	0.429 (0.273-0.683)	0.40 (0.10-1.00)
Embeddings, Esri Find Similar Features Using Embeddings	0.743 (0.528-0.886)	0.484 (0.318-0.629)	0.58 (0.40-0.80)
Embeddings, numpy cosine (open fallback)	0.743 (0.528-0.886)	0.484 (0.318-0.629)	0.58 (0.40-0.80)
Random ordering (2,000 per block)	0.500	0.285	0.286

• Both methods beat random on average, and the embeddings did better in 4 of 5 blocks. In the north, northeast, west and southeast blocks, the embedding AUC was 0.70-0.89 against 0.55-0.81 for the overlay.
• The urban core reverses that. The central block (Downtown to the Galleria) holds 444 of the 708 independents. There the embeddings were close to random (AUC 0.528, P@10 0.40) and the overlay did well (AUC 0.744, P@10 1.00). With that block hidden, the query is built only from suburban shop hexes, so it describes suburbs. The method finds "more of what you showed it", and it is only as good as the query.
• Inside a held-out block the competition term barely matters. Hiding the block's shops makes the term nearly constant there, so the two overlay rows are almost identical. The test therefore measures the demand criteria, not the competition penalty.

Esri tool vs the open re-implementation. arcpy.geoai.FindSimilarFeaturesUsingEmbeddings reports that it builds one query embedding from the query features. Cosine similarity to the mean of the query vectors, written in numpy, reproduces it exactly: Spearman rank correlation 1.000000, maximum absolute score difference 1.6 × 10⁻⁷, identical top 10% over all 880 hexes (results/summary.json). Two other variants match less well: the mean of unit vectors (ρ = 0.987) and the best single-query match (ρ = 0.663). The numpy Gi* also matches arcpy.stats.HotSpots (contiguity edges and corners) exactly (ρ = 1.0, max |Δz| = 0.0).

The two methods disagree. Their top-10% sets share 4 of 88 hexes (Jaccard 0.023). Over the hexes the overlay does not mask, their scores are uncorrelated (Spearman 0.035). The overlay favours high-income, younger hexes with few shops nearby, such as the area near Humble and Atascocita in the northeast (best hex 9.03/10). The embeddings favour middle-income suburbs that already look like shop areas, such as Katy, Cypress and Clear Lake (best similarity 0.936). One method asks "where are the gaps?" and the other asks "where looks like a coffee neighbourhood?". Neither answers "where will a shop make money?".

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗