Referencia — sei.yaml

🟡 Parcial — El esquema es v1alpha1: el conjunto de campos descrito aquí está implementado, pero la versión del esquema aún evoluciona con el motor (puede cambiar sin aviso entre versiones).

sei.yaml es el manifiesto del sistema de IA que el motor lee al inicio de cada subcomando. Es el único fichero declarativo: cada repositorio contiene exactamente un sei.yaml en su raíz y gobierna un solo sistema. Declara la finalidad del sistema, la tarea, el marco regulatorio, el pipeline de evaluación y el programa de riesgos (Art. 9) en línea, en la sección risk.

sei init genera un sei.yaml mínimo si no existe. El campo oscal.assessment_plan se puebla mediante sei compile.

Firma de la evidencia

La evidencia que el motor deriva de este manifiesto (.sei/bundle.json y demás artefactos) se firma con ECDSA-P256 (RFC 6979) + DSSE + in-toto, mediante un firmante enchufable (local o Scaleway KMS, según SEI_SIGNING_BACKEND). Ver Firmar y verificar evidencia.

---

Manifiesto de ejemplo — un sistema de crédito

El siguiente manifiesto es un ejemplo ilustrativo de un sistema de crédito al consumo (alto riesgo, EU AI Act Anexo III §5), pensado para enseñar la estructura de un sei.yaml. Los valores son orientativos; adáptalos a tu sistema:

sei.yaml — sistema de crédito (tabular / clasificación)

apiVersion: seigarrena.dev/v1alpha1
kind: AISystem

# 1. Identidad y finalidad del sistema
system:
  name: loan-scoring
  intended_purpose: "Scoring crediticio para aprobacion de prestamos al consumo."
  organization: acme-bank
  version: "1.0.0"
  decisions: [loan_approval, loan_denial]
  affected_persons: [solicitantes]
  component_type: ai-model
  # Mal uso razonablemente previsible (ISO 42001 6.1.4 / EU AI Act Art.9(2)(b));
  # `addressed_by` enlaza cada uno con el/los riesgo(s) que lo atienden.
  potential_misuses:
    - id: mu.proxy-discrimination
      description: "Introducir variables proxy de atributos protegidos para sortear los controles de equidad."
      addressed_by: [risk.unfair-credit-exclusion, risk.data-governance]

# 2. Naturaleza de la tarea
task:
  modality: tabular
  type: classification

# 3. Marco regulatorio
context:
  applicable_standards:
    - eu/pren-18228@2026
    - iso/23894@2023
    - eu/ai-act@2024
    - eu/dora@2022

# 4. Datos y modelo
dataset: { croissant: data/german_credit.croissant.json }   # el eval carga el dataset vía Croissant
artifacts:
  model: { kind: logreg, seed: 42 }

# 5. Medición y reproducción
eval: { script: train.py }   # el QUÉ: el TRATAMIENTO (variante de entrenamiento; su digest → deriva modelo)
pipeline: { tool: dvc, metrics: metrics.json }   # el CÓMO: recómputo reproducible (dvc repro → dvc.lock)
oscal: { assessment_plan: shared_data/policies/assessment_plan.oscal.yaml }   # generado por sei compile

