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

intentkit/skills/venice_audio/venice_audio.py

@@ -0,0 +1,240 @@
+import hashlib
+import json
+import logging
+from typing import Any, Dict, Optional, Type
+
+import httpx
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.venice_audio.base import VeniceAudioBaseTool
+from intentkit.skills.venice_audio.input import AllowedAudioFormat, VeniceAudioInput
+from intentkit.utils.s3 import FileType, store_file_bytes
+
+logger = logging.getLogger(__name__)
+
+base_url = "https://api.venice.ai"
+
+
+class VeniceAudioTool(VeniceAudioBaseTool):
+    """
+    Tool for generating audio using the Venice AI Text-to-Speech API (/audio/speech).
+    It requires a specific 'voice_model' to be configured for the instance.
+    Handles API calls, rate limiting, storage, and returns results or API errors as dictionaries.
+
+    On successful audio generation, returns a dictionary with audio details.
+    On Venice API error (non-200 status), returns a dictionary containing
+    the error details from the API response instead of raising an exception.
+    """
+
+    name: str = "venice_audio_text_to_speech"
+    description: str = (
+        "Converts text to speech using a configured Venice AI voice model. "
+        "Requires input text. Optional parameters include speed (0.25-4.0, default 1.0) "
+        "and audio format (mp3, opus, aac, flac, wav, pcm, default mp3)."
+    )
+    args_schema: Type[BaseModel] = VeniceAudioInput
+    skill_store: SkillStoreABC = Field(
+        description="The skill store instance for accessing system/agent configurations and persisting data."
+    )
+
+    async def _arun(
+        self,
+        input: str,
+        voice_model: str,
+        config: RunnableConfig,
+        speed: Optional[float] = 1.0,
+        response_format: Optional[AllowedAudioFormat] = "mp3",
+        **kwargs,  # type: ignore
+    ) -> Dict[str, Any]:
+        """
+        Generates audio using the configured voice model via Venice AI TTS /audio/speech endpoint.
+        Stores the resulting audio using store_file_bytes.
+        Returns a dictionary containing audio details on success, or API error details on failure.
+        """
+        context = self.context_from_config(config)
+        final_response_format = response_format if response_format else "mp3"
+        tts_model_id = "tts-kokoro"  # API model used
+
+        try:
+            # --- Setup Checks ---
+            api_key = self.get_api_key(context)
+
+            _, error_info = self.validate_voice_model(context, voice_model)
+            if error_info:
+                return error_info
+
+            if not api_key:
+                message = (
+                    f"Venice AI API key configuration missing for skill '{self.name}'."
+                )
+                details = f"API key not found for category '{self.category}'. Please configure it."
+                logger.error(message)
+                return {
+                    "error": True,
+                    "error_type": "ConfigurationError",
+                    "message": message,
+                    "details": details,
+                    "voice_model": voice_model,
+                    "requested_format": final_response_format,
+                }
+
+            if not voice_model:
+                message = (
+                    f"Instance of {self.name} was created without a 'voice_model'."
+                )
+                details = "Voice model must be specified for this tool instance."
+                logger.error(message)
+                return {
+                    "error": True,
+                    "error_type": "ConfigurationError",
+                    "message": message,
+                    "details": details,
+                    "voice_model": voice_model,
+                    "requested_format": final_response_format,
+                }
+
+            await self.apply_rate_limit(context)
+
+            # --- Prepare API Call ---
+            payload: Dict[str, Any] = {
+                "model": tts_model_id,
+                "input": input,
+                "voice": voice_model,
+                "response_format": final_response_format,
+                "speed": speed if speed is not None else 1.0,
+                "streaming": False,
+            }
+
+            payload = {k: v for k, v in payload.items() if v is not None}
+
+            logger.debug(
+                f"Venice Audio API Call: Voice='{voice_model}', Format='{final_response_format}', Payload='{payload}'"
+            )
+
+            headers = {
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            }
+            api_url = f"{base_url}/api/v1/audio/speech"
+
+            # --- Execute API Call ---
+            async with httpx.AsyncClient(timeout=120.0) as client:
+                response = await client.post(api_url, json=payload, headers=headers)
+                logger.debug(
+                    f"Venice Audio API Response: Voice='{voice_model}', Format='{final_response_format}', Status={response.status_code}"
+                )
+
+                content_type_header = str(
+                    response.headers.get("content-type", "")
+                ).lower()
+
+                # --- Handle API Success or Error from Response Body ---
+                if response.status_code == 200 and content_type_header.startswith(
+                    "audio/"
+                ):
+                    audio_bytes = response.content
+                    if not audio_bytes:
+                        message = (
+                            "API returned success status but response body was empty."
+                        )
+                        logger.warning(
+                            f"Venice Audio API (Voice: {voice_model}) returned 200 OK but empty audio content."
+                        )
+                        return {
+                            "error": True,
+                            "error_type": "NoContentError",
+                            "message": message,
+                            "status_code": response.status_code,
+                            "voice_model": voice_model,
+                            "requested_format": final_response_format,
+                        }
+
+                    # --- Store Audio ---
+                    file_extension = final_response_format
+                    audio_hash = hashlib.sha256(audio_bytes).hexdigest()
+                    key = f"{self.category}/{voice_model}/{audio_hash}.{file_extension}"
+
+                    size_limit = 1024 * 20  # 20Mb Size limit
+                    stored_url = await store_file_bytes(
+                        file_bytes=audio_bytes,
+                        key=key,
+                        file_type=FileType.AUDIO,
+                        size_limit_bytes=size_limit,
+                    )
+
+                    if not stored_url:
+                        message = "Failed to store audio: S3 storage is not configured."
+                        logger.error(
+                            f"Failed to store audio (Voice: {voice_model}): S3 storage is not configured."
+                        )
+                        return {
+                            "error": True,
+                            "error_type": "StorageConfigurationError",
+                            "message": message,
+                            "voice_model": voice_model,
+                            "requested_format": final_response_format,
+                        }
+
+                    logger.info(
+                        f"Venice TTS success: Voice='{voice_model}', Format='{final_response_format}', Stored='{stored_url}'"
+                    )
+                    # --- Return Success Dictionary ---
+                    return {
+                        "audio_url": stored_url,
+                        "audio_bytes_sha256": audio_hash,
+                        "content_type": content_type_header,
+                        "voice_model": voice_model,
+                        "tts_engine": tts_model_id,
+                        "speed": speed if speed is not None else 1.0,
+                        "response_format": final_response_format,
+                        "input_text_length": len(input),
+                        "error": False,
+                        "status_code": response.status_code,
+                    }
+                else:
+                    # Non-200 API response or non-audio content
+                    error_details: Any = f"Raw error response text: {response.text}"
+                    try:
+                        parsed_details = response.json()
+                        error_details = parsed_details
+                    except json.JSONDecodeError:
+                        pass  # Keep raw text if JSON parsing fails
+
+                    message = "Venice Audio API returned a non-success status or unexpected content type."
+                    logger.error(
+                        f"Venice Audio API Error: Voice='{voice_model}', Format='{final_response_format}', Status={response.status_code}, Details: {error_details}"
+                    )
+                    return {
+                        "error": True,
+                        "error_type": "APIError",
+                        "message": message,
+                        "status_code": response.status_code,
+                        "details": error_details,
+                        "voice_model": voice_model,
+                        "requested_format": final_response_format,
+                    }
+
+        except Exception as e:
+            # Global exception handling for any uncaught error
+            error_type = type(
+                e
+            ).__name__  # Gets the class name of the exception (e.g., 'TimeoutException', 'ToolException')
+            message = f"An unexpected error occurred during audio generation for voice {voice_model}."
+            details = str(e)  # The string representation of the exception
+
+            # Log the error with full traceback for debugging
+            logger.error(
+                f"Venice Audio Tool Global Error ({error_type}): {message} | Details: {details}",
+                exc_info=True,
+            )
+
+            return {
+                "error": True,
+                "error_type": error_type,  # e.g., "TimeoutException", "ToolException", "ClientError", "ValueError"
+                "message": message,
+                "details": details,
+                "voice_model": voice_model,
+                "requested_format": final_response_format,
+            }

