peruopen 0.1.0a1__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 (44) hide show
  1. peruopen-0.1.0a1/.claude/settings.json +6 -0
  2. peruopen-0.1.0a1/.github/workflows/ci.yml +24 -0
  3. peruopen-0.1.0a1/.github/workflows/etl.yml +53 -0
  4. peruopen-0.1.0a1/.github/workflows/publish.yml +53 -0
  5. peruopen-0.1.0a1/.github/workflows/spike_sources.yml +26 -0
  6. peruopen-0.1.0a1/.gitignore +24 -0
  7. peruopen-0.1.0a1/.python-version +1 -0
  8. peruopen-0.1.0a1/CLAUDE.md +78 -0
  9. peruopen-0.1.0a1/LICENSE +27 -0
  10. peruopen-0.1.0a1/PKG-INFO +126 -0
  11. peruopen-0.1.0a1/README.md +89 -0
  12. peruopen-0.1.0a1/data/registry/datasets.json +49 -0
  13. peruopen-0.1.0a1/docs/datasets/macro_series.md +55 -0
  14. peruopen-0.1.0a1/docs/datasets/macro_uit.md +41 -0
  15. peruopen-0.1.0a1/docs/fuentes.md +103 -0
  16. peruopen-0.1.0a1/docs/hosting.md +149 -0
  17. peruopen-0.1.0a1/docs/licencias-datos.md +22 -0
  18. peruopen-0.1.0a1/docs/roadmap.md +36 -0
  19. peruopen-0.1.0a1/pipelines/__init__.py +9 -0
  20. peruopen-0.1.0a1/pipelines/__main__.py +79 -0
  21. peruopen-0.1.0a1/pipelines/build.py +86 -0
  22. peruopen-0.1.0a1/pipelines/common.py +110 -0
  23. peruopen-0.1.0a1/pipelines/extractors/__init__.py +16 -0
  24. peruopen-0.1.0a1/pipelines/extractors/bcrp.py +123 -0
  25. peruopen-0.1.0a1/pipelines/extractors/uit.py +75 -0
  26. peruopen-0.1.0a1/pipelines/publish.py +227 -0
  27. peruopen-0.1.0a1/pipelines/registry.py +71 -0
  28. peruopen-0.1.0a1/pipelines/validation.py +99 -0
  29. peruopen-0.1.0a1/pyproject.toml +88 -0
  30. peruopen-0.1.0a1/spikes/probe_sources.py +238 -0
  31. peruopen-0.1.0a1/src/peruopen/__init__.py +109 -0
  32. peruopen-0.1.0a1/src/peruopen/config.py +59 -0
  33. peruopen-0.1.0a1/src/peruopen/data_manager.py +246 -0
  34. peruopen-0.1.0a1/src/peruopen/datasets/__init__.py +1 -0
  35. peruopen-0.1.0a1/src/peruopen/datasets/macro.py +97 -0
  36. peruopen-0.1.0a1/src/peruopen/engine.py +197 -0
  37. peruopen-0.1.0a1/src/peruopen/exceptions.py +30 -0
  38. peruopen-0.1.0a1/src/peruopen/mcp_server.py +72 -0
  39. peruopen-0.1.0a1/src/peruopen/py.typed +0 -0
  40. peruopen-0.1.0a1/tests/conftest.py +64 -0
  41. peruopen-0.1.0a1/tests/test_end_to_end.py +123 -0
  42. peruopen-0.1.0a1/tests/test_parsers.py +57 -0
  43. peruopen-0.1.0a1/tests/test_readonly.py +74 -0
  44. peruopen-0.1.0a1/tests/test_smoke.py +5 -0
