placeroot 0.3.0__tar.gz

placeroot-0.3.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.DS_Store
+
+# Local Claude Code session state (agent worktrees, etc.) — never shipped.
+.claude/

placeroot-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vibe Mapper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

placeroot-0.3.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: placeroot
+Version: 0.3.0
+Summary: Ground AI agents in open map data. MCP server for Overture Maps — compact answers, no API key.
+Project-URL: Homepage, https://placeroot.dev
+Project-URL: Repository, https://github.com/chuofringer/placeroot
+Project-URL: Issues, https://github.com/chuofringer/placeroot/issues
+Author-email: Vibe Mapper <chuo.fringer@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,duckdb,geospatial,mcp,openstreetmap,overture-maps
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=1.5.5
+Requires-Dist: mcp[cli]>=2.0.0
+Description-Content-Type: text/markdown
+
+# PlaceRoot
+
+**Ground AI agents in open map data.**
+
+PlaceRoot is an MCP server that answers spatial questions from [Overture Maps](https://overturemaps.org) — queried live with DuckDB, no API key, no signup, no vendor platform.
+
+- **Answers, not data dumps.** Every tool returns compact, ranked results that fit in an agent's context window (~2K tokens), never raw GeoJSON.
+- **Fresh, rich place data.** Operating status, confidence scores, and brands from Overture (contributed by Meta, Uber, TomTom, and others).
+- **Zero setup.** Queries run directly against Overture's public GeoParquet on S3 — no ETL, no database, no key.
+
+## Quick start
+
+Add to Claude Desktop / Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "placeroot": {
+      "command": "uvx",
+      "args": ["placeroot"]
+    }
+  }
+}
+```
+
+Or run it directly:
+
+```bash
+uv run placeroot          # stdio MCP server
+uv run placeroot --http   # streamable-HTTP endpoint at http://127.0.0.1:8321/mcp
+```
+
+`--http` serves plain HTTP with no TLS or auth — put a reverse proxy in front for anything beyond local use.
+
+## Tools
+
+| Tool | Answers |
+|---|---|
+| `find_places` | Named places near a point, nearest first, with category, confidence, and operating status |
+| `summarize_area` | What's in an area: total places and top categories |
+| `place_details` | One place in full: addresses, contacts, brand, sources, confidence |
+| `admin_lookup` | The admin hierarchy containing a point: neighborhood up to country |
+| `compare_areas` | 2–5 areas side by side: category mix, density, and what differs most |
+| `within_distance` | Is the nearest matching place within N meters of a point? |
+| `geocode` | Free-text place name → ranked candidates with coordinates and admin context |
+| `resolve_place` | Free-text place reference → ranked, typed GERS ids an agent can hold onto |
+| `reverse_geocode` | Point → nearest address plus its containing division chain |
+| `summarize_buildings` | Building stock in an area: count, footprint area, height and use mix |
+| `buildings_at` | Nearest building footprints to a point |
+| `isochrone` | The area reachable within N minutes on foot, bike, or car — on PlaceRoot's own routing graph |
+| `render_map` | Any result → a self-contained interactive HTML map |
+| `simplify_geometry` | Any GeoJSON geometry → simplified to a token budget |
+
+More on the way — see [ROADMAP.md](ROADMAP.md).
+
+## Why
+
+Agents are bad at maps. Existing map tools either require vendor API keys or return raw GeoJSON far too large for a context window. PlaceRoot's design rule: every answer fits in ~2K tokens, and anything bigger returns a summary plus a link.
+
+A few things that make it work:
+
+- **GERS ids everywhere.** Every place carries its stable Overture [GERS](https://docs.overturemaps.org/gers/) id, so an agent can hold onto a place across turns and look it up again with `place_details(id=...)` instead of re-searching.
+- **Keyless geocoding.** `geocode`/`reverse_geocode` are built entirely on Overture's divisions and addresses themes — deterministic matching, no third-party geocoding API. 100% hit@1 on a ~113-query real-world benchmark (`scripts/geocode_benchmark.py`).
+- **Local caching.** Hot data is cached on first use, so repeat queries answer in milliseconds and keep working offline. Set `PLACEROOT_CACHE=off` to always query upstream.
+- **Self-hostable end to end.** Optionally mirror the data to your own S3-compatible storage and point PlaceRoot at it — see [docs/MIRROR.md](docs/MIRROR.md).
+
+## Development
+
+```bash
+uv sync                    # installs pytest + ruff (dev dependency group)
+uv run pytest              # offline tests against committed fixtures
+uv run pytest -m live      # also run opt-in tests against real Overture S3
+uv run ruff check .
+```
+
+## License
+
+MIT

placeroot-0.3.0/PLAN.md

@@ -0,0 +1,180 @@
+# PlaceRoot — Product Plan
+
+**One-liner:** An open-source MCP server that grounds AI agents in the real world using
+Overture Maps / OSM open data — answering spatial questions in compact, token-efficient
+form, with no API key and no vendor platform.
+
+**Repo:** https://github.com/chuofringer/placeroot
+
+## Positioning
+
+| Against | They are | PlaceRoot is |
+|---|---|---|
+| Google Maps grounding (Gemini-native + Maps Grounding Lite hosted MCP, GA Oct–Dec 2025) | Keyed + billed ($14–25/1K prompts), no-caching/no-training terms, Google-data-only | Keyless, open data you may store, cache, and train on |
+| Mapbox / TomTom / Esri / CARTO / HERE / Precisely MCP servers | Funnels into paid platforms (API keys, metered) | Open data, keyless |
+| srivinod1/overture-mcp-server (the one near-clone) | Same architecture (DuckDB over Overture S3, keyless), but 4★, dormant since Mar 2026, pinned six releases stale; budgets tool *schemas*, not answers; punts geocoding/routing/display to other MCPs | Maintained, honest geometry, token-budgeted *responses*, current release |
+| New Overture adjacents (thatapicompany/overture-maps-mcp, Jul 2026; soapboxbuild/overture-mcp, Jun 2026) | Keyed wrappers over hosted APIs or buildings-only slices; 0★ each; thatapicompany claims "token-efficient summaries" qualitatively, no budgets, no GERS in responses beyond soapboxbuild's buildings lookups | Keyless, full theme coverage, measured budgets, GERS everywhere |
+| gis-mcp and GIS-function servers (176★, active) | Raw computation toolboxes (geometry ops, data out) | Answers, not data |
+| OSM MCP servers (largest 215★, abandoned >1yr; no *active* successor over 30★ — wiseman/osm-mcp has 86★ but is equally dead since Mar 2025) | Overpass/Nominatim wrappers: rate limits, usage policies, stale data | Overture GeoParquet direct: operating status, confidence, brands |
+| geowire (multi-provider gateway, launched 2026-07-18) | BYOK vendor-API aggregator; "keyless" floor is rate-limited Nominatim/OSRM (incl. a keyless OSRM isochrone); 0★ as of 2026-08-06 | Truly keyless at scale; Overture-native; own routing graph |
+| Camino AI (getcamino.ai) | Pure-play "location intelligence for agents" startup with a native MCP server — but API-keyed, metered, "17x cheaper than Google Places" as the pitch | Keyless and free; open data you may store and train on |
+| ORATOR (Overture's experimental knowledge-graph MCP, built by Wherobots) | Regional prototype (SF Bay Area) on proprietary Wherobots/Iceberg infra, explicitly a proof-of-concept | Keyless, self-hostable, global today |
+| GeoLibre / GeoAgent (opengeos) | An app for humans / a Strands-based agent that drives GIS software; no MCP layer, no Overture focus | Plumbing for agents (and a future GeoLibre bridge) |
+
+Market context (extensive study 2026-08-05; superseding the initial Aug 2026 scan):
+~40 location MCP servers across the registries; the official MCP registry returns **zero
+results for "overture"**. Nobody ships token-budgeted answers as the headline feature —
+the closest is Google Grounding Lite's "AI-generated place data summaries" (keyed,
+billed) and srivinod1's tool-schema "progressive disclosure" (dormant). The payload
+problem is now publicly named — Mapbox's "GeoAI in 2026" post (Dec 2025) calls large
+geospatial payloads MCP's biggest challenge; a Geoawesome essay (June 2026) shows a
+45K-token GeoJSON collapsing to a 25-token reference — but no one ships the fix as a
+product. Overture itself now markets our thesis: "50 members converge on open data to
+ground AI" (July 2026), with GERS pitched as the anti-hallucination anchor and headed
+toward OGC standardization. Foursquare's open places data is flowing *into* Overture
+(~6M POIs merged in 2025), while FSQ's own MCP server targets its paid API and is
+near-dormant. OpenAI and Anthropic have picked no maps partner — Claude's connector
+directory lists only TomTom; the "default maps tool" slot in both ecosystems is open.
+Category traction ceiling remains low (Mapbox official: 350★; only geo-MCP story with
+real HN traction: 105 points).
+
+Re-verification sweep 2026-08-06 (three-track: open-source registry sweep, commercial
+vendor survey, claim-by-claim check): **all ten claims of the 2026-08-05 study stand.**
+The registry search for "overture" is still empty; the near-clone is still dormant
+(last commit 2026-02-28); nobody ships numeric token budgets, GERS ids in responses,
+keyless global isochrones, or self-contained offline map artifacts. The token-payload
+pain point gained a second corporate validator: HERE's "Location Reasoning" (announced
+May 2026) is an entire enterprise product marketed on reducing token usage. New since
+the study, all adjacent rather than head-on: thatapicompany/overture-maps-mcp
+(2026-07-16, keyed wrapper over a hosted API, 0★ — first competitor to even gesture at
+token efficiency), capan/isochrone (registered to the official MCP registry
+**2026-08-06**, keyless own-graph isochrones — but Berlin-only, pedestrian-only, one
+tool), and sparkgeo/geo-mcp-servers (2026-08-02, 36★) — a curated tracker of 77
+geospatial MCP servers whose only Overture entry is the dormant near-clone. The
+sparkgeo tracker is both a listing target and the best ongoing competitive radar for
+this category. Discoverability hazard: "Overture" searches are polluted by an
+unrelated 629★ coding-agent tool of the same name (SixHq/Overture). The `placeroot`
+name remained unclaimed on PyPI, npm, and GitHub as of 2026-08-06 — re-verified, but
+verification is not a reservation; only #16's publishes are.
+
+## Design rules
+
+1. **Answers, not data.** Every tool response fits in ~2K tokens. Big results return a
+   summary + retrievable artifact, never raw GeoJSON dumps.
+2. **Open data, keyless by default.** Overture S3 GeoParquet via DuckDB (no ETL, no
+   database); OSM services that permit anonymous use.
+3. **No hard dependency on anyone else.** Nothing on the critical path may be gated on
+   another project's roadmap, another service's rate limit, or another team's willingness
+   to integrate. External systems may make PlaceRoot faster or fresher; none may make it
+   stop working. Consequences: geocoding is built on Overture rather than wrapping
+   Nominatim; the map viewer is a self-contained artifact rather than a bridge to someone
+   else's app; routing is our own graph rather than a hosted Valhalla; the upstream release
+   is discovered, pinned, cached, and mirrorable.
+4. **Permanent scope exclusion: hazard- and property-risk scoring.** No flood/fire/wind
+   risk scores, property risk ratings, or insurance-flavored analytics — ever.
+
+## Naming
+
+"placeroot" chosen 2026-08-05 after availability research: PyPI, npm, GitHub repo names,
+and .com/.io/.dev/.ai all unclaimed; no company, product, social account, or trademark
+found under the name. Runners-up rejected: geoplinth (SEO collision with Geoplin),
+groundfact (social channels exist), 15 others (registered domains or package collisions).
+
+## Phases
+
+### Phase 1 — MVP (in progress)
+
+- [x] DuckDB query layer over Overture S3 (release 2026-07-22.0), bbox pushdown
+- [x] `find_places` — nearest named places; taxonomy, confidence, operating_status
+      (verified live: downtown Austin, 8 results ≈ 390 tokens, 5.6s cold)
+- [x] `summarize_area` — category mix (1,944 places ≈ 320 tokens)
+- [x] MCP server (Python SDK 2.0), `uv run placeroot`
+- [x] Fix radius geometry and count correctness (#1, #2, #3)
+- [x] Overture release auto-discovery + graceful degradation (#4, #5)
+- [x] Offline test suite and CI (#6); measured token budget (#7)
+- [x] Local tile cache — warm ~21ms, cold under ~5s, works offline (#8, #31)
+- [x] `place_details`, `compare_areas`, `within_distance` (#9, #12, #13, #41)
+- [x] `geocode` / `reverse_geocode` on Overture data (hit@1 100% live, saturated set), `admin_lookup` (#10, #11, #43, #46, #47)
+- [x] `simplify_geometry` (the payload tool) (#14)
+- [x] Expose GERS ids in every tool response (#25)
+- [x] Register domains: placeroot.dev (canonical) + placeroot.com (redirect), done
+      2026-08-05; .io intentionally skipped (#27)
+- [ ] Publish PyPI + npm (#16 — P0 as of 2026-08-05: the architecture is replicable
+      and the registry search is empty)
+
+Full triage on the [project board](https://github.com/users/chuofringer/projects/2).
+
+### Phase 2 — Distribution (weeks 8–13)
+
+- [x] Self-contained map artifact — any result opens as a live HTML map we ship
+      ourselves (#15). A GeoLibre bridge is an additional output target and a community
+      relationship, not a dependency; engage opengeos early either way.
+- [x] placeroot.dev landing page built (#28) — deploy awaits DNS/Pages setup (yours)
+- [x] Listing entries drafted for all 8 registries (docs/launch/registry-submissions.md,
+      incl. the sparkgeo/geo-mcp-servers curated tracker found 2026-08-06);
+      submission itself is owner-side, gated on #16's publishes
+- [x] Show HN text + community outreach notes drafted (docs/launch/); posting is owner-side
+- [x] "Why agents are bad at maps" essay drafted (docs/launch/), Mapbox/Geoawesome cited
+- [x] Tokens-per-correct-answer benchmark shipped and run live (#26): 90% accuracy,
+      median 2,543x fewer tokens than raw payloads (benchmarks/results.md)
+- [x] Flagship demo: site-selection agent entirely on open data (#17 — live-verified, ~5.9K tokens for a 17-call analysis)
+
+**Traction bar (~week 14):** judged on signals we own (#19, defined with
+collection methods and the decision rule in [docs/METRICS.md](docs/METRICS.md)) — download trend over four
+weeks, distinct connecting clients, inbound issues/PRs from people we did not contact, and
+named real uses. Stars are reported, not a gate: they measure other people's attention, not
+whether this is worth building.
+
+### Phase 3 — Hosted tier (months 4–7, gated on Phase 2 bar)
+
+- Free: local server forever. Hosted $0/$29/$99: remote streamable-HTTP endpoint,
+  pre-warmed indexes, monthly Overture refresh, isochrones/routing on our own graph (#17).
+  The hosted tier sells latency and convenience — never access.
+- Infra <$100/mo (Cloudflare Workers + R2, or single box + DuckDB).
+- Expectation: $500–3K MRR year one; primary value is audience + substrate for what's next.
+
+### Phase 4 — Demand-driven expansions
+
+GERS id resolution service; live layers (transit, weather context — not hazard risk);
+buildings/transportation themes; team features; white-label for agent platforms.
+
+## Risks
+
+(Reassessed 2026-08-05 against the extensive competitive study.)
+
+1. **opengeos ships an MCP layer first** — *downgraded*. Verified: no MCP layer in
+   GeoLibre or GeoAgent; their agent effort targets GIS analysis via Strands, not place
+   grounding. Still engage their community; still structurally defused (#15). Watch
+   GeoAgent's roadmap — one Overture tool factory would change this.
+2. **Foundation labs bake maps in via one big partner** — *partially materialized, at
+   Google only*: Gemini has native Maps grounding and Maps Grounding Lite exports it to
+   any MCP client — but keyed, billed ($14–25/1K), rate-limited, no-caching/no-training
+   terms. OpenAI (Yelp/Zillow verticals via Apps SDK) and Anthropic (TomTom connector
+   only) picked no horizontal partner. Keyless open data remains the wedge; Google's
+   pricing gives us a concrete cost comparison.
+3. **Attention, not code, is the bottleneck** → Phase 2 checklist is scheduled work;
+   half of weekly hours in weeks 8–13 go to distribution.
+4. **Upstream Overture changes layout, schedule, or access** → release discovery with a
+   pinned fallback (#4), a schema probe that degrades per-tool rather than failing all
+   (#5), a local cache that answers offline (#8), and eventually our own mirror (#20).
+5. **The near-clone revives, or someone wraps existing pieces** — *escalating on a
+   weeks timescale, not months*. srivinod1's overture-mcp-server has our architecture
+   (dormant, 4★), and the DuckDB `overture` community extension (geocode, place
+   readers, category normalization) is one wrapper away from being an MCP server.
+   Two adjacents appeared within three weeks of the 2026-08-05 study and one more
+   the day after (thatapicompany 2026-07-16, capan/isochrone registered 2026-08-06);
+   none is head-on yet, but each occupies a fragment of our combination. Moat is
+   execution: maintenance, honest geometry, token-budgeted answers, GERS ids (#22),
+   current releases — and shipping #16 before the empty "overture" registry search
+   fills. Standing radar: watch sparkgeo/geo-mcp-servers for new entrants.
+6. **Foursquare ships keyless agent tooling on FSQ OS Places** — license permits it;
+   today their MCP server is API-keyed and near-dormant, and FSQ open data flows into
+   Overture, strengthening our substrate. Monitor.
+7. **Overture-official tooling subsumes third parties** — ORATOR (Wherobots) is the
+   foundation's experimental MCP prototype. Treat as opportunity first: engage the
+   Product Council discussion, adopt GERS, stay the keyless self-hostable option
+   ORATOR is not.
+
+## Cadence
+
+Solo, ~6–8 hrs/week alongside day job. Phase 1 ≈ 35–45 focused hours.

placeroot-0.3.0/README.md

@@ -0,0 +1,78 @@
+# PlaceRoot
+
+**Ground AI agents in open map data.**
+
+PlaceRoot is an MCP server that answers spatial questions from [Overture Maps](https://overturemaps.org) — queried live with DuckDB, no API key, no signup, no vendor platform.
+
+- **Answers, not data dumps.** Every tool returns compact, ranked results that fit in an agent's context window (~2K tokens), never raw GeoJSON.
+- **Fresh, rich place data.** Operating status, confidence scores, and brands from Overture (contributed by Meta, Uber, TomTom, and others).
+- **Zero setup.** Queries run directly against Overture's public GeoParquet on S3 — no ETL, no database, no key.
+
+## Quick start
+
+Add to Claude Desktop / Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "placeroot": {
+      "command": "uvx",
+      "args": ["placeroot"]
+    }
+  }
+}
+```
+
+Or run it directly:
+
+```bash
+uv run placeroot          # stdio MCP server
+uv run placeroot --http   # streamable-HTTP endpoint at http://127.0.0.1:8321/mcp
+```
+
+`--http` serves plain HTTP with no TLS or auth — put a reverse proxy in front for anything beyond local use.
+
+## Tools
+
+| Tool | Answers |
+|---|---|
+| `find_places` | Named places near a point, nearest first, with category, confidence, and operating status |
+| `summarize_area` | What's in an area: total places and top categories |
+| `place_details` | One place in full: addresses, contacts, brand, sources, confidence |
+| `admin_lookup` | The admin hierarchy containing a point: neighborhood up to country |
+| `compare_areas` | 2–5 areas side by side: category mix, density, and what differs most |
+| `within_distance` | Is the nearest matching place within N meters of a point? |
+| `geocode` | Free-text place name → ranked candidates with coordinates and admin context |
+| `resolve_place` | Free-text place reference → ranked, typed GERS ids an agent can hold onto |
+| `reverse_geocode` | Point → nearest address plus its containing division chain |
+| `summarize_buildings` | Building stock in an area: count, footprint area, height and use mix |
+| `buildings_at` | Nearest building footprints to a point |
+| `isochrone` | The area reachable within N minutes on foot, bike, or car — on PlaceRoot's own routing graph |
+| `render_map` | Any result → a self-contained interactive HTML map |
+| `simplify_geometry` | Any GeoJSON geometry → simplified to a token budget |
+
+More on the way — see [ROADMAP.md](ROADMAP.md).
+
+## Why
+
+Agents are bad at maps. Existing map tools either require vendor API keys or return raw GeoJSON far too large for a context window. PlaceRoot's design rule: every answer fits in ~2K tokens, and anything bigger returns a summary plus a link.
+
+A few things that make it work:
+
+- **GERS ids everywhere.** Every place carries its stable Overture [GERS](https://docs.overturemaps.org/gers/) id, so an agent can hold onto a place across turns and look it up again with `place_details(id=...)` instead of re-searching.
+- **Keyless geocoding.** `geocode`/`reverse_geocode` are built entirely on Overture's divisions and addresses themes — deterministic matching, no third-party geocoding API. 100% hit@1 on a ~113-query real-world benchmark (`scripts/geocode_benchmark.py`).
+- **Local caching.** Hot data is cached on first use, so repeat queries answer in milliseconds and keep working offline. Set `PLACEROOT_CACHE=off` to always query upstream.
+- **Self-hostable end to end.** Optionally mirror the data to your own S3-compatible storage and point PlaceRoot at it — see [docs/MIRROR.md](docs/MIRROR.md).
+
+## Development
+
+```bash
+uv sync                    # installs pytest + ruff (dev dependency group)
+uv run pytest              # offline tests against committed fixtures
+uv run pytest -m live      # also run opt-in tests against real Overture S3
+uv run ruff check .
+```
+
+## License
+
+MIT

placeroot-0.3.0/ROADMAP.md

@@ -0,0 +1,94 @@
+# PlaceRoot Roadmap
+
+Tracked on the [project board](https://github.com/users/chuofringer/projects/2).
+
+## Design rules
+
+1. **Answers, not data.** Every tool response fits in ~2K tokens. Large results
+   return a summary plus a retrievable artifact, never raw GeoJSON dumps.
+2. **Open data only, keyless by default.** Overture Maps GeoParquet and
+   OpenStreetMap services that permit anonymous use.
+3. **No hard dependency on anyone else.** Nothing on the critical path may be
+   gated on another project's roadmap, another service's rate limit, or another
+   team's willingness to integrate. External systems may make PlaceRoot faster
+   or fresher; none may make it stop working.
+4. **Out of scope, permanently: hazard- and property-risk scoring.** PlaceRoot
+   answers "what is where" questions. It will not ship flood/fire/wind risk
+   scores, property risk ratings, or insurance-flavored analytics.
+
+## v0.1
+
+- [x] `find_places` — nearest named places with taxonomy, confidence, operating status
+- [x] `summarize_area` — category mix for an area
+
+## v0.2 — correct, resilient, useful (shipped 2026-08-06)
+
+Correctness and independence first: the query layer has known geometry bugs, no
+tests, and a hardcoded upstream release.
+
+- [x] Fix radius geometry: circular distance in SQL, honest counts (#1, #2, #3)
+- [x] Overture release auto-discovery with pinned fallback (#4)
+- [x] Graceful degradation when upstream is slow, down, or renamed (#5)
+- [x] Offline test suite and CI on committed fixtures (#6)
+- [x] Measured token-budget enforcement with visible truncation (#7)
+- [x] Local row-group cache — warm queries under 500ms, works offline (#8)
+- [x] `place_details` — one place in full (#9)
+- [x] `geocode` / `reverse_geocode` built on Overture, not Nominatim (#10) —
+      live benchmark hit@1 100% over 113 queries (saturated set), warm under 0.3s (#43, #46, #47, #53)
+- [x] `admin_lookup` — point → admin hierarchy (#11)
+- [x] `compare_areas`, `within_distance` (#12, #13)
+- [x] `simplify_geometry` — the payload tool (#14)
+- [x] Expose GERS ids in every tool response — stable place references, no
+      competitor surfaces them (#25)
+
+## v0.3 — capabilities nobody else has keyless (core shipped 2026-08-06)
+
+- [x] Self-contained map artifact: any result renders as a live HTML map, no
+      CDN, no tile key, no external viewer (#15)
+- [x] Own routing stack, walking MVP: routable graph and isochrones from
+      Overture transportation, no hosted routing service on the critical path
+      (#18; drive/cycle, concave hulls, graph caching tracked in #36–#39)
+- [x] Buildings and transportation themes (#23; transportation via the routing
+      stack, buildings via summarize_buildings / buildings_at)
+- [ ] Hosted streamable-HTTP endpoint — sells latency, never access (#24;
+      transport code shipped — `placeroot --http` — hosting/TLS/DNS is the
+      owner-side remainder)
+
+## Later, demand-driven
+
+- [x] GERS id resolution — `resolve_place`: free-text place references →
+      GERS ids, divisions and places merged (#22, #25)
+- [ ] Own mirror of the places theme (#20; tooling + switchover shipped —
+      scripts/mirror_theme.py, PLACEROOT_UPSTREAM_BASE, docs/MIRROR.md —
+      bucket + the 10.5 GB transfer are the owner-side remainder)
+- [ ] Live layers: transit feeds, weather context
+
+## Competitive watch (verified 2026-08-06)
+
+A three-track market re-verification (details in [PLAN.md](PLAN.md)) confirmed the
+category position: no other project ships token-budgeted answers, GERS ids in every
+response, keyless Overture geocoding, keyless global own-graph isochrones, or
+self-contained offline map artifacts. The position is features, not a moat — two
+adjacent projects appeared within three weeks and one the day of the check. Standing
+watch items, none blocking:
+
+- **sparkgeo/geo-mcp-servers** — curated tracker of 77 geo MCP servers; our listing
+  target and the category radar. Check on each release.
+- **capan/isochrone** — keyless own-graph isochrones (Berlin-only, pedestrian-only);
+  the nearest conceptual neighbor to our routing stack.
+- **thatapicompany/overture-maps-mcp** — keyed hosted-API wrapper claiming
+  "token-efficient summaries"; first competitor gesturing at our headline.
+- **Camino AI** — commercial "location intelligence for agents" startup, keyed/metered.
+- **Google Maps Grounding Lite** — free while Experimental; a GA pricing decision
+  ($2.80–7.00/1K published as potential) changes the cost-comparison story.
+- **Overture first-party tooling** — ORATOR is still an SF-Bay prototype; any move
+  toward an official Overture MCP server changes risk 7 in PLAN.md.
+
+The empty "overture" search in the official MCP registry is the clock: #16 ships
+before someone else fills it.
+
+## Relationships, not dependencies
+
+A GeoLibre bridge and upstream contributions to Overture tooling are both
+worth doing and actively wanted. Neither blocks a release. If a partner ships
+first, PlaceRoot still works the same day.

placeroot-0.3.0/benchmarks/README.md

@@ -0,0 +1,116 @@
+# Token benchmark (issue #26)
+
+## Reality check first
+
+[GeoBenchX](https://github.com/Solirinai/GeoBenchX) and GeoAgentBench are
+*agent-with-LLM* benchmarks: they measure whether an LLM correctly chooses
+and chains geospatial tools across a conversation. Running either faithfully
+needs LLM API calls, which this repo has no credentials for and won't fake.
+
+What's here instead is something narrower, but real and runnable today:
+`token_benchmark.py` runs 30 spatial questions — inspired by GeoBenchX's own
+task categories (nearest-POI, area comparison, point-in-admin,
+within-distance, isochrone reachability) — directly against **live**
+Overture data, checks each answer programmatically, and measures **tokens
+per correct answer**: placeroot's compact tool response vs. the token cost
+of the equivalent *raw* payload (unprocessed rows / full geometry) an agent
+would have had to fetch and read itself without placeroot's tool doing the
+filtering, ranking, point-in-polygon, or graph-building.
+
+No LLM is called anywhere in this benchmark. It measures the *data* side of
+the "answers, not data dumps" design rule (README.md), not an agent's tool
+choice — that's what a real GeoBenchX/GeoAgentBench integration would add.
+The task format here (`Task(name, category, fn)`, where `fn()` calls the
+placeroot tool(s) and returns a checked `Outcome`) is deliberately generic
+enough that a future LLM-driven harness could reuse the same task
+definitions and checkers, swapping in an agent's own tool calls for the
+direct calls used here — that integration is tracked as future work under
+this issue's lineage, not solved here.
+
+## Running it
+
+```bash
+uv run python benchmarks/token_benchmark.py
+```
+
+Hits live Overture S3 (no fixture, no mock — same posture as
+`scripts/geocode_benchmark.py`). Each task is 1-3 tool calls; with a warm
+tile cache this finishes in a couple of minutes, longer cold (the isochrone
+tasks build a street graph from scratch and are the slowest part). Prints
+the report and overwrites `benchmarks/results.md` with the run's actual
+output — every number in `results.md` comes from that run, nothing hand-
+edited in.
+
+The harness itself (task definitions, the `Outcome`/`run_task` scoring
+machinery, the raw-payload comparator helpers) is also exercised offline in
+`tests/test_token_benchmark.py`, against the same committed fixtures the
+rest of the test suite uses — `uv run pytest` runs that as part of the
+normal suite, no network required.
+
+## Task categories and what "raw" means per category
+
+Every task calls placeroot's tool(s) through `placeroot.server`'s plain
+Python functions directly (the same functions the MCP server exposes, see
+`server.py`), not over an MCP client transport — this measures response
+payload size, which doesn't depend on the transport. Both the placeroot
+side and the raw side are measured with the same `len(json)//4` heuristic
+`placeroot.budget.estimate_tokens` uses, so every ratio below is directly
+comparable to the server's own token-budget accounting.
+
+- **point_in_admin** (`admin_lookup`): does the containing-division chain
+  include the point's real county and state? Raw side: every division
+  polygon that actually contains the point, with full unsimplified GeoJSON
+  geometry (`ST_AsGeoJSON`) — the full division polygon, not the tool's
+  `{name, type, id}` chain entry.
+- **within_distance**: is a place matching a category within N meters,
+  true/false. Raw side: every place row (every column, not the curated
+  id/name/category/distance the tool returns) inside the same search
+  window (`max_distance_m * 2`, matching the tool's own search radius).
+- **nearest_poi** (`find_places`): does a coffee_shop search near an iconic
+  downtown core turn up a Starbucks in the top 3 (top-3, not top-1,
+  specifically to tolerate ordinary data drift between Overture releases)?
+  Raw side: every place row in the same radius/category predicate.
+- **area_comparison** (`compare_areas`): does a permanently dense downtown
+  core show more total places than a permanently rural/wilderness point at
+  the same radius — a coarse, durable fact, not a fragile exact-count
+  check. Raw side: every place row in both areas' radii, combined.
+- **isochrone**: sanity checks (a well-connected urban point reaches a
+  nonzero area) plus two durable physical invariants — a longer time budget
+  reaches an equal-or-larger area than a shorter one, and a faster mode
+  (drive/cycle) reaches an equal-or-larger area than walking in the same
+  time, at the same point. Raw side: every transportation segment row
+  (with WKT geometry) in the same auto-derived graph-extraction radius the
+  tool itself used — i.e. the raw street-network edges an agent would have
+  had to fetch and read to answer the question itself, not the tool's
+  compact polygon + stats.
+
+## Honesty rules
+
+- A task whose checker fails is counted in the aggregate, not dropped —
+  `results.md`'s table includes every task that ran, correct or not, and a
+  "Failure detail" section spells out exactly what each miss got instead of
+  what it expected.
+- The raw-payload methodology is documented per category above rather than
+  left implicit; where it undercounts the true raw payload (isochrone's raw
+  segments use WKT text in place of the raw binary WKB geometry column, so
+  the row stays JSON-serializable without a custom encoder), that's called
+  out in the code, not smoothed over.
+- No number in this file is asserted without `benchmarks/results.md`
+  backing it — `results.md` is regenerated by, and only by, actually running
+  the script above against live data.
+
+## A finding from running this
+
+The first live run of this benchmark hit a real, reproducible-at-the-time
+tile-cache incompleteness: `find_places` near Times Square returned zero
+results (with `PLACEROOT_CACHE` at its default, on) even though the same
+query with `PLACEROOT_CACHE=off` found a restaurant 10m away. Clearing
+`~/.cache/placeroot` and rerunning made it disappear — a fresh cache
+answered the very first query correctly, and stayed correct on repeat
+queries. That points to a one-off race in cache.py's background tile
+materialization (see its module docstring: a cache miss should always fall
+back to a direct upstream scan for *that* query, so this shouldn't be
+possible even before the background fetch resolves) rather than a
+systematic data gap, but it wasn't chased further here — flagged as a
+follow-up worth its own issue, not fixed in this one. The committed
+`results.md` reflects the rerun against a cleared cache.

placeroot-0.3.0/benchmarks/results.md

@@ -0,0 +1,51 @@
+# Token benchmark results (issue #26)
+
+- Run date: 2026-08-06
+- Overture release: 2026-07-22.0
+- Tasks: 30
+- Accuracy: 27/30 (90.0%)
+- Median tokens ratio (raw / placeroot), over 30 scored tasks: 2543.0x
+- Mean tokens ratio: 11246.6x
+
+Every task that ran is in the table below, including failures — nothing is dropped from the aggregate.
+
+## Per-task results
+
+| task | category | correct | placeroot tokens | raw tokens | ratio |
+|---|---|---|---:|---:|---:|
+| austin_texas_capitol | point_in_admin | yes | 90 | 2349639 | 26107.1x |
+| brooklyn_borough_hall | point_in_admin | yes | 113 | 1819534 | 16102.1x |
+| la_city_hall | point_in_admin | yes | 94 | 1880981 | 20010.4x |
+| chicago_willis_tower | point_in_admin | yes | 135 | 1806458 | 13381.2x |
+| seattle_space_needle | point_in_admin | yes | 91 | 1807274 | 19860.2x |
+| miami_downtown | point_in_admin | yes | 92 | 2000858 | 21748.5x |
+| denver_state_capitol | point_in_admin | yes | 93 | 1752816 | 18847.5x |
+| times_square_restaurant | within_distance | yes | 71 | 766290 | 10792.8x |
+| chicago_loop_coffee | within_distance | yes | 75 | 42024 | 560.3x |
+| hollywood_highland_restaurant | within_distance | yes | 74 | 167766 | 2267.1x |
+| eiffel_tower_restaurant | within_distance | yes | 69 | 153342 | 2222.3x |
+| yellowstone_lake_grocery | within_distance | yes | 13 | 0 | 0.0x |
+| pacific_ocean_any_place | within_distance | yes | 13 | 0 | 0.0x |
+| sahara_desert_any_place | within_distance | yes | 13 | 0 | 0.0x |
+| grand_canyon_remote_restaurant | within_distance | yes | 13 | 0 | 0.0x |
+| times_square_coffee | nearest_poi | **NO** | 181 | 40841 | 225.6x |
+| chicago_loop_coffee | nearest_poi | yes | 185 | 20348 | 110.0x |
+| seattle_downtown_coffee | nearest_poi | yes | 183 | 35743 | 195.3x |
+| sf_union_square_coffee | nearest_poi | **NO** | 181 | 23338 | 128.9x |
+| la_downtown_coffee | nearest_poi | **NO** | 190 | 20250 | 106.6x |
+| boston_downtown_coffee | nearest_poi | yes | 183 | 28713 | 156.9x |
+| manhattan_vs_rural_upstate_ny | area_comparison | yes | 526 | 17410408 | 33099.6x |
+| chicago_loop_vs_rural_il | area_comparison | yes | 526 | 5454757 | 10370.3x |
+| sf_union_sq_vs_sierra_backcountry | area_comparison | yes | 514 | 5916508 | 11510.7x |
+| austin_6th_st_vs_hill_country | area_comparison | yes | 491 | 2550036 | 5193.6x |
+| times_square_walk_15min | isochrone | yes | 2044 | 2836060 | 1387.5x |
+| times_square_drive_ge_walk_15min | isochrone | yes | 3325 | 239697321 | 72089.4x |
+| chicago_loop_walk_10min_vs_20min | isochrone | yes | 3371 | 4687640 | 1390.6x |
+| sf_union_sq_cycle_ge_walk_15min | isochrone | yes | 3770 | 10627117 | 2818.9x |
+| austin_downtown_drive_15min | isochrone | yes | 2039 | 95251683 | 46714.9x |
+
+## Failure detail
+
+- **times_square_coffee** (nearest_poi): expected one of ['Starbucks'] in top-3, got ['Joe Coffee Company', "Dunkin'", 'Central Perk']
+- **sf_union_square_coffee** (nearest_poi): expected one of ['Starbucks'] in top-3, got ['Bancarella', 'Lux Cafe Club', 'Hyatt Coffee Bar']
+- **la_downtown_coffee** (nearest_poi): expected one of ['Starbucks'] in top-3, got ['Barista Society Coffee Boutique', 'Aquarela Coffee', 'The Coffee Bean & Tea Leaf']