intentkit/skills/venice_image/README.md

@@ -0,0 +1,119 @@
+# Venice Image Skill Suite
+
+Venice Image is a comprehensive skill suite for intelligent agents, enabling state-of-the-art AI image generation, enhancement, upscaling, and vision analysis using the [Venice AI API](https://venice.ai/). This suite offers a modular interface: each sub-tool covers a focused aspect of visual intelligence, while sharing unified configuration and error handling.
+
+---
+
+## Features
+
+### 1. **Image Generation**
+Prompt-based creation of new artworks or photorealistic images, with support for multiple leading AI models, extensive style presets, and negative prompting. Models include:
+- **Fluently XL** (realism, professional art)
+- **Flux Dev** (innovative research, art workflows)
+- **Lustify SDXL** (photorealistic, NSFW/SFW)
+- **Pony Realism** (anime/character detail, Danbooru tags)
+- **Venice SD35 / Stable Diffusion 3.5** (Stability AI, creative design)
+
+### 2. **Image Enhancement**
+Stylize or refine *existing* images without changing their resolution—ideal for artistic edits, restoration, or visual polishing.
+
+### 3. **Image Upscaling**
+Increase resolution by 2x or 4x while preserving essential details (with optional noise/replication settings). Great for preparing web images for print or HD use.
+
+### 4. **Image Vision**
+Obtain highly detailed, context-rich textual descriptions of images—useful for content understanding, accessibility, indexing, or cognitive agents.
+
+---
+
+## How It Works
+
+- Tools call the Venice API via secure network requests, automatically handling authentication, rate limiting, and error management.
+- Any generated or processed images are transparently stored in an object store (S3 or compatible), with returned URLs ready for user consumption.
+- Unified logging and troubleshooting: every tool shares a robust diagnostic backbone for consistent developer experience.
+
+---
+
+## Setup and Configuration
+
+All skills require a **Venice API key** for operation.
+
+### Required Configuration
+- `enabled` *(bool)*: Enable or disable the overall skill suite.
+- `api_key` *(string, sensitive)*: Your [Venice AI API key](https://venice.ai/).
+- `states`: Enable/disable and set visibility for each sub-tool (public/private/disabled).
+
+### Advanced Options
+- `safe_mode` *(bool, default: true)*: If true, blurs images classified as adult/NSFW.
+- `hide_watermark` *(bool, default: true)*: Request images without a Venice watermark (subject to Venice policy).
+- `embed_exif_metadata` *(bool, default: false)*: Whether to embed prompt/config info in EXIF metadata.
+- `negative_prompt` *(string)*: Default negative prompt, e.g. `(worst quality: 1.4), bad quality, nsfw`.
+- `rate_limit_number` / `rate_limit_minutes`: (optional) Set a max request rate per agent.
+
+For per-tool configuration, refer to the `states` section in [schema.json](schema.json):
+- Each tool (e.g. `image_generation_flux_dev`, `image_enhance`, etc.) can be set to `"public"` (all users), `"private"` (agent owner only), or `"disabled"` (hidden).
+
+#### Example (YAML/JSON-like)
+```json
+{
+  "enabled": true,
+  "api_key": "<YOUR_VENICE_API_KEY>",
+  "safe_mode": true,
+  "states": {
+    "image_vision": "public",
+    "image_enhance": "private",
+    "image_upscale": "disabled",
+    "image_generation_flux_dev": "public"
+  }
+}
+```
+
+---
+
+## Usage Patterns
+
+Each sub-tool has its own standardized input:
+- URL-based tools (`image_enhance`, `image_upscale`, `image_vision`) require a web-accessible image URL.
+- Generation tools require a *prompt* and offer flexible parameters (size, style, negative prompt, etc).
+
+Errors and troubleshooting info are always returned in a structured dictionary, with clear separation of success and error fields.
+
+---
+
+## Output and Storage
+
+- All generated/processed images are written to S3-compatible storage using a SHA256-based unique key.
+- Returned URLs are agent-accessible and stable.
+- For Vision and non-binary results, the output is returned inline as a dictionary.
+
+---
+
+## Security, License & Compliance
+
+- Your Venice API key is required and kept confidential per config practices.
+- Generated images and tool usage are subject to [Venice AI Terms of Service](https://venice.ai/) and the terms of the respective models (e.g. Stability AI, Black Forest Labs).
+- Agents should implement their own access and moderation layers; Safe Mode and watermarking are best-effort.
+
+---
+
+## Included Sub-Tools
+
+_(For detailed docs, see the respective sub-tool README entries.)_
+
+- image_generation_fluently_xl
+- image_generation_flux_dev
+- image_generation_flux_dev_uncensored
+- image_generation_lustify_sdxl
+- image_generation_pony_realism
+- image_generation_venice_sd35
+- image_generation_stable_diffusion_3_5
+- image_enhance
+- image_upscale
+- image_vision
+
+---
+
+## Contributing & Support
+
+For issues, bugfixes, or requests, please open a GitHub issue or contact the maintainers. This suite is regularly updated as Venice AI evolves.
+
+---

intentkit/skills/venice_image/__init__.py

@@ -0,0 +1,154 @@
+import logging
+from typing import NotRequired, Optional, TypedDict
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import (
+    SkillConfig,
+    SkillState,
+)
+
+# Import the base tool and all specific model skill classes
+from intentkit.skills.venice_image.base import VeniceImageBaseTool
+from intentkit.skills.venice_image.image_enhance.image_enhance import ImageEnhance
+from intentkit.skills.venice_image.image_generation.image_generation_fluently_xl import (
+    ImageGenerationFluentlyXL,
+)
+from intentkit.skills.venice_image.image_generation.image_generation_flux_dev import (
+    ImageGenerationFluxDev,
+)
+from intentkit.skills.venice_image.image_generation.image_generation_flux_dev_uncensored import (
+    ImageGenerationFluxDevUncensored,
+)
+from intentkit.skills.venice_image.image_generation.image_generation_lustify_sdxl import (
+    ImageGenerationLustifySDXL,
+)
+from intentkit.skills.venice_image.image_generation.image_generation_pony_realism import (
+    ImageGenerationPonyRealism,
+)
+from intentkit.skills.venice_image.image_generation.image_generation_stable_diffusion_3_5 import (
+    ImageGenerationStableDiffusion35,
+)
+from intentkit.skills.venice_image.image_generation.image_generation_venice_sd35 import (
+    ImageGenerationVeniceSD35,
+)
+from intentkit.skills.venice_image.image_upscale.image_upscale import ImageUpscale
+from intentkit.skills.venice_image.image_vision.image_vision import ImageVision
+
+# Cache skills at the system level, because they are stateless and only depend on the store
+_cache: dict[str, VeniceImageBaseTool] = {}
+
+logger = logging.getLogger(__name__)
+
+
+# Define the expected structure for the 'states' dictionary in the config
+class SkillStates(TypedDict):
+    image_upscale: SkillState
+    image_enhance: SkillState
+    image_vision: SkillState
+    image_generation_flux_dev: SkillState
+    image_generation_flux_dev_uncensored: SkillState
+    image_generation_venice_sd35: SkillState
+    image_generation_fluently_xl: SkillState
+    image_generation_lustify_sdxl: SkillState
+    image_generation_pony_realism: SkillState
+    image_generation_stable_diffusion_3_5: SkillState
+    # Add new skill names here if more models are added
+
+
+# Define the overall configuration structure for the venice_image category
+class Config(SkillConfig):
+    """Configuration for Venice Image skills."""
+
+    enabled: bool  # Keep standard enabled flag
+    states: SkillStates
+    api_key_provider: str = "agent_owner"
+    api_key: NotRequired[Optional[str]]  # Explicitly Optional
+    safe_mode: NotRequired[bool]  # Defaults handled in base or usage
+    hide_watermark: NotRequired[bool]  # Defaults handled in base or usage
+    negative_prompt: NotRequired[str]  # Defaults handled in base or usage
+    rate_limit_number: NotRequired[Optional[int]]  # Explicitly Optional
+    rate_limit_minutes: NotRequired[Optional[int]]  # Explicitly Optional
+
+
+_SKILL_NAME_TO_CLASS_MAP: dict[str, type[VeniceImageBaseTool]] = {
+    "image_upscale": ImageUpscale,
+    "image_enhance": ImageEnhance,
+    "image_vision": ImageVision,
+    "image_generation_flux_dev": ImageGenerationFluxDev,
+    "image_generation_flux_dev_uncensored": ImageGenerationFluxDevUncensored,
+    "image_generation_venice_sd35": ImageGenerationVeniceSD35,
+    "image_generation_fluently_xl": ImageGenerationFluentlyXL,
+    "image_generation_lustify_sdxl": ImageGenerationLustifySDXL,
+    "image_generation_pony_realism": ImageGenerationPonyRealism,
+    "image_generation_stable_diffusion_3_5": ImageGenerationStableDiffusion35,
+}
+
+
+async def get_skills(
+    config: "Config",
+    is_private: bool,
+    store: SkillStoreABC,
+    **_,  # Allow for extra arguments if the loader passes them
+) -> list[VeniceImageBaseTool]:
+    """Get all enabled Venice Image skills based on configuration and privacy level.
+
+    Args:
+        config: The configuration for Venice Image skills.
+        is_private: Whether the context is private (e.g., agent owner).
+        store: The skill store for persisting data and accessing system config.
+
+    Returns:
+        A list of instantiated and enabled Venice Image skill objects.
+    """
+    # Check if the entire category is disabled first
+    if not config.get("enabled", False):
+        return []
+
+    available_skills: list[VeniceImageBaseTool] = []
+
+    # Include skills based on their state
+    for skill_name, state in config["states"].items():
+        if state == "disabled":
+            continue
+        elif state == "public" or (state == "private" and is_private):
+            available_skills.append(skill_name)
+
+    # Get each skill using the cached getter
+    result = []
+    for name in available_skills:
+        skill = get_venice_image_skill(name, store, config)
+        if skill:
+            result.append(skill)
+    return result
+
+
+def get_venice_image_skill(
+    name: str,
+    store: SkillStoreABC,
+    config: "Config",
+) -> Optional[VeniceImageBaseTool]:
+    """
+    Factory function to get a cached Venice Image skill instance by name.
+
+    Args:
+        name: The name of the skill to get (must match keys in _SKILL_NAME_TO_CLASS_MAP).
+        store: The skill store, passed to the skill constructor.
+
+    Returns:
+        The requested Venice Image skill instance, or None if the name is unknown.
+    """
+
+    # Return from cache immediately if already exists
+    if name in _cache:
+        return _cache[name]
+
+    skill_class = _SKILL_NAME_TO_CLASS_MAP.get(name)
+    if not skill_class:
+        logger.warning(f"Unknown Venice skill: {name}")
+        return None
+
+    # Cache and return the newly created instance
+    _cache[name] = skill_class(
+        skill_store=store,
+    )
+    return _cache[name]

intentkit/skills/venice_image/api.py

@@ -0,0 +1,138 @@
+"""
+This module encapsulates all interactions with the Venice AI API.
+It provides a function, make_venice_api_request, to make POST requests
+to the API and handles the responses, including error handling,
+content type checking, and image storage via S3.  This separation
+of concerns keeps the core skill logic cleaner and easier to maintain.
+"""
+
+import hashlib
+import logging
+from typing import Any, Dict, Optional, Tuple
+
+import httpx
+
+from intentkit.utils.s3 import store_image_bytes
+
+logger = logging.getLogger(__name__)
+
+
+async def make_venice_api_request(
+    api_key: str,
+    path: str,
+    payload: Dict[str, Any],
+    category: str,
+    tool_name: str,
+) -> Tuple[Dict[str, Any], Optional[Dict[str, Any]]]:
+    """
+    Makes a POST request to the Venice AI API, handling all aspects
+    of the API interaction.  This includes:
+
+    1.  Constructing the API URL using a base URL and the provided path.
+    2.  Adding the required authorization header with the provided API key.
+    3.  Sending the POST request with the given payload.
+    4.  Handling potential connection and HTTP errors.
+    5.  Calling the internal _handle_response function to process the API's
+        response, which might be JSON or an image.
+
+    Args:
+        api_key: The Venice AI API key for authentication.
+        path: The API endpoint path (e.g., "/api/v1/image/generate").  Should *not* start with the base URL.
+        payload: The data to send in the request body (as JSON).
+        category: The category of the skill making the request (e.g., "venice_image"). Used for S3 storage and logging purpose.
+        tool_name: The name of the tool or skill making the request (e.g., "image_generation"). Used for S3 storage and logging purpose.
+
+    Returns:
+        A tuple: (success_data, error_data).
+        - success_data:  A dictionary containing the parsed JSON response from the API if the request was successful
+          (or a dictionary containing the S3 URL if the response is an image).
+        - error_data:  A dictionary containing information about any errors that occurred,
+          or None if the request was successful.  The dictionary includes an 'error' key.
+    """
+
+    venice_base_url = "https://api.venice.ai"  # Venice AI API base URL
+
+    if not path.startswith("/"):
+        path = "/" + path
+
+    api_url = f"{venice_base_url}{path}"
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "Accept": "image/*, application/json",
+    }
+
+    logger.info(
+        f"[{category}/{tool_name}] Sending request to {api_url} with payload: {payload}"
+    )
+
+    try:
+        async with httpx.AsyncClient(timeout=180.0) as client:
+            response = await client.post(api_url, json=payload, headers=headers)
+            return await _handle_response(response, category, tool_name)
+
+    except httpx.RequestError as e:
+        error_msg = f"Connection error: {e}"
+        logger.error(f"[{category}/{tool_name}] {error_msg}")
+        return {}, {"success": False, "error": error_msg}
+    except Exception as e:
+        error_msg = f"Unexpected error: {e}"
+        logger.error(f"[{category}/{tool_name}] {error_msg}", exc_info=True)
+        return {}, {"success": False, "error": error_msg}
+
+
+async def _handle_response(
+    response: httpx.Response, category: str, tool_name: str
+) -> Tuple[Dict[str, Any], Optional[Dict[str, Any]]]:
+    """
+    Handles the API response, differentiating between JSON and image responses.
+
+    If the response is an image (based on the 'content-type' header),
+    it stores the image in S3 and returns the S3 URL.
+    If the response is JSON, it parses the JSON and returns it.
+    If any errors occur, it returns an error dictionary.
+    """
+
+    content_type = str(response.headers.get("content-type", "")).lower()
+
+    if response.status_code == 200 and content_type.startswith("image/"):
+        try:
+            upscaled_image_bytes = response.content
+            image_hash = hashlib.sha256(upscaled_image_bytes).hexdigest()
+            file_extension = content_type.split("/")[-1].split("+")[0] or "png"
+
+            key = f"{category}/{tool_name}/{image_hash}.{file_extension}"
+
+            logger.info(f"[{category}/{tool_name}] Storing image with key: {key}")
+
+            stored_url = await store_image_bytes(
+                upscaled_image_bytes, key, content_type=content_type
+            )
+
+            return {"success": True, "result": stored_url}, None
+
+        except Exception as e:
+            error_msg = f"Error processing image response: {e}"
+            logger.error(f"[{category}/{tool_name}] {error_msg}", exc_info=True)
+            return {}, {"success": False, "error": error_msg}
+
+    elif response.status_code == 200:
+        try:
+            logger.info(f"[{category}/{tool_name}] Received successful JSON response.")
+            return response.json(), None
+        except Exception as json_err:
+            error_msg = f"Failed to parse JSON response: {json_err} - {response.text}"
+            logger.error(f"[{category}/{tool_name}] {error_msg}")
+            return {}, {"success": False, "error": error_msg}
+
+    else:
+        try:
+            error_data = response.json()
+            error_msg = f"API returned error: {error_data.get('message', error_data.get('detail', response.text))}"
+            logger.error(f"[{category}/{tool_name}] {error_msg}")
+            return {}, {"success": False, "error": error_msg}
+        except Exception:
+            error_msg = f"API returned status code {response.status_code} with text: {response.text}"
+            logger.error(f"[{category}/{tool_name}] {error_msg}")
+            return {}, {"success": False, "error": error_msg}