intentkit 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

intentkit/skills/unrealspeech/text_to_speech.py

@@ -0,0 +1,177 @@
+import logging
+import os
+from typing import Any, Dict, Literal, Optional, Type
+
+import httpx
+from langchain_core.callbacks.manager import CallbackManagerForToolRun
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.unrealspeech.base import UnrealSpeechBaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class TextToSpeechInput(BaseModel):
+    """Input for TextToSpeech tool."""
+
+    text: str = Field(description="The text to convert to speech. Required.")
+
+    voice_id: str = Field(
+        description="The voice ID to use for speech synthesis. Options include: 'af_bella', 'af_sarah', 'af_nicole', 'af_sky', 'am_adam', 'am_michael', 'bf_emma', 'bf_isabella', 'bm_george', 'bm_lewis'.",
+        default="af_sarah",
+    )
+
+    bitrate: str = Field(
+        description="The audio bitrate. Higher values provide better quality but larger file sizes. Options: '64k', '96k', '128k', '192k', '256k', '320k'.",
+        default="192k",
+    )
+
+    speed: float = Field(
+        description="The speech speed adjustment. Range: -1.0 (slower) to 1.0 (faster), with 0.0 being the normal speed.",
+        default=0.0,
+    )
+
+    timestamp_type: Optional[Literal["word", "sentence"]] = Field(
+        description="The type of timestamps to include in the response. 'word' for word-level timestamps, 'sentence' for sentence-level, or None for no timestamps.",
+        default="word",
+    )
+
+
+class TextToSpeech(UnrealSpeechBaseTool):
+    """Tool for converting text to speech using UnrealSpeech's API.
+
+    This tool converts text to natural-sounding speech in various voices.
+    It can generate speech with different voices, speeds, and qualities.
+    The response includes URLs to the audio file and optional word-level timestamps.
+    """
+
+    name: str = "text_to_speech"
+    description: str = (
+        "Converts text to natural-sounding speech using UnrealSpeech.\n"
+        "Use this tool when you need to generate spoken audio from text.\n"
+        "Returns URLs to the generated audio file and word-level timestamps.\n"
+        "Provides various voice options and speech customization parameters."
+    )
+    args_schema: Type[BaseModel] = TextToSpeechInput
+
+    def get_env_var(self, env_var_name: str) -> Optional[str]:
+        """Helper method to get environment variables."""
+        return os.environ.get(env_var_name)
+
+    async def _arun(
+        self,
+        text: str,
+        voice_id: str = "af_sarah",
+        bitrate: str = "192k",
+        speed: float = 0.0,
+        timestamp_type: Optional[Literal["word", "sentence"]] = "word",
+        config: Optional[RunnableConfig] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """Run the tool to convert text to speech."""
+
+        # Get the API key from context config if available
+        context = self.context_from_config(config) if config else None
+        api_key = (
+            context.config.get("api_key", None) if context and context.config else None
+        )
+
+        # If no API key in config, try to get it from skill store
+        if not api_key:
+            try:
+                agent_id = context.agent.id if context and context.agent else "default"
+                api_key_data = await self.skill_store.get_agent_data(
+                    agent_id, "unrealspeech_api_key"
+                )
+                api_key = api_key_data.get("api_key") if api_key_data else None
+            except Exception as e:
+                logger.warning(f"Failed to get API key from skill store: {e}")
+
+        # If still no API key, check environment variables (handled by UnrealSpeech client)
+        if not api_key:
+            env_key = self.get_env_var("UNREALSPEECH_API_KEY")
+            if not env_key:
+                return {
+                    "success": False,
+                    "error": "No UnrealSpeech API key found. Please set the UNREALSPEECH_API_KEY environment variable or provide it in the agent configuration.",
+                }
+            api_key = env_key
+
+        # Clean up and validate input
+        if not text:
+            return {"success": False, "error": "Text cannot be empty."}
+
+        # Validate bitrate
+        valid_bitrates = ["64k", "96k", "128k", "192k", "256k", "320k"]
+        if bitrate not in valid_bitrates:
+            logger.warning(f"Invalid bitrate '{bitrate}'. Using default '192k'.")
+            bitrate = "192k"
+
+        # Validate speed
+        if not -1.0 <= speed <= 1.0:
+            logger.warning(
+                f"Speed value {speed} is outside valid range (-1.0 to 1.0). Clamping to valid range."
+            )
+            speed = max(-1.0, min(1.0, speed))
+
+        try:
+            # For longer text, use the /speech endpoint for better handling
+            endpoint = "https://api.v8.unrealspeech.com/speech"
+
+            # Prepare the request payload
+            payload = {
+                "Text": text,
+                "VoiceId": voice_id,
+                "Bitrate": bitrate,
+                "Speed": str(speed),
+                "Pitch": "1",
+                "OutputFormat": "uri",
+            }
+
+            # Add timestamp type if specified
+            if timestamp_type:
+                payload["TimestampType"] = timestamp_type
+
+            # Send the request to UnrealSpeech API
+            async with httpx.AsyncClient(timeout=60.0) as client:
+                headers = {
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                }
+
+                response = await client.post(endpoint, json=payload, headers=headers)
+
+                # Check response status
+                if response.status_code != 200:
+                    logger.error(f"UnrealSpeech API error: {response.text}")
+                    return {
+                        "success": False,
+                        "error": f"API error: {response.status_code} - {response.text}",
+                    }
+
+                # Parse response
+                result = response.json()
+
+                # Format the response
+                return {
+                    "success": True,
+                    "task_id": result.get("TaskId"),
+                    "audio_url": result.get("OutputUri"),
+                    "timestamps_url": result.get("TimestampsUri")
+                    if timestamp_type
+                    else None,
+                    "status": result.get("TaskStatus"),
+                    "voice_id": result.get("VoiceId"),
+                    "character_count": result.get("RequestCharacters"),
+                    "word_count": result.get("RequestCharacters", 0)
+                    // 5,  # Rough estimate
+                    "duration_seconds": result.get("RequestCharacters", 0)
+                    // 15,  # Rough estimate (15 chars/sec)
+                    "created_at": result.get("CreationTime"),
+                }
+
+        except Exception as e:
+            logger.error(f"Failed to generate speech: {e}", exc_info=True)
+            return {"success": False, "error": f"Failed to generate speech: {str(e)}"}

intentkit/skills/venice_audio/__init__.py

@@ -0,0 +1,106 @@
+import logging
+from typing import List, Literal, Optional, TypedDict
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import SkillConfig, SkillState
+from intentkit.skills.venice_audio.base import VeniceAudioBaseTool
+from intentkit.skills.venice_audio.venice_audio import VeniceAudioTool
+
+logger = logging.getLogger(__name__)
+
+
+_cache: dict[str, VeniceAudioBaseTool] = {}
+
+_SKILL_NAME_TO_CLASS_MAP = {
+    "text_to_speech": VeniceAudioTool,
+    # Add new mappings here: "skill_name": SkillClassName
+}
+
+
+class SkillStates(TypedDict):
+    text_to_speech: SkillState
+
+
+class Config(SkillConfig):
+    enabled: bool
+    voice_model: Literal["af_heart", "bm_lewis", "custom"]
+    states: SkillStates  # type: ignore
+    api_key_provider: Optional[Literal["agent_owner"]]
+
+    # conditionally required
+    api_key: Optional[str]
+    voice_model_custom: Optional[list[str]]
+
+    # optional
+    rate_limit_number: Optional[int]
+    rate_limit_minutes: Optional[int]
+
+
+async def get_skills(
+    config: "Config",
+    is_private: bool,
+    store: SkillStoreABC,
+    **_,  # Allow for extra arguments if the loader passes them
+) -> list[VeniceAudioBaseTool]:
+    """
+    Factory function to create and return Venice Audio skill tools.
+
+    Args:
+        config: The configuration dictionary for the Venice Audio skill.
+        skill_store: The skill store instance.
+        agent_id: The ID of the agent requesting the skills.
+
+    Returns:
+        A list of VeniceAudioBaseTool instances for the Venice Audio skill.
+    """
+    # Check if the entire category is disabled first
+    if not config.get("enabled", False):
+        return []
+
+    available_skills: List[VeniceAudioBaseTool] = []
+    skill_states = config.get("states", {})
+
+    # Iterate through all known skills defined in the map
+    for skill_name in _SKILL_NAME_TO_CLASS_MAP:
+        state = skill_states.get(
+            skill_name, "disabled"
+        )  # Default to disabled if not in config
+
+        if state == "disabled":
+            continue
+        elif state == "public" or (state == "private" and is_private):
+            # If enabled, get the skill instance using the factory function
+            skill_instance = get_venice_audio_skill(skill_name, store)
+            if skill_instance:
+                available_skills.append(skill_instance)
+            else:
+                # This case should ideally not happen if the map is correct
+                logger.warning(f"Could not instantiate known skill: {skill_name}")
+
+    return available_skills
+
+
+def get_venice_audio_skill(
+    name: str,
+    store: SkillStoreABC,
+) -> Optional[VeniceAudioBaseTool]:
+    """
+    Factory function to get a cached Venice Audio skill instance by name.
+
+    Args:
+        name: The name of voice model.
+        store: The skill store, passed to the skill constructor.
+
+    Returns:
+        The requested Venice Audio skill instance, or None if the name is unknown.
+    """
+
+    # Return from cache immediately if already exists
+    if name in _cache:
+        return _cache[name]
+
+    # Cache and return the newly created instance
+    _cache[name] = VeniceAudioTool(
+        skill_store=store,
+    )
+    return _cache[name]

intentkit/skills/venice_audio/base.py

@@ -0,0 +1,119 @@
+import logging
+from typing import Dict, List, Optional, Tuple, Type
+
+from pydantic import BaseModel, Field
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import IntentKitSkill, SkillContext, ToolException
+
+logger = logging.getLogger(__name__)
+
+
+class VeniceAudioBaseTool(IntentKitSkill):
+    """Base class for Venice Audio tools."""
+
+    name: str = Field(default="venice_base_tool", description="The name of the tool")
+    description: str = Field(description="A description of what the tool does")
+    args_schema: Type[BaseModel]  # type: ignore
+    skill_store: SkillStoreABC = Field(
+        description="The skill store for persisting data"
+    )
+
+    @property
+    def category(self) -> str:
+        return "venice_audio"
+
+    def validate_voice_model(
+        self, context: SkillContext, voice_model: str
+    ) -> Tuple[bool, Optional[Dict[str, object]]]:
+        config = context.config
+
+        selected_model = config.get("voice_model")
+        custom_models = config.get("voice_model_custom", [])
+
+        allowed_voice_models: List[str] = []
+
+        if selected_model == "custom":
+            allowed_voice_models = custom_models or []
+        else:
+            allowed_voice_models = [selected_model] if selected_model else []
+
+        if voice_model not in allowed_voice_models:
+            return False, {
+                "error": f'"{voice_model}" is not allowed',
+                "allowed": allowed_voice_models,
+                "suggestion": "please try again with allowed voice model",
+            }
+
+        return True, None
+
+    def get_api_key(self, context: SkillContext) -> str:
+        """
+        Retrieves the Venice AI API key based on the api_key_provider setting.
+
+        Returns:
+            The API key if found.
+
+        Raises:
+            ToolException: If the API key is not found or provider is invalid.
+        """
+        try:
+            skillConfig = context.config
+            api_key_provider = skillConfig.get("api_key_provider")
+            if api_key_provider == "agent_owner":
+                agent_api_key = context.config.get("api_key")
+                if agent_api_key:
+                    logger.debug(
+                        f"Using agent-specific Venice API key for skill {self.name} in category {self.category}"
+                    )
+                    return agent_api_key
+                raise ToolException(
+                    f"No agent-owned Venice API key found for skill '{self.name}' in category '{self.category}'."
+                )
+
+            elif api_key_provider == "platform":
+                system_api_key = self.skill_store.get_system_config("venice_api_key")
+                if system_api_key:
+                    logger.debug(
+                        f"Using system Venice API key for skill {self.name} in category {self.category}"
+                    )
+                    return system_api_key
+                raise ToolException(
+                    f"No platform-hosted Venice API key found for skill '{self.name}' in category '{self.category}'."
+                )
+
+            else:
+                raise ToolException(
+                    f"Invalid API key provider '{api_key_provider}' for skill '{self.name}'"
+                )
+
+        except Exception as e:
+            raise ToolException(f"Failed to retrieve Venice API key: {str(e)}") from e
+
+    async def apply_rate_limit(self, context: SkillContext) -> None:
+        """
+        Applies rate limiting ONLY if specified in the agent's config ('skill_config').
+        Checks for 'rate_limit_number' and 'rate_limit_minutes'.
+        If not configured, NO rate limiting is applied.
+        Raises ConnectionAbortedError if the configured limit is exceeded.
+        """
+        skill_config = context.config
+        user_id = context.user_id
+
+        # Get agent-specific limits safely
+        limit_num = skill_config.get("rate_limit_number")
+        limit_min = skill_config.get("rate_limit_minutes")
+
+        # Apply limit ONLY if both values are present and valid (truthy check handles None and 0)
+        if limit_num and limit_min:
+            limit_source = "Agent"
+            logger.debug(
+                f"Applying {limit_source} rate limit ({limit_num}/{limit_min} min) for user {user_id} on {self.name}"
+            )
+            if user_id:
+                await self.user_rate_limit_by_category(user_id, limit_num, limit_min)
+        else:
+            # No valid agent configuration found, so do nothing.
+            logger.debug(
+                f"No agent rate limits configured for category '{self.category}'. Skipping rate limit for user {user_id}."
+            )

intentkit/skills/venice_audio/input.py

@@ -0,0 +1,41 @@
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+# Define the allowed format literals based on the API documentation
+AllowedAudioFormat = Literal["mp3", "opus", "aac", "flac", "wav", "pcm"]
+
+
+class VeniceAudioInput(BaseModel):
+    """
+    Input schema for Venice AI Text-to-Speech (/audio/speech endpoint).
+    Defines parameters controllable by the user when invoking the tool.
+    """
+
+    input: str = Field(
+        ...,  # Ellipsis (...) indicates this field is required
+        description="The text to generate audio for. Maximum length is 4096 characters.",
+        min_length=1,  # As per API docs: Required string length: 1
+        max_length=4096,  # As per API docs: The maximum length is 4096 characters.
+    )
+
+    voice_model: str = Field(
+        description="voice model to used to generate voice from text_to_speech tool."
+    )
+
+    speed: Optional[float] = Field(
+        default=1.0,  # As per API docs: default: 1 (using float for consistency)
+        description="The speed of the generated audio. 1.0 is normal speed. Allowed range: 0.25 to 4.0.",
+        ge=0.25,  # As per API docs: Required range: 0.25 <= x
+        le=4.0,  # As per API docs: Required range: x <= 4
+    )
+
+    response_format: Optional[AllowedAudioFormat] = Field(
+        default="mp3",  # As per API docs: default: mp3
+        description="The desired audio format for the output file.",
+    )
+
+    # --- Note on other API parameters ---
+    # 'model': Currently hardcoded to 'tts-kokoro' in VeniceAudioBaseTool._arun. Could be added here if needed.
+    # 'voice': Handled by the 'voice_model' attribute of the specific VeniceAudioBaseTool instance. Not typically set via input schema.
+    # 'streaming': Currently hardcoded to False in VeniceAudioBaseTool._arun. Could be added here if streaming support is implemented.

intentkit/skills/venice_audio/schema.json

@@ -0,0 +1,152 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Venice Audio Skills",
+    "x-icon": "https://ai.service.crestal.dev/skills/venice_audio/venice_audio.jpg",
+    "description": "Configuration for the Venice Audio skill.",
+    "type": "object",
+    "x-tags": [
+        "AI",
+        "Audio",
+        "Text to Speech"
+    ],
+    "properties": {
+        "enabled": {
+            "type": "boolean",
+            "title": "Enabled",
+            "description": "Enable or disable the Venice Audio skill.",
+            "default": false
+        },
+        "voice_model": {
+            "type": "string",
+            "title": "Voice Model",
+            "x-link": "[Listen Voice Example](https://huggingface.co/spaces/hexgrad/Kokoro-TTS)",
+            "enum": [
+                "af_heart",
+                "bm_lewis",
+                "custom"
+            ],
+            "x-enum-title": [
+                "af_heart (default female)",
+                "bm_lewis (default male)",
+                "Custom"
+            ],
+            "description": "Text to speech tool",
+            "default": "af_heart"
+        },
+        "states": {
+            "type": "object",
+            "title": "Skill States",
+            "description": "Enable/disable specific voice models. Only enable one if you want a consistent characteristic for your agent. See docs for voice details and quality grades.",
+            "properties": {
+                "text_to_speech": {
+                    "type": "string",
+                    "title": "Text to Speech",
+                    "enum": [
+                        "disabled",
+                        "public",
+                        "private"
+                    ],
+                    "x-enum-title": [
+                        "Disabled",
+                        "Agent Owner + All Users",
+                        "Agent Owner Only"
+                    ],
+                    "description": "Text to speech tool",
+                    "default": "disabled"
+                }
+            }
+        },
+        "api_key_provider": {
+            "type": "string",
+            "title": "API Key Provider",
+            "description": "Provider of the API key",
+            "enum": [
+                "agent_owner"
+            ],
+            "x-enum-title": [
+                "Owner Provided"
+            ],
+            "default": "agent_owner"
+        }
+    },
+    "required": [
+        "states",
+        "enabled"
+    ],
+    "allOf": [
+        {
+            "if": {
+                "properties": {
+                    "voice_model": {
+                        "const": "custom"
+                    }
+                }
+            },
+            "then": {
+                "properties": {
+                    "voice_model_custom": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        },
+                        "title": "Voice Model (Custom)",
+                        "x-link": "[Supported Voice Model](https://docs.venice.ai/api-reference/endpoint/audio/speech#body-voice)",
+                        "description": "You can add one or more custom voice models.",
+                        "default": [
+                            "af_heart",
+                            "bm_lewis"
+                        ]
+                    }
+                },
+                "required": [
+                    "voice_model_custom"
+                ]
+            }
+        },
+        {
+            "if": {
+                "allOf": [
+                    {
+                        "properties": {
+                            "enabled": {
+                                "const": true
+                            }
+                        }
+                    },
+                    {
+                        "properties": {
+                            "api_key_provider": {
+                                "const": "agent_owner"
+                            }
+                        }
+                    }
+                ]
+            },
+            "then": {
+                "properties": {
+                    "api_key": {
+                        "type": "string",
+                        "title": "Venice API Key",
+                        "x-link": "[Get your API key](https://venice.ai/)",
+                        "x-sensitive": true,
+                        "description": "API Key for authenticating with the Venice AI API."
+                    },
+                    "rate_limit_number": {
+                        "type": "integer",
+                        "title": "Rate Limit Number",
+                        "description": "Number of requests allowed per time window."
+                    },
+                    "rate_limit_minutes": {
+                        "type": "integer",
+                        "title": "Rate Limit Minutes",
+                        "description": "Time window in minutes for rate limiting."
+                    }
+                },
+                "required": [
+                    "api_key"
+                ]
+            }
+        }
+    ],
+    "additionalProperties": true
+}