codetether 1.2.2__py3-none-any.whl

codetether_voice_agent/functiongemma_caller.py

@@ -0,0 +1,380 @@
+"""FunctionGemma caller module for local function calling inference.
+
+This module provides integration with Google's FunctionGemma model
+(google/functiongemma-270m-it) for parsing user intent into structured
+function calls for the CodeTether voice agent system.
+
+The module implements lazy loading of the model to ensure efficient
+resource usage, loading the model only when first needed.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any, Dict, List, Optional
+
+import torch
+from transformers import AutoModelForCausalLM, AutoProcessor
+
+logger = logging.getLogger(__name__)
+
+CODETETHER_TOOLS: List[Dict[str, Any]] = [
+    {
+        'name': 'create_task',
+        'description': 'Create a new task for an agent to execute',
+        'parameters': {
+            'type': 'object',
+            'properties': {
+                'title': {
+                    'type': 'string',
+                    'description': 'The title of the task',
+                },
+                'description': {
+                    'type': 'string',
+                    'description': 'Detailed description of what the task should accomplish',
+                },
+                'codebase_id': {
+                    'type': 'string',
+                    'description': 'Optional identifier for the codebase context',
+                },
+                'agent_type': {
+                    'type': 'string',
+                    'enum': ['build', 'plan', 'general', 'explore'],
+                    'description': 'The type of agent to handle this task',
+                },
+                'priority': {
+                    'type': 'integer',
+                    'description': 'Task priority (higher values indicate higher priority)',
+                },
+            },
+            'required': ['title'],
+        },
+    },
+    {
+        'name': 'list_tasks',
+        'description': 'List tasks with optional filtering',
+        'parameters': {
+            'type': 'object',
+            'properties': {
+                'status': {
+                    'type': 'string',
+                    'description': 'Filter tasks by status',
+                },
+                'codebase_id': {
+                    'type': 'string',
+                    'description': 'Filter tasks by codebase identifier',
+                },
+            },
+        },
+    },
+    {
+        'name': 'get_task',
+        'description': 'Retrieve details of a specific task',
+        'parameters': {
+            'type': 'object',
+            'properties': {
+                'task_id': {
+                    'type': 'string',
+                    'description': 'The unique identifier of the task',
+                },
+            },
+            'required': ['task_id'],
+        },
+    },
+    {
+        'name': 'cancel_task',
+        'description': 'Cancel an active task',
+        'parameters': {
+            'type': 'object',
+            'properties': {
+                'task_id': {
+                    'type': 'string',
+                    'description': 'The unique identifier of the task to cancel',
+                },
+            },
+            'required': ['task_id'],
+        },
+    },
+    {
+        'name': 'get_session_history',
+        'description': 'Retrieve the message history for a session',
+        'parameters': {
+            'type': 'object',
+            'properties': {
+                'session_id': {
+                    'type': 'string',
+                    'description': 'The unique identifier of the session',
+                },
+            },
+            'required': ['session_id'],
+        },
+    },
+    {
+        'name': 'playback_session',
+        'description': 'Play back a session with optional summarization',
+        'parameters': {
+            'type': 'object',
+            'properties': {
+                'session_id': {
+                    'type': 'string',
+                    'description': 'The unique identifier of the session to playback',
+                },
+                'style': {
+                    'type': 'string',
+                    'enum': ['verbatim', 'summary'],
+                    'description': 'The playback style to use',
+                },
+            },
+            'required': ['session_id'],
+        },
+    },
+    {
+        'name': 'discover_agents',
+        'description': 'Discover available agents in the system',
+        'parameters': {
+            'type': 'object',
+            'properties': {},
+        },
+    },
+    {
+        'name': 'send_message',
+        'description': 'Send a message to a specific agent',
+        'parameters': {
+            'type': 'object',
+            'properties': {
+                'agent_name': {
+                    'type': 'string',
+                    'description': 'The name of the target agent',
+                },
+                'message': {
+                    'type': 'string',
+                    'description': 'The message content to send',
+                },
+            },
+            'required': ['agent_name', 'message'],
+        },
+    },
+]
+
+
+class FunctionGemmaCaller:
+    """Caller for FunctionGemma model for local function calling inference.
+
+    This class provides an interface to the FunctionGemma model for parsing
+    natural language user input into structured function calls. It uses lazy
+    loading to defer model initialization until first use.
+
+    Attributes:
+        model_path: Path to the FunctionGemma model (default: google/functiongemma-270m-it)
+        _model: The loaded model instance (None until first call)
+        _processor: The loaded processor instance (None until first call)
+    """
+
+    def __init__(
+        self, model_path: str = 'google/functiongemma-270m-it'
+    ) -> None:
+        """Initialize the FunctionGemma caller.
+
+        Args:
+            model_path: Path to the FunctionGemma model. Can be a HuggingFace
+                model ID or a local path. Defaults to "google/functiongemma-270m-it".
+        """
+        self.model_path = model_path
+        self._model: Optional[AutoModelForCausalLM] = None
+        self._processor: Optional[AutoProcessor] = None
+
+    def _load_model(self) -> None:
+        """Load the FunctionGemma model and processor.
+
+        This method performs lazy loading of the model and processor on first
+        use. The model is loaded in BF16 precision with automatic device mapping.
+
+        Raises:
+            RuntimeError: If the model fails to load.
+        """
+        if self._model is not None and self._processor is not None:
+            return
+
+        try:
+            logger.info(f'Loading FunctionGemma model from {self.model_path}')
+            self._processor = AutoProcessor.from_pretrained(
+                self.model_path,
+                trust_remote_code=True,
+            )
+            self._model = AutoModelForCausalLM.from_pretrained(
+                self.model_path,
+                torch_dtype=torch.bfloat16,
+                device_map='auto',
+                trust_remote_code=True,
+            )
+            logger.info('FunctionGemma model loaded successfully')
+        except Exception as e:
+            logger.error(f'Failed to load FunctionGemma model: {e}')
+            raise RuntimeError(
+                f'Failed to load FunctionGemma model: {e}'
+            ) from e
+
+    async def parse_intent(self, user_input: str) -> Optional[Dict[str, Any]]:
+        """Parse user input into a structured function call.
+
+        This method takes natural language input from the user and uses
+        FunctionGemma to generate a structured function call.
+
+        Args:
+            user_input: The natural language input from the user.
+
+        Returns:
+            A dictionary containing the function name and arguments if a
+            function call is successfully parsed, None otherwise.
+        """
+        self._load_model()
+
+        if self._model is None or self._processor is None:
+            logger.error('Model not loaded after _load_model() call')
+            return None
+
+        try:
+            messages = [
+                {
+                    'role': 'user',
+                    'content': user_input,
+                },
+            ]
+
+            input_text = self._processor.apply_chat_template(
+                messages,
+                tokenize=False,
+                add_generation_prompt=True,
+            )
+
+            inputs = self._processor(
+                input_text,
+                return_tensors='pt',
+            ).to(self._model.device)
+
+            outputs = self._model.generate(
+                **inputs,
+                max_new_tokens=256,
+                do_sample=False,
+                temperature=None,
+                top_p=None,
+            )
+
+            generated_text = self._processor.decode(
+                outputs[0],
+                skip_special_tokens=False,
+            )
+
+            function_call = self._parse_function_call(generated_text)
+
+            if function_call:
+                logger.info(f'Parsed function call: {function_call}')
+            else:
+                logger.debug(
+                    f'No function call found in output: {generated_text}'
+                )
+
+            return function_call
+
+        except Exception as e:
+            logger.error(f'Error during intent parsing: {e}')
+            return None
+
+    def _parse_function_call(self, output: str) -> Optional[Dict[str, Any]]:
+        """Parse FunctionGemma output format into a structured dictionary.
+
+        The FunctionGemma output format uses special tokens to delimit
+        function calls:
+        <start_function_call>call:func_name{arg1:<escape>value1<escape>,...}<end_function_call>
+
+        Args:
+            output: The raw text output from FunctionGemma.
+
+        Returns:
+            A dictionary with 'name' and 'args' keys if a valid function call
+            is found, None otherwise.
+        """
+        start_tag = '<start_function_call>'
+        end_tag = '<end_function_call>'
+
+        start_idx = output.find(start_tag)
+        end_idx = output.find(end_tag)
+
+        if start_idx == -1 or end_idx == -1:
+            logger.debug(f'No function call markers found in output')
+            return None
+
+        start_idx += len(start_tag)
+        function_call_str = output[start_idx:end_idx]
+
+        func_call_pattern = r'^call:(\w+)\{(.+)\}$'
+        match = re.match(func_call_pattern, function_call_str)
+
+        if not match:
+            logger.debug(f'Invalid function call format: {function_call_str}')
+            return None
+
+        func_name = match.group(1)
+        args_str = match.group(2)
+
+        try:
+            args = self._extract_args(args_str)
+        except Exception as e:
+            logger.error(f'Failed to extract arguments: {e}')
+            return None
+
+        return {'name': func_name, 'args': args}
+
+    def _extract_args(self, args_str: str) -> Dict[str, Any]:
+        """Extract arguments from the function call string.
+
+        Parses argument strings in the format:
+        arg1:<escape>value1<escape>,arg2:<escape>value2<escape>
+
+        Args:
+            args_str: The argument string to parse.
+
+        Returns:
+            A dictionary mapping argument names to their values.
+
+        Raises:
+            ValueError: If the argument string is malformed.
+        """
+        if not args_str.strip():
+            return {}
+
+        args: Dict[str, Any] = {}
+        escape_token = '<escape>'
+
+        while args_str:
+            eq_idx = args_str.find(':')
+
+            if eq_idx == -1:
+                raise ValueError(f'Invalid argument format: {args_str}')
+
+            arg_name = args_str[:eq_idx].strip()
+            args_str = args_str[eq_idx + 1 :]
+
+            if not args_str.startswith(escape_token):
+                raise ValueError(
+                    f"Expected escape token for argument '{arg_name}': {args_str}"
+                )
+
+            args_str = args_str[len(escape_token) :]
+            end_escape_idx = args_str.find(escape_token)
+
+            if end_escape_idx == -1:
+                raise ValueError(
+                    f"Missing closing escape token for argument '{arg_name}'"
+                )
+
+            arg_value = args_str[:end_escape_idx]
+            args[arg_name] = arg_value
+            args_str = args_str[end_escape_idx + len(escape_token) :]
+
+            if args_str.startswith(','):
+                args_str = args_str[1:].strip()
+
+        return args

codetether_voice_agent/session_playback.py

@@ -0,0 +1,247 @@
+"""Session playback module for voice-based replay of historical conversations.
+
+This module provides functionality to playback historical sessions via voice,
+either verbatim or as a summary. It handles message formatting, role-based
+prefixes, and interruption handling for natural conversation flow.
+"""
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from codetether_voice_agent.mcp_client import CodeTetherMCP
+
+logger = logging.getLogger(__name__)
+
+
+class SessionPlayback:
+    """Handles voice playback of historical conversation sessions.
+
+    Provides methods to replay sessions either verbatim (reading each message)
+    or as a summary, with support for natural interruption handling.
+    """
+
+    def __init__(self, mcp_client: 'CodeTetherMCP') -> None:
+        """Initialize the session playback handler.
+
+        Args:
+            mcp_client: The MCP client instance for session operations.
+        """
+        self.mcp_client = mcp_client
+        self._interrupted = False
+        self._playback_task: Optional[asyncio.Task] = None
+
+    async def start(
+        self, session: Any, session_id: str, style: str = 'verbatim'
+    ) -> None:
+        """Start playback of a historical session.
+
+        Main entry point for playing back sessions. Loads session messages
+        from the MCP client and routes to the appropriate playback method.
+
+        Args:
+            session: The session object to use for voice output.
+            session_id: The unique identifier of the session to playback.
+            style: Playback style - "verbatim" or "summary". Defaults to "verbatim".
+
+        Raises:
+            ValueError: If an invalid playback style is specified.
+        """
+        self._interrupted = False
+        logger.info(f'Starting {style} playback for session: {session_id}')
+
+        try:
+            messages = await self._load_session_messages(session_id)
+
+            if not messages:
+                await session.generate_reply(
+                    instructions='This session has no messages to playback.'
+                )
+                return
+
+            if style == 'verbatim':
+                await self.playback_verbatim(session, messages)
+            elif style == 'summary':
+                await self.playback_summary(session, messages)
+            else:
+                raise ValueError(
+                    f"Invalid playback style: {style}. Must be 'verbatim' or 'summary'"
+                )
+
+        except Exception as e:
+            logger.error(f'Error during session playback: {e}')
+            await session.generate_reply(
+                instructions='I encountered an error while trying to playback the session.'
+            )
+
+    async def playback_verbatim(
+        self, session: Any, messages: List[Dict]
+    ) -> None:
+        """Play back messages verbatim with role prefixes.
+
+        Reads each message aloud exactly as it was written, prefixed with
+        "You said:" for user messages or "The agent responded:" for agent messages.
+        Includes brief pauses between messages for natural pacing.
+
+        Args:
+            session: The session object for voice output.
+            messages: List of message dictionaries to playback.
+        """
+        logger.info(f'Starting verbatim playback of {len(messages)} messages')
+
+        for idx, message in enumerate(messages):
+            if self._interrupted:
+                logger.debug('Playback interrupted during verbatim mode')
+                break
+
+            role = message.get('role', 'unknown')
+            content = message.get('content', '')
+
+            if not content:
+                continue
+
+            prefix = self._get_role_prefix(role)
+            text_to_read = f'{prefix} {content}'
+
+            try:
+                await session.generate_reply(
+                    instructions=f'Read this aloud exactly: {text_to_read}'
+                )
+                await asyncio.sleep(0.5)
+
+            except Exception as e:
+                logger.warning(f'Error reading message {idx}: {e}')
+                continue
+
+        if not self._interrupted:
+            await session.generate_reply(
+                instructions='That concludes the playback of this session.'
+            )
+
+    async def playback_summary(
+        self, session: Any, messages: List[Dict]
+    ) -> None:
+        """Play back messages as a natural summary.
+
+        Creates a coherent summary of all messages and reads it aloud
+        in a conversational manner, rather than reading each message verbatim.
+
+        Args:
+            session: The session object for voice output.
+            messages: List of message dictionaries to summarize.
+        """
+        logger.info(f'Starting summary playback of {len(messages)} messages')
+
+        formatted_text = self._format_messages_for_summary(messages)
+
+        summary_prompt = (
+            'Summarize the following conversation in a natural, conversational way. '
+            "Present it as if you're recounting what happened in the conversation. "
+            'Keep it concise but include the key points and exchanges. '
+            f'Here is the conversation:\n\n{formatted_text}'
+        )
+
+        try:
+            await session.generate_reply(instructions=summary_prompt)
+        except Exception as e:
+            logger.error(f'Error generating summary: {e}')
+            await session.generate_reply(
+                instructions='I was unable to generate a summary of this session.'
+            )
+
+    def _format_messages_for_summary(self, messages: List[Dict]) -> str:
+        """Format messages into a readable string for summarization.
+
+        Creates a clean, linear representation of the conversation for
+        the LLM to summarize effectively.
+
+        Args:
+            messages: List of message dictionaries.
+
+        Returns:
+            A formatted string representation of the conversation.
+        """
+        formatted_parts = []
+
+        for message in messages:
+            role = message.get('role', 'unknown')
+            content = message.get('content', '')
+
+            if not content:
+                continue
+
+            prefix = self._get_role_prefix(role)
+            formatted_parts.append(f'{prefix}\n{content}\n')
+
+        return '\n'.join(formatted_parts)
+
+    def _get_role_prefix(self, role: str) -> str:
+        """Get the appropriate role prefix for voice playback.
+
+        Args:
+            role: The role identifier from the message.
+
+        Returns:
+            A human-readable prefix for the role.
+        """
+        role_prefix_map = {
+            'user': 'You said:',
+            'assistant': 'The agent responded:',
+            'agent': 'The agent responded:',
+            'system': 'System note:',
+        }
+
+        return role_prefix_map.get(role, f'{role.capitalize()}:')
+
+    def interrupt(self) -> None:
+        """Signal that playback has been interrupted.
+
+        Sets the interrupted flag to pause or stop current playback.
+        Call this method when user interruption is detected.
+        """
+        self._interrupted = True
+        logger.info('Session playback interruption requested')
+
+    def resume(self) -> None:
+        """Resume playback after interruption.
+
+        Resets the interrupted flag to allow playback to continue.
+        Note: This only resets the flag; actual resuming must be
+        handled by the calling code.
+        """
+        self._interrupted = False
+        logger.info('Session playback interruption cleared')
+
+    def is_interrupted(self) -> bool:
+        """Check if playback is currently interrupted.
+
+        Returns:
+            True if playback is interrupted, False otherwise.
+        """
+        return self._interrupted
+
+    async def _load_session_messages(self, session_id: str) -> List[Dict]:
+        """Load messages for a session from the MCP client.
+
+        Args:
+            session_id: The unique identifier of the session.
+
+        Returns:
+            List of message dictionaries for the session.
+        """
+        try:
+            if hasattr(self.mcp_client, 'get_session_messages'):
+                messages = await self.mcp_client.get_session_messages(
+                    session_id
+                )
+                return messages if messages else []
+            else:
+                logger.warning(
+                    'MCP client does not have get_session_messages method'
+                )
+                return []
+
+        except Exception as e:
+            logger.error(f'Failed to load session messages: {e}')
+            return []

codetether_voice_agent/tools/__init__.py

@@ -0,0 +1,21 @@
+from .handlers import (
+    create_task_handler,
+    list_tasks_handler,
+    get_task_handler,
+    cancel_task_handler,
+    get_session_history_handler,
+    discover_agents_handler,
+    send_message_handler,
+)
+from .handlers import register_all_tools
+
+__all__ = [
+    'create_task_handler',
+    'list_tasks_handler',
+    'get_task_handler',
+    'cancel_task_handler',
+    'get_session_history_handler',
+    'discover_agents_handler',
+    'send_message_handler',
+    'register_all_tools',
+]