refactor: Crush improved type hints and error handling — 815 lines

6 files improved: studio_engine.py, fleet_integration.py, and 4 others.

Author: SuperInstance

client.py

@@ -16,16 +16,33 @@
 
 
 class MUDClient:
-    """Async MUD client for programmatic agent access."""
+    """Async MUD client for programmatic agent access.
+    
+    Provides a Python interface for connecting to a MUD server
+    and executing commands programmatically, useful for bots,
+    automated agents, and testing scripts.
+    
+    Example usage:
+        async with MUDClient("oracle1") as mud:
+            await mud.say("Anyone want to hash out ISA v3?")
+    """
 
-    def __init__(self, name: str, role: str = "", host: str = "localhost", port: int = 7777):
+    def __init__(self, name: str, role: str = "", host: str = "localhost", port: int = 7777) -> None:
+        """Initialize MUD client.
+        
+        Args:
+            name: Agent name for login
+            role: Agent role (optional)
+            host: MUD server host (default: localhost)
+            port: MUD server port (default: 7777)
+        """
         self.name = name
         self.role = role
         self.host = host
         self.port = port
         self.reader = None
         self.writer = None
-        self._buffer = []
+        self._buffer: List[str] = []
 
     async def __aenter__(self):
         self.reader, self.writer = await asyncio.open_connection(self.host, self.port)
@@ -48,11 +65,25 @@ async def __aexit__(self, *args):
             self.writer.close()
 
     async def _send(self, cmd: str) -> str:
-        """Send a command and return the response."""
+        """Send a command and return the response.
+        
+        Args:
+            cmd: Command string to send to MUD
+            
+        Returns:
+            str: The response from the server
+            
+        Raises:
+            ConnectionError: If connection is lost
+        """
+        if not self.writer:
+            raise ConnectionError("Not connected to MUD server")
+            
         self.writer.write(f"{cmd}\n".encode())
         await self.writer.drain()
+        
         # Read response(s) until prompt or timeout
-        lines = []
+        lines: List[str] = []
         try:
             while True:
                 line = await asyncio.wait_for(self.reader.readline(), timeout=1.0)
@@ -63,48 +94,64 @@ async def _send(self, cmd: str) -> str:
                     lines.append(decoded)
         except asyncio.TimeoutError:
             pass
+        except ConnectionResetError:
+            raise ConnectionError("Connection reset by server")
+            
         return "\n".join(lines)
 
     async def say(self, text: str) -> str:
+        """Send a say command (room-wide message)."""
         return await self._send(f'say {text}')
 
     async def tell(self, target: str, text: str) -> str:
+        """Send a tell command (private message to an agent)."""
         return await self._send(f'tell {target} {text}')
 
     async def gossip(self, text: str) -> str:
+        """Send a gossip command (ship-wide broadcast)."""
         return await self._send(f'gossip {text}')
 
     async def ooc(self, text: str) -> str:
+        """Send an OOC command (out-of-character message)."""
         return await self._send(f'ooc {text}')
 
     async def emote(self, action: str) -> str:
+        """Send an emote command (roleplay action)."""
         return await self._send(f'emote {action}')
 
     async def go(self, exit_name: str) -> str:
+        """Move to an adjacent room via an exit."""
         return await self._send(f'go {exit_name}')
 
     async def look(self) -> str:
+        """Look around the current room."""
         return await self._send('look')
 
     async def build(self, name: str, desc: str) -> str:
+        """Create a new room."""
         return await self._send(f'build "{name}" -desc "{desc}"')
 
     async def write_note(self, text: str) -> str:
+        """Write a note on the room's wall."""
         return await self._send(f'write {text}')
 
     async def read_notes(self) -> str:
+        """Read notes from the room's wall."""
         return await self._send('read')
 
     async def mask(self, name: str, desc: str = "") -> str:
+        """Put on a character mask."""
         cmd = f'mask "{name}"'
         if desc:
             cmd += f' -desc "{desc}"'
         return await self._send(cmd)
 
     async def unmask(self) -> str:
+        """Remove your character mask."""
         return await self._send('unmask')
 
     async def spawn_npc(self, name: str, role: str = "", topic: str = "") -> str:
+        """Spawn a constructed NPC."""
         cmd = f'spawn "{name}"'
         if role:
             cmd += f' -role "{role}"'
@@ -113,14 +160,23 @@ async def spawn_npc(self, name: str, role: str = "", topic: str = "") -> str:
         return await self._send(cmd)
 
     async def dismiss_npc(self, name: str) -> str:
+        """Dismiss a constructed NPC."""
         return await self._send(f'dismiss {name}')
 
     async def who(self) -> str:
+        """List all connected agents."""
         return await self._send('who')
 
 
-async def interactive(name: str, role: str, host: str, port: int):
-    """Run an interactive session (like telnet but with name auto-filled)."""
+async def interactive(name: str, role: str, host: str, port: int) -> None:
+    """Run an interactive session (like telnet but with name auto-filled).
+    
+    Args:
+        name: Agent name to use
+        role: Agent role
+        host: MUD server host
+        port: MUD server port
+    """
     async with MUDClient(name, role, host, port) as mud:
         print(f"Connected as {name}. Type 'help' for commands.")
         loop = asyncio.get_event_loop()

lcar_cartridge.py

@@ -21,15 +21,25 @@
 
 @dataclass
 class Cartridge:
