diff --git a/skills/geoda-tools/SKILL.md b/skills/geoda-tools/SKILL.md new file mode 100644 index 00000000..298978a3 --- /dev/null +++ b/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. diff --git a/skills/osm-tools/SKILL.md b/skills/osm-tools/SKILL.md new file mode 100644 index 00000000..3dcf23e8 --- /dev/null +++ b/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. + diff --git a/skills/places-tools/SKILL.md b/skills/places-tools/SKILL.md new file mode 100644 index 00000000..5b9a9687 --- /dev/null +++ b/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()`. +