How Semantica's PolicyEngine Enforces Compliance Rules for Decision Tracking

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 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:

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:

# 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 – Validates compliance scenarios, low-confidence violations, invalid outcomes, custom rules, and long-reasoning warnings
• 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 – 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 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.

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 file contains integration tests showing how the policy engine works with the decision-kit API. Additionally, tests/context/test_context_graphs_examples.py provides higher-level examples of querying compliance status from agent contexts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}