Skip to content

Elder

The judge in The Arena.

Elder

orc.themed.elder.Elder

The Elder judges combat between Warriors.

Example

elder = Elder( evaluator_model="claude-3-opus", evaluation_criteria="Judge based on code quality and efficiency.", )

Or with a pre-built judge:

elder = Elder(judge=MetricsJudge(weights={"accuracy": 0.7, "latency": 0.3}))

Source code in orc/themed/elder.py 
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
78
79
80
81
82
83
84
class Elder:
    """The Elder judges combat between Warriors.

    Example:
        elder = Elder(
            evaluator_model="claude-3-opus",
            evaluation_criteria="Judge based on code quality and efficiency.",
        )

        # Or with a pre-built judge:
        elder = Elder(judge=MetricsJudge(weights={"accuracy": 0.7, "latency": 0.3}))
    """

    def __init__(
        self,
        evaluator_model: Optional[str] = None,
        evaluation_criteria: Optional[str] = None,
        judge: Optional[Judge] = None,
        llm: Optional[Any] = None,
    ):
        """
        Initialize an Elder.

        Args:
            evaluator_model: LLM model to use for evaluation (e.g., "claude-3-opus").
            evaluation_criteria: Custom criteria for evaluation.
            judge: Pre-built Judge instance (overrides evaluator_model if provided).
            llm: LLMProvider instance for LLM-based judging.
        """
        self.evaluator_model = evaluator_model
        self.evaluation_criteria = evaluation_criteria
        self._llm = llm
        self._judge = judge

    @property
    def judge(self) -> Judge:
        """Get or create the underlying Judge instance."""
        if self._judge is not None:
            return self._judge

        # If an LLM provider was given, use LLMJudge
        if self._llm is not None:
            criteria = (
                [c.strip() for c in self.evaluation_criteria.split(",")]
                if self.evaluation_criteria
                else None
            )
            self._judge = LLMJudge(self._llm, criteria=criteria)
        else:
            # Default to MetricsJudge
            self._judge = MetricsJudge()

        return self._judge

    async def evaluate(
        self,
        task: str,
        submissions: List[Submission],
    ) -> Verdict:
        """
        Evaluate warrior submissions and determine the victor.

        Args:
            task: The task/challenge description.
            submissions: List of warrior submissions (typically 2).

        Returns:
            Verdict with the winner and reasoning.
        """
        return await self.judge.evaluate(task, submissions)

judge property

Get or create the underlying Judge instance.

__init__(evaluator_model=None, evaluation_criteria=None, judge=None, llm=None)

Initialize an Elder.

Parameters:

Name Type Description Default
evaluator_model Optional[str]

LLM model to use for evaluation (e.g., "claude-3-opus").

 None
evaluation_criteria Optional[str]

Custom criteria for evaluation.

 None
judge Optional[Judge]

Pre-built Judge instance (overrides evaluator_model if provided).

 None
llm Optional[Any]

LLMProvider instance for LLM-based judging.

 None
Source code in orc/themed/elder.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def __init__(
    self,
    evaluator_model: Optional[str] = None,
    evaluation_criteria: Optional[str] = None,
    judge: Optional[Judge] = None,
    llm: Optional[Any] = None,
):
    """
    Initialize an Elder.

    Args:
        evaluator_model: LLM model to use for evaluation (e.g., "claude-3-opus").
        evaluation_criteria: Custom criteria for evaluation.
        judge: Pre-built Judge instance (overrides evaluator_model if provided).
        llm: LLMProvider instance for LLM-based judging.
    """
    self.evaluator_model = evaluator_model
    self.evaluation_criteria = evaluation_criteria
    self._llm = llm
    self._judge = judge

evaluate(task, submissions) async

Evaluate warrior submissions and determine the victor.

Parameters:

Name Type Description Default
task str

The task/challenge description.

 required
submissions List[Submission]

List of warrior submissions (typically 2).

 required

Returns:

Type Description
Verdict

Verdict with the winner and reasoning.
Source code in orc/themed/elder.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
async def evaluate(
    self,
    task: str,
    submissions: List[Submission],
) -> Verdict:
    """
    Evaluate warrior submissions and determine the victor.

    Args:
        task: The task/challenge description.
        submissions: List of warrior submissions (typically 2).

    Returns:
        Verdict with the winner and reasoning.
    """
    return await self.judge.evaluate(task, submissions)

TheArena (Themed API)

orc.themed.the_arena.TheArena

Bases: Arena

The Arena where Warriors compete for supremacy.

Same functionality as Arena but accepts Warriors and Elders directly, and produces themed console output.

Example

arena = TheArena( warriors=[grog, thrall, sylvanas], elder=elder, challenge_probability=0.3, )

