Metadata-Version: 2.5
Name: milpa-sdk
Version: 0.1.0a1
Summary: SDK del ecosistema Milpa: manifests, perfiles de estructura, roles y fronteras de dominio
Project-URL: Homepage, https://codeberg.org/kasailabs/milpa-sdk
Project-URL: Repository, https://codeberg.org/kasailabs/milpa-sdk
Project-URL: Issues, https://codeberg.org/kasailabs/milpa-sdk/issues
Project-URL: Changelog, https://codeberg.org/kasailabs/milpa-sdk/src/branch/main/CHANGELOG.md
Author: Kasai Labs
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,ecosystem,governance,monorepo,project-structure
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# 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`](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](docs/02-diagramas/D05-que-es-milpa-y-que-no.md).

## 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](docs/01-manifiesto/README.md), los
  [diagramas](docs/02-diagramas/README.md) o el [índice](docs/INDEX.md) completo.

---

## Documentación

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

```bash
../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?"*.

| Capacidad | Objetivo | Estado actual |
|-----------|----------|---------------|
| **Manifests** | cargar y validar; herencia separada | loader estricto ejecutable; herencia pendiente |
| **Perfiles** | validar estructura en sólo lectura | catálogo y validación ejecutables |
| **Roles** | decidir con identidad confiable | stub; identidad/auditoría pendientes |
| **Dominios** | autorizar y delegar enforcement a un adapter | stub; no impone RLS por sí solo |

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`](docs/04-contratos/01-api-publica.md).

## Preparación local

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

```bash
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

```python
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](docs/03-operacion/03-que-no-esta-implementado.md) 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:

| Perfil | Para qué |
|--------|----------|
| `node` | Nodo organizativo puro: verticales, capas, agrupadores |
| `product-dossier` | Producto en planeación (marca, tesis, features, MVP, roadmap) |
| `software-single` | Repo de implementación con un solo deployable |
| `software-monorepo` | Varios deployables que comparten librerías internas |
| `research` | Proyecto cuyo entregable es conocimiento verificable |
| `library` | Paquete publicable a un registro |

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:

```python
@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`](LICENSE).

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

## Enlaces

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

## Estado de implementación

Ver [`docs/PLAN_IMPLEMENTACION.md`](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.
