mindroom 0.0.0__py3-none-any.whl → 0.1.0__py3-none-any.whl

mindroom/tools_metadata.py

@@ -0,0 +1,220 @@
+"""Tool metadata and enhanced registration system."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Literal
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from agno.tools import Toolkit
+
+from mindroom.credentials import get_credentials_manager
+
+# Registry mapping tool names to their factory functions
+TOOL_REGISTRY: dict[str, Callable[[], type[Toolkit]]] = {}
+
+
+def register_tool(name: str) -> Callable[[Callable[[], type[Toolkit]]], Callable[[], type[Toolkit]]]:
+    """Decorator to register a tool factory function.
+
+    Args:
+        name: The name to register the tool under
+
+    Returns:
+        Decorator function
+
+    """
+
+    def decorator(func: Callable[[], type[Toolkit]]) -> Callable[[], type[Toolkit]]:
+        TOOL_REGISTRY[name] = func
+        return func
+
+    return decorator
+
+
+def get_tool_by_name(tool_name: str) -> Toolkit:
+    """Get a tool instance by its registered name."""
+    if tool_name not in TOOL_REGISTRY:
+        available = ", ".join(sorted(TOOL_REGISTRY.keys()))
+        msg = f"Unknown tool: {tool_name}. Available tools: {available}"
+        raise ValueError(msg)
+
+    try:
+        tool_factory = TOOL_REGISTRY[tool_name]
+        tool_class = tool_factory()
+
+        creds_manager = get_credentials_manager()
+        credentials = creds_manager.load_credentials(tool_name) or {}
+        metadata = TOOL_METADATA[tool_name]
+
+        init_kwargs = {}
+        if metadata.config_fields:
+            for field in metadata.config_fields:
+                if field.name in credentials:
+                    init_kwargs[field.name] = credentials[field.name]
+
+        return tool_class(**init_kwargs)
+
+    except ImportError as e:
+        logger.warning(f"Could not import tool '{tool_name}': {e}")
+        logger.warning(f"Make sure the required dependencies are installed for {tool_name}")
+        raise
+
+
+class ToolCategory(str, Enum):
+    """Tool categories for organization."""
+
+    EMAIL = "email"
+    SHOPPING = "shopping"
+    ENTERTAINMENT = "entertainment"
+    SOCIAL = "social"
+    DEVELOPMENT = "development"
+    RESEARCH = "research"
+    INFORMATION = "information"
+    PRODUCTIVITY = "productivity"
+    COMMUNICATION = "communication"
+    INTEGRATIONS = "integrations"
+    SMART_HOME = "smart_home"
+
+
+class ToolStatus(str, Enum):
+    """Tool availability status."""
+
+    AVAILABLE = "available"
+    COMING_SOON = "coming_soon"
+    REQUIRES_CONFIG = "requires_config"
+
+
+class SetupType(str, Enum):
+    """Tool setup type."""
+
+    NONE = "none"  # No setup required
+    API_KEY = "api_key"  # Requires API key
+    OAUTH = "oauth"  # OAuth flow
+    SPECIAL = "special"  # Special setup (e.g., for Google)
+    COMING_SOON = "coming_soon"  # Not yet available
+
+
+@dataclass
+class ConfigField:
+    """Definition of a configuration field."""
+
+    name: str  # Environment variable name (e.g., "SMTP_HOST")
+    label: str  # Display label (e.g., "SMTP Host")
+    type: Literal["boolean", "number", "password", "text", "url", "select"] = "text"
+    required: bool = True
+    default: Any = None
+    placeholder: str | None = None
+    description: str | None = None
+    options: list[dict[str, str]] | None = None  # For select type
+    validation: dict[str, Any] | None = None  # min, max, pattern, etc.
+
+
+@dataclass
+class ToolMetadata:
+    """Complete metadata for a tool."""
+
+    name: str  # Internal tool name (e.g., "gmail")
+    display_name: str  # Display name (e.g., "Gmail")
+    description: str  # Description for UI
+    category: ToolCategory
+    status: ToolStatus = ToolStatus.AVAILABLE
+    setup_type: SetupType = SetupType.NONE
+    icon: str | None = None  # Icon identifier for frontend
+    icon_color: str | None = None  # Tailwind color class like "text-blue-500"
+    config_fields: list[ConfigField] | None = None  # Detailed field definitions
+    dependencies: list[str] | None = None  # Required pip packages
+    auth_provider: str | None = None  # Name of integration that provides auth (e.g., "google")
+    docs_url: str | None = None  # Documentation URL
+    helper_text: str | None = None  # Additional help text for setup
+    factory: Callable | None = None  # Factory function to create tool instance
+
+
+# Global registry for tool metadata
+TOOL_METADATA: dict[str, ToolMetadata] = {}
+
+
+def register_tool_with_metadata(
+    *,
+    name: str,
+    display_name: str,
+    description: str,
+    category: ToolCategory,
+    status: ToolStatus = ToolStatus.AVAILABLE,
+    setup_type: SetupType = SetupType.NONE,
+    icon: str | None = None,
+    icon_color: str | None = None,
+    config_fields: list[ConfigField] | None = None,
+    dependencies: list[str] | None = None,
+    auth_provider: str | None = None,
+    docs_url: str | None = None,
+    helper_text: str | None = None,
+) -> Callable[[Callable[[], type]], Callable[[], type]]:
+    """Decorator to register a tool with metadata.
+
+    This decorator stores comprehensive metadata about tools that can be used
+    by the frontend and other components.
+
+    Args:
+        name: Tool identifier used in registry
+        display_name: Human-readable name for UI
+        description: Brief description of what the tool does
+        category: Tool category for organization
+        status: Availability status of the tool
+        setup_type: Type of setup required
+        icon: Icon identifier for frontend
+        icon_color: CSS color class for the icon
+        config_fields: List of configuration fields
+        dependencies: Required Python packages
+        auth_provider: Name of integration that provides authentication
+        docs_url: Link to documentation
+        helper_text: Additional setup instructions
+
+    Returns:
+        Decorator function
+
+    """
+
+    def decorator(func: Callable) -> Callable:
+        # Create metadata object
+        metadata = ToolMetadata(
+            name=name,
+            display_name=display_name,
+            description=description,
+            category=category,
+            status=status,
+            setup_type=setup_type,
+            icon=icon,
+            icon_color=icon_color,
+            config_fields=config_fields,
+            dependencies=dependencies,
+            auth_provider=auth_provider,
+            docs_url=docs_url,
+            helper_text=helper_text,
+            factory=func,
+        )
+
+        # Store in metadata registry
+        TOOL_METADATA[name] = metadata
+
+        # Also register in TOOL_REGISTRY for actual tool loading
+        TOOL_REGISTRY[name] = func
+
+        return func
+
+    return decorator
+
+
+def get_tool_metadata(name: str) -> ToolMetadata | None:
+    """Get metadata for a tool by name."""
+    return TOOL_METADATA.get(name)
+
+
+def get_all_tool_metadata() -> dict[str, ToolMetadata]:
+    """Get all tool metadata."""
+    return TOOL_METADATA.copy()

mindroom/topic_generator.py

@@ -0,0 +1,153 @@
+"""Generate contextual topics for Matrix rooms using AI."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import nio
+from agno.agent import Agent
+from pydantic import BaseModel, Field
+
+from mindroom.ai import _cached_agent_run, get_model_instance
+from mindroom.constants import STORAGE_PATH_OBJ
+from mindroom.logging_config import get_logger
+
+if TYPE_CHECKING:
+    from mindroom.config import Config
+
+logger = get_logger(__name__)
+
+
+class RoomTopic(BaseModel):
+    """Structured room topic response."""
+
+    topic: str = Field(description="The room topic - concise, informative, with emoji")
+
+
+async def generate_room_topic_ai(room_key: str, room_name: str, config: Config) -> str | None:
+    """Generate a contextual topic for a room using AI based on its purpose and configured agents.
+
+    Args:
+        room_key: The room key/alias (e.g., 'dev', 'analysis', 'lobby')
+        room_name: Display name for the room
+        config: Configuration with agent settings
+
+    Returns:
+        A contextual topic string for the room
+
+    """
+    # Get agents configured for this room
+    agents_in_room = []
+    for agent_name, agent_config in config.agents.items():
+        if room_key in agent_config.rooms:
+            display_name = agent_config.display_name or agent_name
+            agents_in_room.append(display_name)
+
+    # Build agent list for the prompt
+    agent_list = ", ".join(agents_in_room)
+
+    prompt = f"""Generate a concise, informative room topic for a MindRoom Matrix room.
+
+Context about MindRoom:
+MindRoom is a platform that frees AI agents from being trapped in single apps. Key features:
+- AI agents with persistent memory that work across all platforms (Slack, Discord, Telegram, WhatsApp)
+- Agents collaborate naturally in threads and remember everything across sessions
+- Built on Matrix protocol for secure, federated communication
+- 80+ integrations with tools like Gmail, GitHub, Spotify, Home Assistant
+- Self-hosted or cloud options with military-grade encryption
+
+Room details:
+- Room key/alias: {room_key}
+- Room name: {room_name}
+- Configured agents: {agent_list if agent_list else "No specific agents configured yet"}
+
+Create a topic that:
+1. Describes the room's purpose based on its name
+2. Mentions the AI agents or capabilities available
+3. Highlights MindRoom's persistent memory or cross-platform nature when relevant
+4. Is welcoming and informative
+5. Uses 1-2 relevant emojis
+6. Is under 100 characters
+7. Follows this format: [emoji] [Description] • [Capabilities/Purpose]
+
+Examples:
+- 💻 Development Hub • AI agents that remember your code patterns across sessions
+- 📊 Analysis Center • Persistent insights with cross-platform data access
+- 🏠 Main Lobby • Your AI team headquarters with continuous memory
+- 💰 Finance Room • AI agents tracking markets 24/7 with full context
+- 🔬 Research Lab • Collaborative AI exploration with shared knowledge
+
+Generate the topic:"""
+
+    model = get_model_instance(config, "default")
+
+    agent = Agent(
+        name="TopicGenerator",
+        role="Generate contextual room topics",
+        model=model,
+        response_model=RoomTopic,
+    )
+
+    session_id = f"topic_{room_key}"
+    try:
+        response = await _cached_agent_run(
+            agent=agent,
+            full_prompt=prompt,
+            session_id=session_id,
+            agent_name="TopicGenerator",
+            storage_path=STORAGE_PATH_OBJ,
+        )
+    except Exception:
+        logger.exception(f"Error generating topic for room {room_key}")
+        return None
+    content = response.content
+    assert isinstance(content, RoomTopic)  # Type narrowing for mypy
+    return content.topic
+
+
+async def ensure_room_has_topic(
+    client: nio.AsyncClient,
+    room_id: str,
+    room_key: str,
+    room_name: str,
+    config: Config,
+) -> bool:
+    """Ensure a room has a topic set, generating one if needed.
+
+    Args:
+        client: Matrix client
+        room_id: The room ID
+        room_key: The room key/alias
+        room_name: Display name for the room
+        config: Configuration with agent settings
+
+    Returns:
+        True if topic was set or already exists, False on error
+
+    """
+    # Check if room already has a topic
+    response = await client.room_get_state_event(room_id, "m.room.topic")
+    if isinstance(response, nio.RoomGetStateEventResponse) and response.content.get("topic"):
+        logger.debug(f"Room {room_key} already has topic: {response.content['topic']}")
+        return True
+
+    # Generate and set topic
+    logger.info(f"Generating AI topic for existing room {room_key}")
+    topic = await generate_room_topic_ai(room_key, room_name, config)
+    if topic is None:
+        logger.warning(f"Failed to generate topic for room {room_key}")
+        return False
+
+    # Set the topic
+    response = await client.room_put_state(
+        room_id=room_id,
+        event_type="m.room.topic",
+        content={"topic": topic},
+    )
+
+    if isinstance(response, nio.RoomPutStateResponse):
+        logger.info(f"Set topic for room {room_key}: {topic}")
+        return True
+
+    logger.warning(f"Failed to set topic for room {room_key}: {response}")
+    return False