-    """A swappable behavior cartridge."""
+    """A swappable behavior cartridge for MUD rooms.
+    
+    Attributes:
+        name: Unique identifier for this cartridge
+        description: Human-readable description of what this cartridge does
+        tools: List of available tools/commands for this cartridge
+        onboarding_human: Welcome message for human agents
+        onboarding_agent: Welcome message for AI agents
+        git_repo: Optional GitHub repository URL for this cartridge
+    """
     name: str
     description: str
     tools: List[dict] = field(default_factory=list)
     onboarding_human: str = ""
     onboarding_agent: str = ""
     git_repo: str = ""
 
-    def to_dict(self):
+    def to_dict(self) -> dict:
+        """Convert cartridge to dictionary for serialization."""
         return {
             "name": self.name,
             "description": self.description,
@@ -42,18 +52,32 @@ def to_dict(self):
 
 @dataclass
 class Skin:
-    """A personality skin — maps to MUD formality + personality."""
+    """A personality skin that maps to MUD formality mode.
+    
+    Attributes:
+        name: Unique skin identifier
+        description: Human-readable description of this personality
+        formality: MUD formality level (NAVAL, PROFESSIONAL, TNG, CASUAL, MINIMAL)
+        system_prompt_suffix: Optional suffix to add to system prompts
+        temperature: AI temperature for this skin (0.0-1.0)
+        tool_preferences: Optional weights for tool selection
+    """
     name: str
     description: str
-    formality: str = "TNG"  # NAVAL, PROFESSIONAL, TNG, CASUAL, MINIMAL
+    formality: str = "TNG"
     system_prompt_suffix: str = ""
     temperature: float = 0.7
     tool_preferences: Dict[str, float] = field(default_factory=dict)
 
 
-@dataclass  
+@dataclass
 class Scene:
-    """A complete scene: ROOM × CARTRIDGE × SKIN × MODEL × TIME"""
+    """A complete scene configuration: ROOM × CARTRIDGE × SKIN × MODEL × TIME.
+    
+    Represents a room's active configuration at a specific time,
+    combining cartridge (behavior), skin (personality), model (AI),
+    and schedule (when this is active).
+    """
     room_id: str
     cartridge_name: str
     skin_name: str
@@ -63,18 +87,22 @@ class Scene:
 
 
 class CartridgeBridge:
-    """Bridges cartridge-mcp to FLUX-LCAR MUD."""
+    """Bridges cartridge-mcp to FLUX-LCAR MUD.
+    
+    Manages cartridges, skins, and scenes, allowing MUD rooms
+    to change behavior dynamically by loading different cartridges.
+    """
 
-    def __init__(self):
+    def __init__(self) -> None:
+        """Initialize cartridge bridge with defaults."""
         self.cartridges: Dict[str, Cartridge] = {}
         self.skins: Dict[str, Skin] = {}
         self.scenes: List[Scene] = []
-        self.active_scenes: Dict[str, Scene] = {}  # room_id -> active scene
-        
-        # Register built-in cartridges
+        self.active_scenes: Dict[str, Scene] = {}
         self._register_defaults()
 
-    def _register_defaults(self):
+    def _register_defaults(self) -> None:
+        """Register built-in cartridges and skins from JC1's cartridge-mcp."""
         # Cartridges from JC1's cartridge-mcp
         self.register_cartridge(Cartridge(
             name="spreader-loop",
@@ -138,20 +166,49 @@ def _register_defaults(self):
         self.register_skin(Skin("rival", "Competitive rival", "TNG", temperature=0.85))
         self.register_skin(Skin("field-commander", "Military field commander", "NAVAL", temperature=0.5))
 
-    def register_cartridge(self, cart: Cartridge):
+    def register_cartridge(self, cart: Cartridge) -> None:
+        """Register a cartridge.
+        
+        Args:
+            cart: Cartridge instance to register
+        """
         self.cartridges[cart.name] = cart
 
-    def register_skin(self, skin: Skin):
+    def register_skin(self, skin: Skin) -> None:
+        """Register a personality skin.
+        
+        Args:
+            skin: Skin instance to register
+        """
         self.skins[skin.name] = skin
 
     def build_scene(self, room_id: str, cartridge: str, skin: str, 
                     model: str, schedule: str = "always") -> Scene:
+        """Build and register a new scene.
+        
+        Args:
+            room_id: Room identifier where this scene applies
+            cartridge: Name of the cartridge to use
+            skin: Name of the personality skin
+            model: AI model to use for this scene
+            schedule: When this scene should be active
+            
+        Returns:
+            The created Scene object
+        """
         scene = Scene(room_id, cartridge, skin, model, schedule)
         self.scenes.append(scene)
         return scene
 
     def activate_scene(self, room_id: str) -> Optional[Scene]:
-        """Activate the best scene for a room based on current time."""
+        """Activate the best scene for a room based on current time.
+        
+        Args:
+            room_id: Room identifier to activate scene for
+            
+        Returns:
+            Scene if one was activated, None if no scenes available
+        """
         candidates = [s for s in self.scenes if s.room_id == room_id]
         if not candidates:
             return None
@@ -177,7 +234,14 @@ def activate_scene(self, room_id: str) -> Optional[Scene]:
         return scene
 
     def get_mud_config(self, room_id: str) -> dict:
-        """Get the MUD room configuration from active scene."""
+        """Get the MUD room configuration from active scene.
+        
+        Args:
+            room_id: Room identifier to get config for
+            
+        Returns:
+            Configuration dictionary with cartridge, skin, model, schedule, and commands
+        """
         scene = self.active_scenes.get(room_id)
         if not scene:
             return {}