plot-finder 0.1.0__tar.gz

plot_finder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ernest Ilchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plot_finder-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: plot-finder
+Version: 0.1.0
+Summary: Query Polish ULDK (GUGiK) API to find land parcels by TERYT ID or coordinates
+Author: Ernest Ilchenko
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ernestilchenko/plot-finder
+Keywords: uldk,gugik,parcel,plot,geodesy,poland,teryt
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.24
+Requires-Dist: shapely>=2.0
+Requires-Dist: pyproj>=3.6
+Requires-Dist: astral>=3.2
+Provides-Extra: viz
+Requires-Dist: folium>=0.14; extra == "viz"
+Requires-Dist: Pillow>=9.0; extra == "viz"
+Provides-Extra: ai
+Requires-Dist: openai>=1.0; extra == "ai"
+Dynamic: license-file
+
+# plot-finder
+
+![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-green)
+![Pydantic](https://img.shields.io/badge/Pydantic-v2-E92063?logo=pydantic&logoColor=white)
+![OpenStreetMap](https://img.shields.io/badge/OpenStreetMap-7EBC6F?logo=openstreetmap&logoColor=white)
+![OSRM](https://img.shields.io/badge/OSRM-Routing-blue)
+![OpenWeather](https://img.shields.io/badge/OpenWeather-API-orange?logo=openweathermap&logoColor=white)
+![Open-Meteo](https://img.shields.io/badge/Open--Meteo-Climate-1a73e8)
+
+> Python library to find Polish land parcels and analyze their surroundings.
+
+Query the [ULDK (GUGiK)](https://uldk.gugik.gov.pl/) API to get parcel data by TERYT ID or coordinates, then analyze nearby infrastructure using OpenStreetMap.
+
+![Plot with geometry, radius and nearby places](assets/showcase.png)
+
+## Installation
+
+```bash
+pip install plot-finder           # base
+pip install plot-finder[viz]      # + interactive maps & PNG export
+pip install plot-finder[ai]       # + AI-powered analysis (OpenAI)
+```
+
+**Requirements:** Python 3.10+ | `pydantic` `httpx` `shapely` `pyproj`
+
+## Quick Start
+
+```python
+from plot_finder import Plot, PlotAnalyzer, PlotReporter
+
+# Find a parcel
+plot = Plot(plot_id="141201_1.0001.6509")
+print(plot.voivodeship)  # mazowieckie
+print(plot.centroid)     # (x, y)
+
+# Analyze surroundings
+analyzer = PlotAnalyzer(plot, radius=3000)
+
+for place in analyzer.education():
+    print(f"{place.name} — {place.distance_m}m, walk {place.walk_min}min")
+
+# Full report
+report = PlotReporter(analyzer).report()
+report.model_dump_json()
+
+# Visualization (pip install plot-finder[viz])
+from plot_finder.visualizer import PlotVisualizer
+viz = PlotVisualizer(report)
+viz.save("map.html")  # interactive map
+viz.save("map.png")   # static image
+```
+
+## Documentation
+
+| Page | Description |
+|------|-------------|
+| [Plot](docs/plot.md) | Finding parcels by TERYT ID or coordinates |
+| [PlotAnalyzer](docs/analyzer.md) | Analyzing surroundings (education, shops, transport, etc.) |
+| [Climate](docs/climate.md) | Temperature, precipitation, wind, frost/hot days (Open-Meteo) |
+| [Air Quality](docs/air.md) | Air pollution data (OpenWeatherMap API) |
+| [Sunlight](docs/sun.md) | Sunrise, sunset, daylight hours |
+| [Place](docs/place.md) | Result model with travel times |
+| [Report](docs/report.md) | Full structured report (PlotReporter) |
+| [Visualizer](docs/visualizer.md) | Interactive HTML maps & static PNG images |
+| [AI](docs/ai.md) | AI-powered plot analysis (OpenAI) |
+| [API Reference](docs/api.md) | Full API reference |
+| [Errors](docs/errors.md) | Exception handling and hierarchy |
+
+## License
+
+MIT — use it however you want.

plot_finder-0.1.0/README.md

@@ -0,0 +1,72 @@
+# plot-finder
+
+![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-green)
+![Pydantic](https://img.shields.io/badge/Pydantic-v2-E92063?logo=pydantic&logoColor=white)
+![OpenStreetMap](https://img.shields.io/badge/OpenStreetMap-7EBC6F?logo=openstreetmap&logoColor=white)
+![OSRM](https://img.shields.io/badge/OSRM-Routing-blue)
+![OpenWeather](https://img.shields.io/badge/OpenWeather-API-orange?logo=openweathermap&logoColor=white)
+![Open-Meteo](https://img.shields.io/badge/Open--Meteo-Climate-1a73e8)
+
+> Python library to find Polish land parcels and analyze their surroundings.
+
+Query the [ULDK (GUGiK)](https://uldk.gugik.gov.pl/) API to get parcel data by TERYT ID or coordinates, then analyze nearby infrastructure using OpenStreetMap.
+
+![Plot with geometry, radius and nearby places](assets/showcase.png)
+
+## Installation
+
+```bash
+pip install plot-finder           # base
+pip install plot-finder[viz]      # + interactive maps & PNG export
+pip install plot-finder[ai]       # + AI-powered analysis (OpenAI)
+```
+
+**Requirements:** Python 3.10+ | `pydantic` `httpx` `shapely` `pyproj`
+
+## Quick Start
+
+```python
+from plot_finder import Plot, PlotAnalyzer, PlotReporter
+
+# Find a parcel
+plot = Plot(plot_id="141201_1.0001.6509")
+print(plot.voivodeship)  # mazowieckie
+print(plot.centroid)     # (x, y)
+
+# Analyze surroundings
+analyzer = PlotAnalyzer(plot, radius=3000)
+
+for place in analyzer.education():
+    print(f"{place.name} — {place.distance_m}m, walk {place.walk_min}min")
+
+# Full report
+report = PlotReporter(analyzer).report()
+report.model_dump_json()
+
+# Visualization (pip install plot-finder[viz])
+from plot_finder.visualizer import PlotVisualizer
+viz = PlotVisualizer(report)
+viz.save("map.html")  # interactive map
+viz.save("map.png")   # static image
+```
+
+## Documentation
+
+| Page | Description |
+|------|-------------|
+| [Plot](docs/plot.md) | Finding parcels by TERYT ID or coordinates |
+| [PlotAnalyzer](docs/analyzer.md) | Analyzing surroundings (education, shops, transport, etc.) |
+| [Climate](docs/climate.md) | Temperature, precipitation, wind, frost/hot days (Open-Meteo) |
+| [Air Quality](docs/air.md) | Air pollution data (OpenWeatherMap API) |
+| [Sunlight](docs/sun.md) | Sunrise, sunset, daylight hours |
+| [Place](docs/place.md) | Result model with travel times |
+| [Report](docs/report.md) | Full structured report (PlotReporter) |
+| [Visualizer](docs/visualizer.md) | Interactive HTML maps & static PNG images |
+| [AI](docs/ai.md) | AI-powered plot analysis (OpenAI) |
+| [API Reference](docs/api.md) | Full API reference |
+| [Errors](docs/errors.md) | Exception handling and hierarchy |
+
+## License
+
+MIT — use it however you want.

plot_finder-0.1.0/plot_finder/__init__.py

@@ -0,0 +1,42 @@
+from plot_finder.air import AirQuality
+from plot_finder.analyzer import PlotAnalyzer
+from plot_finder.climate import Climate
+from plot_finder.place import Place
+from plot_finder.report import PlotReport, PlotReporter
+from plot_finder.sun import SunInfo
+from plot_finder.exceptions import (
+    NothingFoundError,
+    OpenMeteoError,
+    OSRMError,
+    OSRMTimeoutError,
+    OpenWeatherAuthError,
+    OpenWeatherError,
+    OverpassError,
+    OverpassRateLimitError,
+    OverpassTimeoutError,
+    PlotNotFoundError,
+    ULDKError,
+)
+from plot_finder.plot import Plot
+
+__all__ = [
+    "AirQuality",
+    "Climate",
+    "SunInfo",
+    "NothingFoundError",
+    "OpenMeteoError",
+    "OpenWeatherAuthError",
+    "OpenWeatherError",
+    "Place",
+    "Plot",
+    "PlotAnalyzer",
+    "PlotReport",
+    "PlotReporter",
+    "OSRMError",
+    "OSRMTimeoutError",
+    "OverpassError",
+    "OverpassRateLimitError",
+    "OverpassTimeoutError",
+    "PlotNotFoundError",
+    "ULDKError",
+]

plot_finder-0.1.0/plot_finder/ai.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+try:
+    import openai
+except ImportError:
+    openai = None  # type: ignore[assignment]
+
+if TYPE_CHECKING:
+    from plot_finder.report import PlotReport
+
+
+class PlotAI:
+    """AI-powered plot analysis using OpenAI.
+
+    Parameters
+    ----------
+    report : PlotReport
+        The report to analyze.
+    api_key : str
+        OpenAI API key.
+    model : str
+        OpenAI model to use.
+    """
+
+    def __init__(
+        self,
+        report: PlotReport,
+        *,
+        api_key: str,
+        model: str = "gpt-4o-mini",
+    ) -> None:
+        if openai is None:
+            raise ImportError(
+                "openai is required for AI analysis. "
+                "Install it with: pip install plot-finder[ai]"
+            )
+        self._context = report.model_dump_json()
+        self._api_key = api_key
+        self._model = model
+
+    def _chat(self, system: str, user: str) -> str:
+        client = openai.OpenAI(api_key=self._api_key)
+        response = client.chat.completions.create(
+            model=self._model,
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+        )
+        return response.choices[0].message.content
+
+    def summary(self) -> str:
+        """Natural language summary of the plot and surroundings."""
+        return self._chat(
+            "You are a real-estate analyst. Summarize the plot data below in "
+            "clear, concise natural language. Mention location, nearby "
+            "infrastructure, transport, nature, air quality, and sunlight.",
+            self._context,
+        )
+
+    def rate(self, purpose: str = "living") -> str:
+        """Rate the plot 1-10 for a given purpose with explanation."""
+        return self._chat(
+            "You are a real-estate analyst. Rate the plot 1-10 for the "
+            f"purpose of **{purpose}**. Provide the rating and a short "
+            "explanation covering pros and cons.",
+            self._context,
+        )
+
+    def advantages(self) -> str:
+        """Key advantages of this location."""
+        return self._chat(
+            "You are a real-estate analyst. List the key advantages of "
+            "this location based on the data. Be specific and concise.",
+            self._context,
+        )
+
+    def disadvantages(self) -> str:
+        """Key disadvantages and risks of this location."""
+        return self._chat(
+            "You are a real-estate analyst. List the key disadvantages and "
+            "risks of this location based on the data. Be specific and concise.",
+            self._context,
+        )
+
+    def ask(self, question: str) -> str:
+        """Freeform Q&A about the plot."""
+        return self._chat(
+            "You are a real-estate analyst. Answer the user's question "
+            "about the plot based on the data below.\n\n" + self._context,
+            question,
+        )

plot_finder-0.1.0/plot_finder/air.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel
+
+
+class AirQuality(BaseModel):
+    aqi: int
+    aqi_label: str
+    co: float
+    no: float
+    no2: float
+    o3: float
+    so2: float
+    pm2_5: float
+    pm10: float
+    nh3: float