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,65 @@
+---
+name: nominatim_reverse_geocode
+kind: function
+lang: py
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "def nominatim_reverse_geocode(lat: float, lon: float, lang: str = 'es') -> dict"
+description: "Reverse geocoding usando Nominatim (OpenStreetMap). Convierte coordenadas lat/lon a una dirección estructurada con calle, ciudad, país y otros campos normalizados."
+tags: [geocoding, nominatim, openstreetmap, osm, reverse-geocoding, geo, location, address]
+params:
+  - name: lat
+    desc: "Latitud en grados decimales (rango -90 a 90)."
+  - name: lon
+    desc: "Longitud en grados decimales (rango -180 a 180)."
+  - name: lang
+    desc: "Código de idioma ISO 639-1 para la respuesta (ej: 'es', 'en', 'fr'). Por defecto 'es'."
+output: "Diccionario con campos normalizados: display_name (dirección completa legible), street (calle/road), house_number, neighbourhood, city (city→town→village), state, country, postcode, lat, lon, osm_type (node/way/relation), osm_id. Campos ausentes retornan string vacío."
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: ["urllib.request", "urllib.parse", "json"]
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/infra/nominatim_reverse_geocode.py"
+---
+
+## Ejemplo
+
+```python
+from infra.nominatim_reverse_geocode import nominatim_reverse_geocode
+
+addr = nominatim_reverse_geocode(40.4168, -3.7038)
+# {
+#   "display_name": "Puerta del Sol, Sol, Madrid, ...",
+#   "street": "Puerta del Sol",
+#   "house_number": "",
+#   "neighbourhood": "Sol",
+#   "city": "Madrid",
+#   "state": "Comunidad de Madrid",
+#   "country": "España",
+#   "postcode": "28013",
+#   "lat": 40.4168,
+#   "lon": -3.7038,
+#   "osm_type": "way",
+#   "osm_id": 12345678
+# }
+
+# Con idioma inglés
+addr_en = nominatim_reverse_geocode(48.8566, 2.3522, lang="en")
+# {"city": "Paris", "country": "France", ...}
+```
+
+## Notas
+
+- Usa `urllib.request` de stdlib — sin dependencias externas.
+- El header `User-Agent: fn_registry/1.0` es obligatorio según la política de uso de Nominatim.
+- Timeout de 5 segundos. Para coordenadas en zonas remotas puede necesitarse más.
+- Campo `city` se resuelve con fallback: `city → town → village → ""`.
+- `lat`/`lon` del resultado son los del objeto OSM encontrado, que puede diferir ligeramente de los de entrada.
+- Nominatim tiene límite de 1 request/segundo por IP. Para uso intensivo, considerar un servidor propio.
+- Lanza `RuntimeError` en errores HTTP o de red.