ControlBook

A ControlBook turns a regulation into checks. Each obligation names the regulation it serves, the evaluators that test it, and the pass rate it needs. Sengol never hardcodes a regulation: every gate verdict and every report reads the active ControlBook. One ControlBook is active per install. Activate it in Settings → General or with POST /v1/controlbook (how).

Shape

controlbook.yaml

controlbook_id: acme-advisory-agents   # stable id
display_name: Acme Bank - Advisory agents
organization: Acme Bank
version: "2026.1"                      # bump on every change
policies: [OSFI_E23]                   # catalog ids this book covers
industry: BANKING
region: CA
default_risk_tier: HIGH                # HIGH | MEDIUM | LOW
approved_by: Chief Risk Officer

obligation_mappings:
  - obligation_id: E23-3.2-pii
    policy_id: OSFI_E23
    description: Responses never disclose a customer's personal identifiers.
    risk_tier: HIGH
    evaluators: [PIIEvaluator]
    thresholds:
      pass_rate: 0.95
    severity: CRITICAL
    critical_veto: true
    coverage_required: true

gold_score_formula:
  formula_type: weighted_average
  app_weights:
    E23-3.2-pii: 1.0
  minimum_floor: 0.80
  compliant_threshold: 0.90

judge_by_tier:
  HIGH:
    provider: openai          # "anthropic" (default) or any OpenAI-compatible provider
    model: gpt-4o-mini

sengol controlbook validate --file controlbook.yaml

Top-level fields

Field	Required	Meaning
`controlbook_id`	yes	Stable id. Signed into records written under this book.
`display_name`, `organization`	yes	Shown on reports.
`version`	yes	A string. The same id and version cannot be re-uploaded with different content.
`policies`	yes	Policy ids from the catalog, or your custom policies.
`industry`, `region`	yes	Used for catalog filtering and reports.
`obligation_mappings`	yes	The checks. See below.
`gold_score_formula`	yes	How obligation results roll up into one score.
`default_risk_tier`	no	`MEDIUM` by default. Also picks the judge in `judge_by_tier`.
`judge_by_tier`	no	LLM judge `provider` and `model` per risk tier, used by `sengol gate`.
`approved_by`	no	Who approved this book.
`authority_model`	no	Who may override decisions per risk tier (`override_authority`).

Obligation fields

Field	Meaning
`obligation_id`	Your id, for example the regulation’s section number.
`policy_id`	The policy this obligation serves. Only records labelled with this policy count toward it.
`description`	Plain-language statement for reports.
`risk_tier`	`HIGH`, `MEDIUM` or `LOW`.
`evaluators`	Evaluator class names. See the evaluator library.
`thresholds.pass_rate`	Minimum share of passing records, from `0` to `1`.
`severity`	`CRITICAL`, `HIGH`, `MEDIUM` or `LOW`.
`critical_veto`	`true`: one failure blocks promotion, whatever the pass rate.
`coverage_required`	`true`: a period with no evidence fails instead of passing silently.
`evidence`	`per_call` (default) rolls up over every record. `sampled` rolls up over the calls that online scoring sampled, and the report states the sampling design. A sampled obligation must list at least one evaluator.
`truncated_days`	For a `sampled` obligation: what happens when head sampling stopped on a day of the report period. `fail` (default) fails the obligation. `report` judges it on the calls it has and discloses the days.

An obligation reports NO_RECORDS_OBSERVED when no record in the period both ran its evaluators and carried its policy_id. Developers set the label with policies=[...] on each input.

human_review_required is accepted in the file but does not route anything to the review queue today.

Gold score

formula_type is one of weighted_average, minimum_threshold or all_must_pass. (custom_expression is reserved and not implemented.) app_weights maps obligation ids to weights. The agent is compliant when the score reaches compliant_threshold (default 0.85). Under weighted_average, a score below minimum_floor (default 0.80) is clamped to 0; under minimum_threshold, every obligation must also clear the floor.

The policy catalog

29 regulations ship. List them with sengol policy list, filter with --region or --industry, and inspect one with sengol regulation show <ID>.

Region	Policy ids
Canada	`OSFI_E23`, `OSFI_B10`, `FINTRAC_6F`, `PIPEDA`
United States	`SR_11_7`, `SR_26_2`, `OCC_2011_12`, `HIPAA`, `CCPA`, `SOX`, `US_TREASURY_AI_RMF`
European Union	`EU_AI_ACT`, `GDPR`, `EBA_ML`
United Kingdom	`PRA_SS1_23`, `FCA_AI`, `UK_GDPR`
Singapore	`MAS_TRM`, `MAS_FEAT`, `PDPA_SG`
Saudi Arabia	`SAMA_AI`, `PDPL_SA`
India	`RBI_IT`, `IRDAI_AI`, `DPDP_IN`
Australia	`APRA_CPG234`
Global	`NIST_AI_RMF`, `ISO_42001`, `BCBS_239`

Custom policies

Add internal policies under custom_policies in sengol.yaml. Ids must not collide with built-in ones:

sengol.yaml

custom_policies:
  ACME_FAIR_ADVICE:
    display_name: Acme Fair Advice Standard
    region: CA
    industries: [BANKING]
    authority: Acme Bank Model Risk Committee
    version: "2026"

SENGOL_CONFIG=sengol.yaml sengol policy list --region CA

POLICY_ID         REGION  INDUSTRIES         VERSION  DISPLAY_NAME
----------------  ------  -----------------  -------  ------------------------------
ACME_FAIR_ADVICE  CA      BANKING            2026     Acme Fair Advice Standard
FINTRAC_6F        CA      BANKING            2023     FINTRAC Part 6F — AML/ATF ...
...

Required: display_name and region. Optional: industries, authority, url, version, and report (title, subtitle, plain_language).

The appliance validates an uploaded ControlBook against its own catalog. For it to accept a custom policy, set SENGOL_CONFIG on the API process to a file with the same custom_policies block.

Get started

Journeys

Concepts

Guides

Reference

Shape

Top-level fields

Obligation fields

Gold score

The policy catalog

Custom policies

​Shape

​Top-level fields

​Obligation fields

​Gold score

​The policy catalog

​Custom policies

Shape

Top-level fields

Obligation fields

Gold score

The policy catalog

Custom policies