result = await arena.battle("Optimize the database queries")

Source code in orc/themed/the_arena.py 
 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
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
class TheArena(Arena):
    """The Arena where Warriors compete for supremacy.

    Same functionality as Arena but accepts Warriors and Elders directly,
    and produces themed console output.

    Example:
        arena = TheArena(
            warriors=[grog, thrall, sylvanas],
            elder=elder,
            challenge_probability=0.3,
        )

        result = await arena.battle("Optimize the database queries")
    """

    def __init__(
        self,
        warriors: List[Warrior],
        elder: Elder,
        challenge_probability: float = 0.3,
        **config_kwargs: Any,
    ):
        """
        Initialize TheArena.

        Args:
            warriors: List of Warrior agents competing.
            elder: Elder judge to evaluate trials.
            challenge_probability: Base probability of challenge (0-1).
            **config_kwargs: Additional Arena config options.
        """
        # Build ArenaConfig
        config = ArenaConfig(
            challenge_probability=challenge_probability,
            **config_kwargs,
        )

        # Initialize parent Arena with warriors as agents and elder's judge
        on_challenge = self._themed_on_challenge
        on_succession = self._themed_on_succession
        on_trial_complete = self._themed_on_trial_complete

        super().__init__(
            agents=warriors,
            judge=elder.judge,
            config=config,
            on_challenge=on_challenge,
            on_succession=on_succession,
            on_trial_complete=on_trial_complete,
        )

        self.warriors = {w.name: w for w in warriors}
        self.elder = elder

    async def battle(
        self,
        task: str,
        domain: Optional[str] = None,
        context: Optional[Dict[str, Any]] = None,
    ) -> TrialResult:
        """Execute a battle (alias for process).

        Args:
            task: The challenge to execute.
            domain: Optional domain hint.
            context: Execution context.

        Returns:
            TrialResult with the outcome.
        """
        return await self.process(task, domain, context)

    def get_warchief(self, domain: str) -> Optional[Warchief]:
        """Get the Warchief (current leader) for a domain.

        Args:
            domain: The domain to query.

        Returns:
            Warchief instance or None if no leader.
        """
        warlord_name = self.get_warlord(domain)
        if not warlord_name:
            return None

        warrior = self.warriors.get(warlord_name)
        if not warrior:
            return None

        reputation = self.get_reputation(warlord_name, domain)
        return Warchief(warrior=warrior, domain=domain, reputation=reputation)

    def _themed_on_challenge(self, warlord: str, challenger: str, domain: str):
        """Themed output when a challenge is issued."""
        print(f"\n⚔️ CHALLENGE: {challenger} challenges {warlord} for the '{domain}' domain!")

    def _themed_on_succession(self, old_warlord: str, new_warlord: str, domain: str):
        """Themed output when leadership changes."""
        print(f"\n👑 SUCCESSION: {new_warlord} defeats {old_warlord}! A new Warchief rises!")

    def _themed_on_trial_complete(self, verdict: Any):
        """Themed output when a trial completes."""
        winner = verdict.winner
        if verdict.is_tie:
            print("  ⚖️ The Elder declares a TIE — Warchief retains the throne!")
        else:
            print(f"  ⚖️ The Elder has spoken: {winner} prevails!")

__init__(warriors, elder, challenge_probability=0.3, **config_kwargs)

Initialize TheArena.

Parameters:

Name Type Description Default
warriors List[Warrior]

List of Warrior agents competing.

 required
elder Elder

Elder judge to evaluate trials.

 required
challenge_probability float

Base probability of challenge (0-1).

 0.3
**config_kwargs Any

Additional Arena config options.

 {}
Source code in orc/themed/the_arena.py 
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
def __init__(
    self,
    warriors: List[Warrior],
    elder: Elder,
    challenge_probability: float = 0.3,
    **config_kwargs: Any,
):
    """
    Initialize TheArena.

    Args:
        warriors: List of Warrior agents competing.
        elder: Elder judge to evaluate trials.
        challenge_probability: Base probability of challenge (0-1).
        **config_kwargs: Additional Arena config options.
    """
    # Build ArenaConfig
    config = ArenaConfig(
        challenge_probability=challenge_probability,
        **config_kwargs,
    )

    # Initialize parent Arena with warriors as agents and elder's judge
    on_challenge = self._themed_on_challenge
    on_succession = self._themed_on_succession
    on_trial_complete = self._themed_on_trial_complete

    super().__init__(
        agents=warriors,
        judge=elder.judge,
        config=config,
        on_challenge=on_challenge,
        on_succession=on_succession,
        on_trial_complete=on_trial_complete,
    )

    self.warriors = {w.name: w for w in warriors}
    self.elder = elder

