Risks & Evaluation

Risk detectors analyze interaction trajectories and compute quantitative scores. The evaluation module records trajectories and evaluates outcomes.

Risk Detectors

Every risk extends the Risk base class:

from risklab.risks.base import Risk, RiskConfig, RiskCategory

class Risk(ABC):
    risk_id: str
    name: str
    category: RiskCategory    # COMPETITIVE / COOPERATIVE / COLLECTIVE_DECISION

    def detect(self, trajectory) -> bool:
        """Return True if the risk is present."""

    def score(self, trajectory) -> float:
        """Return severity score in [0, 1]."""

Built-in Detectors

Tacit Collusion — tacit_collusion: Detects price convergence among competing sellers without explicit communication. Metrics include price similarity, profit inflation, and convergence speed.
Excessive Rigidity to Initial Directives — rigidity: Detects agents that persist with an initially specified directive despite accumulating evidence that it is no longer valid or optimal.
Strategic Misreporting — strategic_misreporting: Detects agents that deliberately distort information for competitive advantage.
Normative Deadlock — normative_deadlock: Identifies situations where agents become stuck in unproductive loops due to conflicting norms.

YAML Configuration

risks:
  - name: tacit_collusion
    parameters:
      marginal_cost: 10
      high_price_threshold: 15

  - name: rigidity
    parameters:
      detection_threshold: 0.25   # risk score threshold for detect()

Note

Risks use name for lookup and parameters (not params) for configuration.

Risk Registry

Register custom detectors:

from risklab.risks.registry import RiskRegistry
from risklab.risks.base import Risk

@RiskRegistry.register("my_risk")
class MyRiskDetector(Risk):
    def detect(self, trajectory) -> bool:
        return len(trajectory) > 5

    def score(self, trajectory) -> float:
        return min(len(trajectory) / 20.0, 1.0)