# How Semantica's PolicyEngine Enforces Compliance Rules for Decision Tracking

> Semantica's PolicyEngine enforces compliance by validating decision records against custom rules. Get detailed reports on violations and warnings for better tracking.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-09

---

**Semantica's PolicyEngine validates every decision record against configurable rules—including confidence thresholds, allowed outcomes, and required metadata—returning a detailed compliance report with violations and warnings.**

Semantica implements a lightweight policy engine inside its `ContextGraph` class to ensure decision tracking meets organizational standards. According to the semantica-agi/semantica source code, the engine systematically validates decision data against customizable compliance rules every time a decision is examined or stored, making it ideal for audit trails and regulatory requirements.

## Core Architecture and Source Location

The compliance enforcement logic resides in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py) within the **`enforce_decision_policy`** method (lines 2867-2919). This method serves as the primary entry point for validating decision dictionaries against policy constraints.

The engine uses a lightweight design that accepts a decision record and an optional custom rule set, then executes a series of validation checks. By default, the system applies built-in thresholds for confidence scores, outcome categories, metadata requirements, and reasoning length limits.

## Default Rule Configuration and Custom Overrides

The PolicyEngine operates with a sensible default configuration that callers can override via the `policy_rules` parameter. The default rule set includes:

- **Minimum confidence threshold** – Rejects decisions with low certainty scores
- **Allowed outcomes** – Restricts decisions to predefined categorical values
- **Required metadata fields** – Enforces presence of critical tracking information
- **Maximum reasoning length** – Flags excessively verbose explanations as warnings

When calling `enforce_decision_policy`, developers can pass a custom dictionary to `policy_rules` to override any default values without modifying the source code.

## The Four-Step Validation Workflow

The `enforce_decision_policy` method executes four distinct validation checks in sequence:

### Confidence Threshold Validation

The engine first verifies that `decision_data["confidence"]` meets or exceeds the `min_confidence` threshold defined in the active rule set. If the confidence score falls below this minimum, the system records a violation indicating non-compliance.

### Outcome Allowlist Verification

Next, the method checks that the decision's `outcome` field exists within the `required_outcomes` list. Any outcome not explicitly defined in the policy rules generates a violation, preventing undocumented decision categories from entering the system.

### Required Metadata Field Checks

The engine validates that every field listed in `required_metadata` is present in the decision record. Missing fields trigger violations, ensuring that critical tracking information—such as decision maker identity or timestamps—cannot be omitted.

### Reasoning Length Limits

Finally, the system checks if the `reasoning` string exceeds `max_reasoning_length`. Unlike other checks, excessive length generates a **warning** rather than a violation, allowing the decision to pass while flagging potential verbosity issues for review.

## Result Composition and Return Structure

The `enforce_decision_policy` method returns a standardized dictionary containing four keys:

- **`compliant`** – Boolean indicating whether zero violations were found
- **`violations`** – List of human-readable strings describing each rule breach
- **`warnings`** – List of non-blocking issues (such as lengthy reasoning)
- **`policy_rules`** – The complete rule set applied during validation (defaults or custom)

This structure enables downstream systems to make binary compliance decisions while preserving detailed audit trails for regulatory review.

## Practical Implementation Examples

The following examples demonstrate how to enforce compliance rules using both default and custom configurations:

```python
from semantica.context.context_graph import ContextGraph

g = ContextGraph()

# 1️⃣ Enforce with default rules

decision = {
    "category": "mortgage",
    "outcome": "approved",
    "confidence": 0.92,
    "reasoning": "Strong applicant profile.",
    "decision_maker": "underwriter_ai_v5",
}
result = g.enforce_decision_policy(decision)
print(result["compliant"])   # True

```

For specialized use cases, override specific rules while keeping defaults for other checks:

```python

# 2️⃣ Enforce with a custom rule set

custom_rules = {
    "min_confidence": 0.80,
    "required_outcomes": ["green_light", "red_light", "hold"],
    "required_metadata": ["decision_maker"],
}
decision2 = {
    "outcome": "green_light",
    "confidence": 0.85,
    "reasoning": "All risk metrics satisfied.",
    "decision_maker": "trading_bot",
}
result2 = g.enforce_decision_policy(decision2, policy_rules=custom_rules)
print(result2)   # {'compliant': True, 'violations': [], 'warnings': [], 'policy_rules': {...}}

```

## Testing and Verification

The Semantica repository includes comprehensive test coverage for the policy engine. Key test files include:

- [`tests/test_030_context_graph_realworld_extended.py`](https://github.com/semantica-agi/semantica/blob/main/tests/test_030_context_graph_realworld_extended.py) – Validates compliance scenarios, low-confidence violations, invalid outcomes, custom rules, and long-reasoning warnings
- [`tests/context/test_agent_context_decisions.py`](https://github.com/semantica-agi/semantica/blob/main/tests/context/test_agent_context_decisions.py) – Tests integration between the policy engine and the decision-kit API
- [`tests/context/test_context_graphs_examples.py`](https://github.com/semantica-agi/semantica/blob/main/tests/context/test_context_graphs_examples.py) – Demonstrates querying the policy engine from higher-level contexts

These test suites verify that the engine correctly identifies violations while allowing valid decisions to pass through the compliance pipeline.

## Summary

- The PolicyEngine lives in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py) inside the `enforce_decision_policy` method (lines 2867-2919)
- It validates decisions against four rule types: confidence thresholds, outcome allowlists, required metadata, and reasoning length limits
- Violations block compliance while reasoning length issues generate warnings only
- Developers can override default rules via the `policy_rules` parameter without modifying core source code
- The method returns a structured dictionary with boolean compliance status, violation lists, and applied rule sets

## Frequently Asked Questions

### What happens when a decision fails the confidence threshold check?

When a decision's confidence score falls below the `min_confidence` value specified in the active policy rules, the engine adds a violation message to the `violations` list and sets `compliant` to `False`. The decision record is flagged for review but remains in the system for audit purposes.

### Can I enforce custom metadata requirements without changing the source code?

Yes. Pass a custom dictionary to the `policy_rules` parameter when calling `enforce_decision_policy`. Include a `required_metadata` list containing your specific field names. The engine will validate that all listed fields exist in the decision record without requiring modifications to [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py).

### Why does exceeding the reasoning length limit generate a warning instead of a violation?

The reasoning length check produces a warning rather than a violation because verbose explanations do not compromise data integrity or compliance standards. The `max_reasoning_length` rule flags potentially excessive verbosity for human review while allowing the decision to pass through automated compliance checks.

### Where can I find examples of the PolicyEngine integrated with real decision workflows?

The [`tests/context/test_agent_context_decisions.py`](https://github.com/semantica-agi/semantica/blob/main/tests/context/test_agent_context_decisions.py) file contains integration tests showing how the policy engine works with the decision-kit API. Additionally, [`tests/context/test_context_graphs_examples.py`](https://github.com/semantica-agi/semantica/blob/main/tests/context/test_context_graphs_examples.py) provides higher-level examples of querying compliance status from agent contexts.