sei.yaml Reference

🟡 Partial — The schema is v1alpha1: the field set described here is implemented, but the schema version still evolves alongside the engine (it may change without notice between versions).

sei.yaml is the AI system manifest the engine reads at the start of every subcommand. It is the single declarative file: each repository contains exactly one sei.yaml at its root and governs a single system. It declares the system’s intended purpose, the task, the regulatory context, the evaluation pipeline, and the risk programme (Art. 9) inline, in the risk section.

sei init generates a minimal sei.yaml if one does not exist. The oscal.assessment_plan field is populated by sei compile.

Evidence signing

The evidence the engine derives from this manifest (.sei/bundle.json and the other artifacts) is signed with ECDSA-P256 (RFC 6979) + DSSE + in-toto, via a pluggable signer (local or Scaleway KMS, per SEI_SIGNING_BACKEND). See Sign and verify evidence.

---

Example manifest — a credit system

The following manifest is an illustrative example of a consumer credit system (high-risk, EU AI Act Annex III §5), meant to teach the structure of a sei.yaml. The values are indicative; adapt them to your own system:

sei.yaml — credit system (tabular / classification)

apiVersion: seigarrena.dev/v1alpha1
kind: AISystem

# 1. System identity and intended purpose
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
  # Reasonably foreseeable misuse (ISO 42001 6.1.4 / EU AI Act Art.9(2)(b));
  # `addressed_by` links each one to the risk(s) that address it.
  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. Nature of the task
task:
  modality: tabular
  type: classification

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

# 4. Data and model
dataset: { croissant: data/german_credit.croissant.json }   # eval loads the dataset via Croissant
artifacts:
  model: { kind: logreg, seed: 42 }

# 5. Measurement and reproduction
eval: { script: train.py }   # the WHAT: the TREATMENT (training variant; its digest → model drift)
pipeline: { tool: dvc, metrics: metrics.json }   # the HOW: reproducible recomputation (dvc repro → dvc.lock)
oscal: { assessment_plan: shared_data/policies/assessment_plan.oscal.yaml }   # generated by sei compile

# 6. Risk programme (Art.9) — formerly a separate file; now inline
risk:
  appetite: { individual: MEDIUM, society: MEDIUM, organization: HIGH }   # inherent HIGH exceeds MEDIUM → treatment required (6.4.4)
  criteria: { scale: "5x5" }
  overall_residual_criterion: HIGH   # prEN 18228 cl. 10: GLOBAL residual criterion (≠ per-risk appetite)
  risks:
    - id: risk.unfair-credit-exclusion
      title: "Unfair Credit Exclusion of Minorities"
      impact: { individual: HIGH, society: HIGH, organization: HIGH }
      likelihood: LIKELY            # ISO 6.4.3 analysis — inherent 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 target; the blocking control CONFIRMS it
          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: {}

The risk register is now a section of sei.yaml (risk.risks[]), not a separate AssuranceProgram.yaml file. The full structure of each risk and measure is described in AssuranceProgram / OSCAL.

---

Field reference

apiVersion

Type: string — Current value: seigarrena.dev/v1alpha1

Schema version. The v1alpha1 prefix indicates the structure may evolve without backward compatibility until the engine reaches API stability.

---

kind

Type: string — Current value: AISystem

Resource type discriminator. Reserved for future extension (e.g. AIDataset, AIPipeline).

---

system

System identity and scope metadata.

Field	Type	Description
name	string	System identifier. Appears in the evidence bundle and in the Annex IV the cloud assembles.
intended_purpose	string	Intended purpose of the system (EU AI Act Art. 13(3)(b); Annex IV §1). Changing this field may trigger Drift A (mandatory re-triage).
organization	string	Organisation responsible for the system.
version	string	System version (semver). Appears in Annex IV §1.
decisions	list	Decisions the system makes (e.g. loan_approval, loan_denial). Consumed by sei impact.
affected_persons	list	Categories of persons affected by the system’s decisions.
component_type	string	AI component type (e.g. ai-model).
potential_misuses	list	Reasonably foreseeable misuse (ISO 42001 §6.1.4 / EU AI Act Art. 9(2)(b)). Each entry has id, description, and addressed_by (ids of the risks that address it). sei impact flags unaddressed misuse as a GAP (advisory).

system.potential_misuses[]

Field	Type	Description
id	string	Misuse case identifier (e.g. mu.proxy-discrimination).
description	string	Description of the unintended but anticipable use.
addressed_by	list	Ids of risk.risks entries that address it; empty = unaddressed (advisory).

---

context

Regulatory context of the system.

Field	Type	Description
applicable_standards	list	Canonical ids of the applicable standards (e.g. eu/pren-18228@2026, iso/23894@2023, eu/ai-act@2024, eu/dora@2022). The first one is the highest priority. sei conformance without --standard emits all those with a clause catalog.

---

task

Describes the nature of the AI task.

Field	Type	Known values	Description
modality	string	tabular, image	Input data modality. Determines which bias and performance metrics are relevant.
type	string	classification, segmentation	Task type. Informs the KAG which risks to propose by default.

Medical scenario

In medical, modality: image and type: segmentation. The engine does not change; only the metric selection in the evaluation script and the risks the KAG proposes.

---

eval

Field	Type	Description
script	path	The WHAT: the treatment. Points to the evaluation/training script. The digest of this file, together with the resulting model digest, enters sei.lock. A script change triggers Drift B (re-measurement without re-triage if the intended purpose does not change).

