How to Check Decision Rules for Policy Compliance in Semantica

Semantica validates decision policy compliance through the ContextGraph.enforce_decision_policy method, which evaluates decisions against configurable rules for confidence thresholds, allowed outcomes, and required metadata fields.

The semantica-agi/semantica repository implements policy compliance checking as a core knowledge-graph operation. Every decision stored in the system can be validated against domain-specific rules to ensure AI-generated outcomes meet organizational standards. This article explains how to check decision rules for policy compliance in Semantica using both the native Python API and the MCP (Multi-Channel Protocol) tool interface.

Understanding the Policy Enforcement Architecture

The Knowledge Graph Foundation

Semantica stores every decision as a node in its knowledge-graph. This architecture enables persistent, queryable decision records that maintain relationships with other contextual data. According to the source code in semantica/context/context_graph.py, the policy enforcement logic resides directly within the ContextGraph class, allowing seamless integration with the graph's traversal and validation capabilities.

The enforce_decision_policy Method

The primary entry point for compliance checking is ContextGraph.enforce_decision_policy, implemented at lines 5068-5099 in semantica/context/context_graph.py. This method accepts a decision payload and an optional custom rule set, then returns a structured compliance report containing violations, warnings, and the applied policy configuration.

Built-in Default Rules and Validation Logic

When checking decision rules for policy compliance, Semantica applies a default rule set unless overridden by the caller. As defined in lines 5070-5076 of the context graph implementation, these defaults enforce:

• Minimum confidence threshold: 0.7 (decisions with lower confidence scores trigger violations)
• Whitelisted outcomes: only approved, rejected, or flagged are considered valid
• Required metadata fields: decision_maker must be present in the decision data
• Maximum reasoning length: 1000 characters (exceeding this generates a warning, not a violation)

The Policy Compliance Validation Process

When you check decision rules for policy compliance in Semantica, the system executes a four-step validation pipeline:

1. Rule source selection – If you supply a policy_rules dictionary, Semantica uses your custom configuration; otherwise, it falls back to the built-in defaults defined at lines 5068-5080.

2. Field validation – The system checks each rule against the supplied decision_data:

   • Confidence scores below the threshold add violations to the results list
   • Outcomes not present in the whitelist generate violations
   • Missing required metadata fields trigger violations
   • Excessively long reasoning strings produce warnings (non-blocking)

3. Result composition – The method constructs a dictionary containing:

   • compliant: Boolean indicating overall compliance status
   • violations: List of specific rule breaches
   • warnings: List of non-critical issues (e.g., reasoning length)
   • policy_rules: The complete rule set applied during evaluation

4. MCP exposure – The same validation logic is exposed through the MCP tool interface, accessible via the enforce_decision_policy tool name.

Practical Implementation Examples

Using the Native Python API

The most direct way to check decision rules for policy compliance is calling the method on a ContextGraph instance:

from semantica.context.context_graph import ContextGraph

g = ContextGraph()
decision = {
    "category": "loan_approval",
    "scenario": "Applicant with good credit",
    "reasoning": "Credit score > 750, income stable",
    "outcome": "approved",
    "confidence": 0.85,
    "decision_maker": "loan_bot",
}

result = g.enforce_decision_policy(decision)
print(result)

# {'compliant': True, 'violations': [], 'warnings': [], 'policy_rules': {...}}

Supplying Custom Policy Rules

Because the rule set uses plain Python dictionaries, you can override any parameter at call-time without modifying core code. This enables domain-specific policies for industries like healthcare or finance:

custom_rules = {
    "min_confidence": 0.9,                    # Stricter threshold

    "required_outcomes": ["approved"],        # Restrict to single outcome

    "required_metadata": ["decision_maker", "risk_score"],
    "max_reasoning_length": 500,
}

result = g.enforce_decision_policy(decision, policy_rules=custom_rules)
print(result["violations"])

# Output: ["Missing required field: risk_score"]

Integrating with MCP Tools

The policy enforcement capability is exposed through the MCP decision tools registry. The tool references the RECORD_DECISION schema defined in semantica_mcp/mcp/schemas.py (lines 39-78) and can be invoked through the Multi-Channel Protocol:

from semantica_mcp.mcp.tools.decisions import DECISION_TOOLS

# Access the enforce_decision_policy tool from the registry

tool = next(t for t in DECISION_TOOLS if t["name"] == "enforce_decision_policy")

# The tool handler accepts the same decision payload and optional rules

compliance_result = tool["_handler"](decision_data=decision)

For workflows requiring custom logic, you can substitute handle_analyze_decision_impact with enforce_decision_policy while maintaining the same input schema validation.

Summary

• Check decision rules for policy compliance in Semantica using ContextGraph.enforce_decision_policy in semantica/context/context_graph.py.
• Default rules require 0.7 minimum confidence, specific outcomes (approved, rejected, flagged), and a decision_maker metadata field.
• Pass custom policy_rules dictionaries to override defaults for domain-specific requirements without code changes.
• The method returns a structured result with compliant, violations, warnings, and policy_rules keys.
• Access the same functionality through MCP tools using the JSON schema defined in semantica_mcp/mcp/schemas.py.

Frequently Asked Questions

What is the default confidence threshold for policy compliance?

The default rule set enforces a minimum confidence of 0.7. Decisions with confidence scores below this threshold generate violations in the compliance result, while the outcome field must match one of the whitelisted values: approved, rejected, or flagged.

Can I enforce policies without modifying Semantica's core code?

Yes. The enforce_decision_policy method accepts an optional policy_rules parameter that accepts a plain Python dictionary. You can supply custom thresholds, required metadata fields, and outcome restrictions at runtime, enabling domain-specific compliance for clinical AI, financial lending, or other verticals without altering the source in semantica/context/context_graph.py.

How does the MCP tool differ from the native ContextGraph method?

The MCP tool provides the same validation logic through the Multi-Channel Protocol interface, making it accessible to external clients and services. While ContextGraph.enforce_decision_policy operates directly on the knowledge graph instance, the MCP tool wraps this functionality for remote invocation, using the RECORD_DECISION schema from semantica_mcp/mcp/schemas.py for input validation.

What happens if a decision's reasoning exceeds the maximum length?

When reasoning strings exceed the configured max_reasoning_length (default 1000 characters), Semantica adds a warning to the result's warnings list, but the decision remains compliant unless other violations exist. This distinguishes length checks from hard requirements like confidence thresholds or required metadata fields.

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