Referencia — froga.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).

froga.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 froga.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.

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

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 froga.yaml. Los valores son orientativos; adáptalos a tu sistema:

apiVersion: venturalitica.ai/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

# 3b. Evaluación declarada por humano (OBLIGATORIO para `froga run`)
# El KAG no está disponible: el QM/dev declara la clasificación a mano.
classification:
  tier: high                                  # high | limited | minimal | prohibited
  basis:
    - "EU AI Act Annex III §5(b)"             # base legal de la clasificación
  rationale: |
    Scoring crediticio que decide el acceso a crédito al consumo (alto riesgo, Anexo III §5).

# 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, params: params.yaml }   # el CÓMO: recómputo reproducible (dvc repro → dvc.lock)
oscal: { assessment_plan: shared_data/policies/assessment_plan.oscal.yaml }   # generado por froga 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; held-out n=200, IC cruza el umbral → INCONCLUSO (no confirma)
          measures:
            - id: unfair-credit-exclusion
              metric: demographic_parity_diff
              constraint: "< 0.092"
              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 froga.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: venturalitica.ai/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 `froga 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). `froga 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. `froga 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`, `text`, …	Modalidad de los datos de entrada. Determina qué métricas de sesgo y rendimiento son relevantes. Campo de texto libre (sin enum); el esqueleto de `froga init` nombra `tabular`, `image`, `text`.
`type`	string	`classification`, `segmentation`, …	Tipo de tarea (lo lee el motor del manifiesto). Campo de texto libre (sin enum). En el futuro informará al KAG qué riesgos proponer; hoy los riesgos se declaran a mano.

`classification`

Obligatorio para froga run. Evaluación declarada por humano: el Quality Manager / dev declara la clasificación del sistema a mano (el KAG que la propondría es línea futura, hoy no disponible). Si este bloque falta, froga run aborta con un error explícito: «El manifiesto no declara classification. El KAG no está disponible — declara la evaluación a mano en froga.yaml (tier/basis/rationale) y commitea.»

Campo	Tipo	Descripción
`tier`	enum	Categoría de riesgo del sistema. Valores: `high`, `limited`, `minimal`, `prohibited`.
`basis`	lista	Base legal de la clasificación (p. ej. `"EU AI Act Annex III §5(b)"`). Opcional; por defecto vacía.
`rationale`	string	Justificación de por qué el sistema cae en ese `tier`. Opcional; admite texto multilínea.

La clasificación viaja firmada en el bundle de evidencia. froga init deja este bloque comentado como TODO: rellénalo antes del primer froga run.

`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 `froga.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 JSON de métricas que el pipeline escribe tras ejecutarse, con la forma `{ id-de-la-measure: valor }` (la clave es el `id` de cada `measures[]`, no el valor de su campo `metric`). El motor lo lee y casa cada clave con el `control-id` del OSCAL para evaluar los controles de la barrera de riesgo.
`params`	ruta	`params.yaml`	Fichero de hiperparámetros del pipeline. Su digest entra en el hash de la fase modelo. Por defecto: `params.yaml`.

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 `froga compile`. Define qué controles se miden y bajo qué condiciones. La barrera `froga 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 froga.yaml. Si el programa de riesgos cambia, ejecute froga 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 equipo usa para declarar riesgos de sesgo (EU AI Act Art. 10; el KAG futuro asistirá esa identificación).

`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 la barrera de riesgo de froga run, la compilación del plan OSCAL de froga compile y la evaluación de conformidad de froga 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. Cada riesgo puede incluir los primitivos canónicos opcionales del modelo de riesgo agnóstico (ver abajo).
`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 froga.yaml es el registro de auditoría de identificación de riesgos (ISO 23894 §6.4.2). Ver la Referencia del CLI froga para froga compile.

`risk.risks[]` — primitivos canónicos del modelo agnóstico

Los siguientes campos son opcionales (serde(default)) en cada entrada risk.risks[]. Su ausencia no altera los bundles firmados existentes (non-breaking). Los usan los catálogos de proyección de riesgo (froga risk-projection) para mapear cada riesgo al vocabulario de la norma de destino:

Campo	Tipo	Descripción
`source`	string (opcional)	Origen o fuente del riesgo (vocabulario ISO 14971/prEN 18228: “hazard source”).
`pathway`	string (opcional)	Camino o mecanismo de materialización del daño (cómo el source llega al harm).
`consequence`	string (opcional)	Consecuencia o daño final si el riesgo se materializa.
`benefit_risk`	string (opcional)	Declaración de la evaluación beneficio-riesgo (ISO 14971 §9: justifica la aceptación del riesgo residual cuando el beneficio supera el daño potencial).

`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 la barrera 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 del sesgo (en el demo loan-scoring, el flag mitigate de params.yaml); con la evidencia held-out (n=200) infrapotenciada, el control de equidad queda INCONCLUSO en vez de verde.

`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 froga 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 froga 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 froga review (commit con trailer Froga-Reviewed-by:). El escenario loan declara P6M (revisión semestral).

`roles`

Opcional. Declara el rol en el EU AI Act del sistema (Art. 3 / Art. 25). froga run lo sella en el bundle firmado; la nube lo lee del bundle verificado (no de la BD ni de configuración sin firmar).

roles:
  - role: provider                   # provider | deployer | importer | distributor |
                                     # authorised_representative | product_manufacturer |
                                     # gpai_provider | integrator
    since: "2026-01-01"              # fecha de asunción del rol (ISO 8601)
    market_phase: placed_on_market   # research | development | real_world_testing |
                                     # placed_on_market | put_into_service
    # trigger / supersedes (Art. 25) — opcionales

El campo es no-redistribuible por clave (key-specificity): está firmado con la clave ECDSA-P256 del motor de ese sistema; no puede transferirse a otro sistema sin re-firmar. La nube muestra el rol en el Anexo IV solo cuando proviene del bundle verificado.

Ciclo de vida del manifiesto

froga init          →  crea froga.yaml mínimo (si no existe)
[editar froga.yaml] →  declarar system, task, context, classification (obligatoria), pipeline y la sección risk
froga compile       →  genera oscal.assessment_plan desde la sección risk de froga.yaml
froga run           →  lee froga.yaml completo; barrera de riesgo; escribe .froga/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 .froga/*.

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

Referencia — froga.yaml

Manifiesto de ejemplo — un sistema de crédito

Referencia de campos

apiVersion

kind

system

system.potential_misuses[]

context

task

classification

eval

pipeline

oscal

dataset

artifacts

risk

risk.risks[] — primitivos canónicos del modelo agnóstico

risk.appetite

risk.criteria

risk.overall_residual_criterion

risk.review_interval

roles