Skip to content

Challenge Strategies

Strategies that control when warriors challenge for domain leadership.

AlwaysChallenge

orc.strategies.always.AlwaysChallenge

Strategy that always challenges when eligible.

Use this for aggressive agents that want to maximize their chances of gaining leadership.

Source code in orc/strategies/always.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class AlwaysChallenge:
    """
    Strategy that always challenges when eligible.

    Use this for aggressive agents that want to maximize
    their chances of gaining leadership.
    """

    def should_challenge(
        self,
        domain: str,
        warlord_name: str,
        warlord_reputation: float,
        challenger_reputation: float,
    ) -> bool:
        """Always returns True."""
        return True

should_challenge(domain, warlord_name, warlord_reputation, challenger_reputation)

Always returns True.

Source code in orc/strategies/always.py 
14
15
16
17
18
19
20
21
22
def should_challenge(
    self,
    domain: str,
    warlord_name: str,
    warlord_reputation: float,
    challenger_reputation: float,
) -> bool:
    """Always returns True."""
    return True

ReputationBased

orc.strategies.reputation.ReputationBased

Strategy that challenges when reputation exceeds the Warlord's.

Only challenges when the agent has a meaningful reputation advantage over the current Warlord.

Example

strategy = ReputationBased(threshold=0.1)

Will challenge if challenger_rep > warlord_rep + 0.1

Source code in orc/strategies/reputation.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
class ReputationBased:
    """
    Strategy that challenges when reputation exceeds the Warlord's.

    Only challenges when the agent has a meaningful reputation
    advantage over the current Warlord.

    Example:
        strategy = ReputationBased(threshold=0.1)
        # Will challenge if challenger_rep > warlord_rep + 0.1
    """

    def __init__(self, threshold: float = 0.1):
        """
        Initialize the strategy.

        Args:
            threshold: Minimum reputation advantage required to challenge.
        """
        self.threshold = threshold

    def should_challenge(
        self,
        domain: str,
        warlord_name: str,
        warlord_reputation: float,
        challenger_reputation: float,
    ) -> bool:
        """Challenge if reputation exceeds threshold."""
        return challenger_reputation > warlord_reputation + self.threshold

__init__(threshold=0.1)

Initialize the strategy.

Parameters:

Name Type Description Default
threshold float

Minimum reputation advantage required to challenge.

 0.1
Source code in orc/strategies/reputation.py 
18
19
20
21
22
23
24
25
def __init__(self, threshold: float = 0.1):
    """
    Initialize the strategy.

    Args:
        threshold: Minimum reputation advantage required to challenge.
    """
    self.threshold = threshold

should_challenge(domain, warlord_name, warlord_reputation, challenger_reputation)

Challenge if reputation exceeds threshold.

Source code in orc/strategies/reputation.py 
27
28
29
30
31
32
33
34
35
def should_challenge(
    self,
    domain: str,
    warlord_name: str,
    warlord_reputation: float,
    challenger_reputation: float,
) -> bool:
    """Challenge if reputation exceeds threshold."""
    return challenger_reputation > warlord_reputation + self.threshold

CooldownStrategy

orc.strategies.cooldown.CooldownStrategy

Strategy with cooldown after losses.

Reduces challenge frequency after losses to avoid wasting resources on unlikely wins.

Example

