llmaps 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. llmaps-0.1.0/.gitignore +55 -0
  2. llmaps-0.1.0/CHANGELOG.md +39 -0
  3. llmaps-0.1.0/CONTRIBUTING.md +82 -0
  4. llmaps-0.1.0/LICENSE +22 -0
  5. llmaps-0.1.0/PHILOSOPHY.md +71 -0
  6. llmaps-0.1.0/PKG-INFO +258 -0
  7. llmaps-0.1.0/README.md +196 -0
  8. llmaps-0.1.0/docs/api/components.md +193 -0
  9. llmaps-0.1.0/docs/api/layers.md +163 -0
  10. llmaps-0.1.0/docs/api/map.md +152 -0
  11. llmaps-0.1.0/docs/api/sources.md +112 -0
  12. llmaps-0.1.0/docs/recipes/comparison.md +66 -0
  13. llmaps-0.1.0/docs/recipes/embedded-map.md +57 -0
  14. llmaps-0.1.0/docs/recipes/feature-state-highlighting.md +161 -0
  15. llmaps-0.1.0/docs/recipes/heatmap.md +59 -0
  16. llmaps-0.1.0/examples/README.md +188 -0
  17. llmaps-0.1.0/examples/cafes/build_map.py +162 -0
  18. llmaps-0.1.0/examples/cafes/data/.gitkeep +0 -0
  19. llmaps-0.1.0/examples/cafes/map.html +1849 -0
  20. llmaps-0.1.0/examples/cafes/prepare_data.py +120 -0
  21. llmaps-0.1.0/examples/earthquakes/build_map.py +217 -0
  22. llmaps-0.1.0/examples/earthquakes/download_data.py +12 -0
  23. llmaps-0.1.0/examples/earthquakes/earthquakes_map.html +1772 -0
  24. llmaps-0.1.0/examples/earthquakes/earthquakes_with_depth.geojson +1 -0
  25. llmaps-0.1.0/examples/earthquakes/map.html +1853 -0
  26. llmaps-0.1.0/examples/earthquakes/prepare_data.py +58 -0
  27. llmaps-0.1.0/examples/index.html +279 -0
  28. llmaps-0.1.0/examples/world_population/build_map.py +179 -0
  29. llmaps-0.1.0/examples/world_population/data/.gitkeep +0 -0
  30. llmaps-0.1.0/examples/world_population/map.html +1851 -0
  31. llmaps-0.1.0/examples/world_population/prepare_data.py +111 -0
  32. llmaps-0.1.0/llmaps/LLM_CONTEXT.md +120 -0
  33. llmaps-0.1.0/llmaps/__init__.py +24 -0
  34. llmaps-0.1.0/llmaps/components/__init__.py +20 -0
  35. llmaps-0.1.0/llmaps/components/base.py +17 -0
  36. llmaps-0.1.0/llmaps/components/basemap_switcher.py +36 -0
  37. llmaps-0.1.0/llmaps/components/controls.py +47 -0
  38. llmaps-0.1.0/llmaps/components/feature_search.py +89 -0
  39. llmaps-0.1.0/llmaps/components/legend.py +99 -0
  40. llmaps-0.1.0/llmaps/components/popup.py +56 -0
  41. llmaps-0.1.0/llmaps/components/search.py +61 -0
  42. llmaps-0.1.0/llmaps/components/sidebar.py +77 -0
  43. llmaps-0.1.0/llmaps/core/__init__.py +9 -0
  44. llmaps-0.1.0/llmaps/core/config.py +6 -0
  45. llmaps-0.1.0/llmaps/core/generator.py +110 -0
  46. llmaps-0.1.0/llmaps/core/legend_generator.py +352 -0
  47. llmaps-0.1.0/llmaps/core/utils.py +216 -0
  48. llmaps-0.1.0/llmaps/expressions.py +236 -0
  49. llmaps-0.1.0/llmaps/layers/__init__.py +16 -0
  50. llmaps-0.1.0/llmaps/layers/base.py +79 -0
  51. llmaps-0.1.0/llmaps/layers/circle.py +56 -0
  52. llmaps-0.1.0/llmaps/layers/fill.py +60 -0
  53. llmaps-0.1.0/llmaps/layers/h3.py +111 -0
  54. llmaps-0.1.0/llmaps/layers/vector_tile.py +121 -0
  55. llmaps-0.1.0/llmaps/map.py +406 -0
  56. llmaps-0.1.0/llmaps/optimizers/__init__.py +25 -0
  57. llmaps-0.1.0/llmaps/optimizers/compression.py +103 -0
  58. llmaps-0.1.0/llmaps/optimizers/multipoint.py +50 -0
  59. llmaps-0.1.0/llmaps/optimizers/visibility.py +73 -0
  60. llmaps-0.1.0/llmaps/sources/__init__.py +9 -0
  61. llmaps-0.1.0/llmaps/sources/api.py +44 -0
  62. llmaps-0.1.0/llmaps/sources/base.py +40 -0
  63. llmaps-0.1.0/llmaps/sources/file.py +56 -0
  64. llmaps-0.1.0/llmaps/sources/vector_tile.py +33 -0
  65. llmaps-0.1.0/llmaps/templates/base.html +34 -0
  66. llmaps-0.1.0/llmaps/templates/css/.gitkeep +1 -0
  67. llmaps-0.1.0/llmaps/templates/css/base.css +718 -0
  68. llmaps-0.1.0/llmaps/templates/js/.gitkeep +1 -0
  69. llmaps-0.1.0/llmaps/templates/js/comparison.js.j2 +35 -0
  70. llmaps-0.1.0/llmaps/templates/js/components.js.j2 +597 -0
  71. llmaps-0.1.0/llmaps/templates/js/config.js.j2 +32 -0
  72. llmaps-0.1.0/llmaps/templates/js/init.js.j2 +28 -0
  73. llmaps-0.1.0/llmaps/templates/js/layers.js.j2 +125 -0
  74. llmaps-0.1.0/llmaps/templates/js/sources.js.j2 +109 -0
  75. llmaps-0.1.0/llmaps/tiles.py +71 -0
  76. llmaps-0.1.0/pyproject.toml +50 -0
  77. llmaps-0.1.0/tests/.gitkeep +1 -0