# 6. Programa de riesgos (Art.9) — antes en un fichero aparte; ahora en línea
risk:
  appetite: { individual: MEDIUM, society: MEDIUM, organization: HIGH }   # inherente HIGH excede MEDIUM → requiere tratamiento (6.4.4)
  criteria: { scale: "5x5" }
  overall_residual_criterion: HIGH   # prEN 18228 cl. 10: criterio del residual GLOBAL (≠ apetito por-riesgo)
  risks:
    - id: risk.unfair-credit-exclusion
      title: "Unfair Credit Exclusion of Minorities"
      impact: { individual: HIGH, society: HIGH, organization: HIGH }
      likelihood: LIKELY            # análisis ISO 6.4.3 — inherente LIKELY×HIGH = HIGH
      treat:
        - method: REDUCE
          action: "Acotar la paridad demográfica de la decisión y el balance de clase por grupo."
          controls: [eu/ai-act@2024#art-15]
          residual_likelihood: UNLIKELY   # 6.5 objetivo; el control bloqueante lo CONFIRMA
          measures:
            - id: unfair-credit-exclusion
              metric: demographic_parity_diff
              constraint: "< 0.03"
              severity: high
              enforcement: gate
              lifecycle: [validation]
              article: "15"
              control_tier: protective
              standard_clauses: ["eu/pren-18228@2026#9.2", "iso/23894@2023#6.5"]
              inputs: { prediction: prediction, dimension: gender }
  applicability: {}

El registro de riesgos es ahora una sección de sei.yaml (risk.risks[]), no un fichero AssuranceProgram.yaml separado. La estructura completa de cada riesgo y cada medida se describe en AssuranceProgram / OSCAL.

---

Referencia de campos

apiVersion

Tipo: string — Valor actual: seigarrena.dev/v1alpha1

Versión del esquema. El prefijo v1alpha1 indica que la estructura puede evolucionar sin compatibilidad hacia atrás hasta que el motor alcance estabilidad de API.

---

kind

Tipo: string — Valor actual: AISystem

Discriminador de tipo de recurso. Reservado para extensión futura (p. ej. AIDataset, AIPipeline).

---

system

Metadatos de identidad y alcance del sistema.

Campo	Tipo	Descripción
name	string	Identificador del sistema. Aparece en el bundle de evidencia y en el Anexo IV que la nube ensambla.
intended_purpose	string	Finalidad prevista del sistema (EU AI Act Art. 13(3)(b); Anexo IV §1). Cambiar este campo puede activar Deriva A (re-triaje obligatorio).
organization	string	Organización responsable del sistema.
version	string	Versión del sistema (semver). Aparece en el Anexo IV §1.
decisions	lista	Decisiones que toma el sistema (p. ej. loan_approval, loan_denial). Las consume sei impact.
affected_persons	lista	Categorías de personas afectadas por las decisiones del sistema.
component_type	string	Tipo de componente de IA (p. ej. ai-model).
potential_misuses	lista	Mal uso razonablemente previsible (ISO 42001 §6.1.4 / EU AI Act Art. 9(2)(b)). Cada entrada tiene id, description y addressed_by (ids de los riesgos que lo atienden). sei impact señala el mal uso sin atender como HUECO (advisory).

system.potential_misuses[]

Campo	Tipo	Descripción
id	string	Identificador del caso de mal uso (p. ej. mu.proxy-discrimination).
description	string	Descripción del uso no previsto pero anticipable.
addressed_by	lista	Ids de los riesgos de risk.risks que lo atienden; vacío = sin atender (advisory).

---

context

Marco regulatorio del sistema.

Campo	Tipo	Descripción
applicable_standards	lista	Ids canónicos de los estándares aplicables (p. ej. eu/pren-18228@2026, iso/23894@2023, eu/ai-act@2024, eu/dora@2022). El primero es el prioritario. sei conformance sin --standard emite todos los que tienen catálogo de cláusulas.

---

task

Describe la naturaleza de la tarea de IA.

Campo	Tipo	Valores conocidos	Descripción
modality	string	tabular, image	Modalidad de los datos de entrada. Determina qué métricas de sesgo y rendimiento son relevantes.
type	string	classification, segmentation	Tipo de tarea. Informa al KAG qué riesgos proponer por defecto.

Escenario medical

En medical, modality: image y type: segmentation. El motor no cambia; solo la selección de métricas en el script de evaluación y los riesgos que el KAG propone.

---

eval

Campo	Tipo	Descripción
script	ruta	El QUÉ: el tratamiento. Apunta al script de evaluación/entrenamiento. El digest de este fichero, junto con el digest del modelo resultante, entra en sei.lock. Un cambio de script activa Deriva B (re-medición sin re-triaje si la finalidad no varía).

El eval.script define la variante de tratamiento: la diferencia entre V1 y V2 del modelo es un cambio en este script. Ver Modalidades de tratamiento.

---

pipeline

Campo	Tipo	Valores conocidos	Descripción
tool	string	dvc, mlflow, dagster	Selecciona el adapter del seam Reproducer. El núcleo Rust nunca importa la herramienta directamente: el adapter encapsula la invocación del CLI correspondiente (dvc repro, mlflow run, dagster job execute).
metrics	ruta	—	Ruta al fichero de métricas que el pipeline escribe tras ejecutarse. El motor lo lee para evaluar los controles del gate de riesgo.

Los tres backends están probados en CI. Ver Deriva tipada para la relación entre pipeline.tool y el pipeline_lock_digest del bundle.

---

oscal

Campo	Tipo	Descripción
assessment_plan	ruta	Ruta al fichero OSCAL de plan de evaluación generado por sei compile. Define qué controles se miden y bajo qué condiciones. El gate sei run lo consume para evaluar cada control declarado en la sección risk.

Este fichero no se edita a mano: es un artefacto derivado de la sección risk de sei.yaml. Si el programa de riesgos cambia, ejecute sei compile para regenerarlo.

---

dataset

Campo	Tipo	Descripción
croissant	ruta	Ruta al descriptor Croissant del dataset. El script eval.script carga el dataset a través de este descriptor. Croissant-RAI permite declarar metadatos de equidad (distribuciones, atributos sensibles) que el KAG usa para detectar riesgos de sesgo (EU AI Act Art. 10).

---

artifacts

Declara los artefactos del sistema distintos del script y el dataset.

Campo	Tipo	Descripción
model.kind	string	Familia o arquitectura del modelo (logreg, totalsegmentator, …). Informativo; aparece en el Anexo IV.
model.seed	entero	Semilla de aleatoriedad para reproducibilidad determinista del pipeline.

---

risk

Es el programa de aseguramiento (EU AI Act Art. 9) en línea, antes en un fichero AssuranceProgram.yaml aparte. Configura el modelo de riesgo ISO 23894 y contiene el registro de riesgos vivo. Los campos de esta sección gobiernan el gate de riesgo de sei run, la compilación del plan OSCAL de sei compile y la evaluación de conformidad de sei conformance.

Campo	Tipo	Descripción
appetite	objeto	Apetito de riesgo por dimensión de impacto (ver abajo).
criteria	objeto	Criterios de análisis (la escala de la matriz).
overall_residual_criterion	enum	Criterio del residual global del sistema (prEN 18228 cl. 10).
review_interval	string (ISO 8601)	Cadencia de la revisión periódica del riesgo (ISO 23894 §6.6); opcional (ver abajo).
risks	lista	Registro de riesgos: cada riesgo con su impact, likelihood, tratamiento (treat) y medidas. Su estructura completa se documenta en AssuranceProgram / OSCAL.
applicability	objeto	Aplicabilidad de controles (Declaración de Aplicabilidad); {} si no se declara nada.

El registro de riesgos crece durante el desarrollo; git blame sobre la sección risk de sei.yaml es el registro de auditoría de identificación de riesgos (ISO 23894 §6.4.2). Ver la Referencia del CLI sei para sei compile y sei assess.

risk.appetite

Apetito de riesgo por dimensión de impacto. Cada dimensión puede tomar los valores LOW, MEDIUM, HIGH, o CRITICAL.

Dimensión	Descripción
individual	Impacto sobre personas individuales afectadas por las decisiones del sistema.
society	Impacto sobre grupos, comunidades o la sociedad en conjunto.
organization	Impacto sobre la organización que despliega el sistema.

El apetito es el umbral de evaluación (ISO 23894 §6.4.4): un riesgo cuyo nivel inherente supera el apetito declarado requiere tratamiento antes de que el gate de riesgo pueda estar verde.

En loan, el apetito individual y social es MEDIUM; el nivel inherente del riesgo unfair-credit-exclusion (discriminación por género) es HIGH, lo que requiere el tratamiento V2 del script.

risk.criteria

Campo	Valor actual	Descripción
scale	"5x5"	Escala de la matriz de análisis: Likelihood (1–5) × Impact (1–5) = nivel 1–25, mapeado a LOW/MEDIUM/HIGH/CRITICAL. Fijado en 5x5; otras escalas no están implementadas en v1alpha1.

risk.overall_residual_criterion

Tipo: LOW | MEDIUM | HIGH | CRITICAL

Criterio del residual global del sistema (prEN 18228 cl. 10). Es distinto del apetito por-riesgo: mientras que el apetito evalúa cada riesgo individual, el overall_residual_criterion evalúa si la suma de residuales individuales mantiene el sistema dentro del rango aceptable para el conjunto del sistema.

En v1alpha1 este criterio se reporta como advisory por sei conformance; ver Estado e incompletitudes.

risk.review_interval

Tipo: string con una duración ISO 8601 (p. ej. P6M = seis meses, P1Y = un año). Opcional.

Declara la cadencia de la revisión periódica del riesgo (ISO 23894 §6.6). Entra en el bundle de evidencia firmado, de modo que sei reconstruct puede determinar cuándo vence la revisión por TIEMPO: una aprobación más antigua que review_interval reabre el ciclo (estado «en revisión periódica») hasta que la dirección vuelve a aprobar. La revisión se registra con sei review (commit con trailer Sei-Reviewed-by:). El escenario loan declara P6M (revisión semestral).

Escenario medical — diferencias

En medical, el manifiesto omite overall_residual_criterion (el campo es opcional) y fija todas las dimensiones del apetito a HIGH, reflejo del perfil de riesgo de la imagen médica (EU AI Act Anexo III §6, MDR). La modalidad de tratamiento es supervisión humana HOTL (Art.14) y restricciones de Dice por peor subgrupo (control confirmante en modo audit), no un cambio de código del modelo BYO (totalsegmentator).

Ver Los dos gates para la relación entre ambos escenarios y el mismo motor.

---

Ciclo de vida del manifiesto

sei init          →  crea sei.yaml mínimo (si no existe)
[editar sei.yaml] →  declarar system, task, context, pipeline y la sección risk
sei compile       →  genera oscal.assessment_plan desde la sección risk de sei.yaml
sei run           →  lee sei.yaml completo; gate de riesgo; escribe .sei/bundle.json

El Anexo IV (EU AI Act Art. 11) no lo emite el motor: lo ensambla y renderiza el plano de control (la nube) a partir del bundle.json firmado. Ver Los artefactos .sei/*.

Consulta la Referencia del CLI sei para los flags de cada subcomando.