Metadata-Version: 2.5
Name: peruopen
Version: 0.1.0a2
Summary: Datos públicos oficiales del Perú (SUNAT, BCRP, INEI, MEF), curados en Parquet y consultables con DuckDB y MCP.
Project-URL: Homepage, https://github.com/DDR2AS/peruopen
Project-URL: Repository, https://github.com/DDR2AS/peruopen
Project-URL: Issues, https://github.com/DDR2AS/peruopen/issues
Project-URL: Documentation, https://github.com/DDR2AS/peruopen/tree/main/docs
Author: Diego Avila
License-Expression: MIT
License-File: LICENSE
Keywords: bcrp,datos-abiertos,duckdb,mcp,open-data,parquet,peru,sunat,ubigeo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: Spanish
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: duckdb<2,>=1.1
Requires-Dist: httpx<1,>=0.27
Requires-Dist: platformdirs<5,>=4.3
Requires-Dist: pyarrow>=17
Provides-Extra: mcp
Requires-Dist: fastmcp<3,>=2.3; extra == 'mcp'
Provides-Extra: pandas
Requires-Dist: pandas<3,>=2.2; extra == 'pandas'
Provides-Extra: pipeline
Requires-Dist: boto3<2,>=1.34; extra == 'pipeline'
Provides-Extra: polars
Requires-Dist: polars<2,>=1.9; extra == 'polars'
Description-Content-Type: text/markdown

# peruopen

**Datos públicos oficiales del Perú, curados y versionados, listos para consultar
con una línea de Python o SQL, y sin scraping al ejecutar.**

> 🚧 **Estado: pre-alpha.** Ya funcionan el módulo `macro` (BCRP y UIT), la
> librería y el servidor MCP. Todavía no hay versión en PyPI ni vitrina pública.
> Ver [docs/roadmap.md](https://github.com/DDR2AS/peruopen/blob/main/docs/roadmap.md).

## Qué es

peruopen reúne datasets públicos del Estado peruano (SUNAT, BCRP, INEI/RENIEC,
MEF, El Peruano) en archivos **Apache Parquet** normalizados y validados, con un
catálogo único. Se consultan con **DuckDB**, se exportan a Polars o Pandas, y se
exponen a agentes de IA (Claude, Cursor, etc.) mediante un servidor **MCP**.

La diferencia con un scraper: los portales del Estado cambian, se caen o bloquean
IPs. peruopen nunca consulta esos portales al ejecutarse. Un pipeline en CI genera
snapshots versionados y la librería solo lee esos snapshots, que quedan
cacheados en tu máquina.

## Uso

```bash
pip install peruopen
```

> 📘 **¿Primera vez?** Sigue la [guía paso a paso](https://github.com/DDR2AS/peruopen/blob/main/docs/guia/README.md):
> instalar, consultar los datos y conectar peruopen a Claude (MCP).

```python
import peruopen as pe

pe.list_datasets()  # qué hay
pe.macro.uit(2026)  # -> 5500
pe.macro.tipo_cambio(desde="2026-01-01").df()  # pandas (o .pl() para polars)

pe.query("""
    SELECT year(fecha) AS anio, round(avg(valor), 3) AS tc_promedio
    FROM macro_series WHERE serie = 'PD04638PD'
    GROUP BY 1 ORDER BY 1
""").df()
```

La primera vez se descarga solo lo que consultas y queda en caché. Después, la
librería revisa como máximo una vez al día si hay datos nuevos. No hay que hacer
nada para actualizar.

| Necesito… | Cómo |
|---|---|
| Forzar la revisión de datos nuevos | `pe.update()` |
| Ver qué versión tengo | `pe.status()` |
| Trabajar sin internet | `PERUOPEN_OFFLINE=1` |
| Resultados reproducibles | `pe.connect(snapshot="2026-11-22")` |
| Borrar la caché | `pe.clear_cache()` |

### Para agentes de IA (MCP)

```json
{"mcpServers": {"peruopen": {"command": "uvx", "args": ["--from", "peruopen[mcp]", "peruopen-mcp"]}}}
```

Expone tres tools: `list_datasets`, `describe_dataset` y `query` (SQL de solo
lectura, sin acceso a otros archivos, con límite de filas y timeout).

### Desarrollo: probar en local sin la nube

```bash
pip install -e ".[pipeline,mcp]"
python -m pipelines run --target local --dir data/vitrina   # cocina + vitrina local
PERUOPEN_BASE_URL="$PWD/data/vitrina" python -c "import peruopen as pe; print(pe.macro.uit())"
```

## Datasets planificados (v0.1)

| Módulo | Fuente | Contenido |
|---|---|---|
| `calendario` | El Peruano / gob.pe | Feriados y días no laborables, días hábiles 2020–2027 |
| `macro` ✅ | BCRP, SUNAT | Tipo de cambio, inflación, tasa de referencia, PBI, UIT |
| `geo` | INEI / RENIEC | Ubigeos con equivalencias, coordenadas y macrorregión |
| `sunat` | SUNAT | Padrón reducido RUC |

`estado` (MEF y SEACE/OECE) queda para v0.2.

## Proyectos relacionados

- [perudata](https://github.com/cesarchavezp29/perudata): microdatos de encuestas
  del INEI (ENAHO, ENDES…). Complementa a peruopen.
- [horaciochacon/peruopen](https://github.com/horaciochacon/peruopen): paquete
  **R** con el mismo nombre que envuelve el portal CKAN de datosabiertos.gob.pe.
  No tiene relación con este proyecto.

## Licencia

El código es MIT (ver [LICENSE](https://github.com/DDR2AS/peruopen/blob/main/LICENSE)). Los **datos** conservan la licencia de
su fuente oficial.
