Convert geoda/osm/places tools to Codex skills

skills/geoda-tools/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: geoda-tools
+description: Use @openassistant/geoda (GeoDa) spatial analysis tools in TypeScript/JavaScript apps (classification, spatial join, weights, Moran/LISA, regression, and common spatial operations).
+---
+
+# GeoDa tools (@openassistant/geoda)
+
+Use this skill when you need spatial statistics or vector-geometry operations and you’re building on the OpenAssistant tool format (`OpenAssistantTool`).
+
+## Quick start
+
+1) Import the tool(s) you need from `@openassistant/geoda`.
+2) Provide the required `context` functions (many tools intentionally throw until you wire these up).
+3) Wrap with `convertToVercelAiTool(...)` (or your adapter) and pass into your LLM call.
+
+```ts
+import { dataClassify, spatialWeights, globalMoran } from '@openassistant/geoda';
+import { convertToVercelAiTool } from '@openassistant/utils';
+
+const tools = {
+  dataClassify: convertToVercelAiTool({
+    ...dataClassify,
+    context: { getValues: async (datasetName, variableName) => /* number[] */ [] },
+  }),
+  spatialWeights: convertToVercelAiTool({
+    ...spatialWeights,
+    context: { getGeometries: async (datasetName) => /* GeoJSON.Feature[] */ [] },
+  }),
+  globalMoran: convertToVercelAiTool({
+    ...globalMoran,
+    context: { getValues: async () => [], getGeometries: async () => [] },
+  }),
+};
+```
+
+## Tool map (what to use when)
+
+- `dataClassify`: Compute class breaks for a numeric variable (needs `context.getValues(datasetName, variableName)`).
+- `spatialJoin`: Aggregate/join attributes between two geometry datasets (needs `context.getGeometries(...)`; optionally `getValues(...)`; optionally `saveAsDataset(...)`).
+- `spatialWeights`: Build weights matrices (queen/rook/knn/threshold) for later spatial stats (needs `context.getGeometries(datasetName)`).
+- `globalMoran`: Global Moran’s I spatial autocorrelation (typically use with `spatialWeights`; needs `context.getValues(...)` and (depending on inputs) geometries).
+- `lisa`: Local indicators (local Moran/Geary/Getis-Ord/quantile LISA) for clusters/outliers (needs `context.getValues(...)`; weights usually come from `spatialWeights`).
+- `spatialRegression`: Spatial regression (OLS + spatial lag/error) (needs `context.getValues(...)`; spatial models also need a `weightsId` from `spatialWeights`).
+- `standardizeVariable`: Standardize/normalize a variable (needs `context.getValues(...)`; can optionally save outputs as a dataset depending on `saveData`).
+- `rate`: Compute rates/standardizations (needs dataset values; see tool context).
+- Spatial ops: `area`, `buffer`, `centroid`, `dissolve`, `grid`, `length`, `perimeter`, `thiessenPolygons`, `mst`, `cartogram` (these operate on geometries; most require `context.getGeometries(datasetName)` and some require `saveAsDataset(...)`).
+
+## Common pitfalls
+
+- Many tools ship with a default `context` that throws; always override the needed functions before calling.
+- Be consistent about geometry format: most tools expect GeoJSON features/geometries (and some use GeoDa binary geometry under the hood).
+- For LISA / Moran / regression, create weights first (or pass a previously-created `weightsID`) so results are reproducible.

skills/osm-tools/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: osm-tools
+description: Use @openassistant/osm tools (geocoding, reverse geocoding, routing, isochrones, roads, and US boundary helpers) in TypeScript/JavaScript apps; includes required API keys and context wiring.
+---
+
+# OSM tools (@openassistant/osm)
+
+Use this skill when you need to turn addresses into coordinates, compute routes/isochrones, fetch roads, or download US administrative boundary GeoJSON.
+
+## Quick start
+
+```ts
+import { geocoding, routing } from '@openassistant/osm';
+import { convertToVercelAiTool } from '@openassistant/utils';
+
+const tools = {
+  geocoding: convertToVercelAiTool(geocoding), // no API key (Nominatim)
+  routing: convertToVercelAiTool({
+    ...routing,
+    context: { getMapboxToken: () => process.env.MAPBOX_TOKEN! },
+  }),
+};
+```
+
+## What needs API keys / context
+
+- `geocoding`, `reverseGeocoding`: OpenStreetMap Nominatim (no key; be mindful of rate limits).
+- `routing`, `isochrone`: Mapbox APIs (requires `context.getMapboxToken()`; typically from `process.env.MAPBOX_TOKEN`).
+- `roads`: Overpass API; optionally accepts `datasetName` and uses `context.getGeometries(datasetName)` to derive bounds.
+- US boundary helpers: `getUsStateGeojson`, `getUsCountyGeojson`, `getUsCityGeojson`, `getUsZipcodeGeojson`, `queryZipcode` (fetch/cached from public sources; no key).
+
+## Tool map
+
+- `geocoding`: Address → point GeoJSON (dataset cached with generated name).
+- `reverseGeocoding`: Coordinate → best-matching address/place name.
+- `routing`: Route between two coordinates (returns LineString + distance/duration; Mapbox).
+- `isochrone`: Travel-time polygon(s) from an origin point (Mapbox).
+- `roads`: Fetch road network lines within bounds or around an existing dataset (Overpass).
+- US helpers: Download GeoJSON for states/counties/cities/zipcodes and basic zipcode queries.
+
+## Notes
+
+- These tools perform network fetches; use timeouts/rate limits appropriately in your runtime.
+- For routing/isochrone, if you only have addresses, call `geocoding` first to obtain coordinates.
+

skills/places-tools/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: places-tools
+description: Use @openassistant/places tools (Foursquare place search + geotagging and SearchAPI-powered web search) in TypeScript/JavaScript apps; includes required API keys and context wiring.
+---
+
+# Places tools (@openassistant/places)
+
+Use this skill when you need POI/place search, to geotag a coordinate, or to run a structured web search and store results as a dataset.
+
+## Quick start
+
+```ts
+import { placeSearch, geoTagging, webSearch } from '@openassistant/places';
+import { convertToVercelAiTool } from '@openassistant/utils';
+
+const tools = {
+  placeSearch: convertToVercelAiTool({
+    ...placeSearch,
+    context: { getFsqToken: () => process.env.FSQ_TOKEN! },
+  }),
+  geoTagging: convertToVercelAiTool({
+    ...geoTagging,
+    context: { getFsqToken: () => process.env.FSQ_TOKEN! },
+  }),
+  webSearch: convertToVercelAiTool({
+    ...webSearch,
+    context: { getSearchAPIKey: () => process.env.SEARCH_API_KEY! },
+  }),
+};
+```
+
+## Tool map
+
+- `placeSearch` (Foursquare): Search places by query + `near` or lat/lon (+ optional filters like categories, open_now, price). Returns GeoJSON and a generated dataset name.
+- `geoTagging` (Foursquare): Given a coordinate, return nearby place context / enrichment.
+- `webSearch` (SearchAPI): Google-style web search returning structured results (requires `context.getSearchAPIKey()`).
+
+## Notes
+
+- Use `placeSearch` when you want mappable POIs (GeoJSON); use `webSearch` when you want links/snippets and “what is X?” style retrieval.
+- Both `placeSearch` and `geoTagging` require an API token via `context.getFsqToken()`.
+