@tomtom-org/maps-sdk-plugin-agent-toolkit 0.2.11 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # TomTom Maps SDK - Agent Toolkit Plugin
 
-A headless conversational agent that gives Large Language Models tool-based control over a [TomTom Map](https://developer.tomtom.com/) and TomTom location services, powered by [Vercel AI SDK v6](https://ai-sdk.dev/).
+A headless conversational agent that gives Large Language Models tool-based control over a [TomTom Map](https://docs.tomtom.com/maps-sdk-js/guides/map/tomtom-map) and TomTom location services, powered by [Vercel AI SDK v6](https://ai-sdk.dev/).
 
 No UI is included — bring your own chat interface. No LLM provider is bundled — supply any AI SDK-compatible model.
 
@@ -69,7 +69,7 @@ function ChatPanel() {
 }
 ```
 
-See [`examples/map-chat-agent`](../../examples/map-chat-agent) for a full working example.
+See [`examples/map-chat-agent-react`](../../examples/map-chat-agent-react) for a full working example.
 
 ## Tools reference
 
@@ -115,10 +115,13 @@ The plugin ships a `DEFAULT_TOOLS` registry covering search, routing, traffic, r
 
 | Tool | Description |
 |---|---|
-| `addByodLayer` | Ingest a customer-authored GeoJSON layer from a URL or inline `FeatureCollection` |
+| `addByodSource` | Ingest a customer-authored GeoJSON source (URL or inline `FeatureCollection`) and profile its shape; the entry has no layers and renders nothing until the agent sets them via `setByodLayers` |
 | `recallByod` | List BYOD entries, or retrieve a single entry's full `FeatureCollection` by id |
+| `setByodLayers` | Restyle a BYOD entry — replace its MapLibre layers (type + data-driven paint) using the entry's data `profile` |
 | `updateByodDisplay` | Show, hide, or clear BYOD layers on the map |
 
+> See the [Bring your own data](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/byod) guide for ingestion patterns, visibility lifecycle, and how BYOD entries feed into `analyseData` / `processData`.
+
 ### Unified data tools — scope-aware code generation
 
 | Tool | Description |
@@ -127,7 +130,7 @@ The plugin ships a `DEFAULT_TOOLS` registry covering search, routing, traffic, r
 | `processData` | Transform entries into new `places`, `placeConnections`, `geometries`, `byod`, or a `fitOnMap` camera move via dynamic JS |
 | `executeMaplibreCode` | Execute arbitrary MapLibre JS against the live `Map` instance — escape hatch for custom layers, animations, raster overlays |
 
-> See the [Code generation](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/tools#code-generation) section of the guide for the threat model — these tools have no sandbox.
+> See [Code generation](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/code-generation) for the injected identifiers, output contracts, and threat model (these tools have no sandbox), and [Scope-aware data tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/scope-aware-data-tools) for how the per-turn classifier scope keeps the prompt small.
 
 ### Map display
 
@@ -184,6 +187,8 @@ The plugin ships a `DEFAULT_TOOLS` registry covering search, routing, traffic, r
 
 ## Customization
 
+> See [Customizing tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/customizing-tools) for the full walkthrough — registry resolution, removing or replacing defaults, adding scopable custom tools, and starting from a blank slate.
+
 ### `createMapAgent` options
 
 ```typescript
@@ -329,6 +334,8 @@ type ToolEntry<S extends ToolState = ToolState> = {
 
 ## State management
 
+> See the [State](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/state) guide for a per-slice deep dive, `entryMode` semantics (`multiple` vs `single`), inspecting state from your application, and adding custom slices.
+
 `ToolState` is organized by feature area. Each slice manages lazy-initialized map modules and an append-only history of results produced during the session. Built-in slices:
 
 - `PlacesState` — place / geometry entry history
@@ -360,7 +367,7 @@ agent.state.places;  // PlacesState — append-only history of place entries
 
 ## Intent classifier
 
-The intent classifier is an optional per-turn optimization that selects which tools the LLM sees, reducing noise and improving accuracy.
+The intent classifier is an optional per-turn optimization that selects which tools the LLM sees, reducing noise and improving accuracy. See the [How it works](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/how-it-works) guide for the full two-phase pipeline (classification → tool loop), prompt assembly, and observability hooks.
 
 ```typescript
 import { createMapAgent, createDefaultClassifier } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
@@ -563,7 +570,15 @@ export type * from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
 
 ## References
 
+- [Agent Toolkit guides](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/overview) — full documentation set:
+    - [How it works](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/how-it-works) — two-phase pipeline (classifier + tool loop), prompt assembly, observability
+    - [Tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/tools) — per-tool reference
+    - [State](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/state) — per-slice reference, entry modes, custom slices
+    - [Customizing tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/customizing-tools) — add, replace, remove, or start from a blank slate
+    - [Code generation](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/code-generation) — `analyseData` / `processData` / `executeMaplibreCode` (threat model included)
+    - [Scope-aware data tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/scope-aware-data-tools) — per-turn scope mechanism
+    - [Bring your own data](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/byod) — ingest customer GeoJSON layers
 - [AI SDK v6 documentation](https://ai-sdk.dev/)
 - [TomTom Maps SDK documentation](https://developer.tomtom.com/)
 - [Engineering guidelines](./ENGINEERING-GUIDELINES.md) — tool design standards, state management, system prompt structure
-- [Example application](../../examples/map-chat-agent) — full chat interface implementation
+- [Example application](../../examples/map-chat-agent-react) — full chat interface implementation

package/dist/index.d.ts

@@ -46,10 +46,9 @@ import { z } from 'zod';
  */
 declare type AddBYODEntryOptions = {
     /**
-     * Explicit MapLibre layer specs. When omitted, the slice inspects the
-     * FeatureCollection and picks defaults by geometry type
-     * (Point → circle, Line → line, Polygon → fill). Mixed-kind entries get
-     * one layer per kind present.
+     * Explicit MapLibre layer specs. Layers are never derived automatically:
+     * when omitted the entry is created with no layers and renders nothing until
+     * they are set — by the agent via `setByodLayers`, or by passing them here.
      */
     layers?: CustomGeoJSONLayerSpec[];
     /** Provenance for the data. Defaults to `{ kind: 'integrator' }`. */
@@ -105,6 +104,44 @@ declare class BaseMapState implements StateSlice {
 
 /* Excluded from this release type: buildSystemPrompt */
 
+/**
+ * A single analysis result attached to a BYOD entry. Produced by `analyseData`
+ * when the entry is passed via `byodEntryIDs`; `data` is whatever the dynamic
+ * code returned. Structurally identical to the other slices' analysis records
+ * so the shared attach helper treats every slice uniformly.
+ *
+ * @group Agent Toolkit
+ */
+export declare type BYODAnalysis = {
+    /** Unique name within the parent entry (used as a key for the UI). */
+    name: string;
+    timestamp: number;
+    /** Optional human-readable description of what the analysis computed. */
+    description?: string;
+    /** How `data` should be interpreted — plain JSON or a Chart.js configuration. */
+    outputFormat: AnalysisOutputFormat;
+    /** Arbitrary analysis result returned by the dynamic code. */
+    data: unknown;
+};
+
+/**
+ * Token-frugal description of a BYOD FeatureCollection's runtime shape: feature
+ * count, the geometry types present, and a per-property profile. Stored on every
+ * {@link BYODEntry} and surfaced through `addByodSource` / `recallByod`
+ * so the model never has to receive raw GeoJSON just to learn the schema.
+ *
+ * @group Agent Toolkit
+ */
+export declare type BYODDataProfile = {
+    featureCount: number;
+    /** GeoJSON geometry types present (Point / LineString / Polygon / …). */
+    geometryTypes: string[];
+    /** Per-property profile, highest-coverage first. Capped — see `propertiesOmitted`. */
+    properties: BYODPropertyProfile[];
+    /** Count of property keys omitted when the collection has more distinct keys than the cap. */
+    propertiesOmitted?: number;
+};
+
 /**
  * A single entry in the BYOD (bring-your-own-data) GeoJSON history. Each entry
  * is a customer-authored layer the agent can read, render, query, or pipe
@@ -120,9 +157,16 @@ export declare type BYODEntry = {
     /** Provenance for the data — used by recall tools and the UI. */
     source: BYODSource;
     /**
-     * MapLibre layer specs the slice will render this entry under. When omitted
-     * at `addEntry` time the slice fills this in with sensible defaults based
-     * on the entry's geometry types (Point → circle, Line → line, Polygon → fill).
+     * Runtime-inferred shape of `data` — geometry types and a per-property
+     * profile. Derived once at `addEntry` time (see `profileFeatureCollection`)
+     * so recall / ingest tools can describe the data to the model without
+     * shipping the full FeatureCollection.
+     */
+    profile: BYODDataProfile;
+    /**
+     * MapLibre layer specs the slice renders this entry under. Always explicit —
+     * empty until set via `setByodLayers` (the agent path) or by passing `layers`
+     * to `addEntry`. An entry with no layers renders nothing.
      */
     layers: CustomGeoJSONLayerSpec[];
     /**
@@ -133,13 +177,30 @@ export declare type BYODEntry = {
     _module?: CustomGeoJSONModule;
     /** True while this entry's `_module` is rendering on the map. */
     _shown?: boolean;
+    /**
+     * Analyses attached by `analyseData` (keyed by `name` — re-running an analysis with the
+     * same name replaces it). Empty / absent until the first analysis runs against this entry.
+     */
+    _analysis?: BYODAnalysis[];
+};
+
+/** Compact profile of one feature-`properties` key across the whole collection. */
+export declare type BYODPropertyProfile = {
+    /** Property key as it appears in `feature.properties`. */
+    name: string;
+    /** Distinct JSON value types seen for this key (e.g. `["string"]`, `["number", "null"]`). */
+    types: string[];
+    /** Fraction of features carrying this key, 0–1 (1 = present on every feature). */
+    coverage: number;
+    /** Up to a few short, distinct example values — lets the LLM infer semantics. */
+    examples: Array<string | number | boolean>;
 };
 
 /**
  * Where a BYOD entry came from.
  * - `integrator`: seeded programmatically by the embedding app (e.g. user-uploaded file).
- * - `url`: fetched from a URL via `addByodLayer`.
- * - `inline`: passed as inline GeoJSON via `addByodLayer`.
+ * - `url`: fetched from a URL via `addByodSource`.
+ * - `inline`: passed as inline GeoJSON via `addByodSource`.
  *
  * @group Agent Toolkit
  */
@@ -185,11 +246,25 @@ declare class BYODState implements ShownEntriesSlice, StateSlice {
      * rendered on top of a still-visible old one). Returns the assigned id.
      */
     addEntry(data: FeatureCollection, label: string, options?: AddBYODEntryOptions): Promise<string>;
+    /**
+     * Replace the MapLibre layer specs an entry renders under. When the entry already owns a
+     * module (it has been shown at least once) the new specs are pushed live via the module's
+     * `applyConfig` runtime layer diff — no tear-down, no flicker. When no module exists yet the
+     * specs are stored and the next {@link showEntry} picks them up. Throws on an unknown id.
+     */
+    setEntryLayers(entryId: string, layers: CustomGeoJSONLayerSpec[]): void;
+    /**
+     * Attach an analysis to an existing entry (replace if a result of the same name exists).
+     * Mirrors {@link CustomGeometriesState.addAnalysisToEntry} so the shared `analyseData`
+     * attach helper treats BYOD like every other analysable slice. No-op (returns `false`)
+     * when the entry is unknown.
+     */
+    addAnalysisToEntry(entryId: string, analysis: BYODAnalysis): boolean;
     /**
      * Lazy-init the entry's CustomGeoJSONModule. The module is created with a
-     * single source named `data`, configured with this entry's `layers`. Layer
-     * changes after creation are not supported — drop the entry and add it back
-     * to swap layers.
+     * single source named `data`, configured with this entry's `layers`. To swap
+     * layers after creation, call {@link setEntryLayers} — it pushes the new specs
+     * into this module via `applyConfig` rather than recreating it.
      */
     getEntryModule(entryId: string): Promise<CustomGeoJSONModule>;
     /** Render this entry on the map. */
@@ -219,6 +294,11 @@ declare type BYODStateEvents = {
     'shown-change': ReadonlySet<string>;
     /** Display policy switched between `single` and `multiple`. */
     'mode-change': EntryMode;
+    /** An analysis was attached to (or replaced on) an entry by `analyseData`. */
+    'analysis-added': {
+        entryId: string;
+        analysis: BYODAnalysis;
+    };
 };
 
 /**
@@ -585,7 +665,8 @@ export declare const DEFAULT_TOOLS: {
     recallGeometries: ToolDefinition;
     recallPlaces: ToolDefinition;
     recallByod: ToolDefinition;
-    addByodLayer: ToolDefinition;
+    addByodSource: ToolDefinition;
+    setByodLayers: ToolDefinition;
     updateByodDisplay: ToolDefinition;
     recallRoutes: ToolDefinition;
     getCurrentWaypoints: ToolDefinition;
@@ -721,10 +802,18 @@ export declare type FeatureFlags = {
  */
 export declare const formatStateDigestDiff: (prev: StateDigest, next: StateDigest) => string | null;
 
-/** Tagged id for any polygon source in session state. */
+/**
+ * Tagged id for any polygon source in session state.
+ *
+ * @group Agent Toolkit
+ */
 export declare type GeometriesId = z.infer<typeof geometriesIdSchema>;
 
-/** Possible kinds in a geometries id. */
+/**
+ * Possible kinds in a geometries id.
+ *
+ * @group Agent Toolkit
+ */
 export declare type GeometriesIdKind = 'place' | 'places' | 'ranges' | 'customGeometries';
 
 /**
@@ -957,6 +1046,12 @@ declare type IncidentsAnalysisSpec = {
     source: string;
 };
 
+/**
+ * A fresh batch of incidents from a single monitor tick, with the moment it was sampled.
+ * Payload of {@link TrafficIncidentsStateEvents.monitor-tick}.
+ *
+ * @group Agent Toolkit
+ */
 export declare type IncidentSnapshot = {
     takenAt: number;
     incidents: TrafficIncident_2[];
@@ -1066,7 +1161,7 @@ export declare type MapAgentOptions<CS extends ToolState = ToolState> = {
      *     dataEntries: {
      *         routes: { entryMode: 'single' },
      *         incidents: { entryMode: 'single' },
-     *         byod: { enabled: false }, // disables recallByod, addByodLayer, updateByodDisplay + byod scope on analyse/process
+     *         byod: { enabled: false }, // disables recallByod, addByodSource, setByodLayers, updateByodDisplay + byod scope on analyse/process
      *         ranges: { enabled: false }, // disables findReachableAreas + recallRanges
      *     },
      * });
@@ -1159,6 +1254,12 @@ declare class MapPOIsState implements StateSlice {
     reset(): void;
 }
 
+/**
+ * The geographic area a {@link TrafficIncidentsEntry} monitor is polling, captured at
+ * monitor-start time and replayed on every tick.
+ *
+ * @group Agent Toolkit
+ */
 export declare type MonitoredArea = {
     bbox: BBox_2;
     capturedAt: number;
@@ -1392,6 +1493,12 @@ declare type PlacesStateEvents = {
     'mode-change': EntryMode;
 };
 
+/**
+ * Lifecycle state of a per-entry incidents monitor. `stopped-error` indicates the last
+ * poll failed and the timer has been cleared — start the monitor again to retry.
+ *
+ * @group Agent Toolkit
+ */
 export declare type PollingStatus = 'idle' | 'running' | 'stopped-error';
 
 declare type ProviderOptions = Record<string, Record<string, JSONValue | undefined>>;
@@ -2035,7 +2142,7 @@ export declare type ToolNameHint = ToolName | (string & {});
  *
  * @group Agent Toolkit
  */
-export declare const TOOLS_BY_DATA_ENTRY_KIND: Record<DataEntryKind, readonly string[]>;
+export declare const TOOLS_BY_DATA_ENTRY_KIND: Record<DataEntryKind, readonly ToolName[]>;
 
 /**
  * State passed to tool factory functions. Organized by feature area,
@@ -2218,6 +2325,12 @@ declare type TrafficAreaAnalyticsStateEvents = {
     'mode-change': EntryMode;
 };
 
+/**
+ * A single traffic-incidents history entry: the captured query, its incidents, and the
+ * per-entry rendering / monitoring / analysis state owned by {@link TrafficIncidentsState}.
+ *
+ * @group Agent Toolkit
+ */
 export declare type TrafficIncidentsEntry = {
     id: string;
     timestamp: number;
@@ -2321,9 +2434,8 @@ declare class TrafficIncidentsState implements StateSlice {
     replaceEntryData(entryId: TrafficIncidentsEntry['id'], data: TrafficIncident[], sampledAt: number): Promise<boolean>;
     /**
      * Lazy-init and return the entry's TrafficIncidentOverlayModule. Consumers subscribe to
-     * clicks directly on the returned module via `module.events.on('click', ...)`; use
-     * `module.distinctIncidents(features)` inside the handler if a stacked-click count is
-     * needed. Throws on unknown entry id.
+     * clicks directly on the returned module via `module.events.on('click', ...)`;
+     * Throws on unknown entry id.
      */
     getEntryModule(entryId: TrafficIncidentsEntry['id']): Promise<TrafficIncidentOverlayModule>;
     /**