Constraint Engine

The Constraint Engine evaluates business rules against proposed actions using two tiers: JSON predicates for rapid, code-free constraint authoring, and SHACL shapes for formal, logic-based validation.

How It Works

Auto-Tier: JSON Predicates

JSON predicates are the primary constraint format. They are fast to author, easy to understand, and sufficient for most business rules.

The AegisPolicyEngine in policy_engine.py evaluates predicates using evaluate_predicate():

predicate = {
    "all": [
        {"field": "arguments.amount", "op": "lte", "value": 10000},
        {"field": "arguments.currency", "op": "in", "value": ["USD", "EUR"]},
        {"field": "arguments.status", "op": "neq", "value": "deleted"}
    ]
}
result = evaluate_predicate(payload, predicate)

Supported operators:

Operator	Description	Example
`eq`	Equal	`{"field": "status", "op": "eq", "value": "active"}`
`neq`	Not equal	`{"field": "status", "op": "neq", "value": "deleted"}`
`gt`	Greater than	`{"field": "amount", "op": "gt", "value": 0}`
`gte`	Greater than or equal	`{"field": "amount", "op": "gte", "value": 100}`
`lt`	Less than	`{"field": "amount", "op": "lt", "value": 50000}`
`lte`	Less than or equal	`{"field": "amount", "op": "lte", "value": 10000}`
`in`	Value in list	`{"field": "currency", "op": "in", "value": ["USD", "EUR"]}`
`not_in`	Value not in list	`{"field": "region", "op": "not_in", "value": ["restricted"]}`
`regex`	Regular expression match	`{"field": "email", "op": "regex", "value": "^.*@company\\.com$"}`
`glob`	Glob pattern match	`{"field": "path", "op": "glob", "value": "/api/v1/*"}`

The JsonPredicateEvaluator class (json_predicate_evaluator.py) wraps this logic as a ConstraintEvaluator implementation for the pluggable evaluator registry.

Formal-Tier: SHACL Shapes

SHACL (Shapes Constraint Language) provides formal-logic validation for complex business rules that benefit from ontological reasoning.

SHACL Generator (shacl_generator.py) converts structured JSON policy definitions into SHACL Turtle:

# Input: JSON constraint definition
# Output: SHACL Turtle that pyshacl can evaluate

SHACL Evaluator (shacl_evaluator.py) runs pyshacl against action payloads converted to RDF:

result = evaluate_shacl(payload, shacl_graph)
# result.conforms: bool
# result.violations: list of SHACL violations

SHACL Constraint Evaluator (shacl_constraint_evaluator.py) wraps the SHACL evaluator as a ConstraintEvaluator for the pluggable registry, supporting tool pattern matching via fnmatch.

Architecture

Both tiers feed into the same policy engine:

Proposed Action
    ↓
AegisPolicyEngine
    ├── JSON Predicate Evaluator (auto-tier, fast)
    └── SHACL Constraint Evaluator (formal-tier, rigorous)
    ↓
PolicyDecision (merged results from all matching evaluators)

Auto-tier constraints are evaluated first for performance. SHACL constraints are evaluated only if needed (when formal-tier constraints exist for the matching tool pattern).

Configuration

Constraints are created via the REST API:

# Auto-tier (JSON predicate)
POST /api/v1/aegis/constraints
{
  "tier": "auto",
  "tool_patterns": ["salesforce.update_*"],
  "predicate": {"all": [{"field": "arguments.amount", "op": "lte", "value": 10000}]},
  "verdict_on_match": "deny"
}
 
# Formal-tier (SHACL)
POST /api/v1/aegis/constraints
{
  "tier": "formal",
  "tool_patterns": ["ehr.prescribe_*"],
  "shacl_turtle": "<SHACL shape definition>",
  "verdict_on_match": "deny"
}

Technical Details

JSON predicates support dot-notation field access for nested payloads: arguments.contact.address.zip
Regex evaluation is sandboxed with a 1-second timeout to prevent ReDoS
SHACL shapes use safe identifier allowlists to prevent injection via property paths
Constraint evaluation is deterministic — no LLM, no randomness, same input always produces same output
The _check_requirements() function validates structural requirements (required fields must be present)