milpa-sdk

Implementación Python de referencia candidata para una proyección versionada de MILPA. Aspira a leer manifests, validar perfiles sin mutar y ofrecer puntos de decisión para roles y dominios; no define la metodología ni convierte carpetas en una ontología.

Perfil Milpa: library (P5) · Distribución prevista: PyPI milpa-sdk · Estado: alpha parcial no publicable

Qué resuelve y para quién

Un conjunto de repositorios donde cada equipo —y cada agente de software que los lee— decide por su cuenta dónde van la documentación, las decisiones y los reportes es un campo sin letreros: para saber qué hay en cada parcela hay que recorrerla entera. milpa-sdk lee un letrero por repositorio (.milpa-manifest.json) y comprueba, sin tocar nada, si tiene las carpetas que su tipo declarado exige.

Es para quien mantiene varios repositorios —personas o agentes de software que actúan sobre ellos— y quiere una comprobación de estructura reproducible en vez de una convención escrita en prosa que nadie audita.

Analogía, con su origen. El nombre y la imagen se apoyan, de forma didáctica, en la milpa mesoamericana: un policultivo vivo, sostenido durante generaciones por las comunidades que lo cultivan, en el que distintas plantas comparten una misma parcela porque siguen un patrón conocido; la FAO lo reconoció en 2022 como Sistema Importante del Patrimonio Agrícola Mundial (FAO, s.f.; ver docs/referencias.md). La analogía es del curso que la propuso para explicar por qué conviene un patrón compartido, no una lista de roles: MILPA no es "tres roles de agentes", es estructura de proyecto, niveles de certeza, reglas negativas y responsabilidad. Los roles operativos de un sistema multiagente (coordinador, ejecutor, crítico, compuerta determinista, autoridad humana) son cinco y los define la taxonomía del ecosistema, no este SDK. Detalle completo en D05 — qué es MILPA y qué no.

TL;DR

• load_manifest ya lee JSON estricto, acotado y sin ejecutar contenido.
• validate_structure y milpa validate revisan un perfil sin modificar el repositorio.
• inherits sólo se conserva como dato: todavía no se resuelve ni amplía autoridad.
• roles, dominios, identidad y enforcement siguen bloqueados.
• Los perfiles son una proyección candidata hasta fijar revisión y digest del canon.
• Empieza por el manifiesto, los diagramas o el índice completo.

Documentación

Cuatro niveles, de lo general a lo particular, según el estándar documental de Horcón. Ruta de lectura: manifiesto (sin tecnicismos) → diagramas → operación → contratos; el mapa completo y la ruta por perfil están en docs/INDEX.md. El sitio se audita y construye con la CLI de Horcón desde la raíz de este repo:

../horcon/.venv/bin/python -m horcon audit-docs .   # frontmatter, navegación, enlaces
../horcon/.venv/bin/python -m horcon docs build .   # sitio en tmp/site/ (mkdocs --strict)
../horcon/.venv/bin/python -m horcon docs serve .   # servido en 127.0.0.1

Diseño objetivo

Si ASILO responde "¿está permitida esta acción?", Milpa responde "¿quién puede hacerla y dónde vive lo que produce?".

Un decorador no puede impedir que un backend ignore una decisión. El diseño debe separar PDP (decidir) de PEP (aplicar en filesystem, herramienta o almacenamiento) y probar ambos.

require_role (milpa.roles) y domain_boundary (milpa.domains) son importables por ruta de módulo, pero lanzan NotImplementedError en cuanto se llaman y no están en __all__ (src/milpa/__init__.py; fijado por tests/unit/test_api_publica.py): no forman parte de la API pública del paquete. El contrato símbolo por símbolo, con su estado y su prueba, está en docs/04-contratos/01-api-publica.md.

Preparación local

El paquete aún no está publicado. Para trabajar desde el clon:

python3 --version  # debe ser 3.11 o posterior
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
milpa validate .

API ejecutable

from milpa import load_manifest, validate_structure

manifest = load_manifest(".")
reporte = validate_structure(".", profile=manifest.profile)

if not reporte.ok:
    for falta in reporte.missing:
        print(f"falta: {falta}")

El reporte sólo considera obligatorias las rutas missing; unexpected es informativo. Los enlaces simbólicos no satisfacen una ruta obligatoria. Consulta qué no está implementado antes de usarlo en automatización.

Los seis perfiles actuales

El código contiene una transcripción manual del doc 21. El plan la reemplaza por una proyección generada con revisión y digest para evitar dos fuentes de verdad:

Todos comparten el mismo núcleo invariante; solo cambian las carpetas de dominio.

Relación prevista con asilo-core

Los paquetes deben permanecer independientes. Este ejemplo sólo ilustra una composición futura: roles, dominios, política y HITL siguen bloqueados; enforce_schema sí valida forma, pero no reemplaza esas capas:

@require_role("Contador")              # Milpa: ¿quién?
@guardrail(".asilo/axioms.yaml")       # ASILO: ¿está permitido?
@enforce_schema(ReporteFinanciero)     # ASILO: ¿tiene la forma correcta?
def generar_reporte(prompt: str): ...

Licencia

Apache-2.0 — texto completo en LICENSE.

La marca MILPA no se licencia con el código (sección 6 de Apache-2.0); ver NOTICE.

Enlaces

• Documentación completa (cuatro niveles): docs/INDEX.md
• Código fuente (Codeberg): https://codeberg.org/kasailabs/milpa-sdk
• Registro de cambios: CHANGELOG.md
• Incidencias: https://codeberg.org/kasailabs/milpa-sdk/issues

Estado de implementación

Ver docs/PLAN_IMPLEMENTACION.md. El slice manifest → perfil → reporte es ejecutable y de sólo lectura. No usar roles o dominios como control de acceso real, resolver inherits por cuenta propia ni ejecutar validaciones esperando que reparen un repositorio.