llmaps-0.1.0/.gitignore ADDED
@@ -0,0 +1,55 @@
1
+ # Byte-compiled / cached
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+
7
+ # Virtual environments
8
+ .venv/
9
+ venv/
10
+ env/
11
+
12
+ # IDE
13
+ .idea/
14
+ .vscode/
15
+ *.swp
16
+ *.swo
17
+
18
+ # OS
19
+ .DS_Store
20
+ Thumbs.db
21
+
22
+ # Distribution / build
23
+ build/
24
+ dist/
25
+ *.egg-info/
26
+ *.egg
27
+
28
+ # Testing / coverage
29
+ .pytest_cache/
30
+ .coverage
31
+ htmlcov/
32
+ .tox/
33
+
34
+ # Environment
35
+ .env
36
+ .env.local
37
+
38
+ CLAUDE.md
39
+
40
+ # Examples data (downloaded/generated)
41
+ examples/*/data/*.geojson
42
+ examples/*/data/*.csv
43
+ examples/*/data/*.parquet
44
+ examples/*/data/*.zip
45
+ examples/*/data/*.shp
46
+ examples/*/data/*.dbf
47
+ examples/*/data/*.shx
48
+ examples/*/data/*.prj
49
+ examples/*/data/*.cpg
50
+
51
+ # Keep .gitkeep to preserve directory structure
52
+ !examples/*/data/.gitkeep
53
+
54
+ # HTML outputs are committed (for GitHub Pages)
55
+ # Do NOT ignore *.html in examples/
llmaps-0.1.0/CHANGELOG.md ADDED
@@ -0,0 +1,39 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ ## 0.4.0 - New components (A1, A2, A4, C1)
6
+
7
+ - **Added:** `Sidebar` component — sliding side panel for feature details on click. Configurable fields per layer, title, position, width. Takes priority over Popup. Exposes `window.llmapsSidebarOpen/Close` JS API.
8
+ - **Added:** `FeatureSearch` component — search within map data by feature attributes (not a geocoder). Dropdown with debounce, flyTo/fitBounds on select, integrates with Sidebar.
9
+ - **Added:** `Popup(trigger="hover")` — hover mode for popups. Popup follows cursor and disappears on mouseleave.
10
+ - **Added:** `compute_color_stops(values, n_stops, colors, percentiles)` in `expressions` — auto-compute color ramp thresholds from data distributions using percentiles (numpy).
11
+
12
+ ## 0.3.0 - Infrastructure improvements (B3–B5)
13
+
14
+ - **Added:** `Map.add_custom_js(js)` — inject custom JavaScript (string or `Path` to file).
15
+ - **Added:** `Map.add_custom_css(css)` — inject custom CSS (string or `Path` to file).
16
+ - **Added:** `Map.add_custom_html(html)` — inject custom HTML into `<body>`.
17
+ - **Added:** `Map.embed_data(key, data)` — embed arbitrary JSON data as `window.llmapsData.<key>`.
18
+ - **Added:** `window.llmapsGetSourceData(sourceId)` — public JS utility to access GeoJSON data from embedded/compressed/remote sources.
19
+
20
+ ## 0.2.0 - Feature-state support (B1, B2, A3)
21
+
22
+ - **Fixed:** `llmapsOnLayersReady` — now an event queue (multiple callbacks supported).
23
+ - **Added:** `promoteId` support in sources (`promote_id` parameter on `BaseSource`).
24
+ - **Added:** `FillLayer` now accepts expressions for `fill_color` and `fill_opacity`.
25
+ - **Added:** `expressions.feature_state_color()` and `expressions.feature_state_value()` helpers.
26
+ - **Added:** `window.llmapsClearFeatureStates()` and `window.llmapsSetFeatureState()` JS utilities.
27
+
28
+ ## 0.1.1 - FillLayer outline fix
29
+
30
+ - **Fixed:** FillLayer now uses correct MapLibre property `fill-outline-color` instead of invalid `outline-color`/`outline-width`.
31
+ - **Added:** For `stroke_width > 1`, an additional line layer `{id}-outline` is automatically generated.
32
+ - **Docs:** Updated `docs/api/layers.md` with note about stroke_width behavior.
33
+
34
+ ## 0.1.0 - Initial setup
35
+
36
+ - Project structure created.
37
+ - `pyproject.toml` added.
38
+ - MIT license and basic docs initialized.
39
+
llmaps-0.1.0/CONTRIBUTING.md ADDED
@@ -0,0 +1,82 @@
1
+ # Contributing to LLMaps
2
+
3
+ Thank you for considering contributing to LLMaps.
4
+
5
+ ## Development setup
6
+
7
+ 1. Clone the repository and create a virtual environment (or use conda).
8
+ 2. Install in editable mode with optional dependencies:
9
+
10
+ ```bash
11
+ pip install -e ".[all]"
12
+ ```
13
+
14
+ 3. Run tests (when available):
15
+
16
+ ```bash
17
+ pytest tests/
18
+ ```
19
+
20
+ ## Code style
21
+
22
+ - Follow PEP 8.
23
+ - Use type hints for public API (constructors, method signatures).
24
+ - Prefer dataclasses for configuration objects (Map, layers, sources, components).
25
+ - Keep the public API stable and documented in `llmaps/LLM_CONTEXT.md` (and thus `get_llm_context()`) and `docs/api/`.
26
+
27
+ ## Documentation checklist
28
+
29
+ For any public API change, update the documentation. Below is a complete list of files and dependency matrix.
30
+
31
+ ### Documentation files
32
+
33
+ | File | Purpose |
34
+ |------|---------|
35
+ | `llmaps/LLM_CONTEXT.md` | Compact reference for LLMs (`get_llm_context()`). **Most important** — update for ANY API change |
36
+ | `docs/api/map.md` | Map class API (constructor, methods) |
37
+ | `docs/api/layers.md` | Layer API (CircleLayer, FillLayer, H3Layer, VectorTileLayer) |
38
+ | `docs/api/sources.md` | Source API (FileSource, ApiSource, VectorTileSource) |
39
+ | `docs/api/components.md` | Component API (Legend, Popup, Sidebar, FeatureSearch, Search, Controls, BasemapSwitcher) |
40
+ | `docs/recipes/*.md` | Recipes: heatmap, embedded-map, comparison, feature-state-highlighting |
41
+ | `README.md` | Main page — tables of layers, components, tile providers |
42
+ | `examples/README.md` | Examples overview |
43
+ | Docstrings in `*.py` | Class and method documentation in source code |
44
+
45
+ **Note:** `CHANGELOG.md` is updated only on new releases, not on every commit.
46
+
47
+ ### Matrix: what to update
48
+
49
+ | Change type | Must update |
50
+ |------------|-------------|
51
+ | Map parameter | `map.md`, `LLM_CONTEXT.md`, docstring in `map.py` |
52
+ | Map method | `map.md`, `LLM_CONTEXT.md`, docstring in `map.py` |
53
+ | New/changed layer | `layers.md`, `LLM_CONTEXT.md`, docstring, `layers/__init__.py` |
54
+ | New/changed source | `sources.md`, `LLM_CONTEXT.md`, docstring, `sources/__init__.py` |
55
+ | New/changed component | `components.md`, `LLM_CONTEXT.md`, docstring, `components/__init__.py` |
56
+ | Expression helper | `LLM_CONTEXT.md`, docstring in `expressions.py`, `feature-state-highlighting.md` |
57
+ | Tile provider | `map.md`, `LLM_CONTEXT.md`, `tiles.py` |
58
+ | JS API (frontend) | `LLM_CONTEXT.md`, `sources.md`, `feature-state-highlighting.md` |
59
+ | Embedded/compression | `embedded-map.md`, `map.md`, `LLM_CONTEXT.md` |
60
+ | Breaking change | All of the above + BREAKING mark |
61
+
62
+ ### Quick pre-commit checklist
63
+
64
+ - [ ] Docstrings updated in modified classes/methods
65
+ - [ ] `LLM_CONTEXT.md` reflects the change (constructors, scenarios, JS API)
66
+ - [ ] Corresponding file in `docs/api/` updated
67
+ - [ ] `docs/recipes/` updated if pattern affected
68
+ - [ ] Examples in `examples/` work with new API
69
+
70
+ ## Pull requests
71
+
72
+ - Describe the change and why it is needed.
73
+ - Ensure existing tests pass and add tests for new behaviour where appropriate.
74
+ - Update documentation (LLM_CONTEXT.md, docs/api, or recipes) if the public API or usage changes.
75
+
76
+ ## Scope
77
+
78
+ LLMaps is a **library** for generating interactive web maps from Python. It is not a full GIS platform or a web application framework. Contributions that keep the API simple, predictable, and LLM-friendly are especially welcome.
79
+
80
+ ## License
81
+
82
+ By contributing, you agree that your contributions will be licensed under the MIT License.
llmaps-0.1.0/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sergey Abramov
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
llmaps-0.1.0/PHILOSOPHY.md ADDED
@@ -0,0 +1,71 @@
1
+ # LLMaps Philosophy
2
+
3
+ LLMaps is a **Python library** for creating interactive web maps, designed for LLM-assisted development and vibe coding. This document describes the concept, design principles, and how it compares to alternatives.
4
+
5
+ ---
6
+
7
+ ## Concept
8
+
9
+ **LLMaps** — A Python library for creating interactive maps, optimized for LLM-assisted development.
10
+
11
+ - **Library, not framework:** It does not dictate application architecture. You use it inside your code; it does not wrap your app.
12
+ - **Single responsibility:** Build a map configuration, render it to standalone HTML. No server, no backend required for the default embedded mode.
13
+ - **Declarative API:** You describe *what* the map should show (center, zoom, layers, components); the library handles *how* (MapLibre GL JS, Jinja2, templates).
14
+
15
+ ---
16
+
17
+ ## Vibe Coding and LLM-First Design
18
+
19
+ **Vibe coding** here means: writing code with the help of an LLM (e.g. in an IDE or chat). The API is built so that:
20
+
21
+ 1. **Predictable names** — `Map`, `CircleLayer`, `FillLayer`, `FileSource`, `Legend`, `Popup`, `Controls`, `Search`. No magic or overloaded meanings.
22
+ 2. **Stable contracts** — Constructors and methods have clear signatures; `to_dict()` produces a serialisable config. This makes it easy for an LLM to suggest correct code.
23
+ 3. **Composable pieces** — One map, many layers, many components. Add what you need: `map.add_layer(...).add_component(...).save(...)`.
24
+ 4. **Documentation as product** — `get_llm_context()` yields a compact reference (signatures, scenarios, JS utilities) for LLM-assisted code; humans use `docs/api/`.
25
+
26
+ The goal is: *fewer edits, fewer bugs* when generating map code with an LLM.
27
+
28
+ ---
29
+
30
+ ## Design Principles
31
+
32
+ 1. **LLM-first** — Structure and naming are chosen so that both humans and LLMs can find and use the right abstraction quickly (see `get_llm_context()` / LLM_CONTEXT and `docs/api/`).
33
+ 2. **Component-based** — Clear abstractions: `Map`, `Layer`, `Source`, `Component`, `Optimizer`. Each does one job and combines with others.
34
+ 3. **KISS** — Configuration via parameters, dataclasses, or dicts. Complex logic (H3 aggregation, compression, comparison mode) lives inside the library, not in user code.
35
+ 4. **Don’t reinvent the wheel** — Build on proven tools: MapLibre GL JS for the map, Jinja2 for HTML, optional geopandas/h3/geobuf for data and optimizations. Use official plugins (e.g. maplibre-gl-compare) where they fit.
36
+ 5. **Extensibility** — Well-defined extension points: new layer types, new sources, new components, without rewriting the core.
37
+ 6. **English only** — Code, comments, docs, and UI strings are in English for a global, open-source audience.
38
+
39
+ ---
40
+
41
+ ## Comparison with Alternatives
42
+
43
+ | Criterion | Kepler.gl | Folium / ipyleaflet | Custom MapLibre/Leaflet | **LLMaps** |
44
+ |-----------|-----------|---------------------|--------------------------|------------|
45
+ | **Ready-made components** | Limited by UI | Few map primitives | None | Full set: layers, legend, popup, search, controls |
46
+ | **LLM-friendly** | No | Partial (verbose) | Depends on custom code | Yes: index, tags, clear API |
47
+ | **H3 / aggregation** | Yes | No (manual) | Manual | Yes (H3Layer) |
48
+ | **Embedded (file://)** | No | Often needs server | Manual | Yes (embedded=True) |
49
+ | **Comparison (before/after)** | No | No | Manual | Yes (enable_comparison) |
50
+ | **Single HTML output** | No | Possible | Manual | Yes (save/to_html) |
51
+ | **Customization** | Limited by UI | Good | Full | Full (config + templates) |
52
+ | **No backend** | No | Often | Possible | Yes (embedded mode) |
53
+
54
+ **When to use LLMaps:** You want a single Python API to produce a standalone interactive map (especially with embedded data), with minimal boilerplate and good support for LLM-generated code. You are fine with MapLibre GL JS on the frontend and optional dependencies (geopandas, h3, geobuf) for advanced features.
55
+
56
+ **When to choose something else:** You need a full GIS UI (Kepler.gl), tight Jupyter integration only (Folium/ipyleaflet), or a fully custom stack (raw MapLibre/Leaflet and your own backend).
57
+
58
+ ---
59
+
60
+ ## Architecture in Brief
61
+
62
+ - **Python API** — `Map`, layers (`CircleLayer`, `FillLayer`, `H3Layer`, `VectorTileLayer`), sources (`FileSource`, `ApiSource`, `VectorTileSource`), components (`Legend`, `Popup`, `Search`, `Controls`).
63
+ - **Config** — Everything reduces to a serialisable dict (`to_dict()`); no framework magic.
64
+ - **Output** — The generator (`llmaps.core.generator`) turns that config into one HTML file (with inline or linked JS/CSS). Embedded mode inlines GeoJSON (optionally Geobuf+Gzip).
65
+ - **Frontend** — MapLibre GL JS + plugins (e.g. comparison). Templates live under `llmaps/templates/`.
66
+
67
+ ---
68
+
69
+ ## Summary
70
+
71
+ LLMaps combines a small, predictable Python API with a component-based design and an LLM-oriented doc set. It targets developers who want to generate or maintain map code quickly (including with LLMs) and ship a single HTML map without a backend. The philosophy is: **simple to call, explicit in structure, and built on solid open-source building blocks.**
llmaps-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,258 @@
1
+ Metadata-Version: 2.4
2
+ Name: llmaps
3
+ Version: 0.1.0
4
+ Summary: A Python library for creating interactive web maps, optimized for LLM-assisted development.
5
+ Project-URL: Homepage, https://github.com/sergeyabramov/llmaps
6
+ Project-URL: Documentation, https://github.com/sergeyabramov/llmaps
7
+ Project-URL: Source, https://github.com/sergeyabramov/llmaps
8
+ Project-URL: Issues, https://github.com/sergeyabramov/llmaps/issues
9
+ Author: Sergey Abramov
10
+ License: MIT License
11
+
12
+ Copyright (c) 2026 Sergey Abramov
13
+
14
+ Permission is hereby granted, free of charge, to any person obtaining a copy
15
+ of this software and associated documentation files (the "Software"), to deal
16
+ in the Software without restriction, including without limitation the rights
17
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18
+ copies of the Software, and to permit persons to whom the Software is
19
+ furnished to do so, subject to the following conditions:
20
+
21
+ The above copyright notice and this permission notice shall be included in all
22
+ copies or substantial portions of the Software.
23
+
24
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30
+ SOFTWARE.
31
+
32
+ License-File: LICENSE
33
+ Keywords: geospatial,llm,maplibre,maps,visualization
34
+ Classifier: Development Status :: 4 - Beta
35
+ Classifier: Intended Audience :: Developers
36
+ Classifier: License :: OSI Approved :: MIT License
37
+ Classifier: Programming Language :: Python
38
+ Classifier: Programming Language :: Python :: 3
39
+ Classifier: Programming Language :: Python :: 3.9
40
+ Classifier: Programming Language :: Python :: 3.10
41
+ Classifier: Programming Language :: Python :: 3.11
42
+ Classifier: Programming Language :: Python :: 3.12
43
+ Classifier: Topic :: Scientific/Engineering :: GIS
44
+ Classifier: Topic :: Scientific/Engineering :: Visualization
45
+ Requires-Python: >=3.9
46
+ Requires-Dist: jinja2>=3.1.0
47
+ Provides-Extra: all
48
+ Requires-Dist: geobuf; extra == 'all'
49
+ Requires-Dist: geopandas; extra == 'all'
50
+ Requires-Dist: h3; extra == 'all'
51
+ Requires-Dist: jenkspy; extra == 'all'
52
+ Requires-Dist: matplotlib; extra == 'all'
53
+ Provides-Extra: classify
54
+ Requires-Dist: jenkspy; extra == 'classify'
55
+ Requires-Dist: matplotlib; extra == 'classify'
56
+ Provides-Extra: compression
57
+ Requires-Dist: geobuf; extra == 'compression'
58
+ Provides-Extra: h3
59
+ Requires-Dist: geopandas; extra == 'h3'
60
+ Requires-Dist: h3; extra == 'h3'
61
+ Description-Content-Type: text/markdown
62
+
63
+ # LLMaps
64
+
65
+ ![Python](https://img.shields.io/badge/python-%3E%3D3.9-blue)
66
+ ![License](https://img.shields.io/badge/license-MIT-green)
67
+ ![MapLibre](https://img.shields.io/badge/frontend-MapLibre%20GL%20JS-orange)
68
+
69
+ **A Python library for creating interactive web maps, optimized for LLM-assisted development.**
70
+
71
+ Encapsulates best practices for interactive web map development behind a predictable, composable API — so both you and your LLM produce correct code on the first try. Outputs a single HTML file powered by MapLibre GL JS.
72
+
73
+ <details>
74
+ <summary>Table of Contents</summary>
75
+
76
+ - [Features](#features)
77
+ - [Installation](#installation)
78
+ - [Quick Start](#quick-start)
79
+ - [Examples](#examples)
80
+ - [Built With](#built-with)
81
+ - [Comparison with Alternatives](#comparison-with-alternatives)
82
+ - [Architecture](#architecture)
83
+ - [Documentation](#documentation)
84
+ - [Tile Providers](#tile-providers)
85
+ - [License](#license)
86
+ - [Contact](#contact)
87
+ - [Contributing](#contributing)
88
+
89
+ </details>
90
+
91
+ ## Features
92
+
93
+ - **Declarative API** — composable `Map` + layers + sources + components. Describe *what* the map should show; the library handles *how*.
94
+ - **Single HTML output** — standalone file with MapLibre GL JS; works via `file://` when data is embedded.
95
+ - **Embedded mode** — inline GeoJSON (optionally Geobuf + Gzip) so you can share one file.
96
+ - **Comparison mode** — before/after slider using the MapLibre compare plugin.
97
+ - **Feature-state expressions** — GPU-efficient dynamic styling (`fill_color`, `opacity`) via `setFeatureState`.
98
+ - **Extensible** — custom JS/CSS/HTML injection, `embed_data()` for arbitrary JSON.
99
+ - **Built-in attribution** — automatic LLMaps branding with GitHub link (customizable or removable).
100
+ - **LLM-friendly** — predictable names, stable contracts; use `get_llm_context()` for a compact reference in chat.
101
+
102
+ **Available building blocks:**
103
+
104
+ | Category | Classes |
105
+ |----------|---------|
106
+ | **Layers** | `CircleLayer`, `FillLayer`, `H3Layer`, `VectorTileLayer` |
107
+ | **Sources** | `FileSource`, `ApiSource`, `VectorTileSource` |
108
+ | **Components** | `Legend`, `Popup`, `Sidebar`, `Search`, `FeatureSearch`, `Controls`, `BasemapSwitcher` |
109
+
110
+ ## Installation
111
+
112
+ ```bash
113
+ pip install llmaps
114
+ ```
115
+
116
+ Optional extras:
117
+
118
+ ```bash
119
+ pip install llmaps[h3] # H3 aggregation (h3, geopandas)
120
+ pip install llmaps[compression] # Geobuf + Gzip for embedded data
121
+ pip install llmaps[all] # h3 + compression
122
+ ```
123
+
124
+ **Context for LLM:** To give your LLM the right context when generating map code, run this in your project directory once. Then in chat use `@llmaps_context.md`:
125
+
126
+ ```bash
127
+ python -c "import llmaps; open('llmaps_context.md','w').write(llmaps.get_llm_context())"
128
+ ```
129
+
130
+ ## Quick Start
131
+
132
+ ```python
133
+ from llmaps import Map
134
+ from llmaps.layers import CircleLayer
135
+ from llmaps.sources import FileSource
136
+ from llmaps.components import Legend, Popup, Controls
137
+
138
+ source = FileSource(id="points", path="data/points.geojson")
139
+ layer = CircleLayer(
140
+ id="points-layer",
141
+ source=source,
142
+ radius=6,
143
+ color="#3182bd",
144
+ opacity=0.8,
145
+ )
146
+
147
+ m = Map(center=[10.0, 50.0], zoom=4, title="My Map", tiles="osm")
148
+ m.add_layer(layer)
149
+ m.add_component(Legend(layer_labels={"points-layer": "Points"}))
150
+ m.add_component(Popup(fields=["name", "value"], field_labels={"name": "Name", "value": "Value"}))
151
+ m.add_component(Controls(zoom=True, scale=True))
152
+
153
+ m.auto_extent()
154
+ m.save("my_map.html")
155
+ ```
156
+
157
+ ## Attribution
158
+
159
+ By default, all maps include a LLMaps attribution with a link to the GitHub repository:
160
+
161
+ ```python
162
+ # Default LLMaps attribution
163
+ m = Map(center=[10.0, 50.0], zoom=5)
164
+ # Result: "© OpenStreetMap contributors | © LLMaps"
165
+ ```
166
+
167
+ You can customize or disable the attribution:
168
+
169
+ ```python
170
+ # Custom attribution
171
+ m = Map(center=[10.0, 50.0], zoom=5, custom_attribution='© My Company')
172
+
173
+ # Disable custom attribution
174
+ m = Map(center=[10.0, 50.0], zoom=5, custom_attribution=None)
175
+ # Result: "© OpenStreetMap contributors"
176
+ ```
177
+
178
+ ## Examples
179
+
180
+ | Example | Description |
181
+ |---------|-------------|
182
+ | [01_quick_start.py](examples/01_quick_start.py) | Circle layer, legend, popup, controls; synthetic points. |
183
+ | [02_fill_layer.py](examples/02_fill_layer.py) | Fill layer (polygons). |
184
+ | [03_h3_heatmap.py](examples/03_h3_heatmap.py) | H3 hexagon heatmap, embedded mode, auto_extent. |
185
+ | [04_comparison.py](examples/04_comparison.py) | Before/after comparison with slider; embedded. |
186
+
187
+ Run an example:
188
+
189
+ ```bash
190
+ cd examples
191
+ python 01_quick_start.py
192
+ # Opens or writes 01_quick_start.html
193
+ ```
194
+
195
+ ## Built With
196
+
197
+ - [MapLibre GL JS](https://maplibre.org/) — frontend map rendering
198
+ - [Jinja2](https://jinja.palletsprojects.com/) — HTML template engine
199
+ - Optional: [H3](https://h3geo.org/), [GeoPandas](https://geopandas.org/), [Geobuf](https://github.com/pygeobuf/pygeobuf)
200
+
201
+ ## Comparison with Alternatives
202
+
203
+ | Criterion | Kepler.gl | Folium / ipyleaflet | Custom MapLibre/Leaflet | **LLMaps** |
204
+ |-----------|-----------|---------------------|--------------------------|------------|
205
+ | **Ready-made components** | Limited by UI | Few map primitives | None | Full set: layers, legend, popup, sidebar, search, controls |
206
+ | **LLM-friendly** | No | Partial (verbose) | Depends on custom code | Yes: keyword index, clear API, stable contracts |
207
+ | **H3 / aggregation** | Yes | No (manual) | Manual | Yes (H3Layer) |
208
+ | **Embedded (file://)** | No | Often needs server | Manual | Yes (`embedded=True`) |
209
+ | **Comparison (before/after)** | No | No | Manual | Yes (`enable_comparison`) |
210
+ | **Single HTML output** | No | Possible | Manual | Yes (`save` / `to_html`) |
211
+ | **Customization** | Limited by UI | Good | Full | Full (config + templates + custom JS/CSS) |
212
+ | **No backend** | No | Often | Possible | Yes (embedded mode) |
213
+
214
+ **When to use LLMaps:** You want a single Python API to produce a standalone interactive map (especially with embedded data), with minimal boilerplate and good support for LLM-generated code.
215
+
216
+ **When to choose something else:** You need a full GIS UI (Kepler.gl), tight Jupyter-only integration (Folium/ipyleaflet), or a fully custom frontend stack (raw MapLibre/Leaflet with your own backend).
217
+
218
+ ## Architecture
219
+
220
+ ```
221
+ Python API → Config (to_dict()) → HTML (Jinja2) → Frontend (MapLibre GL JS + plugins)
222
+ ```
223
+
224
+ Everything reduces to a serializable dict — no framework magic. The generator turns that config into one HTML file with inline or linked JS/CSS. See [PHILOSOPHY.md](PHILOSOPHY.md) for design principles and rationale.
225
+
226
+ ## Documentation
227
+
228
+ - **LLM context** — run `python -c "import llmaps; open('llmaps_context.md','w').write(llmaps.get_llm_context())"` and use @llmaps_context.md in chat for a compact API reference.
229
+ - **[PHILOSOPHY.md](PHILOSOPHY.md)** — Concept, design principles, comparison with alternatives.
230
+ - **[docs/api/](docs/api/)** — Map, layers, sources, components (parameters and examples).
231
+ - **[docs/recipes/](docs/recipes/)** — Heatmap, comparison, embedded map, feature-state highlighting.
232
+
233
+ ## Tile Providers
234
+
235
+ Use the `tiles` argument when creating the map:
236
+
237
+ | Key | Provider | Attribution |
238
+ |-----|----------|-------------|
239
+ | `"osm"` | OpenStreetMap (default) | © OpenStreetMap contributors |
240
+ | `"carto-light"` | Carto Light | © OpenStreetMap contributors, © CARTO |
241
+ | `"carto-dark"` | Carto Dark | © OpenStreetMap contributors, © CARTO |
242
+ | `"yandex"` | Yandex Maps | © Yandex Maps |
243
+ | `"2gis"` | 2GIS | © 2GIS |
244
+
245
+ ## License
246
+
247
+ MIT. See [LICENSE](LICENSE).
248
+
249
+ ## Contact
250
+
251
+ **Sergey Abramov**
252
+
253
+ [![Telegram](https://img.shields.io/badge/Telegram-@sergey__abr-2CA5E0?logo=telegram&logoColor=white)](https://t.me/sergey_abr)
254
+ [![Email](https://img.shields.io/badge/Email-sergey.abr71@gmail.com-D14836?logo=gmail&logoColor=white)](mailto:sergey.abr71@gmail.com)
255
+
256
+ ## Contributing
257
+
258
+ See [CONTRIBUTING.md](CONTRIBUTING.md).