Merge branch 'feat/environment-variables' into 'dev'

Docs for environment variables, parameterize some constants

See merge request ics/sp/2025/n25b/pepperplus-cb!38

src/control_backend/agents/actuation/robot_gesture_agent.py

@@ -33,7 +33,7 @@ class RobotGestureAgent(BaseAgent):
     def __init__(
         self,
         name: str,
-        address=settings.zmq_settings.ri_command_address,
+        address: str,
         bind=False,
         gesture_data=None,
         single_gesture_data=None,

src/control_backend/agents/communication/ri_communication_agent.py

@@ -38,7 +38,7 @@ class RICommunicationAgent(BaseAgent):
     def __init__(
         self,
         name: str,
-        address=settings.zmq_settings.ri_command_address,
+        address=settings.zmq_settings.ri_communication_address,
         bind=False,
     ):
         super().__init__(name)
@@ -168,7 +168,7 @@ class RICommunicationAgent(BaseAgent):
             bind = port_data["bind"]
 
             if not bind:
-                addr = f"tcp://localhost:{port}"
+                addr = f"tcp://{settings.ri_host}:{port}"
             else:
                 addr = f"tcp://*:{port}"
 

src/control_backend/agents/perception/vad_agent.py

@@ -103,12 +103,11 @@ class VADAgent(BaseAgent):
 
         self._connect_audio_in_socket()
 
-        audio_out_port = self._connect_audio_out_socket()
-        if audio_out_port is None:
+        audio_out_address = self._connect_audio_out_socket()
+        if audio_out_address is None:
             self.logger.error("Could not bind output socket, stopping.")
             await self.stop()
             return
-        audio_out_address = f"tcp://localhost:{audio_out_port}"
 
         # Connect to internal communication socket
         self.program_sub_socket = azmq.Context.instance().socket(zmq.SUB)
@@ -161,13 +160,14 @@ class VADAgent(BaseAgent):
             self.audio_in_socket.connect(self.audio_in_address)
         self.audio_in_poller = SocketPoller[bytes](self.audio_in_socket)
 
-    def _connect_audio_out_socket(self) -> int | None:
+    def _connect_audio_out_socket(self) -> str | None:
         """
-        Returns the port bound, or None if binding failed.
+        Returns the address that was bound to, or None if binding failed.
         """
         try:
             self.audio_out_socket = azmq.Context.instance().socket(zmq.PUB)
-            return self.audio_out_socket.bind_to_random_port("tcp://localhost", max_tries=100)
+            self.audio_out_socket.bind(settings.zmq_settings.vad_pub_address)
+            return settings.zmq_settings.vad_pub_address
         except zmq.ZMQBindError:
             self.logger.error("Failed to bind an audio output socket after 100 tries.")
             self.audio_out_socket = None

src/control_backend/core/config.py

@@ -1,3 +1,12 @@
+"""
+An exhaustive overview of configurable options. All of these can be set using environment variables
+by nesting with double underscores (__). Start from the ``Settings`` class.
+
+For example, ``settings.ri_host`` becomes ``RI_HOST``, and
+``settings.zmq_settings.ri_communication_address`` becomes
+``ZMQ_SETTINGS__RI_COMMUNICATION_ADDRESS``.
+"""
+
 from pydantic import BaseModel
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
@@ -8,16 +17,17 @@ class ZMQSettings(BaseModel):
 
     :ivar internal_pub_address: Address for the internal PUB socket.
     :ivar internal_sub_address: Address for the internal SUB socket.
-    :ivar ri_command_address: Address for sending commands to the Robot Interface.
-    :ivar ri_communication_address: Address for receiving communication from the Robot Interface.
-    :ivar vad_agent_address: Address for the Voice Activity Detection (VAD) agent.
+    :ivar ri_communication_address: Address for the endpoint that the Robot Interface connects to.
+    :ivar vad_pub_address: Address that the VAD agent binds to and publishes audio segments to.
     """
 
+    # ATTENTION: When adding/removing settings, make sure to update the .env.example file
+
     internal_pub_address: str = "tcp://localhost:5560"
     internal_sub_address: str = "tcp://localhost:5561"
-    ri_command_address: str = "tcp://localhost:0000"
     ri_communication_address: str = "tcp://*:5555"
     internal_gesture_rep_adress: str = "tcp://localhost:7788"
+    vad_pub_address: str = "inproc://vad_stream"
 
 
 class AgentSettings(BaseModel):
@@ -36,6 +46,8 @@ class AgentSettings(BaseModel):
     :ivar robot_speech_name: Name of the Robot Speech Agent.
     """
 
+    # ATTENTION: When adding/removing settings, make sure to update the .env.example file
+
     # agent names
     bdi_core_name: str = "bdi_core_agent"
     bdi_belief_collector_name: str = "belief_collector_agent"
@@ -67,6 +79,8 @@ class BehaviourSettings(BaseModel):
     :ivar transcription_token_buffer: Buffer for transcription tokens.
     """
 
+    # ATTENTION: When adding/removing settings, make sure to update the .env.example file
+
     sleep_s: float = 1.0
     comm_setup_max_retries: int = 5
     socket_poller_timeout_ms: int = 100
@@ -91,6 +105,8 @@ class LLMSettings(BaseModel):
     :ivar local_llm_model: Name of the local LLM model to use.
     """
 
+    # ATTENTION: When adding/removing settings, make sure to update the .env.example file
+
     local_llm_url: str = "http://localhost:1234/v1/chat/completions"
     local_llm_model: str = "gpt-oss"
 
@@ -104,6 +120,8 @@ class VADSettings(BaseModel):
     :ivar sample_rate_hz: Sample rate in Hz for the VAD model.
     """
 
+    # ATTENTION: When adding/removing settings, make sure to update the .env.example file
+
     repo_or_dir: str = "snakers4/silero-vad"
     model_name: str = "silero_vad"
     sample_rate_hz: int = 16000
@@ -117,6 +135,8 @@ class SpeechModelSettings(BaseModel):
     :ivar openai_model_name: Model name for OpenAI-based speech recognition.
     """
 
+    # ATTENTION: When adding/removing settings, make sure to update the .env.example file
+
     # model identifiers for speech recognition
     mlx_model_name: str = "mlx-community/whisper-small.en-mlx"
     openai_model_name: str = "small.en"
@@ -128,6 +148,7 @@ class Settings(BaseSettings):
 
     :ivar app_title: Title of the application.
     :ivar ui_url: URL of the frontend UI.
+    :ivar ri_host: The hostname of the Robot Interface.
     :ivar zmq_settings: ZMQ configuration.
     :ivar agent_settings: Agent name configuration.
     :ivar behaviour_settings: Behavior configuration.
@@ -140,6 +161,8 @@ class Settings(BaseSettings):
 
     ui_url: str = "http://localhost:5173"
 
+    ri_host: str = "localhost"
+
     zmq_settings: ZMQSettings = ZMQSettings()
 
     agent_settings: AgentSettings = AgentSettings()