Plan — Participant base class + participation contract

Introduce a common Participant ABC above BaseAgent and BaseTool. Add BaseService for lightweight bus participants. Formalize the participation contract: every participant owns a config yaml with an id: field.

Motivation

Agents, tools, and services all live on the bus, but they share no common base. AGENT_ID and TOOL_ID are hardcoded class constants rather than config values. Services (CompactionService, RewardService) use AGENT_ID even though they are not agents. There is no stated contract for what it means to participate in LoCAL2.

Participation Contract

Every participant must:

1. Have a config yaml (under config/ and src/local/defaults/)
2. Declare CONFIG_NAME — the key passed to get_config()
3. Set id: in that yaml — the identity used as sender_id on all bus messages

If id: is absent, self.id returns "[set id in yaml]" — no startup failure, visible in logs and UI.

New Class Hierarchy

Participant ABC

File: src/local/participants/participant.py (new)

"""Participant — root base class for all LoCAL2 bus participants."""
from __future__ import annotations

from abc import ABC, abstractmethod
from typing import ClassVar

from local.config_loader import get_config

_UNSET = "[set id in yaml]"


class Participant(ABC):
    """Root base for every LoCAL2 bus participant.

    Contract:
      - Declare CONFIG_NAME pointing to the participant's own yaml
      - Set id: in that yaml
    """

    CONFIG_NAME: ClassVar[str]

    @property
    def id(self) -> str:
        cfg = get_config(self.CONFIG_NAME) or {}
        return cfg.get("id") or _UNSET

BaseService (new)

File: src/local/participants/base_service.py (new)

CompactionService and RewardService share the same pattern: subscribe to one or more subjects, loop receiving envelopes, publish back. BaseService captures that skeleton.

"""BaseService — lightweight bus participant with a subscribe loop."""
from __future__ import annotations

import logging
from abc import abstractmethod

from local.participants.participant import Participant

logger = logging.getLogger(__name__)


class BaseService(Participant):
    """Participant with a simple subscribe-and-dispatch run loop.

    Subclasses implement _handle(envelope).
    """

    def run(self) -> None:
        logger.info("%s ready", self.id)
        while True:
            try:
                envelope = self._sub.receive()
            except Exception as exc:
                logger.error("%s: receive error: %s", self.id, exc)
                continue
            try:
                self._handle(envelope)
            except Exception as exc:
                logger.error("%s: handler error: %s", self.id, exc, exc_info=True)

    @abstractmethod
    def _handle(self, envelope) -> None: ...

BaseAgent changes

File: src/local/agents/base_agent.py (modified)

• Inherit from Participant instead of ABC
• Remove AGENT_ID: ClassVar[str] — replaced by Participant.id
• All self.AGENT_ID references → self.id

BaseTool changes

File: src/local/tools/base_tool.py (modified)

• Inherit from Participant instead of ABC
• Remove TOOL_ID: ClassVar[str] — replaced by Participant.id
• All self.TOOL_ID references → self.id
• CONFIG_NAME already declared — no change needed there

CompactionService changes

File: src/local/services/compaction_service.py (modified)

• Inherit from BaseService
• Remove AGENT_ID = "compaction_service"
• Add CONFIG_NAME = "compaction"
• Move subscribe loop boilerplate to BaseService.run(); rename _check → _handle
• All self.AGENT_ID → self.id

RewardService changes

File: src/local/services/reward_service.py (modified)

• Inherit from BaseService
• Remove any hardcoded ID constant
• Add CONFIG_NAME = "reward"
• Move subscribe loop to BaseService.run() if not already compatible

Per-participant CONFIG_NAME additions

New and Updated Config Files

New yamls (both config/ and src/local/defaults/)

# config/datetime.yaml
id: datetime_tool

# config/compaction.yaml
id: compaction_service

# config/reward.yaml
id: reward_service

id: added to all existing yamls

Module structure

New directory src/local/participants/ houses the base classes shared across agents, tools, and services:

src/local/participants/
  __init__.py
  participant.py      ← Participant ABC
  base_service.py     ← BaseService

BaseAgent stays in src/local/agents/. BaseTool stays in src/local/tools/. Both import from local.participants.

GeneratorAgent special case

GeneratorAgent has both a participant id (from generator.yaml) and an instance_id (from system.yaml, used for peer identification in distributed mode). These remain distinct — self.id identifies the participant type; self._instance_id identifies the specific running instance.

File Map

Test Impact

Any test that instantiates a participant and accesses AGENT_ID or TOOL_ID directly will need updating. Tests that check sender_id on published envelopes will continue to work — the value is unchanged, just the source moves from class constant to config.

Acceptance Criteria

• All participants expose self.id; no AGENT_ID or TOOL_ID class constants remain
• Every participant has a config yaml with id:
• Removing id: from a yaml produces "[set id in yaml]" in logs and bus messages — no exception
• CompactionService and RewardService extend BaseService
• All existing tests pass