feat: limit transcription output length based on input

Using heuristics. Also adds documentation and initial unit tests.

ref: N25B-209

test/unit/conftest.py

@@ -11,6 +11,7 @@ def pytest_configure(config):
     mock_spade = MagicMock()
     mock_spade.agent = MagicMock()
     mock_spade.behaviour = MagicMock()
+    mock_spade.message = MagicMock()
     mock_spade_bdi = MagicMock()
     mock_spade_bdi.bdi = MagicMock()
 
@@ -21,6 +22,7 @@ def pytest_configure(config):
     sys.modules["spade"] = mock_spade
     sys.modules["spade.agent"] = mock_spade.agent
     sys.modules["spade.behaviour"] = mock_spade.behaviour
+    sys.modules["spade.message"] = mock_spade.message
     sys.modules["spade_bdi"] = mock_spade_bdi
     sys.modules["spade_bdi.bdi"] = mock_spade_bdi.bdi
 
@@ -43,3 +45,16 @@ def pytest_configure(config):
     sys.modules["torch"] = mock_torch
     sys.modules["zmq"] = mock_zmq
     sys.modules["zmq.asyncio"] = mock_zmq.asyncio
+
+    # --- Mock whisper ---
+    mock_whisper = MagicMock()
+    mock_mlx = MagicMock()
+    mock_mlx.core = MagicMock()
+    mock_mlx_whisper = MagicMock()
+    mock_mlx_whisper.transcribe = MagicMock()
+
+    sys.modules["whisper"] = mock_whisper
+    sys.modules["mlx"] = mock_mlx
+    sys.modules["mlx.core"] = mock_mlx
+    sys.modules["mlx_whisper"] = mock_mlx_whisper
+    sys.modules["mlx_whisper.transcribe"] = mock_mlx_whisper.transcribe