mindroom/voice_handler.py

@@ -0,0 +1,266 @@
+"""Voice message handler with speech-to-text and intelligent command recognition."""
+
+from __future__ import annotations
+
+import os
+import ssl
+import tempfile
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import aiofiles
+import aiohttp
+import nio
+from agno.agent import Agent
+from nio import crypto
+
+from .ai import get_model_instance
+from .commands import get_command_list
+from .constants import VOICE_PREFIX
+from .logging_config import get_logger
+
+if TYPE_CHECKING:
+    from .config import Config
+
+logger = get_logger(__name__)
+
+
+async def handle_voice_message(
+    client: nio.AsyncClient,
+    room: nio.MatrixRoom,  # noqa: ARG001
+    event: nio.RoomMessageAudio | nio.RoomEncryptedAudio,
+    config: Config,
+) -> str | None:
+    """Handle a voice message event.
+
+    Args:
+        client: Matrix client
+        room: Matrix room
+        event: Voice message event
+        config: Application configuration
+
+    Returns:
+        The transcribed and formatted message, or None if transcription failed
+
+    """
+    if not config.voice.enabled:
+        return None
+
+    try:
+        # Download the audio file
+        audio_data = await _download_audio(client, event)
+        if not audio_data:
+            logger.error("Failed to download audio file")
+            return None
+
+        # Transcribe the audio
+        transcription = await _transcribe_audio(audio_data, config)
+        if not transcription:
+            logger.warning("Failed to transcribe audio or empty transcription")
+            return None
+
+        logger.info(f"Raw transcription: {transcription}")
+
+        # Process transcription with AI for command/agent recognition
+        formatted_message = await _process_transcription(transcription, config)
+
+        logger.info(f"Formatted message: {formatted_message}")
+
+        if formatted_message:
+            # Add a note that this was transcribed from voice
+            return f"{VOICE_PREFIX}{formatted_message}"
+
+    except Exception:
+        logger.exception("Error handling voice message")
+        return None
+    return None
+
+
+async def _download_audio(
+    client: nio.AsyncClient,
+    event: nio.RoomMessageAudio | nio.RoomEncryptedAudio,
+) -> bytes | None:
+    """Download and decrypt audio file from Matrix.
+
+    Args:
+        client: Matrix client
+        event: Audio event
+
+    Returns:
+        Audio file bytes or None if failed
+
+    """
+    try:
+        # Unencrypted audio
+        mxc = event.url
+        response = await client.download(mxc)
+        if isinstance(response, nio.DownloadError):
+            logger.error(f"Download failed: {response}")
+            return None
+        if isinstance(event, nio.RoomMessageAudio):
+            return response.body  # type: ignore[no-any-return]
+
+        assert isinstance(event, nio.RoomEncryptedAudio)
+        # Decrypt the audio
+        return crypto.attachments.decrypt_attachment(  # type: ignore[no-any-return]
+            response.body,
+            event.source["content"]["file"]["key"]["k"],
+            event.source["content"]["file"]["hashes"]["sha256"],
+            event.source["content"]["file"]["iv"],
+        )
+
+    except Exception:
+        logger.exception("Error downloading audio")
+    return None
+
+
+async def _transcribe_audio(audio_data: bytes, config: Config) -> str | None:
+    """Transcribe audio using OpenAI-compatible API.
+
+    Args:
+        audio_data: Audio file bytes
+        config: Application configuration
+
+    Returns:
+        Transcription text or None if failed
+
+    """
+    try:
+        # Save audio to temporary file (required by most STT APIs)
+        with tempfile.NamedTemporaryFile(suffix=".ogg", delete=False) as tmp_file:
+            tmp_file.write(audio_data)
+            tmp_path = tmp_file.name
+
+        try:
+            # Use OpenAI-compatible API for transcription
+            stt_host = config.voice.stt.host
+            if stt_host:
+                # Self-hosted solution
+                url = f"{stt_host}/v1/audio/transcriptions"
+            else:
+                # OpenAI or compatible cloud service
+                url = "https://api.openai.com/v1/audio/transcriptions"
+
+            api_key = config.voice.stt.api_key or os.getenv("OPENAI_API_KEY")
+            headers = {"Authorization": f"Bearer {api_key}"}
+
+            # Prepare multipart form data
+            async with aiofiles.open(tmp_path, "rb") as audio_file:
+                audio_content = await audio_file.read()
+
+            data = aiohttp.FormData()
+            data.add_field("file", audio_content, filename="audio.ogg", content_type="audio/ogg")
+            data.add_field("model", config.voice.stt.model)
+
+            # Make the API request (with SSL verification disabled if needed)
+            ssl_context = ssl.create_default_context()
+            ssl_context.check_hostname = False
+            ssl_context.verify_mode = ssl.CERT_NONE
+
+            connector = aiohttp.TCPConnector(ssl=ssl_context)
+            async with (
+                aiohttp.ClientSession(connector=connector) as session,
+                session.post(url, headers=headers, data=data) as response,
+            ):
+                if response.status != 200:
+                    error_text = await response.text()
+                    logger.error(f"STT API error: {response.status} - {error_text}")
+                    return None
+
+                result = await response.json()
+                return result.get("text", "").strip()  # type: ignore[no-any-return]
+
+        finally:
+            # Clean up temporary file
+            Path(tmp_path).unlink()
+
+    except Exception:
+        logger.exception("Error transcribing audio")
+        return None
+
+
+async def _process_transcription(transcription: str, config: Config) -> str:
+    """Process transcription to recognize commands and agent names.
+
+    Args:
+        transcription: Raw transcription text
+        config: Application configuration
+
+    Returns:
+        Formatted message with proper commands and mentions
+
+    """
+    try:
+        # Get list of available agents and teams
+        agent_names = list(config.agents.keys())
+        agent_display_names = {name: cfg.display_name for name, cfg in config.agents.items()}
+
+        team_names = list(config.teams.keys()) if config.teams else []
+        team_display_names = {name: cfg.display_name for name, cfg in config.teams.items()} if config.teams else {}
+
+        # Build the prompt for the AI
+        prompt = f"""You are a voice command processor for a Matrix chat bot system.
+Your task is to convert spoken transcriptions into properly formatted chat commands.
+
+Available agents (use EXACT agent name after @):
+{chr(10).join([f"  - @{name} or @mindroom_{name} (spoken as: {agent_display_names[name]})" for name in agent_names])}
+
+Available teams (use EXACT team name after @):
+{chr(10).join([f"  - @{name} (spoken as: {team_display_names[name]})" for name in team_names]) if team_names else "  (none)"}
+
+Examples of correct formatting:
+- User says "HomeAssistant turn on the fan" → "@home turn on the fan"  (NOT @homeassistant)
+- User says "schedule turn off the lights in 10 minutes" → "!schedule in 10 minutes turn off the lights"
+- User says "hey home assistant agent schedule to turn off the guest room lights in 10 seconds" → "!schedule in 10 seconds @home turn off the guest room lights"
+- User says "cancel schedule ABC123" → "!cancel_schedule ABC123"
+- User says "list my schedules" → "!list_schedules"
+
+{get_command_list()}
+
+CRITICAL RULES:
+1. ALWAYS use the EXACT agent name (the part before the parentheses) after @, NOT the display name
+   - If agent is listed as "@home (spoken as: HomeAssistant)", use "@home" NOT "@homeassistant"
+2. If the user speaks a command, format it as !command
+3. !schedule commands MUST include a time (in X minutes, at 3pm, tomorrow, etc.)
+   - The time should come right after !schedule
+4. When both command AND agent are mentioned, command comes FIRST
+5. Agent mentions come FIRST when just addressing them (no command):
+   - "research agent, find papers" → "@research find papers"
+   - "ask the email agent to check mail" → "@email check mail"
+6. Fix common speech recognition errors (e.g., "at research" → "@research")
+7. Be smart about intent - "ask the research agent" means "@research"
+8. Keep the natural language but add proper formatting
+9. If unclear, prefer natural language over forcing commands
+
+Transcription: "{transcription}"
+
+Output the formatted message only, no explanation:"""
+
+        # Get the AI model to process the transcription
+        model = get_model_instance(config, config.voice.intelligence.model)
+
+        # Create an agent for voice command processing
+        agent = Agent(
+            name="VoiceCommandProcessor",
+            role="Convert voice transcriptions to properly formatted chat commands",
+            model=model,
+        )
+
+        # Process the transcription with the agent
+        session_id = f"voice_process_{uuid.uuid4()}"
+        response = await agent.arun(prompt, session_id=session_id)
+
+        # Extract the content from the response
+        if response and response.content:
+            return response.content.strip()  # type: ignore[no-any-return]
+
+    except Exception as e:
+        logger.exception("Error processing transcription")
+        # Return error message so user knows what happened
+        from .error_handling import get_user_friendly_error_message  # noqa: PLC0415
+
+        return get_user_friendly_error_message(e, "VoiceProcessor")
+    else:
+        # Return original transcription if no valid response from model
+        return transcription