@@ -0,0 +1,6 @@
1
+ {
2
+ "attribution": {
3
+ "commit": "",
4
+ "pr": ""
5
+ }
6
+ }
@@ -0,0 +1,24 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+
7
+ permissions:
8
+ contents: read
9
+
10
+ jobs:
11
+ test:
12
+ runs-on: ubuntu-latest
13
+ strategy:
14
+ matrix:
15
+ python-version: ["3.11", "3.13"]
16
+ steps:
17
+ - uses: actions/checkout@v7
18
+ - uses: actions/setup-python@v7
19
+ with:
20
+ python-version: ${{ matrix.python-version }}
21
+ - run: pip install -e ".[pipeline,mcp]" pytest ruff
22
+ - run: ruff check .
23
+ - run: ruff format --check .
24
+ - run: pytest -q
@@ -0,0 +1,53 @@
1
+ name: Cocina — publicar datos en R2
2
+
3
+ # Extrae las fuentes oficiales, valida, construye los Parquet y los publica en
4
+ # Cloudflare R2. Al inicio es solo manual. Cuando esté estable, se activa el
5
+ # cron (descomenta `schedule`).
6
+ on:
7
+ workflow_dispatch:
8
+ inputs:
9
+ only:
10
+ description: "Solo estos datasets, separados por espacios (vacío = todos)"
11
+ required: false
12
+ default: ""
13
+ # schedule:
14
+ # - cron: "0 8 * * 1" # lunes 03:00 hora de Lima (08:00 UTC)
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ concurrency:
20
+ group: etl
21
+ cancel-in-progress: false
22
+
23
+ jobs:
24
+ etl:
25
+ runs-on: ubuntu-latest
26
+ timeout-minutes: 60
27
+ steps:
28
+ - uses: actions/checkout@v7
29
+ - uses: actions/setup-python@v7
30
+ with:
31
+ python-version: "3.11"
32
+ - run: pip install -e ".[pipeline]"
33
+ - name: Cocinar (extraer + validar + Parquet)
34
+ run: |
35
+ if [ -n "${{ inputs.only }}" ]; then
36
+ python -m pipelines build --only ${{ inputs.only }} || true
37
+ else
38
+ python -m pipelines build || true
39
+ fi
40
+ # Un dataset fallido no bloquea a los demás: conserva su versión anterior.
41
+ python -c "import json;c=json.load(open('data/normalized/catalog.json'));print('Fallidos:',c['failed'] or 'ninguno')"
42
+ - name: Publicar en la vitrina (R2)
43
+ env:
44
+ R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
45
+ R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
46
+ R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
47
+ R2_BUCKET: ${{ vars.R2_BUCKET || 'peruopen-data' }}
48
+ run: python -m pipelines publish --target r2
49
+ - uses: actions/upload-artifact@v7
50
+ if: always()
51
+ with:
52
+ name: catalog
53
+ path: data/normalized/catalog.json
@@ -0,0 +1,53 @@
1
+ name: Publicar en PyPI
2
+
3
+ # Se dispara al subir un tag de versión (p. ej. v0.1.0a1). Usa Trusted
4
+ # Publishing (OIDC): no hay tokens de PyPI guardados en el repo.
5
+ #
6
+ # Configuración única en pypi.org → Account settings → Publishing → Add a new
7
+ # pending publisher: project "peruopen", owner "DDR2AS", repository "peruopen",
8
+ # workflow "publish.yml", environment "pypi".
9
+ on:
10
+ push:
11
+ tags: ["v*"]
12
+
13
+ permissions:
14
+ contents: read
15
+
16
+ jobs:
17
+ build:
18
+ runs-on: ubuntu-latest
19
+ steps:
20
+ - uses: actions/checkout@v7
21
+ - uses: actions/setup-python@v7
22
+ with:
23
+ python-version: "3.11"
24
+ - name: El tag debe coincidir con la versión de pyproject.toml
25
+ run: |
26
+ version=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
27
+ if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then
28
+ echo "El tag ${GITHUB_REF_NAME} no coincide con la versión ${version} de pyproject.toml" >&2
29
+ exit 1
30
+ fi
31
+ - run: pip install -e ".[pipeline,mcp]" pytest build twine
32
+ - run: pytest -q
33
+ - run: python -m build
34
+ - run: twine check --strict dist/*
35
+ - uses: actions/upload-artifact@v7
36
+ with:
37
+ name: dist
38
+ path: dist/
39
+
40
+ pypi:
41
+ needs: build
42
+ runs-on: ubuntu-latest
43
+ environment:
44
+ name: pypi
45
+ url: https://pypi.org/project/peruopen/
46
+ permissions:
47
+ id-token: write # necesario para Trusted Publishing
48
+ steps:
49
+ - uses: actions/download-artifact@v8
50
+ with:
51
+ name: dist
52
+ path: dist/
53
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,26 @@
1
+ name: Fase 0 — prueba de fuentes
2
+
3
+ # Corre spikes/probe_sources.py desde una IP de GitHub (EE.UU.) para detectar
4
+ # bloqueos por IP extranjera o por WAF. Solo manual.
5
+ on:
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ probe:
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - uses: actions/checkout@v7
16
+ - uses: actions/setup-python@v7
17
+ with:
18
+ python-version: "3.11"
19
+ - run: pip install "httpx>=0.27,<1"
20
+ - name: Probar fuentes
21
+ run: python spikes/probe_sources.py --json probe_result.json | tee -a "$GITHUB_STEP_SUMMARY"
22
+ - uses: actions/upload-artifact@v7
23
+ if: always()
24
+ with:
25
+ name: probe-result
26
+ path: probe_result.json
@@ -0,0 +1,24 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .venv/
6
+ dist/
7
+ build/
8
+ .pytest_cache/
9
+ .mypy_cache/
10
+ .ruff_cache/
11
+ .coverage
12
+
13
+ # Datos generados por el pipeline: se publican en R2, no se versionan en git.
14
+ # data/registry/ SÍ se versiona.
15
+ data/raw/
16
+ data/staging/
17
+ data/normalized/
18
+ data/vitrina/
19
+ spikes/out/
20
+
21
+ # Secretos y local
22
+ .env
23
+ CLAUDE.local.md
24
+ .claude/settings.local.json
@@ -0,0 +1 @@
1
+ 3.11
@@ -0,0 +1,78 @@
1
+ # CLAUDE.md — peruopen
2
+
3
+ > **peruopen**: librería Python que distribuye datasets públicos oficiales del
4
+ > Perú, curados, normalizados y validados, en Parquet. Se consultan con DuckDB
5
+ > y se exponen vía MCP. Pipeline: extract → build → validate → publish (R2) → catálogo.
6
+
7
+ Este archivo basta para retomar el proyecto en cualquier sesión. Empieza por
8
+ leer `docs/roadmap.md`, que tiene la fase actual y lo que sigue.
9
+
10
+ ## La regla principal: una fuente por sesión, de punta a punta
11
+
12
+ Nunca implementes dos fuentes nuevas en la misma sesión. Nunca dejes una fuente
13
+ a medias: cada una se termina completa (extractor + builder + validación +
14
+ registro + tests + doc en `docs/datasets/`) antes de empezar la siguiente.
15
+
16
+ ## Reglas duras
17
+
18
+ 1. **Cero scraping al ejecutar.** La librería pública (`src/peruopen/`) nunca
19
+ llama a portales del Estado. Solo lee los Parquet publicados (R2) o la caché
20
+ local.
21
+ 2. **Nunca fabricar datos.** Si una fuente falla, el extractor puede usar un
22
+ fallback mínimo para desarrollo, siempre marcado con `source_mode="fallback"`.
23
+ El release rechaza cualquier dataset que no esté en `source_mode="live"`.
24
+ 3. **Los códigos son strings de ancho fijo, nunca int:** `ubigeo` (6),
25
+ `ruc` (11), `ciiu`. Fuerza el tipo al leer el CSV, porque Polars, DuckDB y
26
+ Excel pierden el cero inicial sin avisar.
27
+ 4. **Fechas en ISO** (`date`/`YYYY-MM-DD`), y montos en `decimal` o `float64`
28
+ con la moneda documentada.
29
+ 5. **Encoding:** los portales `gob.pe` suelen servir `latin-1`/`cp1252`.
30
+ Detéctalo y decláralo en el extractor; nunca lo supongas.
31
+ 6. **Procedencia obligatoria.** Cada dataset lleva `source_name`, `source_url`
32
+ y `reuse_policy`. Nunca se quita el link a la fuente oficial.
33
+ 7. **`data/raw/` es write-once.** Un snapshot crudo no se edita después de
34
+ escrito.
35
+ 8. **La librería pública no importa del pipeline.** `src/peruopen/` nunca
36
+ importa de `pipelines/`, porque ahí están las dependencias pesadas detrás
37
+ del extra `[pipeline]`.
38
+ 9. **Verificar el endpoint antes de implementar una fuente,** con una petición
39
+ real (curl o httpx), no solo con búsqueda web. Algunos portales devuelven
40
+ 403 sin un User-Agent de navegador.
41
+ 10. **Código propio, escrito desde cero.** No se copia código de otros
42
+ proyectos. Si alguna vez hiciera falta incorporar código o datos de
43
+ terceros, solo con licencia permisiva explícita y con su aviso de
44
+ copyright. Si la licencia de los datos de una fuente es ambigua, se
45
+ publica solo la metadata y el link.
46
+ 11. **MCP de solo lectura.** Solo `SELECT`/`WITH`, validado con el parser de
47
+ DuckDB, con `enable_external_access=false` y `lock_configuration=true`
48
+ después de registrar las tablas, más un límite de filas y un timeout.
49
+
50
+ ## Mapa (objetivo)
51
+
52
+ ```
53
+ src/peruopen/ # librería pública (pip install peruopen), liviana
54
+ config.py # URLs de R2, caché (platformdirs), variables de entorno
55
+ data_manager.py # manifest + descarga por dataset, verificación SHA256
56
+ engine.py # DuckDB: registra vistas y ejecuta SQL seguro
57
+ datasets/ # helpers tipados por módulo (geo, macro, sunat, calendario)
58
+ mcp_server.py # FastMCP: list_datasets, describe_dataset, query
59
+ pipelines/ # ETL, solo en CI o local con el extra [pipeline]
60
+ extractors/ # uno por fuente: fetch + raw snapshot + ExtractionResult
61
+ builders/ # staging → Parquet final + catálogo
62
+ validation/ # reglas por dominio, funciones puras
63
+ registry/ # DatasetSpec
64
+ data/registry/datasets.json # fuente de verdad de los datasets, editada a mano
65
+ docs/ # roadmap, fuentes, hosting, licencias, datasets/{name}.md
66
+ spikes/ # Fase 0: scripts de prueba de fuentes (desechables)
67
+ ```
68
+
69
+ ## Stack
70
+
71
+ Python ≥3.11, uv, hatchling, ruff, pytest y mypy. Base: duckdb, pyarrow,
72
+ httpx y platformdirs. Extras: `pipeline` (polars, tenacity…) y `mcp` (fastmcp).
73
+ Hosting de datos: Cloudflare R2 (ver `docs/hosting.md`).
74
+
75
+ ## Referencias
76
+
77
+ Si existe `CLAUDE.local.md` (no versionado), léelo: puede apuntar a notas
78
+ de estudio locales. Sirven para aprender y validar, no para copiar.
@@ -0,0 +1,27 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Diego Avila
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
+
23
+ ---
24
+
25
+ Los DATOS distribuidos por peruopen (archivos Parquet publicados) NO están
26
+ cubiertos por esta licencia: cada dataset conserva la licencia de su fuente
27
+ oficial. Ver docs/licencias-datos.md y el campo `reuse_policy` del catálogo.
@@ -0,0 +1,126 @@
1
+ Metadata-Version: 2.5
2
+ Name: peruopen
3
+ Version: 0.1.0a1
4
+ Summary: Datos públicos oficiales del Perú (SUNAT, BCRP, INEI, MEF), curados en Parquet y consultables con DuckDB y MCP.
5
+ Project-URL: Homepage, https://github.com/DDR2AS/peruopen
6
+ Project-URL: Repository, https://github.com/DDR2AS/peruopen
7
+ Project-URL: Issues, https://github.com/DDR2AS/peruopen/issues
8
+ Project-URL: Documentation, https://github.com/DDR2AS/peruopen/tree/main/docs
9
+ Author: Diego Avila
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: bcrp,datos-abiertos,duckdb,mcp,open-data,parquet,peru,sunat,ubigeo
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Natural Language :: Spanish
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
23
+ Requires-Python: >=3.11
24
+ Requires-Dist: duckdb<2,>=1.1
25
+ Requires-Dist: httpx<1,>=0.27
26
+ Requires-Dist: platformdirs<5,>=4.3
27
+ Requires-Dist: pyarrow>=17
28
+ Provides-Extra: mcp
29
+ Requires-Dist: fastmcp<3,>=2.3; extra == 'mcp'
30
+ Provides-Extra: pandas
31
+ Requires-Dist: pandas<3,>=2.2; extra == 'pandas'
32
+ Provides-Extra: pipeline
33
+ Requires-Dist: boto3<2,>=1.34; extra == 'pipeline'
34
+ Provides-Extra: polars
35
+ Requires-Dist: polars<2,>=1.9; extra == 'polars'
36
+ Description-Content-Type: text/markdown
37
+
38
+ # peruopen
39
+
40
+ **Datos públicos oficiales del Perú, curados y versionados, listos para consultar
41
+ con una línea de Python o SQL, y sin scraping al ejecutar.**
42
+
43
+ > 🚧 **Estado: pre-alpha.** Ya funcionan el módulo `macro` (BCRP y UIT), la
44
+ > librería y el servidor MCP. Todavía no hay versión en PyPI ni vitrina pública.
45
+ > Ver [docs/roadmap.md](https://github.com/DDR2AS/peruopen/blob/main/docs/roadmap.md).
46
+
47
+ ## Qué es
48
+
49
+ peruopen reúne datasets públicos del Estado peruano (SUNAT, BCRP, INEI/RENIEC,
50
+ MEF, El Peruano) en archivos **Apache Parquet** normalizados y validados, con un
51
+ catálogo único. Se consultan con **DuckDB**, se exportan a Polars o Pandas, y se
52
+ exponen a agentes de IA (Claude, Cursor, etc.) mediante un servidor **MCP**.
53
+
54
+ La diferencia con un scraper: los portales del Estado cambian, se caen o bloquean
55
+ IPs. peruopen nunca consulta esos portales al ejecutarse. Un pipeline en CI genera
56
+ snapshots versionados y la librería solo lee esos snapshots, que quedan
57
+ cacheados en tu máquina.
58
+
59
+ ## Uso
60
+
61
+ ```python
62
+ import peruopen as po
63
+
64
+ po.list_datasets() # qué hay
65
+ po.macro.uit(2026) # -> 5500
66
+ po.macro.tipo_cambio(desde="2026-01-01").df() # pandas (o .pl() para polars)
67
+
68
+ po.query("""
69
+ SELECT year(fecha) AS anio, round(avg(valor), 3) AS tc_promedio
70
+ FROM macro_series WHERE serie = 'PD04638PD'
71
+ GROUP BY 1 ORDER BY 1
72
+ """).df()
73
+ ```
74
+
75
+ La primera vez se descarga solo lo que consultas y queda en caché. Después, la
76
+ librería revisa como máximo una vez al día si hay datos nuevos. No hay que hacer
77
+ nada para actualizar.
78
+
79
+ | Necesito… | Cómo |
80
+ |---|---|
81
+ | Forzar la revisión de datos nuevos | `po.update()` |
82
+ | Ver qué versión tengo | `po.status()` |
83
+ | Trabajar sin internet | `PERUOPEN_OFFLINE=1` |
84
+ | Resultados reproducibles | `po.connect(snapshot="2026-11-22")` |
85
+ | Borrar la caché | `po.clear_cache()` |
86
+
87
+ ### Para agentes de IA (MCP)
88
+
89
+ ```json
90
+ {"mcpServers": {"peruopen": {"command": "uvx", "args": ["--from", "peruopen[mcp]", "peruopen-mcp"]}}}
91
+ ```
92
+
93
+ Expone tres tools: `list_datasets`, `describe_dataset` y `query` (SQL de solo
94
+ lectura, sin acceso a otros archivos, con límite de filas y timeout).
95
+
96
+ ### Desarrollo: probar en local sin la nube
97
+
98
+ ```bash
99
+ pip install -e ".[pipeline,mcp]"
100
+ python -m pipelines run --target local --dir data/vitrina # cocina + vitrina local
101
+ PERUOPEN_BASE_URL="$PWD/data/vitrina" python -c "import peruopen as po; print(po.macro.uit())"
102
+ ```
103
+
104
+ ## Datasets planificados (v0.1)
105
+
106
+ | Módulo | Fuente | Contenido |
107
+ |---|---|---|
108
+ | `calendario` | El Peruano / gob.pe | Feriados y días no laborables, días hábiles 2020–2027 |
109
+ | `macro` ✅ | BCRP, SUNAT | Tipo de cambio, inflación, tasa de referencia, PBI, UIT |
110
+ | `geo` | INEI / RENIEC | Ubigeos con equivalencias, coordenadas y macrorregión |
111
+ | `sunat` | SUNAT | Padrón reducido RUC |
112
+
113
+ `estado` (MEF y SEACE/OECE) queda para v0.2.
114
+
115
+ ## Proyectos relacionados
116
+
117
+ - [perudata](https://github.com/cesarchavezp29/perudata): microdatos de encuestas
118
+ del INEI (ENAHO, ENDES…). Complementa a peruopen.
119
+ - [horaciochacon/peruopen](https://github.com/horaciochacon/peruopen): paquete
120
+ **R** con el mismo nombre que envuelve el portal CKAN de datosabiertos.gob.pe.
121
+ No tiene relación con este proyecto.
122
+
123
+ ## Licencia
124
+
125
+ El código es MIT (ver [LICENSE](https://github.com/DDR2AS/peruopen/blob/main/LICENSE)). Los **datos** conservan la licencia de
126
+ su fuente oficial.
@@ -0,0 +1,89 @@
1
+ # peruopen
2
+
3
+ **Datos públicos oficiales del Perú, curados y versionados, listos para consultar
4
+ con una línea de Python o SQL, y sin scraping al ejecutar.**
5
+
6
+ > 🚧 **Estado: pre-alpha.** Ya funcionan el módulo `macro` (BCRP y UIT), la
7
+ > librería y el servidor MCP. Todavía no hay versión en PyPI ni vitrina pública.
8
+ > Ver [docs/roadmap.md](https://github.com/DDR2AS/peruopen/blob/main/docs/roadmap.md).
9
+
10
+ ## Qué es
11
+
12
+ peruopen reúne datasets públicos del Estado peruano (SUNAT, BCRP, INEI/RENIEC,
13
+ MEF, El Peruano) en archivos **Apache Parquet** normalizados y validados, con un
14
+ catálogo único. Se consultan con **DuckDB**, se exportan a Polars o Pandas, y se
15
+ exponen a agentes de IA (Claude, Cursor, etc.) mediante un servidor **MCP**.
16
+
17
+ La diferencia con un scraper: los portales del Estado cambian, se caen o bloquean
18
+ IPs. peruopen nunca consulta esos portales al ejecutarse. Un pipeline en CI genera
19
+ snapshots versionados y la librería solo lee esos snapshots, que quedan
20
+ cacheados en tu máquina.
21
+
22
+ ## Uso
23
+
24
+ ```python
25
+ import peruopen as po
26
+
27
+ po.list_datasets() # qué hay
28
+ po.macro.uit(2026) # -> 5500
29
+ po.macro.tipo_cambio(desde="2026-01-01").df() # pandas (o .pl() para polars)
30
+
31
+ po.query("""
32
+ SELECT year(fecha) AS anio, round(avg(valor), 3) AS tc_promedio
33
+ FROM macro_series WHERE serie = 'PD04638PD'
34
+ GROUP BY 1 ORDER BY 1
35
+ """).df()
36
+ ```
37
+
38
+ La primera vez se descarga solo lo que consultas y queda en caché. Después, la
39
+ librería revisa como máximo una vez al día si hay datos nuevos. No hay que hacer
40
+ nada para actualizar.
41
+
42
+ | Necesito… | Cómo |
43
+ |---|---|
44
+ | Forzar la revisión de datos nuevos | `po.update()` |
45
+ | Ver qué versión tengo | `po.status()` |
46
+ | Trabajar sin internet | `PERUOPEN_OFFLINE=1` |
47
+ | Resultados reproducibles | `po.connect(snapshot="2026-11-22")` |
48
+ | Borrar la caché | `po.clear_cache()` |
49
+
50
+ ### Para agentes de IA (MCP)
51
+
52
+ ```json
53
+ {"mcpServers": {"peruopen": {"command": "uvx", "args": ["--from", "peruopen[mcp]", "peruopen-mcp"]}}}
54
+ ```
55
+
56
+ Expone tres tools: `list_datasets`, `describe_dataset` y `query` (SQL de solo
57
+ lectura, sin acceso a otros archivos, con límite de filas y timeout).
58
+
59
+ ### Desarrollo: probar en local sin la nube
60
+
61
+ ```bash
62
+ pip install -e ".[pipeline,mcp]"
63
+ python -m pipelines run --target local --dir data/vitrina # cocina + vitrina local
64
+ PERUOPEN_BASE_URL="$PWD/data/vitrina" python -c "import peruopen as po; print(po.macro.uit())"
65
+ ```
66
+
67
+ ## Datasets planificados (v0.1)
68
+
69
+ | Módulo | Fuente | Contenido |
70
+ |---|---|---|
71
+ | `calendario` | El Peruano / gob.pe | Feriados y días no laborables, días hábiles 2020–2027 |
72
+ | `macro` ✅ | BCRP, SUNAT | Tipo de cambio, inflación, tasa de referencia, PBI, UIT |
73
+ | `geo` | INEI / RENIEC | Ubigeos con equivalencias, coordenadas y macrorregión |
74
+ | `sunat` | SUNAT | Padrón reducido RUC |
75
+
76
+ `estado` (MEF y SEACE/OECE) queda para v0.2.
77
+
78
+ ## Proyectos relacionados
79
+
80
+ - [perudata](https://github.com/cesarchavezp29/perudata): microdatos de encuestas
81
+ del INEI (ENAHO, ENDES…). Complementa a peruopen.
82
+ - [horaciochacon/peruopen](https://github.com/horaciochacon/peruopen): paquete
83
+ **R** con el mismo nombre que envuelve el portal CKAN de datosabiertos.gob.pe.
84
+ No tiene relación con este proyecto.
85
+
86
+ ## Licencia
87
+
88
+ El código es MIT (ver [LICENSE](https://github.com/DDR2AS/peruopen/blob/main/LICENSE)). Los **datos** conservan la licencia de
89
+ su fuente oficial.
@@ -0,0 +1,49 @@
1
+ {
2
+ "macro_series": {
3
+ "description": "Series macroeconómicas oficiales del BCRP: tipo de cambio (interbancario y SBS), inflación (IPC Lima), tasa de referencia y PBI. Formato largo: una fila por serie y fecha.",
4
+ "module": "macro",
5
+ "extractor": "bcrp",
6
+ "source_name": "Banco Central de Reserva del Perú (BCRPData)",
7
+ "source_url": "https://estadisticas.bcrp.gob.pe/estadisticas/series/",
8
+ "update_frequency": "Diaria (tipo de cambio) y mensual (IPC, tasa de referencia, PBI)",
9
+ "primary_key": ["serie", "fecha"],
10
+ "min_records": 20000,
11
+ "columns": [
12
+ {"name": "serie", "type": "string", "description": "Código de la serie en BCRPData (p. ej. PD04638PD)"},
13
+ {"name": "nombre", "type": "string", "description": "Nombre legible de la serie"},
14
+ {"name": "frecuencia", "type": "string", "description": "'diaria' o 'mensual'"},
15
+ {"name": "unidad", "type": "string", "description": "Unidad del valor (S/ por US$, %, índice)"},
16
+ {"name": "fecha", "type": "date", "description": "Fecha del dato. En series mensuales es el primer día del mes"},
17
+ {"name": "valor", "type": "float64", "description": "Valor publicado. Los días sin dato ('n.d.') se omiten"}
18
+ ],
19
+ "reuse_policy": {
20
+ "status": "open-attribution",
21
+ "license": "Condiciones de uso de BCRPData: reproducción libre citando la fuente",
22
+ "license_url": "https://estadisticas.bcrp.gob.pe/estadisticas/series/ayuda/condiciones-de-uso",
23
+ "attribution_required": true,
24
+ "redistribution_ok": true
25
+ }
26
+ },
27
+ "macro_uit": {
28
+ "description": "Valor histórico de la Unidad Impositiva Tributaria (UIT) por año, con el Decreto Supremo que lo fija.",
29
+ "module": "macro",
30
+ "extractor": "uit",
31
+ "source_name": "SUNAT (valores fijados por Decreto Supremo del MEF)",
32
+ "source_url": "https://www.sunat.gob.pe/indicestasas/uit.html",
33
+ "update_frequency": "Anual (diciembre)",
34
+ "primary_key": ["anio"],
35
+ "min_records": 25,
36
+ "columns": [
37
+ {"name": "anio", "type": "int16", "description": "Año de vigencia"},
38
+ {"name": "valor", "type": "int32", "description": "Valor de la UIT en soles (S/)"},
39
+ {"name": "base_legal", "type": "string", "description": "Decreto Supremo que fija el valor (p. ej. D.S. N° 301-2025-EF)"}
40
+ ],
41
+ "reuse_policy": {
42
+ "status": "open-attribution",
43
+ "license": "Dato normativo público (Decreto Supremo)",
44
+ "license_url": "https://www.sunat.gob.pe/indicestasas/uit.html",
45
+ "attribution_required": true,
46
+ "redistribution_ok": true
47
+ }
48
+ }
49
+ }
@@ -0,0 +1,55 @@
1
+ # `macro_series`: series macroeconómicas del BCRP
2
+
3
+ **Fuente:** Banco Central de Reserva del Perú, API pública de BCRPData
4
+ (`https://estadisticas.bcrp.gob.pe/estadisticas/series/api/`).
5
+ **Licencia:** se puede reproducir citando la fuente (condiciones de uso de BCRPData).
6
+ **Actualización de la fuente:** diaria (tipo de cambio) y mensual (resto).
7
+ **Cobertura:** desde 2000-01-01.
8
+
9
+ Formato largo: una fila por serie y fecha. Clave primaria: `(serie, fecha)`.
10
+
11
+ | Columna | Tipo | Descripción |
12
+ |---|---|---|
13
+ | `serie` | string | Código BCRPData |
14
+ | `nombre` | string | Nombre legible |
15
+ | `frecuencia` | string | `diaria` o `mensual` |
16
+ | `unidad` | string | `S/ por US$`, `%` o `índice` |
17
+ | `fecha` | date | Fecha del dato. En series mensuales, el primer día del mes |
18
+ | `valor` | float64 | Valor publicado. Los días sin dato (`n.d.`) se omiten |
19
+
20
+ ## Series incluidas
21
+
22
+ | Código | Serie | Frecuencia |
23
+ |---|---|---|
24
+ | `PD04637PD` | Tipo de cambio interbancario, compra | diaria |
25
+ | `PD04638PD` | Tipo de cambio interbancario, venta | diaria |
26
+ | `PD04639PD` | Tipo de cambio bancario SBS, compra | diaria |
27
+ | `PD04640PD` | Tipo de cambio bancario SBS, venta | diaria |
28
+ | `PN01271PM` | IPC Lima Metropolitana, variación % mensual | mensual |
29
+ | `PN01273PM` | IPC Lima Metropolitana, variación % 12 meses | mensual |
30
+ | `PN38705PM` | IPC Lima Metropolitana, índice (dic.2021 = 100) | mensual |
31
+ | `PD04722MM` | Tasa de referencia de la política monetaria | mensual |
32
+ | `PN01770AM` | PBI, índice (2007 = 100) | mensual |
33
+ | `PN01728AM` | PBI, variación % interanual | mensual |
34
+
35
+ ## Validaciones antes de publicar
36
+
37
+ - Están las 10 series.
38
+ - El último dato no tiene más de 21 días (diarias) o 200 días (mensuales).
39
+ - El tipo de cambio está entre 1 y 10 soles por dólar.
40
+ - No hay claves `(serie, fecha)` duplicadas ni vacías.
41
+
42
+ ## Ejemplos
43
+
44
+ ```python
45
+ import peruopen as po
46
+
47
+ po.macro.tipo_cambio(desde="2026-01-01").df() # interbancario venta
48
+ po.macro.tipo_cambio(tipo="sbs", lado="compra").pl()
49
+ po.macro.inflacion(periodo="12_meses", desde="2025-01-01").df()
50
+ po.query("""
51
+ SELECT year(fecha) AS anio, avg(valor) AS tc_promedio
52
+ FROM macro_series WHERE serie = 'PD04638PD'
53
+ GROUP BY 1 ORDER BY 1
54
+ """).df()
55
+ ```
@@ -0,0 +1,41 @@
1
+ # `macro_uit`: Unidad Impositiva Tributaria
2
+
3
+ **Fuente:** tabla oficial de SUNAT (`https://www.sunat.gob.pe/indicestasas/uit.html`).
4
+ Cada valor lo fija un Decreto Supremo del MEF.
5
+ **Licencia:** dato normativo público. Se cita el D.S. correspondiente.
6
+ **Actualización:** anual (el D.S. sale en diciembre para el año siguiente).
7
+ **Cobertura:** 1994 en adelante.
8
+
9
+ Clave primaria: `anio`.
10
+
11
+ | Columna | Tipo | Descripción |
12
+ |---|---|---|
13
+ | `anio` | int16 | Año de vigencia |
14
+ | `valor` | int32 | Valor en soles (S/) |
15
+ | `base_legal` | string | Decreto Supremo, p. ej. `D.S. N° 301-2025-EF` |
16
+
17
+ ## Decisiones
18
+
19
+ - **Empieza en 1994.** En 1993 hubo valores por semestre fijados por R.M., y en
20
+ 1992 regía la URT, no la UIT.
21
+ - **1996 tuvo dos valores** (cambió en febrero). Se usa S/ 2,200 (D.S. N°
22
+ 012-96-EF), que estuvo vigente casi todo el año.
23
+ - La página de SUNAT mezcla encodings y formatos de número (`5,500` y
24
+ `3.100`). El extractor lee solo los dígitos.
25
+
26
+ ## Validaciones antes de publicar
27
+
28
+ - Años consecutivos, sin huecos.
29
+ - Está el año en curso.
30
+ - El valor nunca baja de un año al siguiente.
31
+ - Valores entre S/ 1,000 y S/ 100,000.
32
+
33
+ ## Ejemplos
34
+
35
+ ```python
36
+ import peruopen as po
37
+
38
+ po.macro.uit() # año actual -> 5500
39
+ po.macro.uit(2020) # -> 4300
40
+ po.macro.uit_historica().df()
41
+ ```