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

.. code-block:: python

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

.. code-block:: yaml

   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:

.. code-block:: python

   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)

.. seealso::

   Trajectory logging, metrics, and task evaluation are covered in the
   dedicated :doc:`/core_modules/evaluation` page.