AgentSkillsCN

guardrails-contracts

在 OptAIC 中设计护栏验证合约时遵循这些模式。适用于信号边界、数据集架构、投资组合约束、PIT 验证和其他领域特定验证规则。涵盖“法律 vs 警察”架构，其中 Definitions 包含合约而 Engine 强制执行它们。

SKILL.md
--- frontmatter
name: guardrails-contracts
description: Follow these patterns when designing guardrails validation contracts in OptAIC. Use for signal bounds, dataset schemas, portfolio constraints, PIT validation, and other domain-specific validation rules. Covers the "Law vs Police" architecture where Definitions contain contracts and the Engine enforces them.

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

code
┌────────────────────────────────────────────────────────────┐
│           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>

code
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