Metadata-Version: 2.5
Name: asilo-core
Version: 0.1.0a1
Summary: SDK de gobernanza para sistemas multi-agente: guardrails, validación de esquemas y Agente Cero
Project-URL: Homepage, https://codeberg.org/kasailabs/asilo-core
Project-URL: Documentation, https://codeberg.org/kasailabs/asilo-core/src/branch/main/docs/INDEX.md
Project-URL: Repository, https://codeberg.org/kasailabs/asilo-core
Project-URL: Changelog, https://codeberg.org/kasailabs/asilo-core/src/branch/main/CHANGELOG.md
Project-URL: Issues, https://codeberg.org/kasailabs/asilo-core/issues
Author: Kasai Labs
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,ai,governance,guardrails,llm,security
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: cli
Requires-Dist: jinja2>=3.1; extra == 'cli'
Requires-Dist: litellm>=1.40; extra == 'cli'
Requires-Dist: rich>=13.7; extra == 'cli'
Requires-Dist: typer>=0.12; extra == 'cli'
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

# asilo-core

> Implementación Python de referencia **candidata** para controles de sistemas multiagente.
> Aspira a traducir una revisión identificable de ASILO a contratos, decisiones de política,
> auditoría y revisión humana sin definir la metodología dentro del paquete.

**Perfil Milpa:** `library` (P5) · **Distribución prevista:** PyPI `asilo-core` · **Estado:** alpha parcial no publicable

## TL;DR

- `enforce_schema` ya valida resultados Pydantic sync/async y nunca reejecuta la función.
- `asilo status` y `asilo doctor` informan capacidades sin red ni secretos.
- `guardrail`, HITL, auditoría y comandos de dominio continúan bloqueados.
- El scaffolding operativo vive hoy en `kasai-crew scaffold`; no se duplica aquí.
- Empieza por [Quickstart](docs/QUICKSTART.md), [diagramas](docs/architecture/DIAGRAMS.md) e
  [índice](docs/INDEX.md).

---

## Documentación

Cuatro niveles, de lo general a lo particular, con ruta de lectura por perfil en
[`docs/INDEX.md`](docs/INDEX.md):

| Perfil | Empieza en |
|---|---|
| No técnico | [`docs/01-manifiesto/`](docs/01-manifiesto/README.md) — la aduana: el modelo propone, la librería valida la forma |
| Arquitecto | [`docs/02-diagramas/`](docs/02-diagramas/README.md) — contexto, capas, secuencia, escalada humana |
| Operador | [`docs/03-operacion/`](docs/03-operacion/README.md) — instalación, comandos, qué no está implementado |
| Auditor | [`docs/04-contratos/`](docs/04-contratos/README.md) — API, axiomas, errores, ADR, fuentes de verdad |

Sitio navegable (MkDocs Material, con el estándar documental de Horcón), desde la raíz del repo:

```bash
../horcon/.venv/bin/python -m horcon audit-docs .    # frontmatter, navegación, enlaces
../horcon/.venv/bin/python -m horcon docs build .    # ensambla tmp/site-src/ y construye tmp/site/
../horcon/.venv/bin/python -m horcon docs serve .    # sirve en 127.0.0.1
```

---

## Diseño objetivo

Un agente autónomo puede producir información falsa, filtrar datos o solicitar acciones
irreversibles. El diseño objetivo interpone controles entre el modelo y el mundo:

| Control | Mecanismo objetivo | Estado actual |
|---------|-------------------|---------------|
| **Esquema** | `@enforce_schema` valida forma contra Pydantic | implementado; una ejecución, sin repairs |
| **Política** | `@guardrail` obtiene una decisión antes de ejecutar | stub; contrato pendiente |
| **Revisión humana** | `@hitl` persiste, autoriza y reanuda una decisión | stub; protocolo pendiente |
| **Auditoría** | eventos minimizados y trazables | inexistente |

Un decorador dentro del mismo proceso no constituye por sí solo una frontera de seguridad:
código con el mismo privilegio puede evitarlo. El enforcement real depende también del
sistema consumidor, sus herramientas, credenciales y puntos de aplicación.

### Qué protege cada pieza, y qué no

| Pieza | Qué protege hoy | Qué NO protege |
|---|---|---|
| `enforce_schema` | La **forma** del resultado contra un modelo Pydantic; una sola ejecución, sin reintentos | Que el contenido sea verdadero, que esté autorizado, o que no lleve una instrucción escondida para el siguiente agente (ver [`docs/asilo/seguridad/aduana-llm.md`](docs/asilo/seguridad/aduana-llm.md)) |
| `guardrail`, `hitl` | Nada: son firmas con contrato escrito que lanzan `NotImplementedError` | Cualquier cosa que su nombre sugiera; llamarlos no bloquea ni pausa nada todavía |
| `asilo status` / `asilo doctor` | Informar, sin red, qué existe | Que lo informado sea "seguro"; son diagnóstico, no control |

Lo que debe poner quien consume esta librería: autenticación y autorización de quien invoca la
acción, credenciales de mínimo privilegio, límites de red y un punto de aplicación fuera del
proceso que pueda de verdad impedir la acción si el decorador falla o se evade.

Una lección concreta, tomada de un hallazgo real en el framework hermano Horcón y registrada en
[`reports/2026-09-22-mejoras-desde-horcon.md`](reports/2026-09-22-mejoras-desde-horcon.md): cuando
exista una revisión humana real (`hitl` dejará de ser un stub), su aprobación **no puede
representarse con un booleano autodeclarado** (`approved: true`) ni con un campo de texto que
rellene el propio código que pide la aprobación. Ese diseño ya falló una vez en un sistema
relacionado: un campo que declaraba quién firmaba se verificaba con la misma firma que lo emitía,
así que cualquiera podía declararse revisor humano. Una aprobación debe llevar una referencia
verificable a quien decide y una huella de qué se revisó exactamente, no la palabra del propio
proceso que la solicita. Esto no está implementado hoy; es una condición que cualquier contrato
futuro de `hitl` debe cumplir antes de aceptarse.

## Instalación

El paquete aún no está publicado. El siguiente comando documenta la distribución prevista,
no un paso que funcione hoy:

```bash
pip install asilo-core
```

## API ejecutable: validación de esquema

```python
from asilo.decorators import enforce_schema
from pydantic import BaseModel

class Reporte(BaseModel):
    titulo: str
    hallazgos: list[str]

@enforce_schema(Reporte)
def normalizar_reporte(payload: dict) -> Reporte:
    return payload
```

## CLI y Agente Cero

El diagnóstico es ejecutable y no llama red:

```bash
asilo status
asilo doctor --json
```

`asilo init`, `explain` y `run` permanecen reservados y salen con código 2, sin traceback.
Para preparar un repo, el recorrido vigente es `kasai-crew scaffold --repo RUTA`. Esto evita
dos implementaciones distintas del Agente 0.

## Estructura

Sigue el perfil `library` del doc 21 de Milpa: `src/` layout (el paquete no vive en la
raíz), `tests/` con suite adversarial obligatoria por tratarse de un proyecto con LLM,
y `docs/asilo/` con los artefactos de gobernanza del propio SDK.

## Estado de implementación

Alpha parcial. Los errores, la validación de esquema y el diagnóstico existen; política,
auditoría, HITL durable y enforcement externo no. Ver `docs/PLAN_IMPLEMENTACION.md` para
puertas y criterios de release. No usar este repo para proteger operaciones reales.

## Licencia

Apache-2.0 — texto completo en [`LICENSE`](LICENSE).

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