> ## Documentation Index > Fetch the complete documentation index at: https://docs.sengol.io/llms.txt > Use this file to discover all available pages before exploring further. # ControlBook > Your regulations as configuration: obligations, evaluators, thresholds and scoring. 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](https://docs.sengol.io/journeys/compliance-officer.md#4-activate-it)). ## Shape ```yaml controlbook.yaml theme={null} 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 ``` ```bash theme={null} 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](#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](https://docs.sengol.io/reference/evaluator-library.md). | | `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. | > [!TIP] > > 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. > [!NOTE] > > `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 `. | 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: ```yaml sengol.yaml theme={null} custom_policies: ACME_FAIR_ADVICE: display_name: Acme Fair Advice Standard region: CA industries: [BANKING] authority: Acme Bank Model Risk Committee version: "2026" ``` ```bash theme={null} SENGOL_CONFIG=sengol.yaml sengol policy list --region CA ``` ```text theme={null} 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`). > [!WARNING] > > 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.