The eval.script defines the treatment variant: the difference between model V1 and V2 is a change to this script. See Treatment modalities.

---

pipeline

Field	Type	Known values	Description
tool	string	dvc, mlflow, dagster	Selects the Reproducer seam adapter. The Rust core never imports the tool directly: the adapter encapsulates the corresponding CLI invocation (dvc repro, mlflow run, dagster job execute).
metrics	path	—	Path to the metrics file the pipeline writes after execution. The engine reads it to evaluate the risk gate controls.

All three backends are tested in CI. See Typed drift for the relationship between pipeline.tool and the pipeline_lock_digest in the bundle.

---

oscal

Field	Type	Description
assessment_plan	path	Path to the OSCAL assessment plan file generated by sei compile. Defines which controls are measured and under what conditions. The sei run gate consumes it to evaluate each control declared in the risk section.

This file is not edited by hand: it is an artifact derived from the risk section of sei.yaml. If the risk programme changes, run sei compile to regenerate it.

---

dataset

Field	Type	Description
croissant	path	Path to the dataset’s Croissant descriptor. The eval.script loads the dataset through this descriptor. Croissant-RAI allows declaring fairness metadata (distributions, sensitive attributes) which the KAG uses to detect bias risks (EU AI Act Art. 10).

---

artifacts

Declares system artifacts other than the script and dataset.

Field	Type	Description
model.kind	string	Model family or architecture (logreg, totalsegmentator, …). Informational; appears in the Annex IV.
model.seed	integer	Randomness seed for deterministic reproducibility of the pipeline.

---

risk

This is the assurance programme (EU AI Act Art. 9) inline, formerly a separate AssuranceProgram.yaml file. It configures the ISO 23894 risk model and holds the living risk register. Fields in this section govern the sei run risk gate, the OSCAL plan compilation by sei compile, and the sei conformance compliance evaluation.

Field	Type	Description
appetite	object	Risk appetite per impact dimension (see below).
criteria	object	Analysis criteria (the matrix scale).
overall_residual_criterion	enum	Criterion for the overall system residual risk (prEN 18228 cl. 10).
review_interval	string (ISO 8601)	Cadence of the periodic risk review (ISO 23894 §6.6); optional (see below).
risks	list	Risk register: each risk with its impact, likelihood, treatment (treat), and measures. Its full structure is documented in AssuranceProgram / OSCAL.
applicability	object	Control applicability (Statement of Applicability); {} if nothing is declared.

The risk register grows during development; git blame on the risk section of sei.yaml is the risk identification audit log (ISO 23894 §6.4.2). See the sei CLI Reference for sei compile and sei assess.

risk.appetite

Risk appetite per impact dimension. Each dimension accepts LOW, MEDIUM, HIGH, or CRITICAL.

Dimension	Description
individual	Impact on individual persons affected by system decisions.
society	Impact on groups, communities, or society as a whole.
organization	Impact on the organisation deploying the system.

The appetite is the evaluation threshold (ISO 23894 §6.4.4): a risk whose inherent level exceeds the declared appetite requires treatment before the risk gate can be green.

In loan, the individual and social appetite is MEDIUM; the inherent level of the unfair-credit-exclusion risk (gender discrimination) is HIGH, which requires the V2 treatment of the script.

risk.criteria

Field	Current value	Description
scale	"5x5"	Analysis matrix scale: Likelihood (1–5) × Impact (1–5) = level 1–25, mapped to LOW/MEDIUM/HIGH/CRITICAL. Fixed at 5x5; other scales are not implemented in v1alpha1.

risk.overall_residual_criterion

Type: LOW | MEDIUM | HIGH | CRITICAL

Criterion for the overall system residual risk (prEN 18228 cl. 10). This is distinct from the per-risk appetite: while the appetite evaluates each individual risk, overall_residual_criterion evaluates whether the sum of individual residuals keeps the system within an acceptable range for the system as a whole.

In v1alpha1 this criterion is reported as advisory by sei conformance; see Status & gaps.

risk.review_interval

Type: a string with an ISO 8601 duration (e.g. P6M = six months, P1Y = one year). Optional.

Declares the cadence of the periodic risk review (ISO 23894 §6.6). It enters the signed evidence bundle, so sei reconstruct can determine when the review falls due by TIME: an approval older than review_interval reopens the cycle (state “under periodic review”) until management approves again. The review is recorded with sei review (a commit with the Sei-Reviewed-by: trailer). The loan scenario declares P6M (semi-annual review).

Medical scenario — differences

In medical, the manifest omits overall_residual_criterion (the field is optional) and sets all appetite dimensions to HIGH, reflecting the risk profile of medical imaging (EU AI Act Annex III §6, MDR). The treatment modality is human HOTL oversight (Art.14) plus worst-subgroup Dice constraints (a confirming control in audit mode), not a code change to the BYO model (totalsegmentator).

See The two gates for the relationship between both scenarios and the same engine.

---

Manifest lifecycle

sei init          →  creates minimal sei.yaml (if it does not exist)
[edit sei.yaml]   →  declare system, task, context, pipeline and the risk section
sei compile       →  generates oscal.assessment_plan from the risk section of sei.yaml
sei run           →  reads full sei.yaml; risk gate; writes .sei/bundle.json

The Annex IV (EU AI Act Art. 11) is not emitted by the engine: it is assembled and rendered by the control plane (the cloud) from the signed bundle.json. See The .sei/* artifacts.

Consult the sei CLI Reference for the flags of each subcommand.