Policy Decision Point

The Policy Decision Point (PDP) is the core of Praxom. It evaluates every proposed agent action against workspace-scoped constraints and returns a deterministic verdict.

How It WorksCopy Anchor Link

PraxomRouter (router.py)Copy Anchor Link

The PraxomRouter class is the top-level orchestrator:

1. Parses the namespaced tool name (e.g., salesforce.update_contact)
2. Resolves the workspace and agent identity
3. Calls the policy engine to evaluate constraints
4. Records an attestation for every decision
5. Routes allowed calls to the downstream server

Evidence classification (_classify_evidence()) determines the quality of evidence used for the decision — higher-quality evidence (steward-confirmed constraints) produces higher-confidence verdicts.

PraxomPolicyEngine (policy_engine.py)Copy Anchor Link

The PraxomPolicyEngine evaluates workspace-scoped constraints:

decision = engine.evaluate(
    tool_name="salesforce.update_contact",
    arguments={"contact_id": "123", "email": "[email protected]"},
    agent_id="agent-7",
    workspace_id=workspace_id
)
# decision.verdict: "allow" | "deny" | "rewrite" | "warn" | "escalate"
# decision.reasons: list of constraint evaluation results
# decision.rewrites: list of field modifications (for REWRITE verdicts)

The policy engine supports:

• Comparison operators: == (alias =), !=, >, <, >=, <=, in, not_in, contains, regex, exists
• Compound logic: all (AND) and any (OR) combinators
• Dot-notation field access: arguments.amount, arguments.contact.email
• Value references: value_ref for dynamic constraint values
• Glob matching: Tool name patterns like salesforce.* or *.delete_*

PraxomMCPGate (mcp_gate.py)Copy Anchor Link

The enforcement point for MCP tool calls. Every tool call passes through the gate:

1. Resolves agent identity from headers (extract_agent_identity())
2. Calls the policy engine for evaluation
3. Handles REWRITE verdicts by applying safe transformations
4. Records attestations via the attestation store
5. Formats tiered error responses (agents get sanitized errors, not internal details)

The GateResult dataclass carries the verdict, modified arguments (for rewrites), and the attestation ID.

ArchitectureCopy Anchor Link

Agent Request
    ↓
PraxomMCPGate (enforcement point)
    ↓
PraxomPolicyEngine (constraint evaluation)
    ↓                    ↓
JSON Predicates     SHACL Shapes
(auto-tier)         (formal-tier)
    ↓                    ↓
PolicyDecision (verdict + reasons)
    ↓
AttestationStore (signed record)
    ↓
Execute or Block

ConfigurationCopy Anchor Link

Constraints are managed via the REST API:

POST /api/v1/praxom/constraints
{
  "workspace_id": "ws-1",
  "tool_patterns": ["salesforce.update_*"],
  "tier": "auto",
  "predicate": {
    "all": [
      {"field": "arguments.amount", "operator": "<=", "value": 10000},
      {"field": "arguments.status", "operator": "!=", "value": "deleted"}
    ]
  },
  "verdict_on_match": "deny"
}

Technical DetailsCopy Anchor Link

• Read actions (determined by _is_read_action() heuristic and the ToolActionClassifier) are pass-through by default
• Regex evaluation has a 1-second timeout to prevent ReDoS attacks (_eval_regex_with_timeout())
• The gate formats errors with _format_error() which strips internal details before returning to agents
• All verdicts are recorded — both ALLOW and DENY produce attestation records for audit completeness