[docs] update docs for Kepler.gl release 3.1 (#2941)

- Added a new release notes/what's new section to show new user-facing features (not a replacement for the changelog, which is a complete timeline of all kepler.gl development)
- Vector tile layer page
- AI assistant page
- SQL explorer/duckdb page
- Updates to ToCs 

---------

Signed-off-by: distefanodevinj <ddistefano@foursquare.com>
Co-authored-by: Igor Dykhta <igorDykhta@users.noreply.github.com>
Co-authored-by: Xun Li <lixun910@gmail.com>
Co-authored-by: Ilya Boyandin <ilya@boyandin.me>

SUMMARY.md

@@ -1,6 +1,7 @@
 # Table of contents
 
 * [Welcome](README.md)
+* [What's new?](docs/release-notes.md)
 * [Docs](docs/README.md)
   * [User guides](docs/user-guides/README.md)
     * [Get Started](docs/user-guides/j-get-started.md)

docs/README.md

@@ -1,6 +1,7 @@
 # Docs
 
 ## Table of contents
+- [What's new?](./release-notes.md)
 - [API References](./api-reference/README.md)
 - [User Guides](./user-guides/README.md)
 - [Jupyter Notebook](./keplergl-jupyter/README.md)

docs/release-notes.md

@@ -0,0 +1,72 @@
+# What's New?
+
+This page shows features that have landed to kepler.gl in major versions. For a complete list of changes to kepler.gl including each minor version, please [visit the full change log](../CHANGELOG.md).
+
+## 3.1 
+
+_Released January 29th, 2025_
+
+### Vector Tiles 
+
+The new [Vector Tile layer](/docs/user-guides/c-types-of-layers/vector.md) allows the map to dynamically retrieve data based on the user's viewport and zoom level. This initial release supports both Mapbox Vector Tiles and PMTiles.
+
+By leveraging the efficiency of vector tiles, users can visualize complex, large-scale datasets without compromising performance, making it easier to explore and analyze geospatial data.
+
+![Vector layer](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-vector.gif)
+
+
+### DuckDB Support & SQL Explorer
+
+Leverage DuckDB directly within kepler.gl your geospatial projects with big data. Write and execute SQL queries to perform custom analyses, visualizing the results on your map.
+
+DuckDB enables in-browser data processing, allowing you to work with large datasets without the need for external infrastructure.
+
+![SQL Data Explorer](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-duck-db.png)
+
+### AI Assistant
+
+Kepler’s AI assistant can edit the map, including filters, base map customization, and a variety of layer configurations. Accessible via text chat, voice chat, and screenshot. The assistant can also produce SQL from natural language, which can be passed to DuckDB.
+
+![AI Assistant](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant.png)
+
+### Base Map Updates: MapLibre + Mapbox
+
+Mapbox and MapLibre base maps are now simultaneously supported.
+
+
+### Color Scale Improvements
+
+Custom color scale is now supported in categorial/ordinal fields, aggregate layers, and other layer components. In addition, custom breaks are now supported within the color scales.
+
+
+### Value Formatting
+
+Formatting for numeric values (e.g. 10,000 can be formatted 10k, $10,000.00, etc; .42 can be formatted as 42%).
+
+
+### Animation Improvements
+
+Includes various updates to the user interface for animation (for both time filters and the trip layer). You may also sync the layers (such as the trip layer) with filters, and conversely sync filters with the layer.
+
+
+### Legend Improvements
+
+The legend is now both movable and resizable, supports the editing of legend values, and offers a scale for radius scaling.
+
+
+### Various Layer Improvements
+
+A number of improvements to layers, including: 
+
+- Zoom to layer button lets users center their viewport on the layer’s data
+- Point layer now supports geojson
+- Arc layer supports creation from h3
+- A vast number of other layer improvements
+
+This release also includes a wide range of bug fixes and performance improvements, which can be viewed in the [full change log.](../CHANGELOG.md)
+
+
+
+
+
+

docs/user-guides/README.md

@@ -37,6 +37,7 @@ This guide will teach you how to perform data analysis in Kepler.gl by adding da
 * [H3](./c-types-of-layers/j-h3.md)
 * [Trip](./c-types-of-layers/k-trip.md)
 * [S2](./c-types-of-layers/l-s2.md)
+* [Vector](./c-types-of-layers/vector.md)
 
 #### [Layer attributes](./d-layer-attributes.md)
 
@@ -59,6 +60,9 @@ This guide will teach you how to perform data analysis in Kepler.gl by adding da
 * [Display legend](./m-map-settings.md#display-legend)
 * [Split maps](./m-map-settings.md#split-maps)
 
+#### [SQL Data Explorer](./sql-data-explorer.md)
+
+#### [AI Assistant](./ai-assistant.md)
 
 #### [Time playback](./h-playback.md)
 

docs/user-guides/ai-assistant.md

@@ -0,0 +1,139 @@
+# AI Assistant
+
+> Note: This feature is currently undergoing development. Stay tuned for updates!
+
+The AI assistant in Kepler.gl is not only a LLM based chatbot, it is engineered to help users with creating maps and analyzing their spatial data. The AI assistant provides a new way that allows users to interact with the data and the map in a more natural and creative way.
+
+![AI Assistant](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant.png 'AI Assistant')
+
+Your conversations can be advanced: `Create a geojson layer using population with quantile color scale and update its colors inspired by Van Gogh's Starry Night`. Or: `Check the correlation between temperature and precipitation in the dataset`.
+
+
+## Supported Providers
+
+The following providers and models are currently supported.
+
+> Note: we are working on feature to allow users specify their own providers, models and base URL.
+
+| **Provider** | **Models**                                                                                      |
+|--------------|------------------------------------------------------------------------------------------------|
+| **OpenAI**   | `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`, `gpt-3.5-turbo-0125`, `o1-mini`, `o1-preview`          |
+| **Google**   | `gemini-2.0-flash-exp`, `gemini-1.5-flash`, `gemini-1.5-pro`, `gemini-1.0-pro`                   |
+| **Ollama** (local)  | `deepseek-r1`, `phi4`, `phi3.5`, `qwen2.5-coder`, `qwen2`, `qawa`, `llava`, `mistral`, `gemma2`, `llama3.3`, `llama3.2`, `llama3.1`, `llama3.1:70b` |
+| **DeepSeek** | `deepseek-chat`, `deepseek-reasoner` |
+
+## Parameters
+
+Before initating the AI assistant, the following parameters are required. A temperature and Top P are selected for you; however, you will need to provide an API key for a remote model, and a base URL for local models.
+
+| **Parameter** | **Description**                                                                                 |
+|---------------|-------------------------------------------------------------------------------------------------|
+| **Temperature** | Controls the randomness of the model's output. Range: `0-2`, Default: `1`. Lower values make responses more focused and deterministic. |
+| **Top P**       | Controls the diversity of the output by limiting the cumulative probability of token selection. Range: `0-1`, Default: `0.8`.          |
+| **API Key**   | Required for OpenAI (`gpt` models) and Google (`gemini` models).                                                                      |
+| **Base URL**  | Required for Ollama (`localhost:11434` or another specified base URL).                                                                |
+
+## Built-in Features
+
+- Take screenshot to ask [[Demo]](https://geoda.ai/img/highlight-screenshot.mp4)
+- Talk to ask [[Demo]](https://geoda.ai/img/highlight-ai-talk.mp4)
+
+### Take a Screenshot to Ask
+
+This feature enables users to capture a screenshot anywhere within kepler.gl application and ask questions about the screenshot.
+
+For example, users can take a screenshot of the map (or partial of the map) and ask questions about the map e.g. *`how many counties are in this screenshot`*, or take a screenshot of the layer configuration panel and ask questions about how to use it, e.g. *`How can I adjust the opacity`*. Users can even take a screenshot of the plots in the chat panel and ask questions about the plots e.g. *`Can you give me a summary of the plot?`*.
+
+![Screenshot to ask](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant-screenshot.png 'Screenshot to ask')
+
+#### How to use this feature?
+
+1. Click the "Screenshot to Ask" button in the chat interface
+2. A semi-transparent overlay will appear
+3. Click and drag to select the area you want to capture
+4. Release to complete the capture
+5. The screenshot will be displayed in the chat interface
+6. You can click the x button on the top right corner of the screenshot to delete the screenshot
+
+### Talk to Ask
+
+This feature enables users to "talk" to the AI assistant. After clicking the "Talk to Ask" button, users can start talking using microphone. When clicking the same button again, the AI assistant will stop listening and send the transcript to the input box.
+
+When using the voice-to-text feature for the first time, users will be prompted to grant microphone access. The browser will display a permission dialog that looks like this:
+
+![Talk to ask](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant-talk-to-ask.png 'Talk to ask')
+
+After granting access, users can start talking to the AI assistant.
+
+> Note: for OpenAI, the whisper model is used to transcribe the audio. Google's gemini models are multimodal models, so the audio-to-text feature is supported by default.
+
+## Map and Data Analysis Assistant
+
+Using LLM function tools, kepler.gl's AI assistant can help transform users's prompt into actions that executed inside kepler.gl. This allows users to interact with kepler.gl in a more natural and creative way.
+
+### Why use LLM function tools?
+
+Function calling enables the AI Assistant to perform specialized tasks that LLMs cannot handle directly, such as complex calculations, data analysis, visualization generation, and integration with external services. This allows the assistant to execute specific operations within kepler.gl while maintaining natural language interaction with users.
+
+### Is my data secure?
+
+Yes, the data you used in kepler.gl stays within the browser, and will **never** be sent to the LLM. Using function tools, we can engineer the AI assistant to use only the meta data for function calling, e.g. the name of the dataset, the name of the layer, the name of the variables, etc. Here is a process diagram to show how the AI assistant works:
+
+![AI Assistant Diagram](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant-diagram.png 'AI Assistant Diagram')
+
+### Actions available to use
+
+The current supported actions are:
+
+- System:
+  - Show dataset/layer/variable info.
+  - Load data from url.
+  - Change the basemap style.
+- Mapping and Data Analysis:
+  - Create map layer from variable.
+  - Query the data using SQL (coming soon)
+  - Classify the data of a variable.
+    - Quantile / Natural (Jenks) Breaks / Percentile / Box / Standard Deviation
+- Plots
+  - Create histogram.
+  - Create scatter plot with regression line.
+- Spatial Analysis:
+  - Spatial join two datasets (e.g. count points and polygons).
+
+> Note: to see our plan to add more actions to the AI assistant, please check out this [Kepler.gl RFC]([https://github.com/kepler-gl/kepler.gl/issues/4689](https://github.com/keplergl/kepler.gl/discussions/2843)) and the [integration of GeoDa with Kepler.gl]([text](https://github.com/GeoDaCenter/openassistant/wiki/Integration-Kepler.gl---GeoDaLib))
+
+Users can simply describe what they want to accomplish in plain text, and the AI Assistant will invoke the appropriate function with the correct parameters that your application can execute. The LLM will identify if the question can be answered by using one or multiple function tools, and the LLM will ask the user to confirm the parameters of each function call.
+
+> *Can you classify the data of the variable "population" using natural breaks and create a geojson layer using the breaks with colors inspired by Van Gogh's Starry Night.*
+
+#### Plots
+
+The plots created by the AI assistant are interactive, and can be used to explore the data.
+
+In each plot, there is a small toolbar on the top right corner, which contains three buttons:
+
+- **Box Select**: Select the data in the plot.
+- **Keep Selection**: Keep the selected data in the plot.
+- **Clear Selection**: Clear the selected data in the plot.
+
+One can click the **Box Select** button first. Then, start selecting the data in the plot by left clicking the mouse and dragging the mouse to select the data. The selected data will be highlighted in the plot and also be highlighted in the map.
+
+##### Scatter Plot
+
+For scatter plot, the AI assistant will create a scatter plot with a regression line by default. If users select points in the plot, there will be 3 different regression lines created: one for all points, one for the selected points, and one for the unselected points.
+
+If users click the 'expand' button on the top right corner of the plot, the plot will be expanded to a floating modal dialog with more details of the regressions shown in a tablt.
+
+The regression details include:
+
+- R-squared
+- Slope
+- Intercept
+- P-value
+- Standard Error
+- Chow test for selected and unselected regression lines
+
+This scatter plot can help users to explore the relationship between two variables, and explore the heterogeneity of the data by selecting different points.
+
+![Scatterplot](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant-scatterplot.png 'Scatterplot')
+

docs/user-guides/c-types-of-layers/vector.md

@@ -3,9 +3,7 @@
 
 Vector layers use the three basic GIS features – lines, points, and polygons – to represent real-world features in digital format.
 
-
-{% embed url="https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-gl-vector-tiles-fsq.mp4" %}
-
+![Vector layer](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-vector.gif 'Vector layer')
 
 # Settings
 
@@ -66,16 +64,5 @@ Height settings for the Vector layer. Height is best viewed with the 3D viewing
 | Fixed Height    | Applies height without additional modifications.   |
 
 
-<!-- Remove after testing -->
-
-## Video Alternative 
-
-<video controls autoplay loop>
-  <source src="https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-gl-vector-tiles-fsq.mp4" type="video/mp4">
-  Your browser does not support the video tag.
-</video>
-
-
-
 
 [Back to table of contents](../README.md)

docs/user-guides/sql-data-explorer.md

@@ -0,0 +1,20 @@
+# SQL/DuckDB Data Explorer 
+
+> Note: This feature is currently undergoing development. Stay tuned for updates!
+
+The new SQL data explorer provides a DucKDB instance where you can use SQL to transform and add data to the map.
+
+![SQL Data Explorer](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-duck-db.png 'SQL Data Explorer')
+
+You will need local data (i.e. data upload for your machine) or data accessible via a remote URL.
+
+Any dataset already added to kepler can be accessed via SQL editor by selecting it via its name in kepler. For instance, if your dataset is named `world-cities.csv`, you can select the entire dataset by writing `SELECT * FROM 'world-cities.csv'`. 
+
+The data does not need to be pre-loaded to kepler -- you may also select data remotely via SQL. The following example loads earthquake data from our sample data repository:
+
+```
+SELECT * FROM 'https://raw.githubusercontent.com/keplergl/kepler.gl-data/refs/heads/master/earthquakes/data.csv'
+```
+
+
+Once you have a data selection you are satisfied with, click **Add to Map**. Your new dataset will be added to kepler. If you have a column that contains recognizable geography data, (i.e. lat/lng columns or polygon geometries), layers will automatically be created.