Guardrails Contract Patterns

Guide for implementing validation contracts that enforce data quality, risk limits, and compliance.

When to Use

Apply when:

Adding validation rules for domain resources
Implementing signal bounds, dataset schema checks
Creating portfolio constraints (weights, leverage)
Enforcing PIT correctness on datasets
Building custom validators
Embedding contracts in Definition resources

Law vs Police Architecture

┌────────────────────────────────────────────────────────────┐
│           DEFINITION RESOURCE (The Law)                     │
│  ├── interface_spec        # Abstract interface             │
│  ├── input_schema          # Expected inputs                │
│  ├── output_schema         # Expected outputs               │
│  ├── compatibility_rules   # Connection rules               │
│  └── guardrail_contracts   # Validation rules               │
│      ├── signal.bounds: {min: -1, max: 1}                  │
│      ├── pit.policy: {knowledge_date_required: true}       │
│      └── dataset.schema: {columns: [...]}                  │
└────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────┐
│           GUARDRAILS ENGINE (The Police)                    │
│  Reads contracts FROM Definitions, enforces at gates:       │
│  ├── Gate 1: Instance Creation (validate config)           │
│  ├── Gate 2: Run Execution (validate inputs)               │
│  ├── Gate 3: Data Write (validate outputs in real-time)    │
│  └── Gate 4: Promotion/Merge (all must pass)               │
└────────────────────────────────────────────────────────────┘

Key Insight: Contracts live IN Definition resources. The Guardrails Engine reads and enforces them—no manual attachment needed.

Core Concepts

ContractRef: Identifies contract kind + JSON schema ContractInstance: Bound contract with config + enforcement hint ContractBundle: Collection of contracts for a resource ValidationReport: Results with issues, enforcement decision

Implementation Workflow

1. Define Contract Kind

Use namespaced naming: <domain>.<aspect>

signal.bounds       # Value range [-1, 1]
signal.schema       # Arrow schema conformance
dataset.pit         # Point-in-time correctness
dataset.freshness   # Data staleness SLA
portfolio.weights   # Sum-to-one, min/max weight
portfolio.leverage  # Gross/net exposure limits

2. Create JSON Schema

Location: optaic/guardrails/contracts/<domain>.py

See references/contract-schemas.md.

3. Implement Validator

Location: optaic/guardrails/validators/<domain>.py

Validators must be pure and deterministic. See references/validators.md.

4. Register Contract

python

ContractRegistry.register(
    kind="signal.bounds",
    schema=SIGNAL_BOUNDS_SCHEMA,
    validator=SignalBoundsValidator,
    version="1.0"
)

5. Write Tests

Test cases:

Valid config + valid data → Pass
Invalid config → Schema validation fail
Valid config + invalid data → Business validation fail

Enforcement Policy

python

# official subspace → BLOCK on errors
# staging subspace → WARN on errors (unless elevated)

if subspace == "official":
    return EnforcementLevel.BLOCK
return EnforcementLevel.WARN

Lifecycle Gates

Guardrails validate at:

resource.create / resource.update
promotion.request / promotion.merge
run.submit / run.start

Reference Files

Contract Schemas - JSON schema patterns
Validators - Validator implementation
Quant Contracts - Domain-specific examples

Search AI Tools

guardrails-contracts

Install this agent skill to your Project

SKILL.md