battle(task, domain=None, context=None) async

Execute a battle (alias for process).

Parameters:

Name Type Description Default
task str

The challenge to execute.

 required
domain Optional[str]

Optional domain hint.

 None
context Optional[Dict[str, Any]]

Execution context.

 None

Returns:

Type Description
TrialResult

TrialResult with the outcome.
Source code in orc/themed/the_arena.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
async def battle(
    self,
    task: str,
    domain: Optional[str] = None,
    context: Optional[Dict[str, Any]] = None,
) -> TrialResult:
    """Execute a battle (alias for process).

    Args:
        task: The challenge to execute.
        domain: Optional domain hint.
        context: Execution context.

    Returns:
        TrialResult with the outcome.
    """
    return await self.process(task, domain, context)

get_warchief(domain)

Get the Warchief (current leader) for a domain.

Parameters:

Name Type Description Default
domain str

The domain to query.

 required

Returns:

Type Description
Optional[Warchief]

Warchief instance or None if no leader.
Source code in orc/themed/the_arena.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def get_warchief(self, domain: str) -> Optional[Warchief]:
    """Get the Warchief (current leader) for a domain.

    Args:
        domain: The domain to query.

    Returns:
        Warchief instance or None if no leader.
    """
    warlord_name = self.get_warlord(domain)
    if not warlord_name:
        return None

    warrior = self.warriors.get(warlord_name)
    if not warrior:
        return None

    reputation = self.get_reputation(warlord_name, domain)
    return Warchief(warrior=warrior, domain=domain, reputation=reputation)

Warchief

orc.themed.warchief.Warchief

The victorious Warrior, granted command.

After winning a trial, the Warchief can delegate sub-tasks to the defeated Warriors.

Example

warchief = Warchief( warrior=victor, domain="data_analysis", reputation=0.95 ) warchief.command(defeated_warrior) print(f"Warband size: {len(warchief.warband)}")

Source code in orc/themed/warchief.py 
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
class Warchief:
    """The victorious Warrior, granted command.

    After winning a trial, the Warchief can delegate sub-tasks
    to the defeated Warriors.

    Example:
        warchief = Warchief(
            warrior=victor,
            domain="data_analysis",
            reputation=0.95
        )
        warchief.command(defeated_warrior)
        print(f"Warband size: {len(warchief.warband)}")
    """

    def __init__(
        self,
        warrior: "Warrior",
        domain: str,
        reputation: float,
    ):
        """
        Initialize a Warchief.

        Args:
            warrior: The Warrior who won the trial.
            domain: The domain they now control.
            reputation: Their reputation score for this domain.
        """
        self.warrior = warrior
        self.domain = domain
        self.reputation = reputation
        self._subordinates: List["Warrior"] = []

    @property
    def name(self) -> str:
        """The Warchief's name (from the underlying warrior)."""
        return self.warrior.name

    def command(self, subordinate: "Warrior"):
        """Add a defeated warrior as a subordinate.

        Args:
            subordinate: The Warrior to add to the warband.
        """
        self._subordinates.append(subordinate)

    @property
    def warband(self) -> List["Warrior"]:
        """All warriors under the Warchief's command."""
        return self._subordinates.copy()

    def __repr__(self) -> str:
        return (
            f"Warchief({self.name}, domain={self.domain}, "
            f"reputation={self.reputation:.2f}, warband_size={len(self._subordinates)})"
        )

name property

The Warchief's name (from the underlying warrior).

warband property

All warriors under the Warchief's command.

__init__(warrior, domain, reputation)

Initialize a Warchief.

Parameters:

Name Type Description Default
warrior Warrior

The Warrior who won the trial.

 required
domain str

The domain they now control.

 required
reputation float

Their reputation score for this domain.

 required
Source code in orc/themed/warchief.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def __init__(
    self,
    warrior: "Warrior",
    domain: str,
    reputation: float,
):
    """
    Initialize a Warchief.

    Args:
        warrior: The Warrior who won the trial.
        domain: The domain they now control.
        reputation: Their reputation score for this domain.
    """
    self.warrior = warrior
    self.domain = domain
    self.reputation = reputation
    self._subordinates: List["Warrior"] = []

command(subordinate)

Add a defeated warrior as a subordinate.

Parameters:

Name Type Description Default
subordinate Warrior

The Warrior to add to the warband.

 required
Source code in orc/themed/warchief.py 
54
55
56
57
58
59
60
def command(self, subordinate: "Warrior"):
    """Add a defeated warrior as a subordinate.

    Args:
        subordinate: The Warrior to add to the warband.
    """
    self._subordinates.append(subordinate)