{
  "markdown": "# emap/labs\n\n`INFRAESTRUCTURA DE INTELIGENCIA GEOGRÁFICA · EUSKADI → EUROPA`\n\n[![evals](https://github.com/r3tr0eth/emap-labs/actions/workflows/evals.yml/badge.svg)](https://github.com/r3tr0eth/emap-labs/actions/workflows/evals.yml)\n[![Licencia](https://img.shields.io/badge/c%C3%B3digo-Apache--2.0-blue)](LICENSE)\n[![Datos](https://img.shields.io/badge/datos-CC--BY--4.0%20%2F%20ODbL-green)](#licencias)\n[![Release](https://img.shields.io/github/v/tag/r3tr0eth/emap-labs?label=datasets)](releases/RELEASE-NOTES.md)\n[![DOI](https://zenodo.org/badge/1295202233.svg)](https://doi.org/10.5281/zenodo.21282784)\n\nLaboratorio de datos e IA detrás de [emap](https://emap-next.vercel.app):\ndatasets urbanos versionados, búsqueda semántica, RAG geoespacial y\nbenchmarks de retrieval en español y euskera. emap es el producto y el primer\nconsumidor de todo lo que sale de aquí.\n\n*EN: Open geographic-retrieval benchmark (Spanish/Basque) and versioned urban\nmobility datasets for the Basque Country. Reproducible in three commands.*\n\n[Benchmark](#benchmark-de-retrieval-eseu) ·\n[MCP](#emap-desde-tu-agente-mcp) ·\n[Reproducir](#reproducir-en-tres-comandos) ·\n[Datasets](#datasets) ·\n[Ética](#ética-y-limitaciones) ·\n[Citar](#cómo-citar)\n\n## Benchmark de retrieval ES/EU\n\nCorpus dorado actual de **162 casos** de búsqueda geográfica hiperlocal sobre\n**22 capas** (fuentes, aseos, parking, transporte, DEA, farmacias,\nbibliotecas, cimas…) en español y euskera: 85 development, **29 held-out\nsellados** y 48 challenge. Incluye 24 casos de abstención\n(`answerable: false` — el retriever que inventa, falla). El euskera se\ncoteja con **Itzuli**, el traductor neuronal del Gobierno Vasco — no es\neuskera artificial de traducción automática sin revisar.\n\nÚltima tabla histórica versionada (k=5, 2026-08-05; no reejecutada en el\nsprint 2026-08-27):\n\n| Retriever | dev ES | **held-out ES** | dev EU | **held-out EU** |\n|---|---|---|---|---|\n| baseline keywords+geo | 74% | 60% | 71% | 62% |\n| híbrido · MiniLM-L12 mult. | 76% | 58% | 71% | 63% |\n| **híbrido · multilingual-e5-large** | **76%** | **73%** | **71%** | **71%** |\n\ne5-large es el modelo desplegado en producción. La calibración es\nτ=0.80/tie=0.01 (propiedad del par modelo+corpus, no heredable).\n\nHallazgo central: **la brecha del euskera no era del idioma, era del modelo**.\nCon MiniLM la etapa semántica apenas aportaba en EU; con e5-large el\nheld-out ES sube de 58% a 73% (+15) y el EU de 63% a 71% (+8).\n\nSuite challenge post-calibración: 48 casos con nuevas capas y edge cases; es\ninformativa y no sustituye al held-out. Informe completo —metodología,\ncoste/latencia, limitaciones—:\n**[`BENCHMARK.md`](BENCHMARK.md)**; lecciones del harness:\n[`evals/README.md`](evals/README.md).\n\n## emap desde tu agente (MCP)\n\n**El primer servidor MCP de movilidad hiperlocal**: existen MCPs genéricos\nde GTFS y de OSM, pero ninguno expone inteligencia de movilidad local a\nagentes — búsqueda semántica bilingüe ES/EU, contexto de lugar, rutas\nmultimodales con infraestructura propia y *el monte en transporte público*.\nCinco herramientas ([`mcp/`](mcp/README.md)):\n\n| Tool | Pregunta que responde |\n|---|---|\n| `search_places` | \"dónde beber agua\" · \"haurra aldatzeko lekua\" (con abstención honesta) |\n| `nearby_pois` | el DEA / aseo / aparcabici / cima más cercana |\n| `explain_place` | qué barrio es esto y qué servicios tiene alrededor |\n| `plan_route` | ruta real transit/walk/bike/car (OSRM/OTP propios) |\n| `plan_hike` | qué cima hago hoy en transporte público (2.825 cimas × 9 redes) |\n\n```json\n{ \"mcpServers\": { \"emap\": {\n    \"command\": \"/ruta/a/emap-labs/.venv/bin/python\",\n    \"args\": [\"/ruta/a/emap-labs/mcp/server.py\"] } } }\n```\n\nRemoto (sin instalar nada), registro `io.github.r3tr0eth/emap`:\n\n```json\n{ \"mcpServers\": { \"emap\": { \"url\": \"https://vps.emapapp.com/mcp\" } } }\n```\n\nMigración de URL a dominio de producto (`emapapp.com`) en curso — detalle\nen [`mcp/README.md`](mcp/README.md). Smoke: `.venv/bin/python mcp/smoke.py\n--base https://vps.emapapp.com --live`.\n\nToda respuesta lleva `attribution` (ODbL + GTFS + CC-BY-4.0). Criterio de\naceptación cumplido y verificado por protocolo: *\"¿dónde dejo la bici cerca\nde San Mamés?\"* → aparcabicis a 47 m, con atribución.\n\n## Reproducir en tres comandos\n\n```bash\ngit clone https://github.com/r3tr0eth/emap-labs && cd emap-labs\npip install -r evals/requirements.txt\npython evals/run.py --retriever hybrid --profile minilm --lang eu\n```\n\nAutocontenido: el snapshot de datos vive en `evals/data/` (el mismo que usa\nel [CI](https://github.com/r3tr0eth/emap-labs/actions/workflows/evals.yml),\ncon gates de regresión **development** en cada push). Held-out solo se ejecuta\nmanualmente para una decisión final; no aparece en cada iteración. Cada JSON\nversiona territorio, perfil, modelo, τ y tie-window. Los perfiles canónicos\nviven en `evals/retriever-config.json`.\n\n## Datasets\n\nPrerelease **v0.3.0-rc.1** (2026-08-29): valida el mismo registro territorial\ny pipeline de retrieval sobre Euskadi y un primer pack oficial de Madrid.\nEl activo descargable incluye 8 datasets / 17.241 registros; Madrid aporta\n2.306 fuentes municipales verificables. El corpus completo de Euskadi conserva\n22 capas de movilidad e infraestructura — fuentes, aseos, parking, aparcabicis,\ncarga eléctrica, desfibriladores, playas, farmacias, bibliotecas, deporte,\nrestaurantes, alojamiento, camping, espacios naturales, cimas, bancos,\npapeleras, reciclaje, refugios, buzones, teléfonos y paradas multi-red\n(metro, Euskotren, Cercanías, Bilbobus, Bizkaibus). Cobertura expandida\na toda Bizkaia. Detalle y metadatos: [`releases/RELEASE-NOTES.md`](releases/RELEASE-NOTES.md).\nCada dataset declara fuente, licencia, fecha y cobertura estimada solo cuando\nes honestamente estimable. Pipelines reproducibles en [`datasets/`](datasets/README.md).\n\n## Estructura\n\n```\nevals/      corpus dorado ES/EU, harness, resultados versionados\ndatasets/   pipelines de datasets propios (places, barrios, scores)\nservice/    servicio semántico (FastAPI + fastembed, corre en VPS propio)\nregions/    packs y registro territorial de runtime\nmcp/        adapter para agentes sobre API + Labs\nreleases/   releases versionadas de datasets\ndocs/       Intelligence/Core, roadmap, ética e informes de cobertura\n```\n\n## Principios\n\n- `DATOS ANTES QUE MODELOS` — no se entrena ni fine-tunea nada en este horizonte.\n- `NO SE FINGE` — lo que no se puede medir se omite; los evals premian decir \"no lo sé\".\n- `DOGFOODING` — nada cuenta como hecho hasta que emap lo usa en producción.\n- `ES/EU EN PARIDAD` — el euskera se escribe, no se traduce.\n\nRegla de decisión: cada desarrollo debe mejorar emap, ser reutilizable,\npublicable como open source o vendible. Si no cumple ninguna, no se hace.\n\n## Ética y limitaciones\n\n[`docs/ETICA-DATOS.md`](docs/ETICA-DATOS.md) es regla dura, no aspiración:\n**se describe la infraestructura, jamás a las personas**. Limitaciones\ndeclaradas: sesgo de mapeo OSM (Bilbao mejor cubierto que la periferia — se\ndeclara en `coverage.notes` de cada dataset), corpus sintético escrito por\nuna persona (las consultas reales anonimizadas lo sustituirán), y umbrales\ncalibrados solo sobre dev — por eso el held-out manda.\n\n## Cómo citar\n\nSi usas el benchmark, el corpus o los datasets, cita el repositorio\n(GitHub: *Cite this repository*, desde [`CITATION.cff`](CITATION.cff)):\n\n```bibtex\n@software{emaplabs2026,\n  author  = {Jiménez, Gaizka},\n  title   = {EMAP Labs: verifiable geographic retrieval benchmark and\n             territorial mobility datasets for Euskadi and Madrid},\n  year    = {2026},\n  doi     = {10.5281/zenodo.21282784},\n  url     = {https://github.com/r3tr0eth/emap-labs},\n  version = {0.3.0-rc.1}\n}\n```\n\n## Agradecimientos\n\nDatos de [OpenStreetMap](https://www.openstreetmap.org/copyright) y\n[Open Data Euskadi](https://opendata.euskadi.eus). Euskera del corpus\ncotejado con [Itzuli](https://www.euskadi.eus/itzuli/) (Gobierno Vasco).\nEmbeddings servidos con [fastembed](https://github.com/qdrant/fastembed).\n\n## Licencias\n\n- **Código**: [Apache-2.0](LICENSE).\n- **Corpus de evaluación propio** (`evals/*.yaml`, docs): [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/deed.es) — atribución \"EMAP Labs\".\n- **Datos derivados**: lo derivado de [OpenStreetMap](https://www.openstreetmap.org/copyright) mantiene **ODbL**; lo derivado de [Open Data Euskadi](https://opendata.euskadi.eus) mantiene **CC-BY-4.0** con atribución al portal. Cada dataset declara su fuente y licencia en sus metadatos.\n",
  "bytes": 8477,
  "sha": "4e0a8e5e2767d8acd0f760a70f010798d22f13fb92ae889a39f32f985170f92f",
  "repo_slug": "r3tr0eth/emap-labs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_r3tr0eth_emap_499bd83e/readme"
}