feat: add Python core and infra functions — PWA, geocoding, POI matching

Nuevas funciones Python: build_guide_prompt, generate_pwa_manifest, generate_service_worker, match_pois_to_interests (core), nominatim_reverse_geocode, ollama_chat, overpass_nearby_pois (infra). Incluye tests unitarios. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 23:47:19 +02:00
parent 01042bc23c
commit dede5e00af
19 changed files with 1568 additions and 0 deletions
@@ -0,0 +1,80 @@
+---
+name: overpass_nearby_pois
+kind: function
+lang: py
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "overpass_nearby_pois(lat: float, lon: float, radius_m: int = 500, categories: list[str] | None = None) -> list[dict]"
+description: "Consulta la Overpass API (OpenStreetMap) para obtener POIs cercanos a una coordenada. Soporta 16 categorias mapeadas a tags OSM (amenity, tourism, historic, leisure, shop). Sin dependencias externas, solo stdlib."
+tags: [osm, openstreetmap, overpass, poi, geolocation, nearby, geocoding, infra, http, stdlib]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: ["json", "urllib.error", "urllib.parse", "urllib.request"]
+params:
+  - name: lat
+    desc: "latitud del punto central de busqueda (grados decimales, -90 a 90)"
+  - name: lon
+    desc: "longitud del punto central de busqueda (grados decimales, -180 a 180)"
+  - name: radius_m
+    desc: "radio de busqueda en metros alrededor del punto central (defecto 500)"
+  - name: categories
+    desc: "lista de categorias a buscar entre: restaurant, cafe, bar, museum, monument, park, library, theatre, cinema, gallery, historic, tourism, shop, hotel, pharmacy, hospital. Si es None, usa todas las categorias comunes excepto hotel, pharmacy, hospital"
+output: "lista de dicts con campos id (int), lat (float), lon (float), name (str), category (str) y tags (dict con todos los tags OSM del nodo)"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/infra/overpass_nearby_pois.py"
+---
+
+## Ejemplo
+
+```python
+from infra.overpass_nearby_pois import overpass_nearby_pois
+
+# POIs en el centro de Madrid (radio 300m)
+pois = overpass_nearby_pois(40.4168, -3.7038, radius_m=300, categories=["museum", "monument"])
+# [{"id": 123, "lat": 40.417, "lon": -3.704, "name": "Museo del Prado", "category": "museum", "tags": {...}}, ...]
+
+# Todos los tipos comunes en radio 500m (defecto)
+all_pois = overpass_nearby_pois(48.8566, 2.3522)
+
+# Bares y restaurantes cerca de la Sagrada Familia
+food = overpass_nearby_pois(41.4036, 2.1744, radius_m=200, categories=["restaurant", "cafe", "bar"])
+```
+
+## Mapeo de categorias a tags OSM
+
+| Categoria   | Tag OSM              |
+|-------------|----------------------|
+| restaurant  | amenity=restaurant   |
+| cafe        | amenity=cafe         |
+| bar         | amenity=bar          |
+| museum      | tourism=museum       |
+| monument    | historic=monument    |
+| park        | leisure=park         |
+| library     | amenity=library      |
+| theatre     | amenity=theatre      |
+| cinema      | amenity=cinema       |
+| gallery     | tourism=gallery      |
+| historic    | historic=*           |
+| tourism     | tourism=*            |
+| shop        | shop=*               |
+| hotel       | tourism=hotel        |
+| pharmacy    | amenity=pharmacy     |
+| hospital    | amenity=hospital     |
+
+## Notas
+
+Solo usa stdlib (urllib.request, urllib.parse, json). Sin dependencias externas.
+
+La query Overpass QL usa union de nodos `(node[...]; node[...];)` con `out body` para obtener coordenadas y tags completos.
+
+El endpoint publico `https://overpass-api.de/api/interpreter` tiene rate limits informales — para uso intensivo considerar un servidor Overpass propio o la instancia de kumi.systems.
+
+El campo `category` refleja la primera coincidencia en el diccionario interno `_CATEGORY_TAGS`, que sigue el orden de insercion de Python 3.7+. Si un nodo tiene multiples tags relevantes (ej: un bar que tambien es restaurante), la categoria asignada sera la primera que matchee.
+
+Timeout hardcodeado a 10 segundos tanto en la directiva Overpass QL `[timeout:10]` como en `urlopen(timeout=10)`.