strategy = CooldownStrategy( base_cooldown=300, # 5 minutes loss_multiplier=2.0, # Double cooldown after each loss )

Source code in orc/strategies/cooldown.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
class CooldownStrategy:
    """
    Strategy with cooldown after losses.

    Reduces challenge frequency after losses to avoid
    wasting resources on unlikely wins.

    Example:
        strategy = CooldownStrategy(
            base_cooldown=300,  # 5 minutes
            loss_multiplier=2.0,  # Double cooldown after each loss
        )
    """

    def __init__(
        self,
        base_cooldown: int = 300,
        loss_multiplier: float = 2.0,
        max_cooldown: int = 3600,
    ):
        """
        Initialize the strategy.

        Args:
            base_cooldown: Base cooldown in seconds.
            loss_multiplier: Cooldown multiplier after each loss.
            max_cooldown: Maximum cooldown in seconds.
        """
        self.base_cooldown = base_cooldown
        self.loss_multiplier = loss_multiplier
        self.max_cooldown = max_cooldown

        # Track losses per domain
        self._losses: Dict[str, int] = {}
        self._last_challenge: Dict[str, datetime] = {}

    def should_challenge(
        self,
        domain: str,
        warlord_name: str,
        warlord_reputation: float,
        challenger_reputation: float,
    ) -> bool:
        """Challenge if cooldown has expired."""
        now = datetime.now(timezone.utc)

        # Check cooldown
        last = self._last_challenge.get(domain)
        if last:
            losses = self._losses.get(domain, 0)
            cooldown = min(
                self.base_cooldown * (self.loss_multiplier ** losses),
                self.max_cooldown,
            )
            elapsed = (now - last).total_seconds()
            if elapsed < cooldown:
                return False

        return True

    def record_loss(self, domain: str):
        """Record a loss for cooldown calculation."""
        self._losses[domain] = self._losses.get(domain, 0) + 1
        self._last_challenge[domain] = datetime.now(timezone.utc)

    def record_win(self, domain: str):
        """Record a win - reset loss counter."""
        self._losses[domain] = 0
        self._last_challenge[domain] = datetime.now(timezone.utc)

__init__(base_cooldown=300, loss_multiplier=2.0, max_cooldown=3600)

Initialize the strategy.

Parameters:

Name Type Description Default
base_cooldown int

Base cooldown in seconds.

 300
loss_multiplier float

Cooldown multiplier after each loss.

 2.0
max_cooldown int

Maximum cooldown in seconds.

 3600
Source code in orc/strategies/cooldown.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def __init__(
    self,
    base_cooldown: int = 300,
    loss_multiplier: float = 2.0,
    max_cooldown: int = 3600,
):
    """
    Initialize the strategy.

    Args:
        base_cooldown: Base cooldown in seconds.
        loss_multiplier: Cooldown multiplier after each loss.
        max_cooldown: Maximum cooldown in seconds.
    """
    self.base_cooldown = base_cooldown
    self.loss_multiplier = loss_multiplier
    self.max_cooldown = max_cooldown

    # Track losses per domain
    self._losses: Dict[str, int] = {}
    self._last_challenge: Dict[str, datetime] = {}

record_loss(domain)

Record a loss for cooldown calculation.

Source code in orc/strategies/cooldown.py 
69
70
71
72
def record_loss(self, domain: str):
    """Record a loss for cooldown calculation."""
    self._losses[domain] = self._losses.get(domain, 0) + 1
    self._last_challenge[domain] = datetime.now(timezone.utc)

record_win(domain)

Record a win - reset loss counter.

Source code in orc/strategies/cooldown.py 
74
75
76
77
def record_win(self, domain: str):
    """Record a win - reset loss counter."""
    self._losses[domain] = 0
    self._last_challenge[domain] = datetime.now(timezone.utc)

should_challenge(domain, warlord_name, warlord_reputation, challenger_reputation)

Challenge if cooldown has expired.

Source code in orc/strategies/cooldown.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def should_challenge(
    self,
    domain: str,
    warlord_name: str,
    warlord_reputation: float,
    challenger_reputation: float,
) -> bool:
    """Challenge if cooldown has expired."""
    now = datetime.now(timezone.utc)

    # Check cooldown
    last = self._last_challenge.get(domain)
    if last:
        losses = self._losses.get(domain, 0)
        cooldown = min(
            self.base_cooldown * (self.loss_multiplier ** losses),
            self.max_cooldown,
        )
        elapsed = (now - last).total_seconds()
        if elapsed < cooldown:
            return False

    return True

SpecialistStrategy

orc.strategies.specialist.SpecialistStrategy

Strategy that only challenges in specialty domains.

For agents that want to focus on specific domains rather than competing broadly.

Example

strategy = SpecialistStrategy(specialties=["data", "analytics"])

Will only challenge in "data" and "analytics" domains

Source code in orc/strategies/specialist.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class SpecialistStrategy:
    """
    Strategy that only challenges in specialty domains.

    For agents that want to focus on specific domains
    rather than competing broadly.

    Example:
        strategy = SpecialistStrategy(specialties=["data", "analytics"])
        # Will only challenge in "data" and "analytics" domains
    """

    def __init__(
        self,
        specialties: Optional[List[str]] = None,
        min_reputation: float = 0.3,
    ):
        """
        Initialize the strategy.

        Args:
            specialties: List of specialty domains. If None, never challenges.
            min_reputation: Minimum reputation required to challenge.
        """
        self.specialties = set(specialties or [])
        self.min_reputation = min_reputation

    def should_challenge(
        self,
        domain: str,
        warlord_name: str,
        warlord_reputation: float,
        challenger_reputation: float,
    ) -> bool:
        """Challenge only in specialty domains with sufficient reputation."""
        if domain not in self.specialties:
            return False
        if challenger_reputation < self.min_reputation:
            return False
        return True

    def add_specialty(self, domain: str):
        """Add a specialty domain."""
        self.specialties.add(domain)

    def remove_specialty(self, domain: str):
        """Remove a specialty domain."""
        self.specialties.discard(domain)

__init__(specialties=None, min_reputation=0.3)

Initialize the strategy.

Parameters:

Name Type Description Default
specialties Optional[List[str]]

List of specialty domains. If None, never challenges.

 None
min_reputation float

Minimum reputation required to challenge.

 0.3
Source code in orc/strategies/specialist.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
def __init__(
    self,
    specialties: Optional[List[str]] = None,
    min_reputation: float = 0.3,
):
    """
    Initialize the strategy.

    Args:
        specialties: List of specialty domains. If None, never challenges.
        min_reputation: Minimum reputation required to challenge.
    """
    self.specialties = set(specialties or [])
    self.min_reputation = min_reputation

add_specialty(domain)

Add a specialty domain.

Source code in orc/strategies/specialist.py 
49
50
51
def add_specialty(self, domain: str):
    """Add a specialty domain."""
    self.specialties.add(domain)

remove_specialty(domain)

Remove a specialty domain.

Source code in orc/strategies/specialist.py 
53
54
55
def remove_specialty(self, domain: str):
    """Remove a specialty domain."""
    self.specialties.discard(domain)

should_challenge(domain, warlord_name, warlord_reputation, challenger_reputation)

Challenge only in specialty domains with sufficient reputation.

Source code in orc/strategies/specialist.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
def should_challenge(
    self,
    domain: str,
    warlord_name: str,
    warlord_reputation: float,
    challenger_reputation: float,
) -> bool:
    """Challenge only in specialty domains with sufficient reputation."""
    if domain not in self.specialties:
        return False
    if challenger_reputation < self.min_reputation:
        return False
    return True

ChallengeStrategy (Base Protocol)

orc.strategies.base.ChallengeStrategy

Bases: Protocol

Protocol for challenge strategies.

Strategies determine when an agent should challenge the current Warlord for leadership of a domain.

Source code in orc/strategies/base.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@runtime_checkable
class ChallengeStrategy(Protocol):
    """
    Protocol for challenge strategies.

    Strategies determine when an agent should challenge
    the current Warlord for leadership of a domain.
    """

    def should_challenge(
        self,
        domain: str,
        warlord_name: str,
        warlord_reputation: float,
        challenger_reputation: float,
    ) -> bool:
        """
        Determine whether to challenge.

        Args:
            domain: The domain in question.
            warlord_name: Name of the current Warlord.
            warlord_reputation: Warlord's reputation in this domain.
            challenger_reputation: Challenger's reputation in this domain.

        Returns:
            True if the agent should challenge, False otherwise.
        """
        ...

should_challenge(domain, warlord_name, warlord_reputation, challenger_reputation)

Determine whether to challenge.

Parameters:

Name Type Description Default
domain str

The domain in question.

 required
warlord_name str

Name of the current Warlord.

 required
warlord_reputation float

Warlord's reputation in this domain.

 required
challenger_reputation float

Challenger's reputation in this domain.

 required

Returns:

Type Description
bool

True if the agent should challenge, False otherwise.
Source code in orc/strategies/base.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
def should_challenge(
    self,
    domain: str,
    warlord_name: str,
    warlord_reputation: float,
    challenger_reputation: float,
) -> bool:
    """
    Determine whether to challenge.

    Args:
        domain: The domain in question.
        warlord_name: Name of the current Warlord.
        warlord_reputation: Warlord's reputation in this domain.
        challenger_reputation: Challenger's reputation in this domain.

    Returns:
        True if the agent should challenge, False otherwise.
    """
    ...